The public methods
*) (* A "VBT" is represented as an object with a private prefix and twelve public methods, which define the way the "VBT" responds to events. *************** *** 61,76 **** interface provides wrapper procedures that call the methods indirectly. *) ! (* \subsection{Screens and domains} *) ! (* Every "VBT" has a {\it screen} that associates a pixel value with each integer lattice point. We write "v[p]" to denote the value of the pixel at point "p" of the screen of the "VBT" "v". Changing ! the pixel values in a "VBT"'s screen is called {\it painting}. The part of a "VBT"'s screen that is visible to the user---or that would be visible if other windows weren't in the way---is called the ! {\it domain} of the "VBT": *) PROCEDURE Domain(v: T): Rect.T; <* LL.sup < v *> (* Return the rectangular extent of the visible part of --- 61,76 ---- interface provides wrapper procedures that call the methods indirectly. *) ! (*Screens and domains
*) ! (* Every "VBT" has a screen that associates a pixel value with each integer lattice point. We write "v[p]" to denote the value of the pixel at point "p" of the screen of the "VBT" "v". Changing ! the pixel values in a "VBT"'s screen is called painting. The part of a "VBT"'s screen that is visible to the user---or that would be visible if other windows weren't in the way---is called the ! domain of the "VBT": *) PROCEDURE Domain(v: T): Rect.T; <* LL.sup < v *> (* Return the rectangular extent of the visible part of *************** *** 90,100 **** The pragma "LL.sup < v" is explained in the next section. *) ! (* \subsection{Locking level} *) (* The global mutex "mu" serializes operations that affect the tree of "VBTs": ! \index{LL (Locking Level)@{\protect\tt LL} (Locking Level)}*) VAR mu: MUTEX; --- 90,104 ---- The pragma "LL.sup < v" is explained in the next section. *) ! (*Locking level
*) (* The global mutex "mu" serializes operations that affect the tree of "VBTs": ! ! LL (Locking Level) ! <TT>LL</TT> (Locking Level) ! ! *) VAR mu: MUTEX; *************** *** 105,115 **** The order in which a thread is allowed to acquire these locks is called the ``locking order''. It is defined by these two rules: ! \medskip\bulletitem The global "mu" precedes every "VBT". ! ! \medskip\bulletitem Every "VBT" precedes its parent. ! ! \medskip\noindent The ``locking level'' of a thread, or "LL" for short, is the set of locks that the thread has acquired. The expression "LL.sup" denotes the maximum of the locks in "LL". (The locking order is partial, but "LL.sup" will be defined for any thread --- 109,118 ---- The order in which a thread is allowed to acquire these locks is called the ``locking order''. It is defined by these two rules: !- The global "mu" precedes every "VBT". !
- Every "VBT" precedes its parent. !
ScreenTypes
*) (* Pixel values are integers. The color associated with a pixel value ! is determined in some manner that depends on the screentype of the "VBT". A value "st" of type "VBT.ScreenType" represents a screentype: *) *************** *** 207,213 **** (* The "ScreenType" interface reveals more details, for example, about color maps. *) ! (* \subsection{Splits and leaves} *) (* User interfaces are usually constructed from a tree of "VBTs" whose root is the ``top-level window'' known to the window manager. "VBTs" --- 210,216 ---- (* The "ScreenType" interface reveals more details, for example, about color maps. *) ! (*Splits and leaves
*) (* User interfaces are usually constructed from a tree of "VBTs" whose root is the ``top-level window'' known to the window manager. "VBTs" *************** *** 244,250 **** "Leaf". *) ! (* \subsection{Timestamps, modifiers, mouse buttons, and cursor positions} *) (* The following types are used in several of the event methods: *) --- 247,253 ---- "Leaf". *) ! (*Timestamps, modifiers, mouse buttons, and cursor positions
*) (* The following types are used in several of the event methods: *) *************** *** 275,288 **** (* Trestle has an internal unsigned clock register that is incremented every few milliseconds. When Trestle reports a mouse or keyboard event to a "VBT", it also reports the value of the clock register when the event ! occurred, which is called the {\it timestamp} of the event. Timestamps serve as unique identifiers for the associated events. Also, the absolute time interval between two events can be computed by subtracting their timestamps with "Word.Minus" and multiplying by "Trestle.TickTime()", which is the absolute interval between clock ! ticks. \index{time interval between events} ! A few keys on the keyboard are defined to be {\it modifiers}, like "Shift", "Control", and "Option". When Trestle reports a mouse or keyboard event to a "VBT", it also reports the set of modifier keys and buttons that were down when the event occurred. Thus the application can distinguish --- 278,294 ---- (* Trestle has an internal unsigned clock register that is incremented every few milliseconds. When Trestle reports a mouse or keyboard event to a "VBT", it also reports the value of the clock register when the event ! occurred, which is called the timestamp of the event. Timestamps serve as unique identifiers for the associated events. Also, the absolute time interval between two events can be computed by subtracting their timestamps with "Word.Minus" and multiplying by "Trestle.TickTime()", which is the absolute interval between clock ! ticks. ! time interval between events ! ! ! A few keys on the keyboard are defined to be modifiers, like "Shift", "Control", and "Option". When Trestle reports a mouse or keyboard event to a "VBT", it also reports the set of modifier keys and buttons that were down when the event occurred. Thus the application can distinguish *************** *** 321,327 **** by at most one child of that split. You should think of the positions controlled by a "VBT" as the visible positions in its domain. *) ! (* \subsection{The mouse method} *) (* Trestle calls a "VBT"'s mouse method to report mouse clicks. The method will be called with "LL.sup = mu", and takes an argument of --- 327,333 ---- by at most one child of that split. You should think of the positions controlled by a "VBT" as the visible positions in its domain. *) ! (*The mouse method
*) (* Trestle calls a "VBT"'s mouse method to report mouse clicks. The method will be called with "LL.sup = mu", and takes an argument of *************** *** 361,374 **** Some Trestle implementations have auxilliary interfaces that allow you to set the amount of time and mouse motion allowed. *) ! (* \subsection{The mouse focus rule} *) (* A split relays mouse clicks to whichever child of the split controls the pixel at the position of the click---more or less. If this rule were applied blindly, a child could receive a down-click and never receive the corresponding up-click, which would make it impossible to program many user interfaces that involve dragging. Therefore the actual rule ! is more complicated. \index{mouse~focus} Each split "sp" contains a variable "mouseFocus(sp)", which records the child of the split that has received a transition of type --- 367,383 ---- Some Trestle implementations have auxilliary interfaces that allow you to set the amount of time and mouse motion allowed. *) ! (*The mouse focus rule
*) (* A split relays mouse clicks to whichever child of the split controls the pixel at the position of the click---more or less. If this rule were applied blindly, a child could receive a down-click and never receive the corresponding up-click, which would make it impossible to program many user interfaces that involve dragging. Therefore the actual rule ! is more complicated. ! mouse~focus ! ! Each split "sp" contains a variable "mouseFocus(sp)", which records the child of the split that has received a transition of type *************** *** 397,403 **** The mouse focus is guaranteed to receive all button transitions until the last button comes up, no matter where it occurs. *) ! (* \subsection{The position method} *) (* Trestle calls a "VBT"'s position method to report cursor positions. The method will be called with "LL.sup = mu", and takes an argument of --- 406,412 ---- The mouse focus is guaranteed to receive all button transitions until the last button comes up, no matter where it occurs. *) ! (*The position method
*) (* Trestle calls a "VBT"'s position method to report cursor positions. The method will be called with "LL.sup = mu", and takes an argument of *************** *** 417,423 **** positions. *) ! (* \subsection{Tracking the cursor by setting cages} *) (* Every "VBT" "v" contains a field "cage(v)", which represents a set of cursor positions. As long as the cursor's position is inside --- 426,432 ---- positions. *) ! (*Tracking the cursor by setting cages
*) (* Every "VBT" "v" contains a field "cage(v)", which represents a set of cursor positions. As long as the cursor's position is inside *************** *** 426,433 **** position to "v", after first resetting "v"'s cage to contain all cursor positions. Resetting the cage inhibits further reporting of cursor positions: to continue tracking, the position method must ! set a new cage. \index{cursor~tracking} ! \index{cages~(for~cursor~tracking)} *) TYPE Cage = RECORD --- 435,448 ---- position to "v", after first resetting "v"'s cage to contain all cursor positions. Resetting the cage inhibits further reporting of cursor positions: to continue tracking, the position method must ! set a new cage. ! cursor~tracking ! ! ! ! cages~(for~cursor~tracking) ! ! *) TYPE Cage = RECORD *************** *** 442,454 **** (* The cage "cg" contains the cursor position "cp" if ! \medskip\bulletitem "cp.pt" is in "cg.rect", ! ! \medskip\bulletitem "cp.gone" is in "cg.inOut", and ! ! \medskip\bulletitem either "cg.screen = AllScreens" or "cg.screen = cp.screen". ! ! \medskip\noindent Trestle imposes the restriction on cages that if "cg.screen = AllScreens", then "cg.rect" must be "Rect.Full" or "Rect.Empty", and if "cg" contains no cursor positions, then it must be equal as a record to "EmptyCage" (which is declared below). For example, --- 457,467 ---- (* The cage "cg" contains the cursor position "cp" if !- "cp.pt" is in "cg.rect", !
- "cp.gone" is in "cg.inOut", and !
- either "cg.screen = AllScreens" or "cg.screen = cp.screen". !
The key method
*) (* Trestle calls a "VBT"'s "key" method to report keystrokes. The method will be called with "LL.sup = mu", and takes an argument of ! type "KeyRec". ! key method ! ! *) TYPE KeyRec = RECORD *************** *** 597,603 **** These interfaces are shipped with SRC Trestle but are not included in the printed version of the reference manual. The codes are chosen to agree with the X Keysym codes (see X Window System, Scheifler ! et al., \cite{XSpec} Appendix E). If the keyboard, like most keyboards, has two symbols on some of the keys, then the "KeySym" for the down transition and later up --- 613,619 ---- These interfaces are shipped with SRC Trestle but are not included in the printed version of the reference manual. The codes are chosen to agree with the X Keysym codes (see X Window System, Scheifler ! et al., [XSpec] Appendix E). If the keyboard, like most keyboards, has two symbols on some of the keys, then the "KeySym" for the down transition and later up *************** *** 621,632 **** "VBT.Acquire". *) ! (* \subsection{The redisplay method} *) (* A typical "VBT" has a ``display invariant'' that defines what its screen looks like as a function of its state. When the state changes, the display invariant is reestablished by updating the screen. ! \index{redisplay~method} \index{marking~for~redisplay} When a series of changes are made, each of which invalidates the display invariant, it is undesirable to update the screen --- 637,654 ---- "VBT.Acquire". *) ! (*The redisplay method
*) (* A typical "VBT" has a ``display invariant'' that defines what its screen looks like as a function of its state. When the state changes, the display invariant is reestablished by updating the screen. ! ! redisplay~method ! ! ! marking~for~redisplay ! ! When a series of changes are made, each of which invalidates the display invariant, it is undesirable to update the screen *************** *** 663,674 **** needed. *) ! (* \subsection{The reshape method} *) (* Trestle calls a "VBT"'s reshape method to report changes in its domain. The method will be called with "LL.sup = mu.v" (as explained below), and takes an argument of type "ReshapeRec". ! \index{reshape method} *) TYPE ReshapeRec = RECORD new, prev, saved: Rect.T; --- 685,699 ---- needed. *) ! (*The reshape method
*) (* Trestle calls a "VBT"'s reshape method to report changes in its domain. The method will be called with "LL.sup = mu.v" (as explained below), and takes an argument of type "ReshapeRec". ! ! reshape method ! ! *) TYPE ReshapeRec = RECORD new, prev, saved: Rect.T; *************** *** 702,717 **** This locking level will be referred to as "v"'s share of "mu", and written "mu.v". Holding "mu" is logically equivalent to holding ! "mu.v" for every "v". Consequently, "mu.v < mu" in the locking order. Holding "mu.v" does not suffice to call a procedure that requires "mu" to be locked; on the other hand you cannot lock "mu" while holding "mu.v", since this would deadlock. *) ! (* \subsection{The rescreen method} *) (* Trestle calls a "VBT"'s rescreen method to report changes to its screentype. The method will be called with "LL.sup = mu.v", and ! takes an argument of type "RescreenRec". \index{rescreen method} *) TYPE RescreenRec = RECORD prev: Rect.T; --- 727,745 ---- This locking level will be referred to as "v"'s share of "mu", and written "mu.v". Holding "mu" is logically equivalent to holding ! "mu.v" for every "v". Consequently, "mu.v < mu" in the locking order. Holding "mu.v" does not suffice to call a procedure that requires "mu" to be locked; on the other hand you cannot lock "mu" while holding "mu.v", since this would deadlock. *) ! (*The rescreen method
*) (* Trestle calls a "VBT"'s rescreen method to report changes to its screentype. The method will be called with "LL.sup = mu.v", and ! takes an argument of type "RescreenRec". ! rescreen method ! ! *) TYPE RescreenRec = RECORD prev: Rect.T; *************** *** 728,739 **** unmarked as it is rescreened. "VBT.Leaf.rescreen" reshapes "v" to empty. *) ! (* \subsection{The repaint method} *) (* Trestle calls a "VBT"'s repaint method to report that part of its screen has been exposed and must be repainted. The method will be called with "LL.sup = mu.v", and takes an argument of type ! "Region.T". \index{repaint method} There are some subtleties if you are scrolling (that is, copying bits from one part of the screen to another) at the same time that --- 756,770 ---- unmarked as it is rescreened. "VBT.Leaf.rescreen" reshapes "v" to empty. *) ! (*The repaint method
*) (* Trestle calls a "VBT"'s repaint method to report that part of its screen has been exposed and must be repainted. The method will be called with "LL.sup = mu.v", and takes an argument of type ! "Region.T". ! repaint method ! ! There are some subtleties if you are scrolling (that is, copying bits from one part of the screen to another) at the same time that *************** *** 744,750 **** that is in "Domain(v)" and not in "bad(v)", the pixel "v[p]" is displayed to the user; that is, if "vis[p]" denotes what is actually visible at pixel "p", then we have the basic invariant ! \index{bad region} \index{exposed region} | vis[p] = v[p] `for all` p `controlled by "v" and outside` bad(v) --- 775,787 ---- that is in "Domain(v)" and not in "bad(v)", the pixel "v[p]" is displayed to the user; that is, if "vis[p]" denotes what is actually visible at pixel "p", then we have the basic invariant ! ! bad region ! ! ! exposed region ! ! | vis[p] = v[p] `for all` p `controlled by "v" and outside` bad(v) *************** *** 781,808 **** method. *) ! (* \subsection{About painting in general} *) (* Trestle's painting procedures all follow the same pattern. The arguments to the procedure specify: ! \medskip\bulletitem a {\it destination}, which is a set of pixels in a "VBT"'s screen. For example, the destination could be a rectangle, a trapezoid, a shape bounded by a curved path, or a region. ! ! \medskip\bulletitem a {\it source}, which is conceptually an infinite array of pixels, not necessarily of the same depth as those on the screen. For example, the source could be a texture, a text string in some font, an explicit bitmap or image, or the "VBT"'s screen itself. ! ! \medskip\bulletitem an {\it operation}, which is a function that takes a destination pixel value and a source pixel value and produces a destination pixel value. For example, the operation could be planewise "XOR". ! ! \medskip\noindent The effect of the painting procedure is to apply the operation to each pixel in the destination region. That is, if "v" is the "VBT", the effect of the painting procedure is to set "v[p] := op(v[p], s[p])" for each point "p" in the destination, where --- 818,843 ---- method. *) ! (*About painting in general
*) (* Trestle's painting procedures all follow the same pattern. The arguments to the procedure specify: !- a destination, which is a set of pixels in a "VBT"'s screen. For example, the destination could be a rectangle, a trapezoid, a shape bounded by a curved path, or a region. !
- a source, which is conceptually an infinite array of pixels, not necessarily of the same depth as those on the screen. For example, the source could be a texture, a text string in some font, an explicit bitmap or image, or the "VBT"'s screen itself. !
- an operation, which is a function that takes a destination pixel value and a source pixel value and produces a destination pixel value. For example, the operation could be planewise "XOR". !
Scrolling (copying one part of the screen to another)
*) PROCEDURE Scroll( *************** *** 868,874 **** By ``simultaneously'' it is meant that the pairs "p", "q" are enumerated in an order so that no destination pixel of an early pair corresponds to a source pixel of any later pair. ! \index{bad region} \index{exposed region} Recall the bad region and exposed region "bad(v)" and "exposed(v)" from the description of the repaint method. --- 903,915 ---- By ``simultaneously'' it is meant that the pairs "p", "q" are enumerated in an order so that no destination pixel of an early pair corresponds to a source pixel of any later pair. ! ! bad region ! ! ! exposed region ! ! Recall the bad region and exposed region "bad(v)" and "exposed(v)" from the description of the repaint method. *************** *** 882,901 **** to the worker thread's queue recording the painting that must be done. Then you must be careful to avoid the following sequence of events: ! \medskip\bulletitem The worker thread removes from its work queue an item indicating that it must repaint some region "A", and determines that the best way to do this is to scroll some other region "B". ! ! \medskip\bulletitem The "repaint" method is activated with exposed region "B"; it adds "B" to the work queue and returns. As it returns, the system sets the "VBT"'s bad and exposed regions to be empty. (See the description of the "repaint" method.) ! ! \medskip\bulletitem The worker thread copies the garbage from "B" into "A". ! ! \medskip Eventually the worker thread will get around to repainting "B", but the damage to "A" will never be repaired. To avoid this race condition, the repaint method should convey --- 923,940 ---- to the worker thread's queue recording the painting that must be done. Then you must be careful to avoid the following sequence of events: !- The worker thread removes from its work queue an item indicating that it must repaint some region "A", and determines that the best way to do this is to scroll some other region "B". !
- The "repaint" method is activated with exposed region "B"; it adds "B" to the work queue and returns. As it returns, the system sets the "VBT"'s bad and exposed regions to be empty. (See the description of the "repaint" method.) !
- The worker thread copies the garbage from "B" into "A". !
Painting textures
*) (* This section describes procedures for texturing rectangles, regions, and trapezoids. *) *************** *** 936,942 **** (* Paint the rectangle "clip" with the texture "src+delta" using the operation "op". *) ! (* A {\it texture} is an infinite periodic pixmap. A texture "txt" is represented by a pixmap "src" with a finite non-empty rectangular domain "Domain(src)"; the rule is that "txt" is the result of tiling the plane with translates of the pixmap "src". Using the convenient --- 975,981 ---- (* Paint the rectangle "clip" with the texture "src+delta" using the operation "op". *) ! (* A texture is an infinite periodic pixmap. A texture "txt" is represented by a pixmap "src" with a finite non-empty rectangular domain "Domain(src)"; the rule is that "txt" is the result of tiling the plane with translates of the pixmap "src". Using the convenient *************** *** 1026,1035 **** "src+delta" using the operation "op". *) ! (* \subsection{Filling and stroking paths} *) (* Trestle also supports PostScript-like graphics operations ! \cite{PostScript}: *) TYPE WindingCondition = {Odd, NonZero}; --- 1065,1074 ---- "src+delta" using the operation "op". *) ! (*Filling and stroking paths
*) (* Trestle also supports PostScript-like graphics operations ! [PostScript] : *) TYPE WindingCondition = {Odd, NonZero}; *************** *** 1051,1058 **** (* The point "p" is entwined by "path" if the winding number of "path" around "p" satisfies the winding condition "wind". To ensure that the winding number is defined even for the points on the path, the ! path is regarded as translated north by $\epsilon$ and west by ! $\epsilon^2$, where $\epsilon$ is infinitesimal. *) PROCEDURE Stroke( v: Leaf; --- 1090,1097 ---- (* The point "p" is entwined by "path" if the winding number of "path" around "p" satisfies the winding condition "wind". To ensure that the winding number is defined even for the points on the path, the ! path is regarded as translated north by $ε$ and west by ! $ε^2$, where $ε$ is infinitesimal. *) PROCEDURE Stroke( v: Leaf; *************** *** 1096,1102 **** segments meeting at some joint is small, then the tip of the miter may extend quite far from the joint point. Trestle implementations are free to bevel those joints whose angle is smaller than some ! implementation-dependent {\it miter limit}. The miter limit will be made available to clients in some to-be-determined interface. On X, the miter limit is 11 degrees. --- 1135,1141 ---- segments meeting at some joint is small, then the tip of the miter may extend quite far from the joint point. Trestle implementations are free to bevel those joints whose angle is smaller than some ! implementation-dependent miter limit. The miter limit will be made available to clients in some to-be-determined interface. On X, the miter limit is 11 degrees. *************** *** 1116,1122 **** (* Like "Stroke" applied to the path containing the segment "(p,q)". *) ! (* \subsection{Painting pixmaps} *) (* The following procedure paints a pixmap without replicating it into an infinite texture: *) --- 1155,1161 ---- (* Like "Stroke" applied to the path containing the segment "(p,q)". *) ! (*Painting pixmaps
*) (* The following procedure paints a pixmap without replicating it into an infinite texture: *) *************** *** 1168,1174 **** returns. If you wish to free the pixmap by calling "src.free()", you should first call "VBT.Sync(v)". *) ! (* \subsection{Painting text} *) (* The text painting procedures take an optional array of displacements, whose entries have the following type: *) --- 1207,1213 ---- returns. If you wish to free the pixmap by calling "src.free()", you should first call "VBT.Sync(v)". *) ! (*Painting text
*) (* The text painting procedures take an optional array of displacements, whose entries have the following type: *) *************** *** 1200,1250 **** (* The arguments to "PaintText" must satisfy at least one of the following two conditions: ! \medskip\bulletitem the background operation is transparent; that is, "op(p, 0) = p" for any pixel "p", or ! ! \medskip\bulletitem the font is self-clearing (see below) and "dl" is empty. ! ! \medskip\noindent If neither condition is true, the effect of "PaintText" is implementation-dependent, but is confined to the clipping rectangle. The "ScrnFont" interface defines the properties of fonts. Here we introduce names for the properties needed to explain "PaintText". If "f" is a font and "ch" is a character, then ! \medskip\bulletitem "printWidth(ch, f)" is the printing width of "ch"; that is, the amount to increment the reference point when "ch" is printed in font "f"; ! ! \medskip\bulletitem "bits(ch, f)" is the bitmap for "ch" in "f", which is positioned with "ch"'s reference point at the origin; ! ! \medskip\bulletitem "height(ch, f)" is the height of "ch" above the baseline; that is, the number of rows of "bits(ch, f)" whose "v"-coordinate is at most zero; and "depth(ch, fnt)" is the number of rows of "bits(ch, f)" whose "v"-coordinate exceeds zero; ! ! \medskip\bulletitem "ascent(f)" and "descent(f)" are the logical extent of "f" above and below the baseline. Some characters may extend higher or lower. ! \medskip\noindent A font is {\it self-clearing} if ! ! \medskip\bulletitem each character's height and depth equal the font's ascent and descent, and ! ! \medskip\bulletitem each character's "printWidth" equals the width of its bitmap and each character's reference point is at the west boundary of its bitmap (or each character's "printWidth" equals the negative of the width of its bitmap and each character's reference point is at the east boundary of its bitmap). ! ! \medskip\noindent The call to "PaintText" is equivalent to the following loop: | rp := pt; | i := 0; --- 1239,1284 ---- (* The arguments to "PaintText" must satisfy at least one of the following two conditions: !- the background operation is transparent; that is, "op(p, 0) = p" for any pixel "p", or !
- the font is self-clearing (see below) and "dl" is empty. !
- "printWidth(ch, f)" is the printing width of "ch"; that is, the amount to increment the reference point when "ch" is printed in font "f"; !
- "bits(ch, f)" is the bitmap for "ch" in "f", which is positioned with "ch"'s reference point at the origin; !
- "height(ch, f)" is the height of "ch" above the baseline; that is, the number of rows of "bits(ch, f)" whose "v"-coordinate is at most zero; and "depth(ch, fnt)" is the number of rows of "bits(ch, f)" whose "v"-coordinate exceeds zero; !
- "ascent(f)" and "descent(f)" are the logical extent of "f" above and below the baseline. Some characters may extend higher or lower. +
- each character's height and depth equal the font's ascent and descent, and !
- each character's "printWidth" equals the width of its bitmap and each character's reference point is at the west boundary of its bitmap (or each character's "printWidth" equals the negative of the width of its bitmap and each character's reference point is at the east boundary of its bitmap). !
Synchronization of painting requests
*) (* To improve painting performance, Trestle combines painting commands into batches, and sends them to the server a batch at a time. *************** *** 1322,1329 **** affects the screen and the time the following paint text command affects the screen, which can produce an undesirable flickering effect. The chances of this happening can be greatly reduced by enclosing the ! two commands in a {\it group}, using the following two procedures: ! \index{paint batch} \index{batch (of painting commands)} *) PROCEDURE BeginGroup(v: Leaf; sizeHint: INTEGER := 0); --- 1356,1369 ---- affects the screen and the time the following paint text command affects the screen, which can produce an undesirable flickering effect. The chances of this happening can be greatly reduced by enclosing the ! two commands in a group, using the following two procedures: ! ! paint batch ! ! ! batch (of painting commands) ! ! *) PROCEDURE BeginGroup(v: Leaf; sizeHint: INTEGER := 0); *************** *** 1353,1359 **** in the output queue have been completed. *) ! (* \subsection{Screen capture} *) PROCEDURE Capture( --- 1393,1399 ---- in the output queue have been completed. *) ! (*Screen capture
*) PROCEDURE Capture( *************** *** 1370,1378 **** all positions of pixels that were not copied. Naturally, Trestle makes "br" as small as it can. If none of the bits are available, the result may be "NIL". ! \index{reading the screen} *) ! (* \subsection{Controlling the cursor shape} *) (* Every "VBT" "v" contains a field "cursor(v)", which is set with the following procedure: *) --- 1410,1421 ---- all positions of pixels that were not copied. Naturally, Trestle makes "br" as small as it can. If none of the bits are available, the result may be "NIL". ! ! reading the screen ! ! *) ! (*Controlling the cursor shape
*) (* Every "VBT" "v" contains a field "cursor(v)", which is set with the following procedure: *) *************** *** 1384,1390 **** child if its mouse focus is "NIL". Only if the cursor of the relevant child is "Cursor.DontCare" or if there is no relevant child does the split display its own cursor. ! \index{cursor shape, how to change} To be more precise, the shape of the cursor over the top level window "v" is determined by the following recursive procedure: --- 1427,1436 ---- child if its mouse focus is "NIL". Only if the cursor of the relevant child is "Cursor.DontCare" or if there is no relevant child does the split display its own cursor. ! ! cursor shape, how to change ! ! To be more precise, the shape of the cursor over the top level window "v" is determined by the following recursive procedure: *************** *** 1409,1415 **** *) ! (* \subsection{Selections} *) (* Trestle maintains an internal table of named selections, which initially contains several selections of general use, --- 1455,1461 ---- *) ! (*Selections
*) (* Trestle maintains an internal table of named selections, which initially contains several selections of general use, *************** *** 1437,1458 **** (* "NilSel" and "Forgery" are reserved for Trestle's internal use. The owner of "KBFocus" (the keyboard focus) is the "VBT" that receives keystrokes. ! \index{input or keyboard focus} \index{keyboard focus} We offer the following suggestions for the use of target and source selections: ! \index{target selection} ! \index{source selection} ! \medskip\bulletitem The target selection. If text, this should be underlined black or reverse video. The selection gesture should not require modifiers like shift or control. ! ! \medskip\bulletitem The source selection. If text, this should be underlined gray. The source gesture should be a modified version of the gesture for making the target selection. ! ! \medskip An operation like ``copy'' should replace the target selection with the value of the source selection. *) --- 1483,1515 ---- (* "NilSel" and "Forgery" are reserved for Trestle's internal use. The owner of "KBFocus" (the keyboard focus) is the "VBT" that receives keystrokes. ! ! input or keyboard focus ! ! ! keyboard focus ! ! We offer the following suggestions for the use of target and source selections: ! ! target selection ! ! ! source selection ! ! ! !- The target selection. If text, this should be underlined black or reverse video. The selection gesture should not require modifiers like shift or control. !
- The source selection. If text, this should be underlined gray. The source gesture should be a modified version of the gesture for making the target selection. !
- "EventNotCurrent": Raised by attempts to access a selection with an event time that is not current. !
- "TimeOut": If you attempt to read or write a selection, and the selection owner's method does not return for an unreasonably long time, then Trestle stops waiting and raises this exception. !
- "Uninstalled": Raised by event-time operations on uninstalled "VBTs"; that is, on "VBTs" none of whose ancestors have been connected to a window system by one of the installation procedures in the "Trestle" interface. !
- "Unreadable", "Unwritable": Raised by attempts to read an unreadable selection, or write an unwritable selection. !
- "UnownedSelection": Raised by attempts to read, write, or deliver miscellaneous codes to the owner of an unowned selection. !
- "WrongType": Raised by attempts to read or write a
selection with a type not supported by the selection owner. *)
! (*
Acquiring and releasing selection ownership
*) PROCEDURE Acquire( v: T; *************** *** 1515,1525 **** "Release" is a no-op if the current owner is not "v" or if "v" is not installed. *) ! (* \subsection{The miscellaneous method} *) (* Trestle calls a "VBT"'s "misc" method to deliver miscellaneous codes. The method will be called with "LL.sup = mu", and takes an ! argument of type "MiscRec". \index{misc method} Trestle maintains an internal table of named miscellaneous code types, which initially contains several types of general interest, --- 1567,1580 ---- "Release" is a no-op if the current owner is not "v" or if "v" is not installed. *) ! (*The miscellaneous method
*) (* Trestle calls a "VBT"'s "misc" method to deliver miscellaneous codes. The method will be called with "LL.sup = mu", and takes an ! argument of type "MiscRec". ! misc method ! ! Trestle maintains an internal table of named miscellaneous code types, which initially contains several types of general interest, *************** *** 1597,1603 **** *) ! (* \subsection{Sending miscellaneous codes} *) (* You can send a miscellanous code to the owner of a selection by using the following procedure: *) --- 1652,1658 ---- *) ! (*Sending miscellaneous codes
*) (* You can send a miscellanous code to the owner of a selection by using the following procedure: *) *************** *** 1618,1624 **** "UnownedSelection". If the selection is unowned it is possible that the "Put" will be silently ignored. *) ! (* \subsection{Circumventing event-time} *) (* The following procedure offers an escape from the event-time protocol. For example, a long-running thread that has no idea what the current --- 1673,1679 ---- "UnownedSelection". If the selection is unowned it is possible that the "Put" will be silently ignored. *) ! (*Circumventing event-time
*) (* The following procedure offers an escape from the event-time protocol. For example, a long-running thread that has no idea what the current *************** *** 1642,1648 **** they are delivered to installed windows or their descendants. The only possible error code is "Uninstalled". *) ! (* \subsection{Communicating selection values} *) (* When you read the value of a Trestle selection you get a result of type "Value": *) --- 1697,1703 ---- they are delivered to installed windows or their descendants. The only possible error code is "Uninstalled". *) ! (*Communicating selection values
*) (* When you read the value of a Trestle selection you get a result of type "Value": *) *************** *** 1674,1680 **** the "Value" to the other application, and only when that application calls the "toRef" method will your "toRef" method be called. ! The "toRef" method in a "Value" will be called with "LL.sup <= mu". The "toRef" method can raise the error "Unreadable" if, for example, the address space of the selection owner has been destroyed. It can also raise the error "WrongType" if the underlying "REFANY" cannot be --- 1729,1735 ---- the "Value" to the other application, and only when that application calls the "toRef" method will your "toRef" method be called. ! The "toRef" method in a "Value" will be called with "LL.sup <= mu". The "toRef" method can raise the error "Unreadable" if, for example, the address space of the selection owner has been destroyed. It can also raise the error "WrongType" if the underlying "REFANY" cannot be *************** *** 1727,1737 **** "WrongType". *) ! (* \subsection{The read and write methods} *) (* Trestle calls a "VBT"'s read and write methods to access any selections that it owns. The method will be called with "LL.sup ! <= mu" (see below). \index{read method} The signature of the read method is --- 1782,1795 ---- "WrongType". *) ! (*The read and write methods
*) (* Trestle calls a "VBT"'s read and write methods to access any selections that it owns. The method will be called with "LL.sup ! <= mu" (see below). ! read method ! ! The signature of the read method is *************** *** 1742,1748 **** The method should return the value of the selection, or raise "Error(Unreadable)" if for some reason the value cannot be delivered, or "Error(WrongType)" if the selection cannot be converted to the ! requested type. The methods will be called with "LL.sup <= mu"; in fact, if the caller of "Read" is in the same address space, "LL" for the method call is the same as "LL" for the caller of "Read", else "LL" for the method call is "{}". --- 1800,1806 ---- The method should return the value of the selection, or raise "Error(Unreadable)" if for some reason the value cannot be delivered, or "Error(WrongType)" if the selection cannot be converted to the ! requested type. The methods will be called with "LL.sup <= mu"; in fact, if the caller of "Read" is in the same address space, "LL" for the method call is the same as "LL" for the caller of "Read", else "LL" for the method call is "{}". *************** *** 1761,1768 **** type. Trestle does not enforce any consistency between "tc" and the typecode of the reference "val.toRef()". For example, if "val.toRef()" is "NIL", the meaning could be determined by "tc". ! The locking level is the same as for the read method. \index{write ! method} While a read or write method is active in a descendant of an installed window, Trestle will block the delivery to that window --- 1819,1829 ---- type. Trestle does not enforce any consistency between "tc" and the typecode of the reference "val.toRef()". For example, if "val.toRef()" is "NIL", the meaning could be determined by "tc". ! The locking level is the same as for the read method. ! write ! method ! ! While a read or write method is active in a descendant of an installed window, Trestle will block the delivery to that window *************** *** 1771,1777 **** asynchronously, to avoid blocking the user. *) ! (* \subsection{Controlling the shape of a VBT} *) (* The preferred shape of a "VBT" is represented by a pair of records of type "SizeRange", one for each axis: *) --- 1832,1838 ---- asynchronously, to avoid blocking the user. *) ! (*Controlling the shape of a VBT
*) (* The preferred shape of a "VBT" is represented by a pair of records of type "SizeRange", one for each axis: *) *************** *** 1786,1792 **** range from "sh.lo" to "sh.hi-1", and its preferred size is "sh.pref". ! A "SizeRange" "sh" is illegal unless "sh.lo <= sh.pref < sh.hi". When a parent "VBT" divides its screen up between its children, it tries to satisfy its children's shape requirements, which it finds --- 1847,1853 ---- range from "sh.lo" to "sh.hi-1", and its preferred size is "sh.pref". ! A "SizeRange" "sh" is illegal unless "sh.lo <= sh.pref < sh.hi". When a parent "VBT" divides its screen up between its children, it tries to satisfy its children's shape requirements, which it finds *************** *** 1827,1836 **** it can also be called from a thread that has "mu" locked. *) ! (* \subsection{Putting properties on a VBT} *) (* Associated with each window is a ``property set'', which is a set ! of non-nil traced references. \index{property set, of window} *) PROCEDURE PutProp(v: T; ref: REFANY); <* LL.sup < v *> --- 1888,1900 ---- it can also be called from a thread that has "mu" locked. *) ! (*Putting properties on a VBT
*) (* Associated with each window is a ``property set'', which is a set ! of non-nil traced references. ! property set, of window ! ! *) PROCEDURE PutProp(v: T; ref: REFANY); <* LL.sup < v *> *************** *** 1850,1859 **** exists. *) ! (* \subsection{Discarding a VBT} *) (* It is good form to call "VBT.Discard(v)" when "v" is about to be ! garbage-collected: \index{discard method} *) PROCEDURE Discard(v: T); <* LL.sup = mu *> (* Prepare for and call "v.discard()". *) --- 1914,1926 ---- exists. *) ! (*Discarding a VBT
*) (* It is good form to call "VBT.Discard(v)" when "v" is about to be ! garbage-collected: ! discard method ! ! *) PROCEDURE Discard(v: T); <* LL.sup = mu *> (* Prepare for and call "v.discard()". *) Index: m3/pm3/graphics/gr-libs/ui/src/vbt/VBTClass.i3 diff -c m3/pm3/graphics/gr-libs/ui/src/vbt/VBTClass.i3:1.1.1.1 m3/pm3/graphics/gr-libs/ui/src/vbt/VBTClass.i3:1.2 *** m3/pm3/graphics/gr-libs/ui/src/vbt/VBTClass.i3:1.1.1.1 Thu Jan 16 16:31:41 1997 --- m3/pm3/graphics/gr-libs/ui/src/vbt/VBTClass.i3 Tue Feb 10 22:28:04 1998 *************** *** 89,95 **** Painting on the vast majority of "VBT"s can be implemented simply by clipping to their domain and then relaying the painting to their parent. ! To speed up this common case, every "VBT" has a {\it short-circuit} bit. If this bit is set then Trestle doesn't call the "VBT"'s "paintbatch" method at all; it just clips to the "VBT"'s domain and paints on its parent. Typically the only "VBT"s whose short-circuit bits are not set --- 89,95 ---- Painting on the vast majority of "VBT"s can be implemented simply by clipping to their domain and then relaying the painting to their parent. ! To speed up this common case, every "VBT" has a short-circuit bit. If this bit is set then Trestle doesn't call the "VBT"'s "paintbatch" method at all; it just clips to the "VBT"'s domain and paints on its parent. Typically the only "VBT"s whose short-circuit bits are not set *************** *** 170,176 **** axisOrder (): Axis.T; END; ! (* From "VBT.Prefix <: Prefix" it follows "VBT.T <: Prefix"; hence every "VBT" is a "MUTEX" object, and has the above fields and methods. The complete revelation for the type "VBT.T" is private to Trestle. --- 170,176 ---- axisOrder (): Axis.T; END; ! (* From "VBT.Prefix <: Prefix" it follows "VBT.T <: Prefix"; hence every "VBT" is a "MUTEX" object, and has the above fields and methods. The complete revelation for the type "VBT.T" is private to Trestle. *************** *** 286,292 **** mistake---it is the responsibility of the split's implementation to paint on the parent as necessary to keep its screen up to date. *) ! (* \subsubsection{Specifications of the split methods} *) (* The first group of methods implement the behavior in the "Split" interface: --- 286,292 ---- mistake---it is the responsibility of the split's implementation to paint on the parent as necessary to keep its screen up to date. *) ! (*Specifications of the split methods
*) (* The first group of methods implement the behavior in the "Split" interface: *************** *** 385,391 **** whenever two children overlap, the top one appears earlier in "succ" order. *) ! (* \subsubsection{Specifications of the up methods} *) (* So much for the split methods; here now are the specifications of the up methods. In all cases, "ch" is a child of "v". --- 385,391 ---- whenever two children overlap, the top one appears earlier in "succ" order. *) ! (*Specifications of the up methods
*) (* So much for the split methods; here now are the specifications of the up methods. In all cases, "ch" is a child of "v". *************** *** 427,433 **** The method call "v.newShape(ch)" signals that "ch"'s size range, preferred size, or axis order may have changed. The default recurses on ! the parent. When the method is called, "LL.sup < v AND LL >= {ch, VBT.mu.ch}". The remaining methods implement event-time operations for a descendent --- 427,433 ---- The method call "v.newShape(ch)" signals that "ch"'s size range, preferred size, or axis order may have changed. The default recurses on ! the parent. When the method is called, "LL.sup < v AND LL >= {ch, VBT.mu.ch}". The remaining methods implement event-time operations for a descendent *************** *** 440,449 **** cd.detail)". When these methods are called, "LL.sup = ch". Similarly, the "readUp" and "writeUp" methods implement the procedures ! "VBT.Read" and "VBT.Write". When these methods are called, "LL.sup <= VBT.mu". *) ! (* \subsubsection{Getting and setting the state of a VBT} *) PROCEDURE Cage (v: VBT.T): VBT.Cage; <* LL >= {v} *> (* Return v's cage. *) --- 440,449 ---- cd.detail)". When these methods are called, "LL.sup = ch". Similarly, the "readUp" and "writeUp" methods implement the procedures ! "VBT.Read" and "VBT.Write". When these methods are called, "LL.sup <= VBT.mu". *) ! (*Getting and setting the state of a VBT
*) PROCEDURE Cage (v: VBT.T): VBT.Cage; <* LL >= {v} *> (* Return v's cage. *) *************** *** 503,509 **** PROCEDURE ClearNewShape (v: VBT.T); <* LL.sup < v *> (* Clear "v"'s "newshape" bit. *) ! (* \subsubsection{Procedures for activating the down methods of a VBT} *) PROCEDURE Reshape (v: VBT.T; READONLY new, saved: Rect.T); <* LL.sup >= VBT.mu.v AND LL.sup <= VBT.mu *> --- 503,509 ---- PROCEDURE ClearNewShape (v: VBT.T); <* LL.sup < v *> (* Clear "v"'s "newshape" bit. *) ! (*Procedures for activating the down methods of a VBT
*) PROCEDURE Reshape (v: VBT.T; READONLY new, saved: Rect.T); <* LL.sup >= VBT.mu.v AND LL.sup <= VBT.mu *> *************** *** 617,623 **** (* Set "v.parent" and "v.upRef" to "NIL"; set "v"'s domain to empty, enqueue a reshape to empty, and clear "v"'s shortcircuit bit. *) ! (* \subsubsection{Procedures for activating the up methods of a VBT} *) (* The following six procedures are like the corresponding procedures in the "VBT" interface, except that they have a different locking level: *) --- 617,623 ---- (* Set "v.parent" and "v.upRef" to "NIL"; set "v"'s domain to empty, enqueue a reshape to empty, and clear "v"'s shortcircuit bit. *) ! (*Procedures for activating the up methods of a VBT
*) (* The following six procedures are like the corresponding procedures in the "VBT" interface, except that they have a different locking level: *) Index: m3/pm3/graphics/gr-libs/ui/src/vbt/m3makefile diff -c m3/pm3/graphics/gr-libs/ui/src/vbt/m3makefile:1.1.1.1 m3/pm3/graphics/gr-libs/ui/src/vbt/m3makefile:1.2 *** m3/pm3/graphics/gr-libs/ui/src/vbt/m3makefile:1.1.1.1 Thu Jan 16 16:31:42 1997 --- m3/pm3/graphics/gr-libs/ui/src/vbt/m3makefile Tue Feb 10 22:28:04 1998 *************** *** 38,40 **** --- 38,60 ---- Module ("MouseSplit") Module ("MiscDetail") + HtmlInterface("Batch") + HtmlInterface("BatchUtil") + HtmlInterface("Cursor") + HtmlInterface("Font") + HtmlInterface("PaintOp") + HtmlInterface("PaintPrivate") + HtmlInterface("Palette") + HtmlInterface("Pixmap") + HtmlInterface("ScreenType") + HtmlInterface("ScrnColorMap") + HtmlInterface("ScrnCursor") + HtmlInterface("ScrnFont") + HtmlInterface("ScrnPaintOp") + HtmlInterface("ScrnPixmap") + HtmlInterface("Trestle") + HtmlInterface("TrestleComm") + HtmlInterface("VBT") + HtmlInterface("VBTClass") + HtmlInterface("VBTTuning") + Index: m3/pm3/graphics/gr-libs/ui/test/Argus/src/m3makefile diff -c m3/pm3/graphics/gr-libs/ui/test/Argus/src/m3makefile:1.2 m3/pm3/graphics/gr-libs/ui/test/Argus/src/m3makefile:1.3 *** m3/pm3/graphics/gr-libs/ui/test/Argus/src/m3makefile:1.2 Tue Jan 28 12:24:40 1997 --- m3/pm3/graphics/gr-libs/ui/test/Argus/src/m3makefile Tue Feb 10 22:48:06 1998 *************** *** 5,12 **** /* Last modified on Wed May 19 16:34:59 PDT 1993 by msm */ /* modified on Fri Apr 30-ip5:58:21 PDT 1993 by mjordan */ ! override ("ui", "../../../..") ! override ("EyesVBT", "../..") import("ui") import("EyesVBT") --- 5,12 ---- /* Last modified on Wed May 19 16:34:59 PDT 1993 by msm */ /* modified on Fri Apr 30-ip5:58:21 PDT 1993 by mjordan */ ! override ("ui", path_of(".." & SL & ".." & SL & ".." & SL "..")) ! override ("EyesVBT", path_of(".." & SL "..")) import("ui") import("EyesVBT") Index: m3/pm3/graphics/gr-libs/ui/test/BadBricks/src/m3makefile diff -c m3/pm3/graphics/gr-libs/ui/test/BadBricks/src/m3makefile:1.2 m3/pm3/graphics/gr-libs/ui/test/BadBricks/src/m3makefile:1.3 *** m3/pm3/graphics/gr-libs/ui/test/BadBricks/src/m3makefile:1.2 Tue Jan 28 12:24:40 1997 --- m3/pm3/graphics/gr-libs/ui/test/BadBricks/src/m3makefile Tue Feb 10 22:48:10 1998 *************** *** 5,11 **** /* Last modified on Wed May 19 16:33:44 PDT 1993 by msm */ /* modified on Fri Apr 30-ip4:31:43 PDT 1993 by mjordan */ ! override ("ui", "../../../..") import("ui") implementation("BadBricks") --- 5,11 ---- /* Last modified on Wed May 19 16:33:44 PDT 1993 by msm */ /* modified on Fri Apr 30-ip4:31:43 PDT 1993 by mjordan */ ! override ("ui", path_of(".." & SL ".." & SL & ".." & SL & "..")) import("ui") implementation("BadBricks") Index: m3/pm3/graphics/gr-libs/ui/test/ButtonTest/src/m3makefile diff -c m3/pm3/graphics/gr-libs/ui/test/ButtonTest/src/m3makefile:1.2 m3/pm3/graphics/gr-libs/ui/test/ButtonTest/src/m3makefile:1.3 *** m3/pm3/graphics/gr-libs/ui/test/ButtonTest/src/m3makefile:1.2 Tue Jan 28 12:24:40 1997 --- m3/pm3/graphics/gr-libs/ui/test/ButtonTest/src/m3makefile Tue Feb 10 22:48:17 1998 *************** *** 5,11 **** /* Last modified on Wed May 19 16:34:34 PDT 1993 by msm */ /* modified on Fri Apr 30-ip5:11:00 PDT 1993 by mjordan */ ! override ("ui", "../../../..") import("ui") implementation("ButtonTest") --- 5,11 ---- /* Last modified on Wed May 19 16:34:34 PDT 1993 by msm */ /* modified on Fri Apr 30-ip5:11:00 PDT 1993 by mjordan */ ! override ("ui", path_of(".." & SL & ".." & SL & ".." & SL & "..")) import("ui") implementation("ButtonTest") Index: m3/pm3/graphics/gr-libs/ui/test/Cards/src/m3makefile diff -c m3/pm3/graphics/gr-libs/ui/test/Cards/src/m3makefile:1.2 m3/pm3/graphics/gr-libs/ui/test/Cards/src/m3makefile:1.3 *** m3/pm3/graphics/gr-libs/ui/test/Cards/src/m3makefile:1.2 Tue Jan 28 12:24:41 1997 --- m3/pm3/graphics/gr-libs/ui/test/Cards/src/m3makefile Tue Feb 10 22:48:22 1998 *************** *** 5,12 **** /* Last modified on Thu May 20 12:28:45 PDT 1993 by msm */ /* modified on Fri Apr 30-ip5:46:52 PDT 1993 by mjordan */ ! override ("ui", "../../../..") ! override ("EyesVBT", "../..") import("ui") import("EyesVBT") --- 5,12 ---- /* Last modified on Thu May 20 12:28:45 PDT 1993 by msm */ /* modified on Fri Apr 30-ip5:46:52 PDT 1993 by mjordan */ ! override ("ui", path_of(".." & SL & ".." & SL & ".." & SL & "..")) ! override ("EyesVBT", path_of(".." & SL & "..")) import("ui") import("EyesVBT") Index: m3/pm3/graphics/gr-libs/ui/test/ColorMonster/src/m3makefile diff -c m3/pm3/graphics/gr-libs/ui/test/ColorMonster/src/m3makefile:1.2 m3/pm3/graphics/gr-libs/ui/test/ColorMonster/src/m3makefile:1.3 *** m3/pm3/graphics/gr-libs/ui/test/ColorMonster/src/m3makefile:1.2 Tue Jan 28 12:24:41 1997 --- m3/pm3/graphics/gr-libs/ui/test/ColorMonster/src/m3makefile Tue Feb 10 22:48:26 1998 *************** *** 5,11 **** /* Last modified on Thu May 20 12:28:41 PDT 1993 by msm */ /* modified on Fri Apr 30-ip4:19:01 PDT 1993 by mjordan */ ! override("ui", "../../../..") import("ui") implementation("ColorMonster") --- 5,11 ---- /* Last modified on Thu May 20 12:28:41 PDT 1993 by msm */ /* modified on Fri Apr 30-ip4:19:01 PDT 1993 by mjordan */ ! override("ui", path_of(".." & SL & ".." & SL & ".." & SL & "..")) import("ui") implementation("ColorMonster") Index: m3/pm3/graphics/gr-libs/ui/test/Draw/src/m3makefile diff -c m3/pm3/graphics/gr-libs/ui/test/Draw/src/m3makefile:1.2 m3/pm3/graphics/gr-libs/ui/test/Draw/src/m3makefile:1.3 *** m3/pm3/graphics/gr-libs/ui/test/Draw/src/m3makefile:1.2 Tue Jan 28 12:24:41 1997 --- m3/pm3/graphics/gr-libs/ui/test/Draw/src/m3makefile Tue Feb 10 22:48:30 1998 *************** *** 5,11 **** /* Last modified on Thu May 20 12:09:23 PDT 1993 by msm */ /* modified on Fri Apr 30-ip5:53:01 PDT 1993 by mjordan */ ! override("ui", "../../../..") import("ui") implementation("Draw") --- 5,11 ---- /* Last modified on Thu May 20 12:09:23 PDT 1993 by msm */ /* modified on Fri Apr 30-ip5:53:01 PDT 1993 by mjordan */ ! override("ui", path_of(".." & SL & ".." & SL & ".." & SL & "..")) import("ui") implementation("Draw") Index: m3/pm3/graphics/gr-libs/ui/test/EyesVBT/src/m3makefile diff -c m3/pm3/graphics/gr-libs/ui/test/EyesVBT/src/m3makefile:1.2 m3/pm3/graphics/gr-libs/ui/test/EyesVBT/src/m3makefile:1.3 *** m3/pm3/graphics/gr-libs/ui/test/EyesVBT/src/m3makefile:1.2 Tue Jan 28 12:24:41 1997 --- m3/pm3/graphics/gr-libs/ui/test/EyesVBT/src/m3makefile Tue Feb 10 22:48:34 1998 *************** *** 5,11 **** /* Last modified on Thu May 20 12:06:03 PDT 1993 by msm */ /* modified on Fri Apr 30-ip5:41:35 PDT 1993 by mjordan */ ! override ("ui", "../../../..") import("ui") Module("EyesVBT") --- 5,11 ---- /* Last modified on Thu May 20 12:06:03 PDT 1993 by msm */ /* modified on Fri Apr 30-ip5:41:35 PDT 1993 by mjordan */ ! override ("ui", path_of(".." & SL & ".." & SL & ".." & SL & "..")) import("ui") Module("EyesVBT") Index: m3/pm3/graphics/gr-libs/ui/test/Hello/src/m3makefile diff -c m3/pm3/graphics/gr-libs/ui/test/Hello/src/m3makefile:1.2 m3/pm3/graphics/gr-libs/ui/test/Hello/src/m3makefile:1.3 *** m3/pm3/graphics/gr-libs/ui/test/Hello/src/m3makefile:1.2 Tue Jan 28 12:24:41 1997 --- m3/pm3/graphics/gr-libs/ui/test/Hello/src/m3makefile Tue Feb 10 22:48:37 1998 *************** *** 5,11 **** /* Last modified on Thu May 20 12:11:01 PDT 1993 by msm */ /* modified on Fri Apr 30-ip4:14:24 PDT 1993 by mjordan */ ! override("ui", "../../../..") import("ui") implementation("Hello") --- 5,11 ---- /* Last modified on Thu May 20 12:11:01 PDT 1993 by msm */ /* modified on Fri Apr 30-ip4:14:24 PDT 1993 by mjordan */ ! override("ui", path_of(".." & SL & ".." & SL & ".." & SL & "..")) import("ui") implementation("Hello") Index: m3/pm3/graphics/gr-libs/ui/test/Monster/src/m3makefile diff -c m3/pm3/graphics/gr-libs/ui/test/Monster/src/m3makefile:1.2 m3/pm3/graphics/gr-libs/ui/test/Monster/src/m3makefile:1.3 *** m3/pm3/graphics/gr-libs/ui/test/Monster/src/m3makefile:1.2 Tue Jan 28 12:24:41 1997 --- m3/pm3/graphics/gr-libs/ui/test/Monster/src/m3makefile Tue Feb 10 22:48:40 1998 *************** *** 5,11 **** /* Last modified on Thu May 20 12:11:45 PDT 1993 by msm */ /* modified on Fri Apr 30-ip5:27:25 PDT 1993 by mjordan */ ! override("ui", "../../../..") import("ui") implementation("Monster") --- 5,11 ---- /* Last modified on Thu May 20 12:11:45 PDT 1993 by msm */ /* modified on Fri Apr 30-ip5:27:25 PDT 1993 by mjordan */ ! override("ui", path_of(".." & SL & ".." & SL & ".." & SL & "..")) import("ui") implementation("Monster") Index: m3/pm3/graphics/gr-libs/ui/test/Sketch2/src/m3makefile diff -c m3/pm3/graphics/gr-libs/ui/test/Sketch2/src/m3makefile:1.2 m3/pm3/graphics/gr-libs/ui/test/Sketch2/src/m3makefile:1.3 *** m3/pm3/graphics/gr-libs/ui/test/Sketch2/src/m3makefile:1.2 Tue Jan 28 12:24:42 1997 --- m3/pm3/graphics/gr-libs/ui/test/Sketch2/src/m3makefile Tue Feb 10 22:48:44 1998 *************** *** 5,11 **** /* Last modified on Thu May 20 12:12:22 PDT 1993 by msm */ /* modified on Fri Apr 30-ip5:34:52 PDT 1993 by mjordan */ ! override("ui", "../../../..") import("ui") implementation("Sketch2") --- 5,11 ---- /* Last modified on Thu May 20 12:12:22 PDT 1993 by msm */ /* modified on Fri Apr 30-ip5:34:52 PDT 1993 by mjordan */ ! override("ui", path_of(".." & SL & ".." & SL & ".." & SL & "..")) import("ui") implementation("Sketch2") Index: m3/pm3/graphics/gr-libs/ui/test/StarAnim/src/m3makefile diff -c m3/pm3/graphics/gr-libs/ui/test/StarAnim/src/m3makefile:1.1.1.1 m3/pm3/graphics/gr-libs/ui/test/StarAnim/src/m3makefile:1.2 *** m3/pm3/graphics/gr-libs/ui/test/StarAnim/src/m3makefile:1.1.1.1 Thu Jan 16 16:31:48 1997 --- m3/pm3/graphics/gr-libs/ui/test/StarAnim/src/m3makefile Tue Feb 10 22:48:48 1998 *************** *** 4,10 **** /* Last modified on Mon Jan 15 13:15:27 PST 1996 by heydon */ ! override ("ui", "../../../..") import ("libm3") import ("ui") --- 4,10 ---- /* Last modified on Mon Jan 15 13:15:27 PST 1996 by heydon */ ! override ("ui", path_of(".." & SL & ".." & SL & ".." & SL & "..")) import ("libm3") import ("ui") Index: m3/pm3/graphics/gr-libs/ui/test/Track/src/m3makefile diff -c m3/pm3/graphics/gr-libs/ui/test/Track/src/m3makefile:1.2 m3/pm3/graphics/gr-libs/ui/test/Track/src/m3makefile:1.3 *** m3/pm3/graphics/gr-libs/ui/test/Track/src/m3makefile:1.2 Tue Jan 28 12:24:42 1997 --- m3/pm3/graphics/gr-libs/ui/test/Track/src/m3makefile Tue Feb 10 22:48:52 1998 *************** *** 5,11 **** /* Last modified on Thu May 20 12:12:41 PDT 1993 by msm */ /* modified on Fri Apr 30-ip5:08:06 PDT 1993 by mjordan */ ! override("ui", "../../../..") import("ui") implementation("Track") --- 5,11 ---- /* Last modified on Thu May 20 12:12:41 PDT 1993 by msm */ /* modified on Fri Apr 30-ip5:08:06 PDT 1993 by mjordan */ ! override("ui", path_of(".." & SL & ".." & SL & ".." & SL & "..")) import("ui") implementation("Track") Index: m3/pm3/graphics/gr-libs/ui/test/TypeInTest/src/m3makefile diff -c m3/pm3/graphics/gr-libs/ui/test/TypeInTest/src/m3makefile:1.2 m3/pm3/graphics/gr-libs/ui/test/TypeInTest/src/m3makefile:1.3 *** m3/pm3/graphics/gr-libs/ui/test/TypeInTest/src/m3makefile:1.2 Tue Jan 28 12:24:42 1997 --- m3/pm3/graphics/gr-libs/ui/test/TypeInTest/src/m3makefile Tue Feb 10 22:48:56 1998 *************** *** 5,11 **** /* Last modified on Thu May 20 12:13:08 PDT 1993 by msm */ /* modified on Fri Apr 30-ip5:22:18 PDT 1993 by mjordan */ ! override("ui", "../../../..") import("ui") implementation("TypeInTest") --- 5,11 ---- /* Last modified on Thu May 20 12:13:08 PDT 1993 by msm */ /* modified on Fri Apr 30-ip5:22:18 PDT 1993 by mjordan */ ! override("ui", path_of(".." & SL & ".." & SL & ".." & SL & "..")) import("ui") implementation("TypeInTest") Index: m3/pm3/graphics/lecternpkg/lecternclient/src/POSIX/m3makefile diff -c m3/pm3/graphics/lecternpkg/lecternclient/src/POSIX/m3makefile:1.4 m3/pm3/graphics/lecternpkg/lecternclient/src/POSIX/m3makefile:1.5 *** m3/pm3/graphics/lecternpkg/lecternclient/src/POSIX/m3makefile:1.4 Thu Dec 18 13:39:24 1997 --- m3/pm3/graphics/lecternpkg/lecternclient/src/POSIX/m3makefile Tue Feb 10 22:49:02 1998 *************** *** 23,28 **** deriveds(pgm, [NAMING_CONVENTIONS[17]]) end ! setCommands("","") simple_c_program("LecternClient") BindExport("LecternClient") --- 23,28 ---- deriveds(pgm, [NAMING_CONVENTIONS[17]]) end ! setCommands() simple_c_program("LecternClient") BindExport("LecternClient") Index: m3/pm3/graphics/lecternpkg/ocr/src/DS3100/m3makefile diff -c m3/pm3/graphics/lecternpkg/ocr/src/DS3100/m3makefile:1.2 m3/pm3/graphics/lecternpkg/ocr/src/DS3100/m3makefile:1.3 *** m3/pm3/graphics/lecternpkg/ocr/src/DS3100/m3makefile:1.2 Tue Jan 28 12:24:20 1997 --- m3/pm3/graphics/lecternpkg/ocr/src/DS3100/m3makefile Tue Feb 10 22:49:05 1998 *************** *** 6,13 **** import("libm3") - /* m3_option("-keep") */ - interface("Chf") interface("Img") interface("Irs") --- 6,11 ---- Index: m3/pm3/graphics/lecternpkg/src/index.html diff -c /dev/null m3/pm3/graphics/lecternpkg/src/index.html:1.1.1.1 *** /dev/null Tue Feb 10 23:29:01 1998 --- m3/pm3/graphics/lecternpkg/src/index.html Sat Jan 31 14:47:10 1998 *************** *** 0 **** --- 1,46 ---- + +Lectern bitmap documents viewer + + ++ Michel Dagenais + Michel Dagenais, GNU General Public License, 1998 + + michel.dagenais@polymtl.ca+
+ Ecole Polytechnique
+ C.P. 6079, Succ. Centre-Ville
+ Montreal, Quebec, H3C 3A7 + 18 January 1998 + documentation + bitmap + ocr + viewer + index +Lectern bitmap documents viewer
+ +++ +The lectern system may be used to view and index documents only available + in geometrical form (Postscript or bitmap). +
-
+
- lectern
- + Browse lectern documents. +
- buildlectern
- + Build lectern documents from Postscript or bitmap files. +
- editlectern
- + Edit the annotations associated with a lectern document. +
- lecternclient
- + Send a command to the lectern program. +
- lecterndoc
- + Internal format for lectern documents. +
- lecterntohtml
- + Create HTML indexes for directories containing lectern documents. +
- + Interface to optical recognition software for retrieving text + from a bitmap file. +
A Simple Distributed Graphics Editor + + ++ Michel Dagenais + Michel Dagenais, GNU General Public License, 1998 + + michel.dagenais@polymtl.ca+
+ Ecole Polytechnique
+ C.P. 6079, Succ. Centre-Ville
+ Montreal, Quebec, H3C 3A7 + 18 January 1998 + distributed + persistent + graphics + editor +A Simple Distributed Graphics Editor
+ +++ +This simple shared graphics editor is a good example of + network and stable objects usage. It enables simultaneous editing + of a board by several users. +
-
+
- board
- + Base library used by board server and client. +
- boardclient
- + Client graphical editor, exchanging update information with the + connected board server. +
- boardserver
- + Board server exchanging update information with connected clients, + and managing the storage of boards. +
- calendar
- + A simple shared calendar application based on the board library + and boardserver. +
Graphics Libraries and Applications + + ++ Michel Dagenais + Michel Dagenais, GNU General Public License, 1998 + + michel.dagenais@polymtl.ca+
+ Ecole Polytechnique
+ C.P. 6079, Succ. Centre-Ville
+ Montreal, Quebec, H3C 3A7 + 18 January 1998 + graphics + wide audience +Graphics Libraries and Applications
+ +++ +2D and 3D graphics libraries and applications. +
+ +
+ +
-
+
- graphics libs +
- General purpose graphics libraries. +
- FormsVBT
- + Graphical user interface description language and interface builder. +
- animation
- + 2D and 3D animation libraries and applications. +
- games
- + Sample demonstration games. +
- lectern
- + The lectern system for browsing documents available in + geometric form (Postscript or bitmap). +
- Shared board
- + A simple distributed graphics editor. +
- sil
- + A native Win32 graphics application. +
- display postscript
- + A library for accessing Display Postcript functions, for supported + platforms. +
Acknowledgments + + +Acknowledgements
+ +PM3
+ +Jerome Collin implemented the fast + integrated backend for Linux ELF with + position independent code and debugging support. + +
Louis-Dominique Dubeau reorganized the compiler and templates to + obtained a simplified single process m3build-m3-quake. + +
+ Tony Hosking, Purdue University, (hosking@cs.purdue.edu), ported the + incremental collector and stack based exceptions to Solaris. He is + working on Persistent Modula-3. + +
Blair McIntyre brought several bug fixes and a new version of the + Pickle library (Blair MacIntyre). + +
Richard Watts ported SRC Modula-3 to NT386 using the gnu-win32 linker, + obviating the need for the MS Visual C++ compiler/linker. + +
Peter Klein (pk@i3.informatik.rwth-aachen.de) + produced a Modula-3 version of the TXL program parsing and + analysis tool, and a Modula-2 to Modula-3 converter. + +
John Podstra developed CVSsup. + +
The M3COCO parser generator was contributed by Ollie Stephens. + +
SRC Modula-3
+ +This section was written at DEC SRC and we presumably is + Bill Kalsow (Critical Mass, kalsow@cmass.com), Eric Muller, + Allan Heydon (heydon@src.dec.com), and + Marc Najork (najork@src.dec.com). + +
Many people contributed to SRC Modula-3, and we would like to thank them. + Below is a partial list of the contributors. + +
+ We use the garbage collector developed by Joel Bartlett + (DEC-WRL). It has been modified to support incremental and + generational collection by John DeTreville + (jdd@src.dec.com, DEC SRC). + +
+ John Dillon (DEC SRC) provided the original C version of thread + switching. + +
+ Mark R. Brown and Greg Nelson (DEC SRC, gnelson@src.dec.com) + designed the readers and writers interfaces. + +
+ Jorge Stolfi (University of Campinas, Brazil, + stolfi@dcc.unicamp.br), + and Stephen Harrison (DEC-WSE) + were very patient alpha-testers. They gave us invaluable bug reports + and also translated some DEC SRC Modula-2+ modules to Modula-3. + +
+ J'erome Chailloux (ILOG) developed the X interfaces while + visiting DEC SRC. We also had numerous discussions about the evolution + of SRC Modula-3. + +
+ The ``gatekeepers'' (DEC-WRL), in particular Paul Vixie, helped with + the distribution of SRC Modula-3. + +
+ David Goldberg (XEROX PARC) ported SRC Modula-3 to the SPARC + machines. + +
+ Ray Lischner ported the system to the Apollo machines. + +
+ Richard Orgass (IBM Rochester) and Roger Hoover (IBM) + ported the system to the IBM machines. + +
+ Piet van Oostrum (Utrecht University) ported the system to the + HP series 9000/300 computers running HP/UX 7.0. + +
+ Pat Lashley (KLA Instruments) contributed the lexer for pps. + +
+ R'egis Crelier (ETH) designed and implemented the pickles + modules while he was a summer intern at SRC. + +
+ Mick Jordan (Sun, mick.jordan@eng.sun.com) provided the AST + toolkit and helped with m3build. + +
+ Stephen Harrison (DEC SRC) wrote the quake interpreter. + +
+ Norman Ramsey (Princeton University) has pushed the system into + obscure corners and found many bugs there. + +
+ R.J. Stroud and Dick Snow (University of Newcastle upon + Tyne) provided the Encore Multimax port. + +
+ Dave Nichols (Xerox PARC) fixed and improved the pretty printer. + +
+ Greg Nelson and Mark Manasse (DEC SRC, msm@src.dec.com) + designed and implemented the Trestle window system. + +
+ Sam Harbison (Tartan, Texas Instruments, harbison@micro.ti.com) + contributed the FieldList interface and is the author of a popular + book on Modula-3. + +
+ Steven Pemberton (CWI) wrote the enquire program and made + it available to the community. + +
+ The vbtkit software has been designed and implemented by a large + number of people at SRC: Andrew Birrell + (birrell@src.dec.com, also involved in the Network objects), + Ken Brooks, + Marc H. Brown (mhb@src.dec.com), + Mark R. Brown, Pat Chan, + Luca Cardelli (luca@src.dec.com, also behind Obliq and several + other packages), John DeTreville, Steve Glassman, + Mark Manasse, Jim Meehan + (jmeehan@mv.us.adobe.com), Greg Nelson, + Jorge Stolfi, Mary-Claire van Leunen. + +
+ FormsVBT is due to Jim Meehan and Marc H. Brown (DEC SRC). + +
+ Peter Klein (RWTH Aachen) contributed a tool to help convert + Modula-2 to Modula-3 programs. He is also responsible for + establishing the first FTP mirror site. + +
+ James J. Walker (GTE Laboratories) ported the system to the + HPPA machines. + +
+ Thomas Brupbacher (ETH Zuerich) ported the system to the + SUN386 machines. + +
+ Dennis Brueni (brueni@csgrad.cs.vt.edu) ported the system + to the OKI machines. + +
+ Dave Detlefs (DEC SRC) wrote the Modula-3 mode for gnuemacs. + David Goldberg (XEROC PARC) wrote the m3tags program. + +
+ Jim Horning (horning@intertrust.com, horning@acm.org, + http://www.intertrust.com/star/horning/), + Paul McJones (DEC SRC, mcjones@src.dec.com) + and Greg Nelson (DEC SRC) + edited, designed, polished and in some cases implemented the + "Interface police" + interfaces. + +
+ Allan Heydon (DEC SRC, heydon@src.dec.com) + implemented the Fmt and Lex + interfaces and contributed the Web description of Modula-3 linking. + +
+ Michel Dagenais (Ecole Polytechnique de Montreal, + michel.dagenais@polymtl.ca) + ported the system to Linux. + +
+ Olaf Wagner ported the system to pcs running FreeBSD 1.1.5 and + FreeBSD 2.0. + +
+ Eric Veach (Stanford) ported the system to MIPS boxes running Irix 5.2. + +
+ Michael Isard (DEC SRC) implemented the Intel x86 code generator + and Windows/NT dynamic loader. + +
+ Carsten Weich (Institut fuer Informatik Universitaet Klagenfurt, + weich@ifi.uni-klu.ac.at) + implemented the stable objects package and the associated stub generator. + +
+ Chuck Thacker (DEC SRC) wrote the original version of Sil. + Bill Kalsow converted it to Modula-3. + +
+ Thanks also to all the people who used SRC Modula-3 and reported bugs. + +
+ The various ports would have been impossible without the work of a + number of people, who kindly made their modifications available. + However, most of the bugs you may find in these ports were introduced + during the final integration of these modifications and we are to be + blamed for them. + +
Miscellaneous
+ ++ Susan Owicki (Stanford University, owicki@mojave.stanford.edu), + and Edward Wobber, (DEC SRC, wobber@src.dec.com), Network objects. + +
+ Laszlo Boeszoermenyi, Universitaet Klagenfurt, Austria, + (laszlo@ifi.uni-klu.ac.at), PC port (m3pc), Programming in style book. + +
+ Klaus Preschern, Universitaet Klagenfurt, Austria, + (preschern@ifi.uni-klu.ac.at), PC port (m3pc). + +
+ Robert Ayers, Adobe, (ayers@Mv.Us.Adobe.Com), the Display Postscript to + Modula-3 interface. + +
+ David N. Gray, Lucid Inc., Menlo Park, (gray@Lucid.Com), + interface between the Lucid environment and the M3 compiler. + +
Rick Hudson, University of Massachusetts at Amherst, + (hudson@cs.umass.edu), Lex and Yacc files for parsing Modula-3. + +
+ Bert Laverman, Groningen University, (laverman@cs.rug.nl), HPPA support. + +
Roland Mittermeir, Universitaet Klagenfurt, Austria, + (mittermeir@ifi.uni-klu.ac.at), Programming in style book. + +
+ Eliot Moss, University Of Massachusetts At Amherst, (moss@Cs.Umass.Edu), + Modula-3 garbage collection and persistency. + +
+ Farshad Nayeri, Critical Mass, (nayeri@cmass.com), + comercial Modula-3 support. + + + Index: m3/pm3/intro/src/bib.html diff -c /dev/null m3/pm3/intro/src/bib.html:1.3 *** /dev/null Tue Feb 10 23:29:04 1998 --- m3/pm3/intro/src/bib.html Tue Feb 10 22:41:03 1998 *************** *** 0 **** --- 1,786 ---- + +
+Modula-3: Annotated Bibliography + + +Modula-3 Annotated Bibliography
+ ++ Copyright (C) 1994, Digital Equipment Corporation + +
Here is a complete list of books, papers and articles related to + Modula-3. A more concise bibliography + organized by topic and containing pointers back to this page is also + available. An important fraction of this documentation is already + included in the individual packages to which they apply. + +
Please send comments and/or additions to + m3-request@src.dec.com. + +
-
+
+
- Martin Abadi,
+ Baby Modula-3 and a Theory of Object,
+ Research Report 95,
+ Systems Research Center, Digital Equipment Corporation,
+ Palo Alto,
+ February, 1993.
+
+ This report describes a theoretical treatment of the semantics of objects. +
+ It's available via anonymous FTP from gatekeeper.dec.com in + + pub/DEC/SRC/research-reports/SRC-095.ps.Z. + +
- Joel F. Bartlett,
+ Compacting Garbage Collection with Ambiguous Roots,
+ Research Report 88/2,
+ Western Research Laboratory, Digital Equipment Corporation,
+ Palo Alto,
+ February, 1988.
+
+ This report describes an algorithm used as the basis for SRC Modula-3 + garbage collector. +
+ It's available on paper, by sending a mail to + WRL-Techreports@decwrl.dec.com (send help as the subject). + +
- A. D. Birrell, J. V. Guttag,
+ J. J. Horning, R. Levin,
+ Synchronization Primitives for a Multiprocessor: A Formal Specification,
+ Research Report 20,
+ Systems Research Center, Digital Equipment Corporation,
+ Palo Alto,
+ August, 1987.
+
+ It's available via anonymous FTP from gatekeeper.dec.com in + + pub/DEC/SRC/research-reports/SRC-020.ps.Z. A revised + version of this paper also appears as Chapter 5 of Systems Programming with Modula-3. + +
- Andrew D. Birrell,
+ An Introduction to Programming with Threads,
+ Research Report 35,
+ Systems Research Center, Digital Equipment Corporation,
+ Palo Alto,
+ January, 1989.
+
+ It's available via anonymous FTP from gatekeeper.dec.com in + + pub/DEC/SRC/research-reports/SRC-035.ps.Z. A revised + version also appears as Chapter 4 of Systems + Programming with Modula-3. + +
- Andrew Birrell, David Evers, Greg Nelson, Susan
+ Owicki, Edward Wobber,
+ Distributed Garbage Collection for Network Objects,
+ Research Report 116,
+ Systems Research Center, Digital Equipment Corporation,
+ Palo Alto,
+ December, 1993.
+
+ This report describes a fault-tolerant and efficient garbage + collection algorithm for distributed systems. It is the algorithm used + to garbage collect Network Objects. +
+ It's available via anonymous FTP from gatekeeper.dec.com in + + pub/DEC/SRC/research-reports/SRC-116.ps.Z. + +
- Andrew Birrell, Greg Nelson,
+ Susan Owicki, Edward Wobber,
+ Network Objects,
+ Research Report 115,
+ Systems Research Center, Digital Equipment Corporation,
+ Palo Alto,
+ February, 1994.
+
+ This report describes the design and implementation of a network + objects system, which allows you to write programs that communicate + over a network, while hiding the messy details of network programming. + Network objects provide functionality similar to remote procedure call (RPC), + but they are more general and easier to use. The system is implemented + in Modula-3. +
+ It's available via anonymous FTP from gatekeeper.dec.com in + + pub/DEC/SRC/research-reports/SRC-115.ps.Z. + +
- Graham M. Birtwistle, Ole-Johan Dahl, Bjorn
+ Myhrhaug, and Kristen Nygaard,
+ Simula Begin,
+ Auerbach,
+ Philadelphia PA, 1973.
+
+ +
- Laszlo Boeszoermenyi, + A Comparison of Modula-3 and Oberon-2 (extended version), + Structured Programming, + Springer-Verlag, + 1993. + Pgs 15-22. + +
- Laszlo Boeszoermenyi and Carsten Weich,
+ Programming with Modula-3: An Introduction to Programming with
+ Style,
+ Springer-Verlag,
+ ISBN 3-540-57911-7,
+ 1995. 577 pgs, including index.
+
+ This book is in German, but it is in the process of being translated + to English. It is an introductory programming text that uses Modula-3 + for its examples. The authors say, "The main concern of the book is to + give a clean and comprehensive introduction to programming for + beginners of a computer science study. We start with more traditional + programming concepts and move toward advanced topics such as + object-oriented programming, parallel & concurrent programming, + exception handling, and persistent data techniques. The book also + presents a large number of complete examples written in Modula-3." + +
- Laszlo Boeszoermenyi and Carsten Weich,
+ Modula-3
+ in Academia: University of Klagenfurt, Austria,
+ Threads: A Modula-3 Newsletter,
+ Issue 1,
+ Fall 1995.
+
+ This article describes the teaching and research efforts centered + around Modula-3 at the University of Klagenfurt in Austria. + +
- Gilad Bracha and William Cook,
+ Mixin-based Inheritance,
+ Proceedings of the Conference on Object-Oriented
+ Programming: Systems, Languages, and Applications;
+ European Conference on Object-Oriented Programming,
+ Pages 303-311,
+ October, 1990.
+
+ +
- Marc H. Brown and John Hershberger,
+ Color and Sound in Algorithm Animation,
+ Research Report 76a,
+ Systems Research Center, Digital Equipment Corporation,
+ Palo Alto,
+ August 30, 1991.
+
+ It's available via anonymous FTP from gatekeeper.dec.com in + + pub/DEC/SRC/research-reports/SRC-076a.ps.Z. +
+ +
- Marc H. Brown,
+ Zeus: A System for Algorithm Animation and Multi-View Editing,
+ Research Report 75,
+ Systems Research Center, Digital Equipment Corporation,
+ Palo Alto,
+ February 28, 1992.
+
+ It's available via anonymous FTP from gatekeeper.dec.com in + + pub/DEC/SRC/research-reports/SRC-075.ps.Z. Also in + Visual Languages '91, October 1991. +
+ +
- Marc H. Brown,
+ The 1992 SRC Algorithm Animation Festival,
+ Research Report 98,
+ Systems Research Center, Digital Equipment Corporation,
+ Palo Alto,
+ March 27, 1993.
+
+ It's available via anonymous FTP from gatekeeper.dec.com in + + pub/DEC/SRC/research-reports/SRC-098.ps.Z. +
+ +
- Marc H. Brown,
+ The 1993 SRC Algorithm Animation Festival,
+ Research Report 126,
+ Systems Research Center, Digital Equipment Corporation,
+ Palo Alto,
+ July 29, 1994.
+
+ It's available via anonymous FTP from gatekeeper.dec.com in + + pub/DEC/SRC/research-reports/SRC-126.ps.Z. +
+ +
- Marc H. Brown and James R. Meehan (editors),
+ VBTkit Reference Manual: A toolkit for Trestle,
+ Systems Research Center, Digital Equipment Corporation,
+ Palo Alto.
+
+ This report is the working definition of the VBTkit toolkit. VBTkit + is a collection of widgets for building graphical user interfaces in + Modula-3. See the FormsVBT Reference Manual + below, which describes a system for easily composing these widgets. +
+ It's available in the vbtkit archive of the SRC Modula-3 + distribution. A draft version is available via anonymous FTP from + gatekeeper.dec.com in + pub/DEC/Modula-3/contrib/vbtkit.25Mar93.ps.Z. +
+ +
- Marc H. Brown and James R. Meehan,
+ The FormsVBT Reference Manual,
+ Systems Research Center, Digital Equipment Corporation,
+ Palo Alto.
+
+ This report is the working definition of the FormsVBT toolkit. + FormsVBT is a system for constructing graphical user interfaces + (GUI's) in Modula-3. +
+ It's available in the formsvbt archive of the SRC Modula-3 + distribution. A draft version is available + via anonymous FTP from gatekeeper.dec.com in + pub/DEC/Modula-3/contrib/formsvbt.25Mar93.ps.Z + and + + pub/DEC/Modula-3/contrib/formsvbt.AppC.26Mar93.ps.Z. +
+ +
- Mark R. Brown and Greg Nelson,
+ IO Streams: Abstract Types, Real Programs,
+ Research Report 53,
+ Systems Research Center, Digital Equipment Corporation,
+ Palo Alto,
+ November, 1989.
+
+ This report shows how to use objects in a real program. Also + defines the de facto standard input/output functions. These + interfaces give an especially good example of partially + opaque types. A revised version of this report also appears as Chapter + 6 of Systems Programming with Modula-3. +
+ +
- Luca Cardelli, James Donahue, Lucille
+ Glassman, Mick Jordan, Bill Kalsow, Greg Nelson,
+ Modula-3 Report,
+ Research Report 31,
+ Systems Research Center, Digital Equipment Corporation,
+ Palo Alto,
+ August 15, 1988.
+
+ The report contains the original definition of the language, + superseded by Research Report 52. +
+ +
- Luca Cardelli, James Donahue, Mick Jordan, Bill
+ Kalsow, Greg Nelson,
+ The Modula-3 Type System,
+ Conference Record of the Sixteenth Annual ACM
+ Symposium on Principles of Programming Languages (POPL),
+ Pages 202-212,
+ January 11-13, 1989.
+
+ +
- Luca Cardelli, James Donahue, Lucille
+ Glassman, Mick Jordan, Bill Kalsow, Greg Nelson,
+ Modula-3 Report (revised),
+ Research Report 52,
+ Systems Research Center, Digital Equipment Corporation,
+ Palo Alto,
+ November, 1989.
+
+ This report is the definition of the Modula-3 language. + It is now only available in hardcopy. The address for + orders is below. The complete language definition, + Chapter 2 of Systems Programming with + Modula-3, is also available + on-line. +
+ +
- Luca Cardelli, James Donahue, Lucille Glassman,
+ Mick Jordan, Bill Kalsow, Greg Nelson,
+ Modula-3 Language Definition,
+ Sigplan Notices
+ 27(8):15-42,
+ August 1992.
+
+ This article consists of Chapters 2 and 3 of SPwM3. + There is an on-line version. +
+ +
- Michel R. Dagenais,
+ Building Distributed OO Applications: Modula-3 Objects at Work,
+ Draft Version,
+ March 8, 1995.
+
+ A draft of a book describing "the latest object-oriented techniques for + developing large interactive distributed applications". The focus is on + the Modula-3 libraries and Network Objects, but the first two chapters + give an introduction to object-oriented programming in general, and + the object methodologies of C++ and Obliq in particular. +
+ +
- Luca Cardelli + Obliq: a lightweight embeddable language for network objects, + User's Manual, Systems Research Center, Digital Equipment Corp., 1994, + by FTP + +
- Amer Diwan,
+ The
+ Whole Program Optimizer,
+ Threads: A Modula-3 Newsletter,
+ Issue 1,
+ Fall 1995.
+
+ This article motivates and describes an optimizer for Modula-3 + programs based on whole-program analysis. An optimizer that looks at + an entire program can do better than one that uses only the + information imported when compiling a single module. Preliminary + results are promising: on benchmark programs, up to 50% of method + invocations can be converted to direct calls. The optimizer is itself + written in Modula-3. +
+ +
- Mary Fernandez,
+ Simple and Effective Link-time Optimization of Modula-3 Programs,
+ SIGPLAN '95,
+ Conference on Programming Language Design and Implementation (PLDI),
+ June, 1995,
+ pgs. 103-115.
+
+ This paper shows how the overhead introduced by Modula-3's opaque + types can be reduced at link time. The optimizations described in the + paper are shown to be effective: they reduce the total number of + instructions by up to 14% and convert as many as 79% of indirect calls + to direct calls. +
+ +
- Mary Fernandez,
+ A Retargetable,
+ Optimizing Linker,
+ PhD Thesis,
+ Department of Computer Science,
+ Princeton University,
+ January, 1996.
+
+ This thesis describes mld, a retargetable, optimizing linker, + for the MIPS, SPARC, and Intel 486 architectures. The linker optimizes + away some of the costs of late binding. In particular, mld's + optimizations permit efficient implementation of Modula-3's + module-encapsulation and data-abstraction features. The thesis + presents the results of applying mld's simple optimization + techniques to several Modula-3 programs and reports their execution + times on the MIPS and Intel 486 architectures. +
+ +
- Steve Freeman,
+ Partial Revelation and Modula-3,
+ Dr. Dobb's Journal,
+ 20(10):36-42,
+ October, 1995.
+
+ This article describes how Modula-3's partial revelations promote + encapsulation and code reuse. The article is one of five on + "object-oriented programming" contained in the same issue (the other + four languages are C++, Ada 95, S, and Cobol '97). +
+ +
- David Goldberg,
+ The Design of Floating-Point Data Types,
+ ACM Letters on Programming Languages and Systems (LOPLAS),
+ 1(2):138-151,
+ June 1992.
+
+ This article describes the Modula-3 treatment of floating-point values. +
+ +
- Markus K. Gröner, I. Utku Moral,
+ Concurrent
+ Breadth-First Search using Modula-3.
+
+ This page describes the authors' experience installing Modula-3 on a + PC and using the language to implement a concurrent breadth-first + search algorithm. The authors were trying to install + M3forDOS, an implementation of Modula-3 that runs + on DOS PC's. They found this installation to be quite + difficult. They eventually ended up using a version of + SRC + Modula-3 that had already been installed on a Unix box at their site. +
+ +
- Sam Harbison,
+ Modula-3,
+ Byte,
+ 15(12):385-392,
+ November, 1990.
+
+ This article is a survey of the Modula-3 language. It gives a brief + history of the language and describes the language's major features, + including modules, exceptions, objects, threads and other support for + concurrent programming, safety, and garbage collection. It also + discusses the basis for some of the more contentious language design + decisions. +
+ +
- Sam Harbison,
+ Safe Programming with Modula-3,
+ Dr. Dobb's Journal,
+ 17(10):88-96,
+ October, 1992.
+
+ This article is a survey of the Modula-3 language. +
+ +
- Samuel P. Harbison,
+ Modula-3,
+ Prentice Hall,
+ ISBN 0-13-596396-6,
+ 1992.
+
+ A complete Modula-3 textbook covering the full + language, with examples and exercises. Includes a + style manual and a user's guide for SRC Modula-3. +
+ The first edition of the book contains many typos. A + list + of errata is available on-line for anonymous FTP (in TeX, + compressed PostScript, or DVI format) from gatekeeper.dec.com + in the directory pub/DEC/Modula-3/errata/. +
+ +
- Ernst A. Heinz,
+ Modula-3*: An
+ efficiently compilable extension of Modula-3 for problem-oriented
+ explicitly parallel programming,
+ Proceedings of the Joint Symposium on Parallel Processing 1993,
+ Pages 269-276,
+ May 17-19, 1993,
+ Tokyo, Japan.
+
+ Available from i41s10.ira.uka.de [129.13.13.110] by anonymous ftp + in directory pub/m3s + as jspp93.ps + or jspp93.ps.gz. +
+ +
- Ernst A. Heinz,
+ Sequential and
+ parallel exception handling in Modula-3*: A unifying semantics
+ specification,
+ Advances in Modular Languages: Proceedings of the Joint Modular
+ Languages Conference,
+ P. Schulthess (editor),
+ Pages 31-49,
+ September 28-30, 1994,
+ Ulm, Germany.
+
+ Available from Universitatsverlag Ulm GmbH or from i41s10.ira.uka.de + [129.13.13.110] by anonymous ftp in directory pub/m3s + as jmlc94.ps + or jmlc94.ps.gz. +
+ +
- Robert Henderson and Benjamin Zorn,
+ A Comparison of Object-Oriented Programming in Four Modern Languages,
+ Technical Report CU-CS-641-93,
+ Department of Computer Science,
+ University of Colorado,
+ Boulder, Colorado,
+ 1993.
+
+ The paper evaluates Oberon, Modula-3, Sather, and Self in the context + of object-oriented programming. While each of these programming + languages provide support for classes with inheritance, dynamic + dispatch, code reuse, and information hiding, they do so in very + different ways and with varying levels of efficiency and simplicity. A + single application was coded in each language and the experience + gained forms the foundation on which the subjective critique is based. + By comparing the actual run-times of the various implementations it is + also possible to present an objective analysis of the efficiency of + the languages. Furthermore, by coding the application using both + explicit dynamic dispatch and static method binding, it is possible to + evaluate the cost of dynamic dispatch in each language. The + application was also coded in C++, thereby providing a well-known + baseline against which the execution times can be compared. +
+ +
- Allan Heydon and Greg Nelson,
+ The Juno-2 Constraint-Based Drawing Editor,
+ Research Report 131a,
+ Systems Research Center, Digital Equipment Corporation,
+ Palo Alto,
+ December, 1994.
+
+ This report describes Juno-2, a constraint-based drawing editor + implemented in Modula-3. For more information, see the + Juno-2 Home Page. +
+ It's available via anonymous FTP from gatekeeper.dec.com in + + pub/DEC/SRC/research-reports/SRC-131a.ps.Z. +
+ +
- Allan Heydon,
+ Implementing
+ Juno-2: The User Interface,
+ Threads: A Modula-3 Newsletter,
+ Issue 1,
+ Fall 1995.
+
+ Juno-2 is a + constraint-based drawing program. This article describes how Modula-3's + FormsVBT, VBTkit, and Trestle libraries were used to implement the + Juno-2 user interface. +
+ +
- C.A.R. Hoare,
+ Monitors: An operating system structuring concept,
+ Communications of the ACM,
+ 17(10),
+ October 1974.
+
+ +
- Jim Horning, Bill Kalsow, Paul McJones, Greg Nelson,
+ Some Useful Modula-3 Interfaces,
+ Research Report 113,
+ Systems Research Center, Digital Equipment Corporation,
+ Palo Alto,
+ December, 1993.
+
+ This report is a description of the SRC standard Modula-3 library interfaces. + It's an essential reference for every Modula-3 programmer! +
+ It's available via anonymous FTP from gatekeeper.dec.com in + + pub/DEC/SRC/research-reports/SRC-113.ps.Z. +
+ +
- Wilson C. Hsieh, Marc E. Fiuczynski,
+ Charles Garrett, Stefan Savage, David Becker, and Brian N. Bershad,
+ Language Support for Extensible Operating Systems,
+ November, 1996.
+
+ Describes the extensions made by the SPIN group at the University of + Washington to the Modula-3 language for use in their SPIN extensible + operating system. +
+ +
- Peter Klein,
+ Designing
+ Software with Modula-3,
+ Technical Report 94-16,
+ Department of Computer Science III,
+ Aachen University of Technology.
+
+ It's available via anonymous FTP from ftp.informatik.rwth-aachen.de + in /pub/reports/1994/94-16.ps.gz. +
+ +
- Butler W. Lampson and David D. Redell,
+ Experience with processes and monitors in Mesa,
+ Communications of the ACM,
+ 23(2),
+ February 1980.
+
+ +
- Mark S. Manasse and Greg Nelson,
+ Trestle Reference Manual,
+ Research Report 68,
+ Systems Research Center, Digital Equipment Corporation,
+ Palo Alto,
+ December, 1991.
+
+ This report is the working definition of the Trestle toolkit for + doing graphics in Modula-3. +
+ +
- Mark S. Manasse and Greg Nelson,
+ Trestle Tutorial,
+ Research Report 69,
+ Systems Research Center, Digital Equipment Corporation,
+ Palo Alto,
+ May, 1992.
+
+ This report is a tutorial introduction to the Trestle toolkit. +
+ +
- Paul McJones and Garret Swart,
+ Evolving the UNIX system interface to support multi-threaded programs,
+ Proceedings of the Winter 1989 USENIX Conference,
+ February 1989.
+
+ +
- Farshad Nayeri,
+ SRC Modula-3: An Elegant, Free, Open,
+ Mature, High-Quality, Clean & Modest Programming Language, System,
+ Library & Tool for Building Robust, Large-Scale, Multi-Threaded &
+ Distributed Programs,
+ March, 1996.
+
+ A happy user promotes SRC Modula-3. The article begins: +
+
+ +Despite its length and buzzword density, the subtitle above is one + the shortest phrases that characterize the virtues of SRC Modula-3. + The language designers' stated goal of "consolidation, not innovation" + is a modest understatement for their wise, elegant, and inventive + combination of features that are greatly needed by the modern + programmer. +
- Farshad Nayeri,
+ "Net Balance: A Network Objects Example",
+ March, 1996.
+
+ The sources of a simple client and server that use network objects. A + gzipped tar archive of the sources and web page is also available. +
+ +
- Greg Nelson (editor),
+ System Programming with Modula-3,
+ Prentice Hall Series in Innovative Technology,
+ ISBN 0-13-590464-1,
+ L.C. QA76.66.S87,
+ 1991.
+
+ This book is the definitive language reference. It includes the + language reference manual and papers on the I/O library, + threads, and the Trestle window system. It is also known as "SPwM3". +
+ Here is its table of contents: + +
-
+
- Introduction +
- Language Definition +
- Standard Interfaces +
- An Introduction to Programming with Threads +
- Thread Synchronization: A Formal Specification +
- I/O Streams: Abstract Types, Real Programs +
- Trestle Window System Tutorial +
- How the Language Got its Spots +
+ +
- Greg Nelson,
+ Initialization
+ of Object Types,
+ Threads: A Modula-3 Newsletter,
+ Issue 1,
+ Fall 1995.
+
+ This article describes the rationale for the way object types are + initialized in Modula-3. Modula-3 doesn't have type + constructors, but you can specify default values for object + fields in the type definition. The article also describes the +
initmethod convention. ++ +
- Paul Rovner,
+ Extending Modula-2 to build large, integrated systems,
+ IEEE Software,
+ 3(6),
+ November 1986.
+
+ +
- Robert Sedgewick,
+ Algorithms in Modula-3,
+ Addison-Wesley,
+ ISBN 0-201-53351-0,
+ L.C. QA76.73.M63S43,
+ 1993.
+
+ Sedgewick's classic text on algorithms. The examples are in Modula-3. +
+ +
- Stephen Schaub,
+ Modula-3 Reference and Tutorial.
+
+ An on-line reference and tutorial, available in three formats: HTML, + Texinfo source, and GNU Info files. All three formats are available as a + gzipped tar file as well. Similar tutorials are available from: + + Concordia University, + + University of Kent at Canterbury + +
+ +
- Emin Gün Sirer, Stefan Savage, Przemyslaw
+ Pardyak, Greg P. DeFouw, and Brian Bershad,
+ Writing an Operating System with Modula-3,
+ November, 1995.
+
+ Describes the experiences of the SPIN group at the University of + Washington using Modula-3 to build a high performance extensible + operating system. Debunks some of the myths surrounding Modula-3 by + arguing that the SRC reference implementation introduces + inefficiencies that are not imposed by the Modula-3 language itself. +
+ +
- Lauren Schmitt,
+ Photon:
+ An Environment for Building Distributed Applications,
+ Threads: A Modula-3 Newsletter,
+ Issue 1,
+ Fall 1995.
+
+ This brief article announces Photon, a commercially supported + development environment based on SRC Modula-3. The first official + release is scheduled for the first quarter of 1996. The first target + platform is Linux PC's. Photon is a product of + Critical Mass, Inc.. +
+ +
- Ryan Stansifer,
+ Trestle by Example,
+ October, 1994.
+
+ An on-line introduction to the Trestle window system. This tutorial + was written to conform with SRC Modula-3 version 2.11. Some of + the interfaces called in this tutorial are obsolete. +
+ A gzip'ed tar archive + of the entire tutorial is available. +
+ +
- Carsten Whimster
+ Using
+ Modula-3 Under OS/2,
+ Electronic Development
+ Magazine, OS/2 edition (EDM/2),
+ March, 1996.
+
+ +
- Geoff Wyant,
+ Introducing Modula-3,
+ Linux Journal,
+ December 1994.
+
+ It's available via anonymous FTP from ftp.gte.com in + /pub/m3/linux-journal.html. + +
+ +
++ You can order SRC Research Reports and videotapes + on-line + through the World-Wide Web. All reports and videotapes are free. +
+ + You can also order reports and videos by contacting: +
+ + SRC Report Distribution
+ +
+ Digital Equipment Corporation
+ 130 Lytton Avenue
+ Palo Alto, CA 94301-1044
++ src-report@src.dec.com +
+ Last modified on Fri Jan 30 09:44:22 EDT 1998 by michel.dagenais@polymtl.ca + modified on Thu May 2 19:44:22 PDT 1996 by heydon + modified on Mon Dec 19 10:23:41 PST 1994 by kalsow + modified on Wed Feb 12 12:48:44 PST 1992 by muller +
+ + + + Index: m3/pm3/intro/src/concise-bib.html diff -c /dev/null m3/pm3/intro/src/concise-bib.html:1.2 *** /dev/null Tue Feb 10 23:29:04 1998 --- m3/pm3/intro/src/concise-bib.html Tue Feb 10 22:41:03 1998 *************** *** 0 **** --- 1,166 ---- + + +Modula-3: Concise Bibliography + + +Modula-3 Concise Bibliography
+ +The complete annotated Modula-3 + bibliography now has over 50 entries. This page is an attempt at a + more concise list of essential Modula-3 references organized + by topic. The links on this page are pointers to the annotated + bibliography. Please send comments and/or additions to m3-request@src.dec.com. + +
Books
+ +-
+
- + Systems Programming with Modula-3, + Nelson, 1991. +
- + Modula-3, + Harbison, 1992. +
- + Algorithms in Modula-3, + Sedgewick, 1993. +
- + Programming with Modula-3, + Boeszoermenyi & Weich, 1995. +
Overview Articles
+ +-
+
- + Introducing Modula-3, + Wyant, 1994. +
- + A Happy User Promotes SRC Modula-3, + Nayeri, 1996. +
- + Modula-3, + Harbison, 1992. +
- + Safe Programming with Modula-3, + Harbison, 1992. +
Documentation of Modula-3 Interfaces
+ +-
+
- + Some Useful Modula-3 Interfaces, + Horning, Kalsow, McJones, & Nelson, 1993. +
- + Network Objects, + Birrell, Nelson, Owicki, & Wobber, 1994. +
- + Trestle Reference Manual, + Manasse & Nelson, 1991. +
- + VBTkit Reference Manual: A toolkit for Trestle, + Brown & Meehan. +
- + The FormsVBT Reference Manual, + Brown & Meehan. +
Introductory Programming Articles
+ +-
+
- + Modula-3 Reference and Tutorial, + Schaub. +
- + Net Balance: A Network Objects + Example", + Nayeri. +
- + Building Distributed OO Applications: + Modula-3 Objects at Work, + Dagenais, 1995. +
- + Partial Revelation and Modula-3, + Freeman, 1995. +
- + Initialization of Object Types, + Nelson, 1995. +
- + Trestle Tutorial, + Manasse & Nelson, 1992. +
- + Trestle by Example, + Stansifer, 1994. +
Modula-3 Ports
+ +-
+
- + Using + Modula-3 Under OS/2, + Whimster, 1996. +
Systems Written in Modula-3
+ +-
+
- + The Juno-2 Constraint-Based Drawing Editor, + Heydon & Nelson, 1994. +
- + Zeus: A System for Algorithm Animation and + Multi-View Editing, + Brown, 1992. +
-
+ Writing an Operating System with
+ Modula-3,
+
Sirer, Savage, Pardyak, DeFouw, & Bershad, 1995. + - + The Whole Program Optimizer, + Diwan, 1995. +
Parallel Programming
+ +-
+
- + An Introduction to Programming with Threads, + Birrell, 1989. +
-
+ Synchronization Primitives for a
+ Multiprocessor: A Formal Specification,
+
Birrell, Guttag, Horning, & Levin, 1987. +
Garbage Collection
+ +-
+
- + Compacting Garbage Collection with + Ambiguous Roots, + Bartlett, 1988. +
-
+ Distributed Garbage Collection for Network
+ Objects,
+
Birrell, Evers, Nelson, Owicki, & Wobber, 1993. +
Comparisons to Other Languages
+ +-
+
- + A Comparison of Modula-3 and Oberon-2, + Boeszoermenyi, 1993. +
-
+ A Comparison of Object-Oriented Programming in Four Modern Languages,
+
Henderson and Zorn, 1993. +
+ Last modified on Thu May 2 19:58:17 PDT 1996 by heydon +
+ + + Index: m3/pm3/intro/src/contacts.html diff -c /dev/null m3/pm3/intro/src/contacts.html:1.1.1.1 *** /dev/null Tue Feb 10 23:29:04 1998 --- m3/pm3/intro/src/contacts.html Sat Jan 31 14:47:15 1998 *************** *** 0 **** --- 1,13 ---- + +Contacts + +Contacts
+The prime site for any Modula-3 related discussion is the Usenet + newsgroup comp.lang.modula3. + Bug reports are welcome on this newsgroup as most distributions have + a large code base in common. + +
Specific requests and questions concerning PM3 may be directed to + Michel Dagenais + + \ No newline at end of file Index: m3/pm3/intro/src/content.html diff -c /dev/null m3/pm3/intro/src/content.html:1.3 *** /dev/null Tue Feb 10 23:29:04 1998 --- m3/pm3/intro/src/content.html Tue Feb 10 22:41:03 1998 *************** *** 0 **** --- 1,88 ---- +
+Content + +Content
++ The PM3 distribution contains over 130 programs and libraries split by + topic along a hierarchical tree. + +
-
+
- Database
- Permanent + storage, including stable (persistent) objects, and database access. +
- Graphics
- + Graphical applications and libraries, including windowing toolkits, + 2D and 3D graphics and animation, graphical editors and viewers, + and miscellaneous demo games. +
- Language
- + Compilers, interpreters, parsing tools, and program development tools + for several languages including Modula-3, Obliq, and Lisp. +
- Libs
- + General purpose libraries for memory management, input-output, + operating system access, data structures, numerical computations, and + miscellaneous topics not covered in the other sections. +
- M3Config
- + Configuration files for PM3, which determine default paths, + compilation options... +
- Network
- + Libraries and applications for networked, distributed applications, + including network objects, mail, www and news readers, and + distributed source and binaries repositories. +
- Text
- + Text and documentation processing libraries and applications, including + SGML/XML parsing tools. +
Guided Tour for New Users
+ +New users will typically want to read the documentation approximately + in the following order. + +
-
+
- + Modula-3 language definition
- This concise definition of the + Modula-3 language may be replaced by the more tutorial book + Modula-3 by Sam Harbison, published by Prentice Hall. +
- The Modula-3 compiler, + + m3build and + + m3ship
- + M3build interprets package (program or library) definitions in + m3makefiles and performs the compilation. M3ship installs + the resulting executable or runtime library files. +
- Modula-3 Standard Library, and other + Useful Modula-3 Interfaces
- This library contains the most commonly + used data structures, Input-Output interfaces, and Operating System + access. +
- m3gdb
- + This Modula-3 aware version of the GNU debugger offers the usual + debugging support functions with support to print Modula-3 values. +
- Trestle, + VBTkit, and + FormsVBT + windowing toolkits
- + Trestle operates at the pixel level and offers all the needed low level + mechanisms. VBTkit has higher level components such as shadowed buttons, + menus, text editors, scrollbars. FormsVBT offers an interactive + user interface builder through a simple description language, and is + the preferred vehicle for first time users. The lower level libraries + (Trestle and VBTkit) offer slightly more flexibility and performance + at the cost of increased programming complexity. +
- Runtime program analysis tools + coverage, + shownew, + showthread + , and + others
- + Several graphical and textual tools and runtime interfaces may be + used to gather information about source code coverage, execution time + profiling, new memory allocations, threads activity, and more. +
- Network Objects
- + Network objects may be used to easily build robust distributed applications + through remote method invocations. +
- Stable Objects
- + Stable objects offer crash resistant persistent storage. +
Copyright + +Copyright
+The Modula-3 release of Ecole Polytechnique de Montreal (PM3) contains + numerous packages from several sources, all freely redistributable. + Each package describes its detailed licensing terms. Our interpretation + of these terms, without any specific legal value, is exposed below. + +
+ The bulk of the distribution originates from DEC SRC and allows + free modification and redistribution, provided that you do not + hold DEC liable for anything related to SRC Modula-3 and that + you pay any fee incurred because of claims of damage arising + from your possession or use or inability to use the software. + By passing along this copyright with any redistribution, you prevent the + situation where someone else would sue DEC and you would be required to + indemnify DEC for such action. + +
+ A few packages or portions of packages are copyrighted by other industrial + research laboratories from Olivetti (m3tk), Xerox (regex), + and Sun Microsystems (m3tk). They may be freely modified and redistributed + provided that the copyright notice is preserved and that you do not assume + any liability on their part. + +
+ A few programs are available under the GNU GPL. These may be freely + redistributed provided that you make the modified source code available. + A few libraries are available under the GNU LGPL. These may be + freely redistributed provided that you make the modified library source + code available and allow relinking with a newer version of the library. + +
+ Our understanding of all the copyrights involved in PM3 is that you can + safely distribute any program or library developed with PM3 provided that you + pass along the copyrights, the source code of the PM3 libraries used + (at least for the LPGL libraries), and the relinkable binaries for + the rest (if you are using any LGPL libraries). + \ No newline at end of file Index: m3/pm3/intro/src/dupl.txt diff -c /dev/null m3/pm3/intro/src/dupl.txt:1.1.1.1 *** /dev/null Tue Feb 10 23:29:04 1998 --- m3/pm3/intro/src/dupl.txt Sat Jan 31 14:47:15 1998 *************** *** 0 **** --- 1,115 ---- + # List of units with the same name along with the word count output + # for the differences. Small numbers indicate small differences + # + diff m3tk/src/misc/TextExtras.i3 http/src/TextExtras.i3 0 0 0 + diff m3tk/src/misc/TextExtras.i3 webvbt/src/TextExtras.i3 0 0 0 + diff m3tk/src/misc/TextExtras.m3 http/src/TextExtras.m3 13 77 481 + diff m3tk/src/misc/TextExtras.m3 webvbt/src/TextExtras.m3 13 77 481 + # Identical except the m3tk version is a bit older; simplifications + # were brought to the newer version. + # + diff netobj/src/netobjrt/AtomPkl.i3 sgml/src/sgmlc/AtomPkl.i3 0 0 0 + diff netobj/src/netobjrt/AtomPkl.m3 sgml/src/sgmlc/AtomPkl.m3 0 0 0 + # To share. + # + diff realgeometry/src/RealInterval.m3 fisheye/src/RealInterval.m3 199 937 5289 + diff realgeometry/src/RealPoint.m3 fisheye/src/RealPoint.m3 584 2514 14063 + diff realgeometry/src/RealInterval.i3 fisheye/src/RealInterval.i3 205 1341 7581 + diff realgeometry/src/RealRect.i3 fisheye/src/RealRect.i3 379 2358 14606 + diff realgeometry/src/RealRect.m3 fisheye/src/RealRect.m3 690 3630 21669 + diff realgeometry/src/RealPoint.i3 fisheye/src/RealPoint.i3 274 1599 9420 + # Both sets have a common origin. In fisheye, everything raises an + # exception. However it is not handled anywhere. Converting fisheye should + # be OK. + # + diff m3browser/src/TCPPeer.i3 tcpextras/src/TCPPeer.i3 0 0 0 + diff m3browser/src/TCPPeer.m3 tcpextras/src/POSIX/TCPPeer.m3 15 82 502 + # Almost identical. Check which one to retain. + # + diff buildlectern/src/OSUtils.i3 zeus/src/OSUtils.i3 83 547 3348 + diff buildlectern/src/OSUtils.i3 postcard/src/OSUtils.i3 164 1124 7139 + diff buildlectern/src/OSUtils.i3 webcard/src/OSUtils.i3 164 1124 7139 + diff buildlectern/src/OSUtils.m3 zeus/src/OSUtils.m3 99 413 3124 + diff buildlectern/src/OSUtils.m3 postcard/src/OSUtils.m3 339 1331 9789 + diff buildlectern/src/OSUtils.m3 webcard/src/OSUtils.m3 337 1317 9718 + # All different, except for webcard/postcard. Check however if these + # functions could be put in a library. + # + diff m3tools/src/M3ID.i3 m3middle/src/M3ID.i3 55 384 2154 + diff m3tools/src/M3ID.m3 m3middle/src/M3ID.m3 560 2979 18651 + # Different. However along with m3browser/src/ID, a lot is shared with Atoms. + # + diff fours/src/Buf.i3 m3markup/src/Buf.i3 19 135 714 + diff fours/src/Buf.m3 m3markup/src/Buf.m3 74 319 1852 + # Fairly similar, could be shared. Pretty small, used to optimize. + # This is also the case for Wx.T instead of Wr.T. Check the performance + # difference and decide, perhaps. + # + diff m3markup/src/MarkUp.i3 m3tohtml/src/MarkUp.i3 18 128 772 + diff m3markup/src/MarkUp.m3 m3tohtml/src/MarkUp.m3 186 898 5469 + diff m3markup/src/M3MarkUp.m3 m3tohtml/src/M3MarkUp.m3 1165 5301 37835 + diff m3markup/src/M3MarkUp.i3 m3tohtml/src/M3MarkUp.i3 16 71 417 + # Same except that one uses Wx instead of Wr. Is the performance difference + # worth it. + # + diff images/src/Images.m3 webvbt/src/Images.m3 359 1521 11391 + diff images/src/Images.i3 webvbt/src/Images.i3 182 1322 8246 + # Different things with images. + # + diff lecterntohtml/src/HTML.m3 webvbt/src/HTML.m3 441 1734 12520 + diff lecterntohtml/src/HTML.i3 webvbt/src/HTML.i3 167 803 5066 + # Look quite different. + # + diff fisheye/src/GraphVBT.m3 mgkit/src/GraphVBT.m3 5697 23300 199456 + diff fisheye/src/GraphVBT.i3 mgkit/src/GraphVBT.i3 949 6055 39187 + # Different things with graphs. + # + diff netobj/src/netobjrt/Protocol.i3 stubgen/src/Protocol.i3 113 770 5001 + # Different. + # + diff fours/src/Config.i3 columns/src/Config.i3 66 379 2379 + diff fours/src/Config.i3 postcard/src/Config.i3 99 502 3465 + diff fours/src/Config.i3 webcard/src/Config.i3 99 502 3465 + diff fours/src/Config.m3 columns/src/Config.m3 372 2008 13591 + diff fours/src/Config.m3 postcard/src/Config.m3 929 4419 34933 + diff fours/src/Config.m3 webcard/src/Config.m3 927 4405 34827 + # Different. + # + diff stablegen/src/FRefRefTbl.m3 stubgen/src/FRefRefTbl.m3 0 0 0 + diff stablegen/src/Type.i3 stubgen/src/Type.i3 66 457 2442 + diff stablegen/src/ValueProc.i3 stubgen/src/ValueProc.i3 0 0 0 + diff stablegen/src/Type.m3 m3front/src/types/Type.m3 1154 5657 38688 + diff stablegen/src/Type.m3 stubgen/src/Type.m3 416 2242 16409 + diff stablegen/src/AstToType.i3 stubgen/src/AstToType.i3 38 216 1332 + diff stablegen/src/Value.m3 stubgen/src/Value.m3 0 0 0 + diff stablegen/src/AstToType.m3 stubgen/src/AstToType.m3 952 3890 39952 + diff stablegen/src/TypeNames.i3 stubgen/src/TypeNames.i3 15 109 631 + diff stablegen/src/Value.i3 m3front/src/values/Value.i3 110 609 3574 + diff stablegen/src/Value.i3 stubgen/src/Value.i3 0 0 0 + diff stablegen/src/FRefRefTbl.i3 stubgen/src/FRefRefTbl.i3 0 0 0 + diff stablegen/src/TypeNames.m3 stubgen/src/TypeNames.m3 108 520 3811 + diff stablegen/src/Value.m3 m3front/src/values/Value.m3 499 2186 13908 + # Similar but different except for one or two trivial files which are + # identical. + # + diff webcard/src/PostcardMain.m3 postcard/src/PostcardMain.m3 79 323 2586 + diff webcard/src/BuiltInDisplay.i3 postcard/src/BuiltInDisplay.i3 0 0 0 + diff webcard/src/BuiltInDisplay.m3 postcard/src/BuiltInDisplay.m3 425 1719 13521 + diff webcard/src/NI.i3 postcard/src/NI.i3 0 0 0 + diff webcard/src/NI.m3 postcard/src/NI.m3 0 0 0 + diff webcard/src/Closure.i3 postcard/src/Closure.i3 19 103 646 + diff webcard/src/FastMenu.i3 postcard/src/FastMenu.i3 0 0 0 + diff webcard/src/FastMenu.m3 postcard/src/FastMenu.m3 0 0 0 + diff webcard/src/BuiltInCompose.i3 postcard/src/BuiltInCompose.i3 0 0 0 + diff webcard/src/BuiltInCompose.m3 postcard/src/BuiltInCompose.m3 9 53 343 + diff webcard/src/UnixMail.m3 postcard/src/UnixMail.m3 8 40 292 + diff webcard/src/MiscUtils.m3 postcard/src/MiscUtils.m3 0 0 0 + diff webcard/src/UnixMail.i3 postcard/src/UnixMail.i3 0 0 0 + diff webcard/src/UtimeExtra.i3 postcard/src/UtimeExtra.i3 0 0 0 + diff webcard/src/Rescreen.m3 postcard/src/Rescreen.m3 0 0 0 + diff webcard/src/MailUtilities.i3 postcard/src/MailUtilities.i3 0 0 0 + diff webcard/src/MailUtilities.m3 postcard/src/MailUtilities.m3 0 0 0 + diff webcard/src/Rescreen.i3 postcard/src/Rescreen.i3 0 0 0 + diff webcard/src/MiscUtils.i3 postcard/src/MiscUtils.i3 0 0 0 + # Webcard is vastly inspired from postcard. Perhaps one replaces the + # other or sharing could be done. Index: m3/pm3/intro/src/history.html diff -c /dev/null m3/pm3/intro/src/history.html:1.1.1.1 *** /dev/null Tue Feb 10 23:29:04 1998 --- m3/pm3/intro/src/history.html Sat Jan 31 14:47:15 1998 *************** *** 0 **** --- 1,71 ---- +
+History + +History
+ ++ The Modula-3 distribution of Ecole Polytechnique de Montreal is directly + based on SRC Modula-3 release 3.6, which appeared in early 1996. + +
SRC Modula-3
++ Version 1.0 was the first public release of SRC Modula-3. It contained the + compiler, runtime and a few tools. The compiler generated intermediate C code + and was only tested on VAX Ultrix 3.1. Subsequent 1.x releases were ported + to several platforms and the libraries reorganized. + +
+ Version 2.0 implements the twelve language changes proposed after the initial + trial period. The compiler and code generator were rearranged and improved. + With subsequent 2.x releases, several new platforms were supported and + significant new packages appeared (FormsVBT, Zeus...). + +
+ Version 3.0 is the first public release of the gcc based native code + generator m3cc, Modula-3 aware debugger m3gdb, and smart recompilation + system m3build. The standard library was cleaned up after a close + review by the interface police. A Windows NT port appeared as well as + new significant packages such as Network objects and Obliq. + Subsequent 3.x releases brought bug fixes, more platforms supported, + speed tuning, and several new packages such as Stable Objects and Anim3D. + +
PM3
++ With release 3.6, in early 1996, DEC SRC Modula-3 reached a mature state. + Bill Kalsow, responsible for the compiler, left DEC SRC around that time + and later joined Critical Mass, a commercial Modula-3 vendor. Since then, + a number of advanced Modula-3 projects at DEC SRC continued in areas such + as 3D animation, static verification, constraint based geometrical editor, + and distributed + applications. In many other areas, including the compiler and base libraries, + few updates were made at DEC SRC. Moreover, these updates are available + separately from the release and must be integrated manually. + +
+ At the same time, several contributions appeared from Modula-3 programmers + around the world and included several bug fixes, enhancements, and + new libraries or tools such as a more platform independent version + of Pickle, an integrated code generator for Linux ELF, + a simplified single process version of m3build-m3-quake, + a port of SRC Modula-3 to NT386 using gnu-win32, and several new + packages such as CVSsup, M3COCO, and M3 TXL. + +
+ After consultations with several key academic Modula-3 programmers with + similar needs, including Peter Klein, Blair McIntyre, and Richard Watts, + it was decided to create a new distribution based on SRC Modula-3. + The new distribution is under CVS version control and is + accessible to remote maintainers. + +
+ The first public release of PM3 included SRC release 3.6 with all patches + applied, a fast integrated Linux ELF code generator, a simplified + m3build-m3-quake with accordingly simplified templates for platform + customization, m3cc and m3gdb based on newer versions of gcc and gdb, + full platform support for NT386GNU through gnu-win32, + a simplified bootstrap and build process, a directory hierarchy + to organize the 130+ packages, SGML/HTML based documentation, + and an automated release procedure to produce updated sources, bootstraps + and binaries every week. + + \ No newline at end of file Index: m3/pm3/intro/src/index.html diff -c /dev/null m3/pm3/intro/src/index.html:1.2 *** /dev/null Tue Feb 10 23:29:04 1998 --- m3/pm3/intro/src/index.html Tue Feb 10 22:41:03 1998 *************** *** 0 **** --- 1,68 ---- +
+PM3: The Modula-3 distribution of Ecole Polytechnique de Montreal + + ++ Michel Dagenais + Michel Dagenais, GNU General Public License, 1998 + + michel.dagenais@polymtl.ca+
+ Ecole Polytechnique
+ C.P. 6079, Succ. Centre-Ville
+ Montreal, Quebec, H3C 3A7 + 17 January 1998 + Modula-3 + Distribution + Compiler + Libraries + wide audience +PM3: The Modula-3 distribution of Ecole Polytechnique de Montreal
+ +++ +This free distribution integrates the excellent SRC Modula-3 development + environment with a number of local enhancements as well as numerous + outside contributions. Key features include an SGML/HTML based documentation + system, easier bootstrap and build, improved Linux support (faster compiler + and better debugging support), and NT 386 support through the gnu win32 + version of gcc. +
This distribution was assembled at Ecole Polytechnique de Montreal to + satisfy internal teaching and research needs as well as to serve + academic and industrial externel needs, along the lines of cooperation on + which the internet was built. This free and rapidly evolving Modula-3 + distribution is directly based on the excellent DEC SRC Modula-3 development + environment. It contains several enhancements produced by Modula-3 programmers + from around the world. + +
Each package group, package or file has information about its authors + and copyright. Documentation files were often contributed separately + by different authors and possibly under a different copyright. Thus, + the author mentioned in the documentation may or may not have contributed to + the code in the corresponding package. Similarly, the copyright mentioned + in the documentation applies to the documentation alone. The source files + may come under a different copyright. + +
The current PM3 release is under the responsability of Louis-Dominique + Dubeau (ldd@step.polymtl.ca) and Michel Dagenais (michel.dagenais@polymtl.ca). + In the coming months, several groups and individuals are expected + to join this effort and take responsability for various parts of the + package hierarchy. + +
-
+
- History +
- Acknowledgments +
- Copyright +
- Installation +
- Content +
- Platform Support +
- Future Plans +
- + Frequently Asked Questions and Answers +
- Contacts +
- Annotated Bibliography +
Installation + + +Installation
+ +The latest version of PM3 may be obtained from m3.polymtl.ca by + WWW or + (FTP). + +
Binary Installation
+ +A binary distribution of PM3 contains executable programs, libraries, + and run time data files (scripts, bitmaps, document type definitions...). + It comes in a tar compressed file and may be untarred from the root + directory. As explained below, you need to set appropriately the PATH + environment variable, and possibly the LD_LIBRARY_PATH environment + variable on some of the platforms supporting shared libraries. +
+ In the examples below, TARGET refers to the platform name and + should be replaced by LINUXELF, SPARC, SOLgnu... depending on your + target platform, and version refers to the PM3 version. +
+ The PATH environment variable must contain the directory where the + executable programs reside, typically /usr/local/pm3-1.1/bin. + On platforms with shared libraries (dynamically linked), the dynamic linker + must find the shared libraries along its path. Typically, the LD_LIBRARY_PATH + environment variable will need to include + /usr/local/pm3-1.1/lib/m3/TARGET. + For some platforms (LINUXELF, SPARC, SOLgnu), the shared libraries paths + are specified at link time and LD_LIBRARY_PATH need not contain + anything, if the shared libraries are at the location specified at link time. +
+ Some programs require data files at run time. The locations for these files may + be specified as a command line option for the program. Default locations + use the values specified in the m3config library. These values reflect + the compiler configuration templates at the time m3config was compiled. + For the compiler itself (m3build and m3ship), a more elaborate scheme is + used to find the templates. A command line option may be set + (-T path), the M3TEMPLATES environment variable may be + specified, and the m3config library values serve as default location. + Failing that, the PATH environment variable is used to locate + m3build and the templates are assume to be reachable from there + using the relative path ../lib/m3/pkg/m3config/src. Because of this, + the compiler finds automatically the templates in most cases, and the + installation may look like: +
+ cassis> cd + cassis>ftp m3.polymtl.ca + ftp> binary + ftp> cd pub/m3/binaries/TARGET + ftp> ls + ftp> cd version + ftp> get usr.tgz + ftp> quit + cassis> cd / + cassis> tar xpfz ~/usr.tgz + cassis> rm ~/usr.tgz + cassis> setenv PATH /usr/local/version/bin:${PATH} + cassis> setenv LD_LIBRARY_PATH \ + > /usr/local/version/lib/m3/TARGET:${LD_LIBRARY_PATH} + cassis> +++ In rare cases, (e.g. if the system libraries are at an unusual location), + you may need to modify the templates in order to reflect your system + configuration. This is achieved by examining the content + of /usr/local/pm3-1.1/lib/m3/pkg/m3config/src/COMMON and + overriding the improper variables and functions in the + platform specific template + /usr/local/pm3-1.1/lib/m3/pkg/m3config/src/TARGET. + +
Source only Installation
++ For a source only distribution, you need a compatible version of m3build and + m3ship already installed. The PATH and LD_LIBRARY_PATH environment + variables also need to be set properly as explained in the previous section. + You may then customize the compiler configuration files in m3config/src, + select the packages to compile in src/m3makefile, + and then proceed with the compilation and installation + (m3build -DRECURSIVE). + +
+ cassis> cd + cassis>ftp m3.polymtl.ca + ftp> binary + ftp> cd pub/m3/pkg + ftp> ls + ftp> get version.tgz + ftp> quit + cassis> tar xpfz version.tgz + cassis> rm version.tgz + cassis> setenv PATH /usr/local/version/bin:${PATH} + cassis> setenv LD_LIBRARY_PATH \ + > /usr/local/version/lib/m3/TARGET:${LD_LIBRARY_PATH} + cassis> cd version + cassis> m3build -DRECURSIVE ++ +Bootstrap Source Installation
++ The bootstrap for a platform contains the assembly source for all the files + comprising m3build and m3ship, and suitable makefiles. + The PATH and LD_LIBRARY_PATH environment variables need to be set properly as + in the previous sections. You may then customize the top level bootstrap + makefile Makefile if needed, customize + the compiler configuration files in m3config/src, + select the packages to compile in src/m3makefile, + and then proceed with the compilation and installation (make). + +
+ cassis> cd + cassis>ftp m3.polymtl.ca + ftp> binary + ftp> cd /pub/m3/pkg + ftp> ls + ftp> get version.tgz + ftp> cd /pub/m3/bootstrap/TARGET + ftp> get version.tgz boot.tgz + ftp> quit + cassis> tar xpfz version.tgz + cassis> tar xpfz boot.tgz + cassis> rm version.tgz boot.tgz + cassis> setenv PATH /usr/local/version/bin:${PATH} + cassis> setenv LD_LIBRARY_PATH \ + > /usr/local/version/lib/m3/TARGET:${LD_LIBRARY_PATH} + cassis> cd version + cassis> make ++ + + + + + Index: m3/pm3/intro/src/logo.gif Index: m3/pm3/intro/src/m3makefile diff -c /dev/null m3/pm3/intro/src/m3makefile:1.2 *** /dev/null Tue Feb 10 23:29:05 1998 --- m3/pm3/intro/src/m3makefile Tue Feb 10 22:41:03 1998 *************** *** 0 **** --- 1,17 ---- + + import("m3doc") + HtmlFile("ack") + HtmlFile("bib") + HtmlFile("concise-bib") + HtmlFile("contacts") + HtmlFile("content") + HtmlFile("copyright") + HtmlFile("history") + HtmlFile("index") + HtmlFile("install") + HtmlFile("platforms") + HtmlFile("todo") + + include_dir("questions") + + OtherPackage("intro") Index: m3/pm3/intro/src/platforms.html diff -c /dev/null m3/pm3/intro/src/platforms.html:1.2 *** /dev/null Tue Feb 10 23:29:05 1998 --- m3/pm3/intro/src/platforms.html Tue Feb 10 22:41:03 1998 *************** *** 0 **** --- 1,111 ---- + +Platform Support + +Platform Support
++ +
Supported platforms
++ PM3 has been ported to several platforms. Bootstraps for the following + platforms are currently produced regularly. + +
-
+
- DS3100
- DECstation 5000/200 Ultrix 4.2. +
- FreeBSD2
- IBM PC, FreeBSD 2.0. +
- HPPA
- HP 700/800, HP-UX 8.0. +
- IRIX5
- SGI/MIPS, IRIX 5.2. +
- LINUXELF
- IBM PC, Linux (ELF object file format) +
- NT386GNU
- IBM PC, Windows/NT and Windows 95 using gnu-win32 tools. +
- SOLgnu
- Sparcstation, Solaris-2.x w/ unbundled gcc. +
- SPARC
- Sparcstation-1, SunOS 4.1.x. +
The following platforms are still active but bootstraps could not be + built lately, mostly because of problems in the gcc based backend. + +
-
+
- ALPHA_OSF
- Alpha/AXP, OSF/1. +
- IBMR2
- IBM RS/6000, AIX 3.1. +
- NEXT
- NeXT(M68K). +
- NT386
- IBM PC, Windows/NT and Windows 95. +
The following platforms have not been active lately. + +
-
+
- AP3000
- Apollo DN4500, Domain/OS 10.2 +
- ARM
- Acorn R260, RISC iX 1.21. +
- FreeBSD
- IBM PC, FreeBSD 1.1.5 +
- HP300
- HP 9000/300, HP-UX 7.0 +
- IBMRT
- IBM RT, IBM/4.3 (AOS 4.3). +
- LINUX
- IBM PC, Linux. +
- OKI
- Okidata 7300 (i860) AT&T SVR4.0. +
- SEQUENT
- Sequent 386 +
- SOLsun
- Sparcstation, Solaris-2.x w/ bundled Sun C. +
- SUN3
- Sun 3, SunOS 4.1 +
- SUN386
- Sun 386i, SunOS 4.0.1. +
- UMAX
- Encore Multimax, UMAX 4.3 (R4.1.1). +
- VAX
- VAX 8800, Ultrix 4.2. +
Porting to new platforms
+ ++ In order to port PM3 to a new platform, the following steps are required. + The differences in PM3 between different POSIX platforms are relatively small + and a new port may often be achieved in a matter of a few days or less. + New entries in tables, and new directories, + are obtained by copying the corresponding portions from + an existing similar platform and making a few modifications. + It is assumed that the new platform already fits in 32 or 64 bits, + and POSIX or WIN32; if not, additional work will be required. + +
-
+
- Install PM3 on a supported platform. +
- Select a short unique name for the new platform. +
- Add an entry for the platform in table Platforms + of the template file m3config/src/COMMON. Add a platform + specific template in directory m3config/src. +
- In file language/modula3/m3compiler/m3middle/src/Target.m3, + add an entry in table Systems, and a section describing the + new platform in the CASE sys OF statement in the Init + procedure. +
- In directory libs/m3core/src/C, add a platform specific + subdirectory defining the interface to C functions such as + setjmp, longjmp, _setjmp, _longjmp, + to stdio.h, and to string.h. Be careful to + get the size of the jmp_buf right. + +
- In directory libs/m3core/src/Csupport, add a platform specific + subdirectory containing a properly configured dtoa.c. + +
- In file libs/m3core/src/float/m3makefile add an entry for the + new platform in table _FloatPieces. + +
- In file libs/m3core/src/runtime/m3makefile add an entry for the + new platform in table EXCEPTION_IMPL. Add a platform + specific subdirectory in libs/m3core/src/runtime implementing + the creation and manipulation of stacks for threads, and defining + and installing signal handlers for signals such as SIGVTALRM and + SIGSEGV. + +
- In file libs/m3core/src/time/POSIX/m3makefile add an entry for the + new platform in table _DateImpls. + +
- In file libs/m3core/src/unix/m3makefile add an entry for the + new platform in table _UnixPieces. If needed, add a platform + specific subdirectory in libs/m3core/src/unix defining the + interface to system services. + +
- In file libs/libm3/src/random/m3makefile add an entry for the + new platform in table _RandomPieces. + +
- In package language/modula3/m3compiler/m3bootstrap issue the + command m3build -DBOOTTARGET=XXX, where XXX should be replaced + by the new platform. If all goes well, a bootstrap should be produced + in the subdirectory YYY/pm3-XXX where YYY is the platform + from which the port is initiated. This bootstrap may then be used + as described in the installation instructions. +
Future Plans + + + +Future Plans
+ +PM3
+ ++ The following items are planned for PM3. Items are listed by + decreasing order of likelyhood of being implemented in the near future. + Help on these items is most appreciated! + +
-
+
- Produce binaries for several platforms at every release through remote + compilation servers. We have NT386GNU, SPARC, and SOLgnu computers readily + accessible. + +
- Test on NT the new release and adapt to gnu-win32 Beta 19 whenever it + comes out. Perhaps the w2p calls in the NT386GNU template could be removed + which would enable much more sharing of the template with other platforms. + +
- Add bug fixes, patches, and contributed packages. Blair's Pickle, + Tony Hosking's Solaris stack walker, Spencer's emacs files, + m3na, and M3 TXL are + among the items on the list. Check enumerating environment variables + under NT386GNU, proper deallocation + of file handles, critical sections, and other handles in Win32 + m3core/libm3 runtime. + +
- Do some profiling and optimisation on the integrated m3build/quake/m3 + and fast LINUXELF code generator. + +
- Decouple m3ship and m3where from m3templates. Currently m3ship is much + too large needlessly. + +
- Progressively document all the packages using m3doc. For some packages + a small introductory index.html file linking to public interfaces + is sufficient. For some other packages, the m3totex documentation may be + reused (libm3/m3core, trestle, vbtkit, formsvbt, netobj, stable, anim3D, + m3tk). + +
- Remove all duplicate files in pm3. + Keep a single copy or each in a library. + A modified m3browser was used to print the list of duplicate files. + The duplicate units (same name) found were analysed to distinguish + simple name clashes from redundancy + [duplicates]. + +
- Detect reusable components hidden in libraries and programs. + Candidates include AtomPkl, FSM, MText. Find a category specialist + for each category to drive this effort and enhance the reusable components. + +
- Increase the use of generic modules. Text may be used for UNICODE + support through generics based on Char.T versus WChar.T ([0..65535]). + Similarly, geometry could benefit from generics based on Integer.T, Float.T, + Point = ARRAY Axis OF Unit, where Axis is {x,y} for 2D and {x,y,z} for 3D. + This could perhaps lead to anim2D versus anim3D. + +
- Provide tools to support diagrams in M3doc + (write xfig to HTML and support diagram tags in the conversion to + LaTeX/Postscript). + +
- Build a library for browsing and analysing Modula-3 code, probably + based on m3tk and m3browser. It could be used for computing metrics + for Modula-3 programs, detecting procedure clones, extracting object oriented + design diagrams (OMT/UML), or building an enhanced integrated development + environment. + Peter Klein is working on a Modula-3 development environment and associated + user interface. + See the + + report + entitled ``Designing Software with Modula-3'', + it describes a software architecture description language + based on Modula-3. + Klaus Preschern, Carsten Weich, Laszlo Boszormenyi + have made the port of Modula-3 to the PC which includes + a student-friendly development environment. + +
- Rework the HTML kit and the web packages to provide a single + package for accessing WWW documents. + +
- Provide a high level Database interface, for both PostgresSQL and + ODBC. Eventually provide a native implementation based on persistent objects + for the same high level interface. + +
- Add some widgets to trestle/vbtkit like a grid (table/matrix) VBT. + Incorporate modifications for a 3D look for scrollbars, Win32 mode + for the TexteditVBT... Make rotated fonts available from Trestle. + +
- Find/develop graph layout and display packages. Such functionality + may be available from the GRAS/Progres project. GraphVBT already does + the display part. + +
- Extend the draw, sharedboard, html2ps, mgkit, visualobliq + or anim3D packages to obtain + a nice structured graphics package. This package, not unlike + Unidraw/Interviews, could be used as a basis for diagram editors, + rich text editors, Web browser widget, user interface builder... + +
- C to Modula-3 converter, initially for declarations (.h files), + to interface C libraries to Modula-3 programs, + but eventually for complete programs. The initial translation would + convert to equivalent UNSAFE structures but subsequent passes may try to + convert char_star to TEXT and so on. + +
- Develop a network object activator. Network objects servers would + be started on demand. + +
- Add some authentication and access control to network objects, probably + along with IPv6. + +
SRC Modula-3
+ ++ Here is an unordered list of small and large tasks that should be done, + which used to be kept on Bill Kalsow's desk and whiteboard. But, + since it seems to grow rather than shrink over time, here it + is. If you want to work on any of these tasks, go for it. +
+ Copyright (C) 1992, 1996, Digital Equipment Corporation. All rights reserved.
+ See the COPYRIGHT for a full description. + +Driver
+-
+
+
- Atomic update of .m3x files + The .m3x files should be updated atomically. If the files are + damaged, users get terribly confused. Similarly, if an object + file gets produced and the version stamps don't get recorded, + users are deceived. + +
- Integrate quake.
+ We should write a Modula-3 version of quake that's callable
+ as a library routine. Then, it should be integrated with the
+ rest of the driver (Done in PM3).
+ The resulting program could persist throughout
+ a development session. Then, the reading, parsing and evaluation
+ of m3makefiles could be cached across builds and
+ the list of source files and configuration data wouldn't be
+ passed through the file system.
+
+ +
- AST cache policy.
+ The current driver keeps an in-memory cache of compiled interfaces,
+ but never flushes entries.
+ So, it's memory usage grows throughout a build.
+ This will be unacceptable when the
+ driver lives across multiple builds.
+
+ +
+ +
Front end
+-
+
+
- New definition of ADR.
+ The front end should default to using the new definition
+ of ADR, where instead of ADDRESS, ADR(x) returns an UNTRACED REF T
+ when the static type of x is T. The new definition increases
+ the safety of interfacing with the C world. This feature is
+ available new with the "-X0@-new_adr@" option, but it should
+ just be the default. The change will require a few source
+ changes (m3core, libm3 and ui are already fixed). Ideally,
+ the new types wouldn't require runtime typecells since NEW
+ is never called on the new types and TYPECASE isn't applicable
+ to UNTRACED REFs.
+
+ +
- Scanning floating-point literals.
+ The front end uses the ancient
+ Convert interface to convert ascii floating point values
+ to internal binary form. We should use something like the new
+ Lex interfaces.
+
+ +
- Floating-point constant folding.
+ The compiler uses the host's LONGREAL type to represent floating-point
+ values. Instead, it should provide a faithful emulation of the
+ target machine's floating point. See m3middle/src/TFloat.m3.
+
+ +
- FIRST/LAST(REAL)
+ According to the language definition, these should be plus and
+ minus infinity on IEEE platforms. I am pretty sure that even if the
+ front end used the right values, it would fail to pass them
+ precisely to the back end.
+
+ +
- Missing debugger info.
+ The following things are not passed through to the debugger:
+ IMPORT A AS B, named scalar constants, the Modula-3
+ type of procedure return values.
+
+ +
- Unreachable TYPECASE arms.
+ The compiler should emit a warning for a TYPECASE label T
+ when an earlier label U is a supertype of T.
+
+ +
- Packed array literals.
+ The front end doesn't always layout arrays of packed values
+ correctly. See procedure GenLiteral in
+ m3front/src/exprs/ArrayExpr.m3.
+
+ +
- Non-regular array literals.
+ The front end doesn't detect 2-D open array initializers where
+ the inner array values are of different sizes until it gets
+ into code generation. It should cleanly report these errors
+ during type checking.
+
+ +
- Type names to prelinker.
+ If the front end passed user-sensible names for types back to
+ the prelinker and they were preserved in the version stamp
+ files, the prelinker could generate better error messages
+ for inconsistencies (e.g. missing or repeated revelations)
+ in the program's types.
+
+ +
- Field packing.
+ Microsoft C supports a "pack" pragma that apparently overrides
+ the normal field packing rules for structures. The result is
+ that the Modula-3 compiler and C compiler disagree about
+ some field layout. For example, CommDlg.PrintDlg has
+ a 32-bit integer field that crosses a 32-bit boundary. A fix would
+ be to define a per-platform parameter that describes the minimum
+ (as opposed to preferred) alignment required for full-word loads.
+ Then, BITS FOR could be used to fix up the offending layouts.
+
+ +
- Fingerprints of set literals.
+ Set literals are not canonicalized before they are fingerprinted.
+ They should be. See procedure GenFPLiteral in
+ m3front/src/exprs/SetExpr.m3.
+
+ +
+ + +
GCC back end
+-
+
+
- Stack overflow checking.
+ The gcc-based back end doesn't check for thread stack overflows.
+ Whenever a procedure is entered whose stack frame is larger
+ than the thread stack's guard page (Target.Guard_page_size),
+ the back end should emit an explicit test for stack overflow.
+ At the moment the front end doesn't tell the back end size
+ of the guard page and the back end doesn't know the size
+ of the stack frame when it begins emitting code for the
+ procedure.
+
+ +
- Gcc optimizer.
+ It seems that every time I try using the optimizer I get burned.
+ The most likely cause is that m3cc/gcc/m3.c is not building
+ properly decorated trees. Given that there's almost no spec for
+ well-formed trees, it's going to require intimite knowledge of gcc
+ or lots of tinkering to find the problems.
+
+ +
- Floating-point opcodes on Alpha.
+ The Alpha machine description should be modified to generate
+ floating point opcodes that allow software fixups of denormalized
+ values. It should also insert trapb instructions where needed.
+
+ +
- Mips-tfile vs. /bin/ld.
+ On DS3100, the version of mips-tfile in gcc 2.5.7 generates object files
+ that cannot be linked by /bin/ld. Problems occur when the object
+ module defines an externally callable procedure and the linker
+ is asked to generate the procedure table. If this problem was
+ fixed, we could generate direct procedure calls rather than indirecting
+ through the interface records.
+
+ +
+ +
NT back end
+-
+
+
- Return values from external procedures.
+ Apparently, not all procedures (e.g. NB30.Netbios) return
+ fully sign-extended results in the return register. I guess the
+ conservative thing to do is to sign or zero extend all procedure
+ results from external procedures. (and procedure variables too?)
+
+ +
- DLLs.
+ We should be able to generate and use DLLs. Unfortunately,
+ Microsoft requires different code sequences to reference
+ a global variable (e.g. interface record) from inside and
+ outside a DLL.
+
+ +
- CodeView symbols.
+ The hooks in M3ObjFile already exist, we just need to generate
+ the debugging data for CodeView debuggers.
+
+ +
- A RISC back end.
+ Somebody should use m3back and m3objfile as
+ starting points to building another backend for one of the
+ current RISC processors. It's much faster to compile
+ directly from M3CG to object file than to go through the
+ "ASCII IL -> gcc -> ASCII .s -> assembler -> object file"
+ mess. Once one RISC back end was written it should be pretty
+ easy to write others. Register handling will be the primary difference
+ from the NT back end. High quality code is not a goal.
+
+ +
+ +
Runtime
+-
+
+
- FloatMode and RealFloat interfaces.
+ Most platforms don't have full implementations of the floating-point
+ interfaces.
+
+ +
- Floating-point exceptions.
+ On the DS3100 platform, we attempt to convert floating point traps
+ into the proper Modula-3 exception. But, the traps are delivered
+ via a Unix signal so the longjmp that delivers the exception must
+ cross a signal handler stack frame. The last time I checked we
+ go a "longjmp botch", so either the jmpbuf is incorrect, or you're
+ not supposed to be able to jump out of a signal handler.
+
+ +
- NT -gui vs. Stdio.
+ When a windows subsystem ("-gui") program is started, it's not
+ given a console. Hence, writes to Stdio.stdout disappear.
+ libm3/src/os/WIN32/ProcessWin32.m3 should be modified
+ so that the standard handles are bound to File.Ts that
+ lazily create consoles. Then, adding print statements to a GUI
+ program would produce useful output.
+
+ +
- Table pickles.
+ The generic table package should register pickle specials.
+ There's no need to pickle a table's internal hash table.
+ The pickle should just contain a list of name/value pairs.
+ The resulting pickle would be robust against changes in the
+ table's hashing function.
+
+ +
- Incremental GC.
+ Several platforms that are capable of supporting the VM-synchronized,
+ incremental and generational features of the garbage collector, need
+ work. For example, ALPHA_OSF should be easy and NT386 should be possible.
+
+ +
- TCP on NT/386
+ The Unix TCP veneer needs to be ported to use WinSock.
+
+ +
- Error messages on NT
+ We need to write or find a routine that generates a readable
+ message from an NT error number. Such a routine must exist.
+
+ +
+ +
Debugger
+-
+
+
- Expression parsing and evaluation.
+ The current expression parser and evaluator are woefully inadequate.
+ For example, they don't handle floating-point literals, TEXT literals,
+ or most of the built-in operations.
+
+ +
+ +
Misc.
+-
+
+
- Versioned shared libraries.
+ There should be a way to provide multiple versions of a shared
+ library. Operating systems that support shared libraries usually
+ support some sort of versioning. The problem is to find a
+ maintainable, portable way to do that in the current Modula-3 and
+ m3build environment.
+
+ +
- QPT is broken.
+ Jim Larus' QPT doesn't seem to work with DS3100 binaries. Possibly
+ the problem is that it doesn't properly translate the exception
+ tables in the initialized data segment. ??
+
+ +
- M3browser and type uids.
+ It should be possible to find types by their 32-bit UID
+ using m3browser.
+
+ +
- Exceptions as return values.
+ What would it cost in time and space to implement exceptions
+ as simple return values? Suppose you were allowed to change
+ the calling convention so that each procedure call site
+ had two return locations. Then, non-exceptional returns would
+ cost nothing (except a little code space) and exceptional
+ returns would be quite fast.
+
+ +
- Modula-3 parser.
+ There should be a reusable, lightweight Modula-3 parser.
+ Probably the parser should be easy to hack and lightweight rather
+ than fully general, extensible, and slow as molasses.
+
+ +
- Validation suite.
+ The current test package m3tests is a joke. Many
+ more tests should be included. The m3makefile should be made
+ to work on NT.
+
+ +
- M3ship warning.
+ M3ship should warn you if the m3makefile is newer than the
+ .M3EXPORTS files. Shipping a package after it's m3makefile
+ has been modified, but before it's been reevaluated, often
+ leads to confusion or surprise.
+
+ +
+ + + Index: m3/pm3/intro/src/questions/.ghindex.html diff -c /dev/null m3/pm3/intro/src/questions/.ghindex.html:1.1.1.1 *** /dev/null Tue Feb 10 23:29:05 1998 --- m3/pm3/intro/src/questions/.ghindex.html Sat Jan 31 14:47:15 1998 *************** *** 0 **** --- 1,101 ---- + +
++ Frequently asked questions and answers + + + +Frequently asked questions and answers
++ +
-
+
- Calling Modula-3 procedures from a C program (1714 bytes) +
- Strange pragmas for Locking levels and other properties (653 bytes) +
- Comparisons between Modula-3 and other languages? (1086 bytes) +
- How to copy heap objects? (1120 bytes) +
- Linking with C++ code (763 bytes) +
- The program receives a SEGV signal under the debugger (489 bytes) +
- Flushing writers to see the output immediately (534 bytes) +
- Is Modula-3 a superset of Modula-2? (238 bytes) +
- M3build versus Make or why m3 does not work (548 bytes) +
- Meeting with other Modula-3 users (272 bytes) +
- Missing RTHooks or similar messages (471 bytes) +
- Recovering from running out of virtual memory (24526 bytes) +
- Exceptions raised by X or Network Objects applications (772 bytes) +
- What is the purpose of BRANDED and REVEAL (4275 bytes) +
- What is the story with Trestle and OpenWindows? (655 bytes) +
- Reading a single character as soon as typed (3277 bytes) +
- Why is Hello World so large? (575 bytes) +
- Why uppercase keywords (510 bytes) +
- CONST Comments in Variables Declarations (2221 bytes) +
- Problems with threads and VTALARM (640 bytes) +
- X libraries not found (339 bytes) +
++ + Index: m3/pm3/intro/src/questions/CcallM3.html diff -c /dev/null m3/pm3/intro/src/questions/CcallM3.html:1.1.1.1 *** /dev/null Tue Feb 10 23:29:05 1998 --- m3/pm3/intro/src/questions/CcallM3.html Sat Jan 31 14:47:15 1998 *************** *** 0 **** --- 1,87 ---- + +
+ ++ ++ + Glimpse HTTP Search (In string, use ";" for AND and "," for OR between keywords)
+ + Glimpse and + GlimpseHTTP, Copyright © 1996, + University of Arizona +
+
+ + + +
+ + Michel Dagenais, 1997. For comments, updates and suggestions + michel.dagenais@polymtl.ca +How to call Modula-3 procedures from a C program? + +How to call Modula-3 procedures from a C program?
++ Calling Modula-3 from C is tricky because M3 has a more elaborate run-time + environment. The simplest solution is to make the main program M3 and then + call C via EXTERNAL routines. Calling back into M3 is then relatively + straightforward. +
+ Here's an example. It calls the C code to lodge the identity of the M3 + procedure to be called back which avoids having to know the actual name used + by the linker. +
+ First a little M3 module to be called from C (M3code), then a C module called + by the M3 main and calling the M3 module (Ccode), and finally the main + program (Main): +
+ (* M3code.i3 *) + + INTERFACE M3code; + IMPORT Ctypes; + PROCEDURE put (a: Ctypes.char_star); + END M3code. + + (* M3code.m3 *) + + UNSAFE MODULE M3code; + IMPORT Ctypes, IO, M3toC; + + PROCEDURE put (a: Ctypes.char_star) = + BEGIN + IO.Put (M3toC.StoT (a) & "\n"); + END put; + + BEGIN + END M3code. + + (* Ccode.i3 *) + + <*EXTERNAL*> INTERFACE Ccode; + IMPORT Ctypes; + PROCEDURE set (p: PROCEDURE (a: Ctypes.char_star)); + PROCEDURE act (a: Ctypes.char_star); + END Ccode. + + /* Ccode.c */ + + typedef void (*PROC)(); + static PROC action; + + void set (p) + PROC p; + { + action = p; /* register the M3 procedure */ + } + + void act (a) + char *a; + { + action (a); /* call the M3 procedure */ + }; + + (* Main.m3 *) + + UNSAFE MODULE Main; + + IMPORT Ccode, M3code, M3toC; + + BEGIN + Ccode.set (M3code.put); + Ccode.act (M3toC.TtoS ("Hello world")); + END Main. + + (* m3makefile *) + + import(libm3) + + interface ("Ccode") + c_source ("Ccode") + module ("M3code") + implementation("Main") + program("mixed") ++ + + Index: m3/pm3/intro/src/questions/ESChecking.html diff -c /dev/null m3/pm3/intro/src/questions/ESChecking.html:1.1.1.1 *** /dev/null Tue Feb 10 23:29:05 1998 --- m3/pm3/intro/src/questions/ESChecking.html Sat Jan 31 14:47:15 1998 *************** *** 0 **** --- 1,12 ---- +Why are there strange pragmas for Locking levels and other properties? +Why are there strange pragmas for Locking levels and other properties?
++ The Trestle (ui library) interfaces contain Locking level pragmas. + The base interfaces (libm3 library) contain SPEC pragmas. These are + not processed by the compiler. Instead the Extended Static Checker, + currently under development at DEC SRC, will report on problems + detected based on the program content and the information specified in + these pragmas + [ESC]. + The Extended Static Checker is not yet available, it may be some time in the + future. Index: m3/pm3/intro/src/questions/bookstore.html diff -c /dev/null m3/pm3/intro/src/questions/bookstore.html:1.1.1.1 *** /dev/null Tue Feb 10 23:29:05 1998 --- m3/pm3/intro/src/questions/bookstore.html Sat Jan 31 14:47:15 1998 *************** *** 0 **** --- 1,10 ---- +
Where to find Modula-3 books? +Where to find Modula-3 books?
++ If you cannot find some of the Modula-3 books at your favorite bookstore, + here are bookstores connected to the net known to carry them: + UCI Bookstore , + Roswell Electronic Computer Bookstore + (rjames@fox.nstn.ns.ca) +
+ Index: m3/pm3/intro/src/questions/compare.html diff -c /dev/null m3/pm3/intro/src/questions/compare.html:1.1.1.1 *** /dev/null Tue Feb 10 23:29:05 1998 --- m3/pm3/intro/src/questions/compare.html Sat Jan 31 14:47:15 1998 *************** *** 0 **** --- 1,24 ---- +
Comparisons between Modula-3 and other languages? +Comparisons between Modula-3 and other languages?
++ From: laszlo@post.ifi.uni-klu.ac.at (Laszlo BOESZOERMENYI) +
+ A Comparison of Modula-3 and Oberon-2 + by myself in + Structured Programming 1993, 14:15-22 +
+ From: nayeri@gte.com +
+ Robert Henderson, Benjamin Zorn, + A Comparison of Object-Oriented Programming in Four Modern Languages, + Department of Computer Science, University of Colorado, Boulder, Colorado, + Technical Report CU-CS-641-93. +
+ The paper evaluates Oberon, Modula-3, Sather, and Self in the + context of object-oriented programming. While each of these + programming languages provide support for classes with inheritance, + dynamic dispatch, code reuse, and information hiding, they do so in + very different ways and with varying levels of efficiency and simplicity. + A single application was coded in each language and the experience + gained forms the foundation on which the subjective critique is based. +
Index: m3/pm3/intro/src/questions/contrib.html diff -c /dev/null m3/pm3/intro/src/questions/contrib.html:1.1.1.1 *** /dev/null Tue Feb 10 23:29:05 1998 --- m3/pm3/intro/src/questions/contrib.html Sat Jan 31 14:47:15 1998 *************** *** 0 **** --- 1,17 ---- + +
+Can I contribute Modula-3 software? + + +Can I contribute Modula-3 software?
+ +Contributions are most welcome. The primary contact to offer + contributions is comp.lang.modula3. + +
+ + The Ecole Polytechnique de Montréal Modula-3 distribution + is the most regularly updated and may be a good place to submit your + contribution. + + Index: m3/pm3/intro/src/questions/copyObject.html diff -c /dev/null m3/pm3/intro/src/questions/copyObject.html:1.1.1.1 *** /dev/null Tue Feb 10 23:29:05 1998 --- m3/pm3/intro/src/questions/copyObject.html Sat Jan 31 14:47:15 1998 *************** *** 0 **** --- 1,38 ---- +
+How to copy heap objects? + +How to copy heap objects?
++ Deep copies are easily performed using Pickles. An object graph is + Pickled to a text writer into a TEXT. Then, a copy is created by + unpickling a new object graph from a text reader created from the + TEXT. +
+ Shallow copies are less often needed but may be performed with the + following procedure: + +
+ PROCEDURE Duplicate (r: REFANY): REFANY = + VAR + tc := TYPECODE (r); + n_dims : INTEGER; + res : REFANY; + shape : RTHeapRep.ArrayShape; + BEGIN + IF (r = NIL) THEN RETURN NIL END; + + (* allocate a new object of the same type (and shape) as the old one *) + RTHeapRep.UnsafeGetShape (r, n_dims, shape); + IF (n_dims <= 0) + THEN res := RTAllocator.NewTraced (tc); + ELSE res := RTAllocator.NewTracedArray (tc, SUBARRAY(shape^, 0, n_dims)); + END; + + (* copy the old data into the new object *) + RTMisc.Copy (RTHeap.GetDataAdr (r), RTHeap.GetDataAdr (res), + RTHeap.GetDataSize (r)); + + RETURN res; + END Duplicate; +
+ Index: m3/pm3/intro/src/questions/cpp.html diff -c /dev/null m3/pm3/intro/src/questions/cpp.html:1.2 *** /dev/null Tue Feb 10 23:29:05 1998 --- m3/pm3/intro/src/questions/cpp.html Sat Jan 31 15:48:43 1998 *************** *** 0 **** --- 1,34 ---- +Can Modula-3 code call C++ and vice-versa? +Can Modula-3 code call C++ and vice-versa?
++ There is no problem to call C++ functions declared as + extern C. You must use a C++ aware linker (e.g. the C++ compiler). + A complete example of M3 calling C++ objects, which in turn call + M3 callbacks, is available in + the sgml library. +
+ On some platforms, a call to get the static variables constructors called may + be required: +
+ From: gwyant@cloyd.East.Sun.COM (Geoffrey Wyant - Sun Microsystems Labs BOS) +
+ You must use your C++ compiler as the linker, rather than /bin/cc + or /bin/ld. +
+ You need to call the function '_main'. The easiest way to do this + is to have the following set of interfaces and implementations: +
+
+ INTERFACE CXXMain; + <*EXTERN "_main"*> CxxMain; + END CXXMain; + + MODULE CXXMain; + BEGIN + CxxMain(); + END;
++ and then import CXXMain into your M3 main module. This will + ensure that the C++ function _main gets called. +
+ Index: m3/pm3/intro/src/questions/debug.html diff -c /dev/null m3/pm3/intro/src/questions/debug.html:1.2 *** /dev/null Tue Feb 10 23:29:05 1998 --- m3/pm3/intro/src/questions/debug.html Sat Jan 31 15:48:43 1998 *************** *** 0 **** --- 1,8 ---- +
Why programs receives a SEGV signal under the debugger? +Why program receives a SEGV signal under the debugger?
++ The garbage collector on some platforms uses the SEGV (segmentation + violation) signal to detect modified portions of the dynamically + allocated space. It is possible to disable this feature or to inform + the debugger to let these signals propagate. See the + m3gdb documentation. Index: m3/pm3/intro/src/questions/flush.html diff -c /dev/null m3/pm3/intro/src/questions/flush.html:1.1.1.1 *** /dev/null Tue Feb 10 23:29:05 1998 --- m3/pm3/intro/src/questions/flush.html Sat Jan 31 14:47:15 1998 *************** *** 0 **** --- 1,10 ---- +
How to get output messages to appear immediately (flushing writers)? +How to get output messages to appear immediately (flushing writers)?
++ Modula-3 Writers are buffered. Thus, you need to issue a Wr.Flush when + the output should appear immediately, for instance to prompt the user + for some input. Since this can become annoying, libraries in other languages + sometimes offer the option of unbuffered writes. In Modula-3, an equivalent + behavior is obtained with AutoFlushWr which gets a background thread to + flush a writer at a specified interval. +
Index: m3/pm3/intro/src/questions/implementations.html diff -c /dev/null m3/pm3/intro/src/questions/implementations.html:1.1.1.1 *** /dev/null Tue Feb 10 23:29:05 1998 --- m3/pm3/intro/src/questions/implementations.html Sat Jan 31 14:47:15 1998 *************** *** 0 **** --- 1,24 ---- + +
+What implementations are available, how do they compare? + + +What implementations are available, how do they compare?
+ ++ All implementations are based on + + DEC SRC Modula-3. + Critical Mass + offers an improved version with commercial support. It features incremental + garbage collection on NT, and a few additional packages like + ODBC database access. + Ecole Polytechnique de Montréal has an + updated distribution. + It features integrated documentation, weekly updates, pre-compiled + binaries for several platforms, and debugging support on NT. +
+ Special versions have been developed for OS/2 and DOS and are available + on the Polymtl site. + + Index: m3/pm3/intro/src/questions/interfaces.html diff -c /dev/null m3/pm3/intro/src/questions/interfaces.html:1.1.1.1 *** /dev/null Tue Feb 10 23:29:05 1998 --- m3/pm3/intro/src/questions/interfaces.html Sat Jan 31 14:47:15 1998 *************** *** 0 **** --- 1,46 ---- + +
+Why objects and interfaces? + + +Why objects and interfaces?
+ ++ Allan Heydon on comp.lang.modula3, May 4th 1993: + +
+ Modula-3 provides two separate mechanisms for data-hiding: one for + hiding details about how interfaces are implemented, and the other + for hiding details about how objects are implemented. + +
+ The first data-hiding mechanism is realized by the distinction between + interfaces and modules. Clients can only import interfaces, so the + names declared in the modules implementing those interfaces are hidden + from clients. Note that this mechanism has only two levels; a name + is either declared in an interface, or it isn't. If a name is only + declared in a module, it can't be used by a client. + +
+ The second data-hiding mechanism is realized by opaque types and + revelations. A Modula-3 interface may declare an object type to be + opaque, in which case only a subset of the fields and methods of + that object are revealed to clients importing the interface. Furthermore, + the Modula-3 revelation mechanism allows a designer to reveal successively + more fields and methods of an object in a series of interfaces. The + fields and methods visible to a client then depends on which interfaces + the client imports. + +
+ The latter mechanism is quite flexible. As opposed to the interface/module + data-hiding mechanism, opaque types allow you to define an arbitrary + number of levels at which more and more information about the implementation + of your object is revealed. + +
+ See Sections 2.2.10, 2.4.6, and 2.4.7 of "Systems Programming with + Modula-3" for more information about opaque types and about partial + and complete revelations. + + + Index: m3/pm3/intro/src/questions/m3doc.html diff -c /dev/null m3/pm3/intro/src/questions/m3doc.html:1.2 *** /dev/null Tue Feb 10 23:29:05 1998 --- m3/pm3/intro/src/questions/m3doc.html Sat Jan 31 15:48:43 1998 *************** *** 0 **** --- 1,31 ---- + +
+Where can I get documents and information on Modula-3? + + +Where can I get documents and information on Modula-3?
+ ++ A concise bibliography and a more + complete bibliography describe Modula-3 + related books, technical reports, and papers. + The definition of Modula-3 is contained in: + "System Programming with Modula-3" + also known as SPwM3. + Sam Harbison has written a more tutorial book titled + Modula3. + +
+ Three main Web servers contain Modula-3 related information: + www.m3.org, + + DEC SRC Modula-3 home page, + and + Ecole Polytechnique de Montré + Modula-3 home page. + +
The Usenet newsgroup comp.lang.modula3 is the official meeting place + for Modula-3 related discussions. + + + Index: m3/pm3/intro/src/questions/m3makefile diff -c /dev/null m3/pm3/intro/src/questions/m3makefile:1.1 *** /dev/null Tue Feb 10 23:29:05 1998 --- m3/pm3/intro/src/questions/m3makefile Sat Jan 31 15:28:00 1998 *************** *** 0 **** --- 1,31 ---- + HtmlFile("CcallM3") + HtmlFile("ESChecking") + HtmlFile("bookstore") + HtmlFile("compare") + HtmlFile("contrib") + HtmlFile("copyObject") + HtmlFile("cpp") + HtmlFile("debug") + HtmlFile("flush") + HtmlFile("implementations") + HtmlFile("interfaces") + HtmlFile("m3doc") + HtmlFile("m3superset") + HtmlFile("make") + HtmlFile("missing") + HtmlFile("new") + HtmlFile("noconnect") + HtmlFile("opaque") + HtmlFile("openwin") + HtmlFile("ptf") + HtmlFile("questions") + HtmlFile("raw-io") + HtmlFile("size") + HtmlFile("srcm3") + HtmlFile("support") + HtmlFile("uppercase") + HtmlFile("varconst") + HtmlFile("vtalarm") + HtmlFile("whatism3") + HtmlFile("whereused") + HtmlFile("xnotfound") Index: m3/pm3/intro/src/questions/m3superset.html diff -c /dev/null m3/pm3/intro/src/questions/m3superset.html:1.1.1.1 *** /dev/null Tue Feb 10 23:29:05 1998 --- m3/pm3/intro/src/questions/m3superset.html Sat Jan 31 14:47:15 1998 *************** *** 0 **** --- 1,6 ---- +
Is Modula-3 a superset of Modula-2? +Is Modula-3 a superset of Modula-2?
++ No; valid Modula-2 programs are not valid Modula-3 programs. However, + there is a tool to help convert Modula-2 programs to Modula-3. +
Index: m3/pm3/intro/src/questions/make.html diff -c /dev/null m3/pm3/intro/src/questions/make.html:1.1.1.1 *** /dev/null Tue Feb 10 23:29:05 1998 --- m3/pm3/intro/src/questions/make.html Sat Jan 31 14:47:15 1998 *************** *** 0 **** --- 1,11 ---- +
M3build versus Make or why m3 does not work? +M3build versus Make or why m3 does not work?
++ The Modula-3 compiler m3 does a much finer grained dependency analysis than + possible with make. For this reason, a very flexible front end, m3build, + reads the program description files, m3makefile, and generates the commands + required to compile and link Modula-3 programs and libraries. The m3makefile + content is documented in the m3build documentation. Calling the m3 compiler + directly is difficult and thus not recommended, especially on PM3 where + it is now merged with m3build. +
Index: m3/pm3/intro/src/questions/missing.html diff -c /dev/null m3/pm3/intro/src/questions/missing.html:1.1.1.1 *** /dev/null Tue Feb 10 23:29:05 1998 --- m3/pm3/intro/src/questions/missing.html Sat Jan 31 14:47:15 1998 *************** *** 0 **** --- 1,8 ---- +
What means Missing RTHooks or similar messages? +What means Missing RTHooks or similar messages?
++ The standard library, libm3, is not included by default. You need in your + m3makefiles to import("libm3") or to import a library which imports libm3. + Otherwise, messages about run time procedures such as RTHooks not being + available are produced. +
Index: m3/pm3/intro/src/questions/new.html diff -c /dev/null m3/pm3/intro/src/questions/new.html:1.1.1.1 *** /dev/null Tue Feb 10 23:29:05 1998 --- m3/pm3/intro/src/questions/new.html Sat Jan 31 14:47:15 1998 *************** *** 0 **** --- 1,495 ---- +
Can a program recover from running out of virtual memory? +Can a program recover from running out of virtual memory?
++ No, this turns out to be quite a thorny problem. I think + the best thing I can do is by attaching to this message the + dialog that went on during the "beta test" of the new library interfaces + (SRC Research Report 113, "Some Useful Modula-3 Interfaces). The + parties are Xerox PARC's David Goldberg, Hans Boehm, Alan Demers, + and David Nichols, and SRC's John DeTreville, who designed and implemented + the garbage collector in SRC Modula-3. The dialog covers many of + the issues, and apparently ends when the participants run out of + steam. +
+ Paul McJones + mcjones@src.dec.com + (editor of SRC 113) + +
RTAllocator should allow handling out of memory
++ David Goldberg: ... there is one system problem that is not currently + handled, namely running out of memory. I would very, very much + like to see this handled in RTAllocator. One approach was + suggested by Roy Levin a while back: Have a RegisterNoMemory(proc) + routine that causes proc() to be called when memory is gone (or + very low). Example of use: in the 'Solitaire' program, the 'Hint' + button generates a tree of possible moves. If this tree gets very + big and consumes all memory, the RegisterNoMemory proc could + abandon the search down the current branch, NIL-out that branch, + and ask for a garbage collection. Currently what happens is that + Solitaire crashes if you bug 'Hint' and memory is low. +
+ Interface Police: Ok, make a concrete proposal and we'll talk. How + low should memory be before the runtime complains? Before or + after a collection? Is it ok to call your procedure from inside + a runtime critical section (after all, you're probably in the + middle of a NEW)? Are multiple notification procedures allowed + to be registered? Shouldn't a routine that consumes arbitrary + amounts of memory be coded to poll the allocator to ask how much + memory is available? +
+ Hans Boehm/Alan Demers/David Goldberg/David Nichols: + We believe that programs wishing to handle allocation failures + will be able to do so with high (but not perfect) reliability if + the interface provides two features: versions of the + RTAllocator.New routines that report if the allocation is not + possible (either by returning NIL or raising an exception), and a + way to register a callback when memory is low. Both features are + necessary. Here are two typical scenarios: +
+
-
+
- The Solitaire program.
+ Before starting, Solitaire allocates a 'safety net' block of
+ memory, and registers a callback. When memory is exhausted,
+ the callback frees the safety net, sets a flag, and returns.
+ In the Solitaire program proper, the inner loop of the move
+ generator checks the flag immediately after allocating a new
+ node. If the flag is set, it abandons the search. It would
+ not work for Solitiare to allocate new tree nodes with
+ RTAllocator.New() and check for an error: as memory gets low,
+ a library routine in some other package could cause an
+ allocation failure.
+
+ Unfortunately, there is a race condition since another thread + could run and do an allocation between the time the faulting + NEW returns and all references to the search tree are NIL'ed. + This can be mimimized by adding some slop to the safety net. + +
- An editor that allocates O(n) bytes of memory when opening an
+ n-byte file.
+ If the users tries to open a huge file, you don't want to
+ crash, but rather tell the user that the file can't be opened
+ (in UNIX, the user can then kill some processes to regain swap
+ space and try again, or in an emacs-style editor he can delete
+ some buffers and try again). A callback won't work for this,
+ because when attempting to open a huge file, the allocation
+ must be aborted: there just isn't enough memory to go around.
+ Instead an RTAllocator.New() routine should be used for this
+ allocation.
+
+ However, the editor will also want to register a callback proc + to guard against NEW()s in other parts of the program that + can't be satisfied. If the callback is passed the size of the + memory allocation that can't be satisfied, the callback will + be able to pick between two strategies. If there is a 'safety + net' which is larger than the block to be allocated, the + callback can free it and set a "low on memory" flag, with the + editor cleaning up properly later. If the safety net is not + big enough, the callback itself can attempt an emergency save + before crashing. +
+ Here's a specific proposal that embodies these ideas. We're not + wedded to the details. Note that RTCollector.LimitRelative is not + essential: it just lifts some of the functionality currently in + RTHeapPolicy. +
+
-
+
- Add the following to RTCollector.i3:
+
+ PROCEDURE LimitAbsolute(n: CARDINAL); + + (* Don't let the heap grow beyond n bytes. The collector/allocator + should observe this in all heap growth decisions. *) + + [Comment from Hans: I don't think there is a way to write + programs that are reasonable citizens on a shared system without + some such facility.] + + PROCEDURE LimitRelative(x: REAL); + + (* Advisory. Try to keep the heap size at roughly x times the + amount of live data. (For ref counting it affects only the + backup collector for cycles.) *) + + [Comments from Hans: The performance of all collectors with + which I am familiar depends crucially on such a parameter. Thus + it might as well be exposed in some portable interface. (The + allocator should of course use less memory if it gains no time + advantage from using more.) The "amount of live data" is, of + course, implementation defined, as are the minimum values of x + that have any chance of being observed.] +
+ + - In RTAllocator.i3, add OutOfMemory to RAISES clauses of all the
+ New routines, and add the following:
+
+
+ EXCEPTION OutOfMemory; + + TYPE + CallBackObj = OBJECT notify(bytes: CARDINAL) END; + + PROCEDURE RegisterHeapFullCallback(obj: CallBackObj); + + (* Add obj.notify to the list of procs to be called if an + allocation request is about to fail, either because of lack + of memory, or due to violation of an + RTCollector.LimitAbsolute imposed limit. The notify method + will be called with an argument specifying the size in bytes + of the allocate call that triggered the callback. The notify + method may not allocate or acquire locks, or call any + procedures that do. It may be invoked synchronously with any + combination of locks held. (Should there be a way to delete + a registered callback?). If a garbage collection after this + callback fails to reclaim enough memory to allocate the + requested object, an exception will be raised if the + allocation was through RTAllocator. Otherwise a checked + runtime error will result. The notify proc is not called + when memory fails from an RTAllocator.New call (these + failures can be caught by the user). + + Typical actions by notify would include one of the following: + + 1) Clearing pointers to reduce the amount of accessible memory. + 2) Calling RTCollector.LimitAbsolute with a larger limit. + *) +
+ + - Variations on this proposal:
+
+ Might want to consider adding: +
+
+ PROCEDURE GetLimitAbsolute(): CARDINAL; + (* Return the current absolute heap limit *) +
++ The usefulness of RTCollector.LimitAbsolute in the callback + would be increased if there was a way to tell if this actually + freed up any more memory. One approach would be to change + CallBackObj to +
+
+ TYPE + CallBackObj = OBJECT + notify(bytes: CARDINAL; retry: BOOLEAN): BOOLEAN + END; +
++ and change the action of RegisterHeapFullCallback to: +
+
+ (* If a garbage collection after all callbacks have been + executed fails to reclaim enough memory to allocate the + requested object, then any notify() procs that returned TRUE + will be called again with retry := TRUE. Otherwise an + exception will be raised if the allocation was through + RTAllocator, or else a checked runtime error will result. *) +
++ Thus, if you wanted to first try and get more memory in the + callback by calling RTCollector.LimitAbsolute, you could return + TRUE and wait for a callback with retry = TRUE. If this second + callback occurs, you will need to clear some pointers to free up + memory. Or another variation: add +
+
+ PROCEDURE GetTotalBytesAllocated(): CARDINAL; + (* Returns the total number of bytes allocated since the program + begin. A CARDINAL may not be big enough, perhaps this should + be a LONGREAL? *) +
++ Then the retry argument to the notify method can be eliminated, + since a call is a retry only if GetTotalBytesAllocated() shows + no additional allocations since the last callback. +
+ + John DeTreville: When I read your March proposal for handling running + out of memory on the traced heap, I didn't quite see how to + implement the details you gave. I've been iterating to create + mechanisms that are simpler and more implementable, and I've now + arrived at quite a simple interface. +
+ In particular, I now believe that (almost) all the functionality + you ask for is already provided by the current interface. I say + "almost" because there's a few status calls to be added, and + because some of the current mechanisms are clunky, but I believe I + can tell a convincing story. Note that these mechanisms are or + would be in SRC-specific interfaces (currently called + RTAllocatorSRC, RTCollectorSRC, and RTHeapRep); I don't think we + understand them well enough to put them into the public IP + interfaces. +
+ Let's first distinguish VM limits from application-imposed limits. + The amount of VM available to the application is a hard limit, + although not one that can easily be predicted. In the current SRC + M3 implementation, both the allocator and the collector allocate + VM from the kernel when necessary. If the collector tries to + allocate VM and fails, the program must crash: there is no way to + reestablish the necessary invariants to let it continue. +
+ I propose treating VM exhaustion as a checked runtime error, in + the allocator and in the collector. The goal is then to establish + and maintain an application-imposed limit that is uniformly + stricter than the VM limit, whatever that may be. +
+ You propose a mechanism to allow calls to the New* procedures to + fail if they would exceed the application-imposed limit. Of + course, only a small part of the code would take advantage of this + facility. This code could equally well query the heap to + determine the current size, and compare it against the limit; if + the program can also predict the size of the object to be + allocated, it can decide whether or not to proceed. +
+ This approach requires some collector-dependent code in the + application, but I doubt that it would be very much. It also + allows possible race conditions, but I believe they're not much + worse in practice than in the original proposal. +
+ You also propose a mechanism to notify the program whenever the + limit is about to be exceeded. It's quite complicated to get such + immediate notification. First, the procedures notified can't + acquire locks or call most procedures in other modules. Second, + it requires a new collection to run synchronously after the + procedures to see if enough space has been freed and whether some + of the procedures must be called again; this causes an + interruption of service. +
+ Here's a different proposal, which might not allow space bounds as + tight as in the original proposal, but which seems simpler. We + would add a mechanism for an application thread to wait for the + next collection to finish. This mechanism could replace the + current mechanisms for registering and unregistering synchronous + monitors, which have numerous complex and poorly documented + constraints on what actions they can perform. +
+ Each time through, the thread could compare the amount of space + still reachable to the application-imposed limit, and either free + some data before the next collection (the ability to hold locks + would be handy here) or increase "gcRatio" to make the collector + work harder and keep the total heap size under control, or both. +
+ There is still the danger that the application could allocate so + rapidly that this asynchronous thread might not be able to keep + up, but otherwise asynchronous actions seem a lot more reasonable + than synchronous. +
+ This is one approach, and there are others. What's nice about + this design is that it requires almost no changes to the + interface, only better status reporting and a replacement of the + mechanisms for registering and unregistering synchronous + collection monitors. Maybe you could even work around the current + lack of these facilities. Let me know what you think. +
+ Hans: One quick comment, without having thought much about the + rest: +
+ "This code could equally well query the heap to determine the + current size, and compare it against the limit; if the program + can also predict the size of the object to be allocated, it + can decide whether or not to proceed." +
+ Is this really true? Since the collector can't move some objects, + there are presumably fragmentation issues. Am I guaranteed to be + able to allocate 1 MB if the current heap size is 1 MB below the + limit? This is certainly false in PCR, and I'm not sure how you + could guarantee it without remapping pages. +
+ John: Hans Boehm notes that I was wrong about the client of New* + being able to predict whether an allocation would succeed or fail, + because of likely page-level fragmentation. This needs to be + fixed in my proposal. +
+ To expand on my earlier message, let me outline a completely + different approach for handling heap overflow, that perhaps has + more in common with the original PARC proposal, but which seems + far too complex and unwieldy to me. This complexity is why I + tried to work out a simpler approach, even at the cost of + providing fewer guarantees. +
+ We start by imagining that we want to be able to continue to run + even if we exhaust VM. First, this means that we can never + allocate VM from inside the collector. The implication is that + whenever we allocate VM in the allocator, we allocate enough extra + to tide us over through the next collection, no matter how much of + the heap it retains. This suggests that we will significantly + overallocate VM. For example, with a stop-and-copy collector and + gcRatio set to 1, a program with a stably-sized reachable set + currently requires 3 times as much space as the reachable set, but + the "failsafe gc" would require 4 times. +
+ (Doing even this well depends crucially upon the SRC + implementation detail that the current collector never copies + objects bigger than one page, but leaves them in place. + Otherwise, the possibility of fragmentation would make it much + more difficult to determine how much memory to leave free for the + collector, and in what sizes of runs of pages. It will also take + some work to avoid off-by-one errors in predicting how much memory + a collection could take.) +
+ Of course, if the client decreases gcRatio, or switches from + sort-and-copy collection to concurrent collection, that would + require allocating more VM, to ensure that the collector cannot + run out of VM. That means that these operations can also fail, + just like allocator operations. +
+ Only some programs will want to be able to back off when they + reach VM limits. Others won't mind getting a checked runtime + error; in return, they will require less VM. Therefore, we need + procedures to switch back and forth between these two modes. + Again, attempting to switch to failsafe mode can fail. +
+ The collector currently allocates its own space on the traced heap + during collections, which will have to be moved to the untraced + heap if we are to predict how much traced heap a collection can + use. Note that in general, once VM is exhausted, allocations on + the untraced heap may start to fail, and so programs will probably + die very quickly once VM is exhausted. But let's move on. +
+ In addition to the VM limit, we also want an application-imposed + limit on heap size. The allocator and collector will guarantee + that the heap size will never exceed this limit. Again, we will + overallocate VM in the allocator to avoid exceeding the limit in + the collector. Again, setting the limit may fail. +
+ So what happens when a NEW fails, or a New*, or switching to + concurrent collection, or setting the application-imposed limit, + or whatever? This happens whenever performing the operation would + exceed the application-imposed limit, or when attempts to allocate + enough extra VM fail. +
+ Some of these can signal an error, and the client can chose to do + something else instead. In some cases, such as setting gcRatio, + it might make sense for the failing operation to tell the client + how close to the impossible value would be possible. +
+ NEW, though, should not signal an error; this would require + massive changes in all existing modules that would not be add + value to most clients. In this case, I can't think of anything + much better than the original proposal. Before attempting to + allocate the object, the collector will try to free up some + storage. First, it can perform a collection, or finish the + current one. If that doesn't do it, it can call one or more + procedures registered by the application to drop links to some + storage, or to change collector parameters. If that doesn't do + it, we can perform another collection. And so on and so on, until + the procedures say to give up. +
+ Note that these collections must be synchronous, since no + allocations may be possible until this mechanism completes, and + the collections will therefore cause interruptions of service. + Note also that the procedures cannot acquire locks, cannot + allocate storage, cannot call thread primitives, and so on, and + therefore cannot call into most libraries; they are essentially + restricted to reading and writing data structures whose + implementations they know, and changing collector parameters. + This seems excessively restrictive, but also unavoidable in this + approach. +
+ In short, this seems like a lot of extra mechanism to add to the + allocator and collector, that doesn't seem to do quite what you + want; it gives you strict limits, but at a cost. My proposal of + this morning is at least much simpler, although it can give looser + limits. +
+ John, continuing: Thinking a little more about the problem of running + out of storage in the untraced heap, it seems that the only + reasonable thing to do is to merge the implementation of the + untraced heap with the traced heap. This was, untraced NEWs that + fail can be handled exactly the same way as traced NEWs, with a + synchronous cleanup routine that frees enough VM to proceed, or + resets parameters. +
+ This means that the allocator and collector cannot use the + untraced heap, but must either use a static amount of storage + which they could overflow, or must allocate enough extra in + response to client applications that they cannot possibly run out + of space. The potential space overhead for maximum-sized stacks, + for example, is huge. +
+ The more this proposal is fleshed out, it more it seems that doing + a good job of recovering from heap overflows is quite tricky, + which is why I suggest a lower-tech approach for now. +
+ Hans: I just went over the last few messages in this thread again. I + think the bottom line is, as you say: +
+ It's hard to implement an out-of-memory call-back on top of the + current collector. Given the current collector, a collector + call-back that allows polling is probably the best you can + reasonably do, and should certainly be provided. +
+ The remaining question, which also seems to be motivated by other + concerns here, is: To what extent are you tied to this collector + design? The problem here seems to be mainly caused by copying old + generation objects, since you could perhaps bound the size of the + young generation? My suspicion, based unfortunately only on + anecdotes, is that this is not a good idea anyway, since it uses + too much space, and is also fairly expensive in copying cost. + (PARCPlace seems to have arrived at the same conclusion, so + there's probably at least one other supporter of this position. + Some recent complaints here about space usage of Modula-3 programs + also point a bit in this direction.) +
+ Do you agree? If so, should the interface be designed ignoring + current constraints, and should we initially accept a partial + implementation? +
+ John: It's been a while, so let me recap where we are, or at least + where I am. +
+ We've been discussing mechanisms for Modula-3 programs to manage + their memory better. In particular, we have proposed ways that + programs could bound the heap size and recover from heap overflow. +
+ I think this topic is complicated enough, and new enough, that we + shouldn't try to get it into the current set of portable + interfaces. The Interface Police concur. +
+ We've floated two broad (families of) proposals for attacking this + problem: +
+
-
+
- Allow strong guarantees on the heap size; these guarantees + would never be broken. + +
- Allow the program to monitor its memory usage, discarding + excess data as necessary. +
+ I think that the first is achievable. Adapting the current SRC Modula-3 + (allocator and) collector to allow such guarantees would take a + month or so. The principal problem is that the current collector + tries to maximize space/time performance, and giving such + guarantees will probably require extra memory to be set aside that + will never be used. The collector would have two modes: with or + without guarantees. Most programs would run without guarantees. +
+ I also think that a usable version of the second is possible with almost + no change to the current collector. The programmer would have to + do more work, and wouldn't get any strong guarantees, but this + approach should work for many programs. +
+ We've also been discussing a third family of proposals, that seem + to combine the worst features of the first and second: they require + significant changes to the current collector, but son't give very + strong guarantees. These seem much less interesting to me. +
+ Here's two pieces of opinion. +
+ First, I propose that we work out the details of #2, and you use + it for a couple of programs. Get some experience with it. This + could help inform a heavier-weight solution. +
+ Second, I wonder whether any of these solutions is a good + candidate for a portable interface. It's one thing not to be + strictly incompatible with a given collector strategy, but quite + another to be easy to plug into an existing collector. Modula-3 + currently doesn't require very much from its collector; making + these proposals standard would significantly increase the + requirements on a Modula-3 implementor. +
+ Index: m3/pm3/intro/src/questions/noconnect.html diff -c /dev/null m3/pm3/intro/src/questions/noconnect.html:1.1.1.1 *** /dev/null Tue Feb 10 23:29:05 1998 --- m3/pm3/intro/src/questions/noconnect.html Sat Jan 31 14:47:15 1998 *************** *** 0 **** --- 1,14 ---- +
Why are exceptions raised by X or Network Objects applications? +Why are exceptions raised by X or Network Objects applications?
++ Graphical applications (based on Trestle/X Windows) raise the + TrestleComm.Failure exception when the DISPLAY environment variable is + incorrect or the X server is refusing the connection. They raise + MachineIDPosix.Failure if the network configuration files are + incorrectly set up, especially on LINUX; /etc/hosts must contain at + least a loopback address (127.0.0.1) and the /etc/rc scripts an + appropriate ifconfig command (/etc/ifconfig lo 127.0.0.1; /etc/route + add 127.0.0.1). Applications with Network Objects may also raise + exceptions or consume all the CPU time available when the network + configuration files are incorrect. +
Index: m3/pm3/intro/src/questions/opaque.html diff -c /dev/null m3/pm3/intro/src/questions/opaque.html:1.1.1.1 *** /dev/null Tue Feb 10 23:29:05 1998 --- m3/pm3/intro/src/questions/opaque.html Sat Jan 31 14:47:15 1998 *************** *** 0 **** --- 1,108 ---- +
What is the purpose of BRANDED and REVEAL? +What is the purpose of BRANDED and REVEAL?
++ Allan Heydon writes: +
+ These two keywords are necessary because of two quite different + features of the language. REVEAL is necessary because Modula-3 has + opaque types and partial revelations. BRANDED is necessary because the + Modula-3 type system uses structural equivalence instead of name + equivalence. +
+ In Modula-3, the concrete structure of a type can be hidden from + clients in an interface. A common idiom is: +
+
+ INTERFACE I; + + TYPE + T <: TPublic; + TPublic = OBJECT + (* fields *) + METHODS + (* methods *) + END; + + END I.
++ The line "T <: TPublic" introduces the type "I.T" as an opaque subtype + of the type "I.TPublic". It does not reveal any of the other details + of the concrete structure of "I.T" to clients. Hence, "I.T" is said to + be an opaque type. Put another way, the structure of "I.T" is + only partially revealed to clients. +
+ In addition, it is possible to reveal more of "I.T"'s structure in + other interfaces, like this: +
+
+ INTERFACE IRep; + + IMPORT I; + + TYPE + TPrivate = I.TPublic OBJECT + (* more fields *) + METHODS + (* more methods *) + END; + + REVEAL + I.T <: TPrivate; + + END IRep.
++ This interface declares a type "IRep.TPrivate" that is a subtype of + "I.TPublic". It also asserts that "I.T" is also a subtype of + "IRep.TPrivate". A client that imports only the interface "I" has + access only to the fields and methods in "I.TPublic" when accessing an + object of type "I.T", but a client that imports both "I" and "IRep" + also has access to the fields and methods in "IRep.TPrivate" when + accessing an object of type "I.T". +
+ The "REVEAL" statement in this module simply asserts a subtype + relation. Unlike type declarations, revelations introduce no new + names. Hence, we could not have used the "TYPE" keyword in this case + because the type "I.T" has already been declared once (albeit + opaquely) in interface "I". +
+ Every opaque type must have a complete revelation. A complete + revelation has the form: +
+
+ REVEAL + T = TConcrete;
++ The revelation specifies that "TConcrete" is the concrete type for the + opaque type "T". +
+ The Modula-3 type system uses structural equivalence instead of name + equivalence. This means that two types are equal iff they have the + same structure. One consequence of this rule is that two types you + might intend to be distinct may actually be equal. This can have + unintended effects on the run-time behavior of your program. For + example, if both types that you expect to be distinct are actually + structurally equivalent and the two types guard two arms of a TYPECASE + statement, the arm for the second type will never be taken. +
+ If you want to avoid accidental equalities between two types, you can + brand one (or both) of them with the BRANDED keyword. A branded type + is equivalent to no other type, even if it is structurally equivalent + to some other type. In essence, the BRANDED keyword adds a bit of + virtual structure to the type that guarantees it will be distinct from + every other type. +
+ The Modula-3 syntax allows you to supply a text constant as a name for + the brand. If you don't supply an explicit brand, the compiler will + make one up; however, the implicit brand invented by the compiler is + not guaranteed to be chosen deterministically. Hence, explicit brands + are useful if you are communicating types from one process to another + and if you want to be sure that the branded type written by one + process matches the branded type read in by the other. +
+ Any two opaque types in a program must be distinct. Otherwise, it + would be too easy for clients to accidentally trip over type + collisions like the TYPECASE example mentioned above. To enforce the + restriction that all opaque types are distinct, the language requires + that the type "TConcrete" in the complete revelation above must be a + branded type. +
Index: m3/pm3/intro/src/questions/openwin.html diff -c /dev/null m3/pm3/intro/src/questions/openwin.html:1.1.1.1 *** /dev/null Tue Feb 10 23:29:05 1998 --- m3/pm3/intro/src/questions/openwin.html Sat Jan 31 14:47:15 1998 *************** *** 0 **** --- 1,15 ---- +
What is the story with Trestle and OpenWindows? +What is the story with Trestle and OpenWindows?
++ Mark Manasse says: +
+ I think that the OpenWindows release should be enough (no need to + get the MIT X release), although there are a few things in Trestle + that trigger devastating bugs in OpenWindows. But the only library + we depend on is Xlib, R4 or later. +
+ The main thing I know that crashes OW 2.0 is the code where we call + GrabKey specifying AnyKey. You can either loop over all of the + keys, or you can just comment out the call; programs won't run exactly + the same, but you probably won't notice the difference. +
Index: m3/pm3/intro/src/questions/ptf.html diff -c /dev/null m3/pm3/intro/src/questions/ptf.html:1.1.1.1 *** /dev/null Tue Feb 10 23:29:05 1998 --- m3/pm3/intro/src/questions/ptf.html Sat Jan 31 14:47:15 1998 *************** *** 0 **** --- 1,21 ---- +
Can I get Modula-3 other than by FTP or HTTP? +Can I get Modula-3 other than by FTP or HTTP?
++ Prime Time Freeware (PTF) includes Modula-3. PTF is + a set of two ISO-9660 CDroms filled with 3GB of freeware, issued + semi-annually. PTF is distributed via bookstores and + mail. You can reach PTF using: +
+
+ Email: ptf@cfcl.com + Fax: [1] (408) 738 2050 + Voice: [1] (408) 738 4832 + Mail: Prime Time Freeware + 415-112 N. Mary Ave., Suite 50 + Sunnyvale, CA 94086 + USA
+ ++ Many Linux CDroms include a copy of the FTP site tsx-11.mit.edu which + has Linux binaries for Modula-3. + Index: m3/pm3/intro/src/questions/questions.html diff -c /dev/null m3/pm3/intro/src/questions/questions.html:1.2 *** /dev/null Tue Feb 10 23:29:06 1998 --- m3/pm3/intro/src/questions/questions.html Tue Feb 10 22:41:10 1998 *************** *** 0 **** --- 1,41 ---- + +
+Modula-3 Frequently asked questions and answers + + +Modula-3 Frequently asked questions and answers
++
-
+
- How to call Modula-3 procedures from a C program? +
- Why are there strange pragmas for Locking levels and other properties? +
- Where to find Modula-3 books? +
- Comparisons between Modula-3 and other languages? +
- Can I contribute Modula-3 software? +
- How to copy heap objects? +
- Can Modula-3 code call C++ and vice-versa? +
- Why program receives a SEGV signal under the debugger? +
- How to get output messages to appear immediately (flushing writers)? +
- What implementations are available, how do they compare? +
- Why objects and interfaces? +
- Where can I get documents and information on Modula-3? +
- Is Modula-3 a superset of Modula-2? +
- M3build versus Make or why m3 does not work? +
- What means Missing RTHooks or similar messages? +
- Can a program recover from running out of virtual memory? +
- Why are exceptions raised by X or Network Objects applications? +
- What is the purpose of BRANDED and REVEAL? +
- What is the story with Trestle and OpenWindows? +
- Can I get Modula-3 other than by FTP or HTTP? +
- How to read a single character as soon as typed? +
- Why is Hello World so large? +
- What is SRC Modula-3? +
- Is commercial support available? +
- Why uppercase keywords? +
- Why CONST Comments in Variables Declarations? +
- Problems with threads, fork and VTALARM? +
- What is Modula-3? +
- Where is Modula-3 used? Is it used in industry? +
- X libraries not found? +
How to read a single character as soon as typed? + + +How to read a single character as soon as typed?
+ ++ Characters typed on the keyboard are usually buffered. They + become visible to the reading program only when the buffer is + full or after, for example, a carriage return is received. + This is not specific to Modula-3. To access the characters as + they are typed, single character commands in a full screen + editor for example, the input reader must be configured properly. +
+ From: rrw1000@cus.cam.ac.uk (Richard Watts)
+ ++ The POSIX way of doing it is to use tcsetattr(), and here is some + code that does it under Solaris 2.x (this was written for serial ports, + but the same thing applies) : +
++ PROCEDURE Open(port : CHAR; timeout : INTEGER := 30) : T RAISES {Error} = + VAR + term : TcPosix.termios; + file : TEXT; + fd : T; + rc : INTEGER; + BEGIN + (* Figure out which device we want to open : *) + + CASE port OF + 'A' => file := "/dev/ttya"; + | 'B' => file := "/dev/ttyb"; + ELSE RAISE Error("Invalid port " & Fmt.Char(port) & " specified.\n"); + END; + + (* Open it. 700 is a good default mode for serial ports. *) + fd := Unix.open(M3toC.TtoS(file), Unix.O_RDWR + , 8_700); + IF fd = -1 THEN + RAISE Error("Open() on " & file & " failed.\n"); + END; + + (* Get the termios structure for it *) + rc := TcPosix.tcgetattr(fd, ADR(term)); + IF rc # 0 THEN + EVAL Unix.close(fd); + RAISE Error("Couldn't get terminal attributes for " & file & ".\n"); + END; + + (* Modify the termios structure *) + + (* The default baud rate is right, but we'd better set it anyway + in case someone left it set up wrong : *) + rc := TcPosix.cfsetospeed(ADR(term), TcPosix.B9600); + + IF rc # 0 THEN + EVAL Unix.close(fd); + RAISE Error("Couldn't set output speed for " & file & "\n"); + END; + + rc := TcPosix.cfsetispeed(ADR(term), TcPosix.B9600); + + IF rc # 0 THEN + EVAL Unix.close(fd); + RAISE Error("Couldn't set input speed for " & file & "\n"); + END; + + (* Modify the line discipline - reset ECHO and ICANON *) + term.c_lflag := Word.And( term.c_lflag, + Word.Not( + Word.Or(TcPosix.ICANON, + TcPosix.ECHO))); + term.c_cc[TcPosix.VMIN] := 0; + term.c_cc[TcPosix.VTIME] := 0; (* Set up timing right *) + + (* Now reset the terminal attributes *) + rc := TcPosix.tcsetattr(fd, TcPosix.TCSANOW, ADR(term)); + + IF rc # 0 THEN + EVAL Unix.close(fd); + RAISE Error("Can't set attributes for " & file & "\n"); + END; + RETURN fd; + END Open; +++ (TcPosix.i3 is one of my interfaces, not libm3's, and I'll supply + it if you like, but it's just a wrapper to tcgetattr and friends. The + baud rate stuff shouldn't be necessary for terminals (or serial + ports..) ). You should be able to somehow get an Rd.T out of this, + I think, but it may involve a bit of hacking. + The University of Cambridge can't have these opinions even if it wants them. + + + Index: m3/pm3/intro/src/questions/size.html diff -c /dev/null m3/pm3/intro/src/questions/size.html:1.1.1.1 *** /dev/null Tue Feb 10 23:29:06 1998 --- m3/pm3/intro/src/questions/size.html Sat Jan 31 14:47:15 1998 *************** *** 0 **** --- 1,14 ---- +
Why is Hello World so large? +Why is Hello World so large?
++ Modula-3 programs are larger than C programs for the following reasons: +
+
- The fixed runtime is substantially larger. It contains a + garbage collector, a thread runtime, and exception support. + Note that Hello World is virtually all runtime. For + larger programs the runtime is not an issue. +
- The generated code includes runtime checks for out-of-bound + array references and NIL pointer. Many of these checks could + be removed by a more sophisticated compiler. +
Index: m3/pm3/intro/src/questions/srcm3.html diff -c /dev/null m3/pm3/intro/src/questions/srcm3.html:1.1.1.1 *** /dev/null Tue Feb 10 23:29:06 1998 --- m3/pm3/intro/src/questions/srcm3.html Sat Jan 31 14:47:15 1998 *************** *** 0 **** --- 1,53 ---- + +
+What is SRC Modula-3? + + +What is SRC Modula-3?
+ ++ SRC-Modula-3 + was built by the DEC Systems Research Center and is freely available and + redistributable, with source code. + In Europe it is also available from + ftp-i3.informatik.rwth-aachen.de in pub/Modula-3. + The most recent version is release 3.6 +
+ The DEC SRC Modula-3 contains the following: +
+
- A native code compiler: uses the GCC backend; on machines/operating
+ systems that have self-describing stacks, an optimized exception
+ handling mechanism is provided, on other architectures,
+ setjmp/longjmp is used. A very fast integrated backend is available
+ on some platforms (currently NT386 and Linux i386).
+
+ The compilation system provides for minimal recompilation. + Only those units that depend on the modified interface item + will be recompiled. +
- m3build: tool that performs dependency analysis and + builds the Modula-3 programs and libraries. +
- m3gdb: a Modula-3 aware version of GDB. +
- Several tools for performance and coverage analysis. +
- A large standard library (libm3) providing
+
+
- A multithread, incremental, generational, conservative garbage + collector +
- Text manipulation. +
- Generic Containers: Lists, Sequences, Tables, SortedLists, SortedTables +
- Atoms and Symbolic expressions (Lisp like lists) +
- An extensible stream IO system +
- Typesafe binary object transcription (persistent objects) +
- Operating system interfaces +
- Portable interfaces to the language runtime +
+ All standard libraries are thread-friendly. + Modula-3 can readily link with existing C libraries; many libraries + including X11R4 and various UNIX libraries are available as + part of libm3. +
- Several other libraries for designing graphical user interfaces + and distributed applications. +
Is commercial support available? +Is commercial support available?
++ Critical Mass Corporation offers an integrated development environment + for Modula-3, Reactor, + as well as training and consulting services. +
+ Index: m3/pm3/intro/src/questions/uppercase.html diff -c /dev/null m3/pm3/intro/src/questions/uppercase.html:1.1.1.1 *** /dev/null Tue Feb 10 23:29:06 1998 --- m3/pm3/intro/src/questions/uppercase.html Sat Jan 31 14:47:15 1998 *************** *** 0 **** --- 1,10 ---- +
Why uppercase keywords? +Why uppercase keywords?
++ Some people prefer uppercase keywords others hate them. Another possibility + is to accept both forms for keywords. This topic has been discussed at length + and there is no solution that will completely satisfy everyone's tastes. + Fortunately this is a very minor issue and you can easily have lowercase + keywords automatically converted for you using an emacs macro package like + m3su . +
Index: m3/pm3/intro/src/questions/varconst.html diff -c /dev/null m3/pm3/intro/src/questions/varconst.html:1.1.1.1 *** /dev/null Tue Feb 10 23:29:06 1998 --- m3/pm3/intro/src/questions/varconst.html Sat Jan 31 14:47:15 1998 *************** *** 0 **** --- 1,58 ---- +
Why CONST Comments in Variables Declarations? +Why CONST Comments in Variables Declarations?
++ John Kominek (kominek@links.uwaterloo.ca) wrote: + Sprinkled throughout SRC m3 you'll find "constant" variables exported + in interfaces. For instance, +
+ VAR (*CONST*) Grain: LONGREAL; +
++ where Grain is assigned during module initialization. + Instead, did the modula-3 designers consider doing this. +
+ READONLY Grain: LONGREAL; +
++ Here the keyword permits only exporting modules to modify the + Grain variable. Is there a problem with this proposal? The READONLY + keyword is successfully used at procedure boundaries, so why not + also at interface boundaries? +
+ Bill Kalsow replies: +
+ A problem with this proposal is that any module can claim to export + the interface containing the variable, hence any module could modify + the variable. + Note that CONST says more than just READONLY. CONST implies that the + variable should not be modified by clients and that once it is + initialized, it won't be changed later by the implementation. + READONLY would only mean that clients should not modify the variable. + IMO, the "right" solution would have been to allow: +
+ INTERFACE Foo; + CONST x: T; + + MODULE Foo; + CONST x: T := <value>; +
++ In the same way it checks revelations for opaque types, the compiler + could check that only one module provided a value for the constant. + But, this proposal doesn't quite hang together either. + Consider this example: +
+ CONST x: INTEGER; + VAR v: [0..x]; +
++ The language definition says that "v"s definition is illegal if "x < 0" + because its type is "empty". The system could refuse to run the + program by delaying the check until it had seem the corresponding + implementation module. But, I think you'll agree that it could + quickly turn into a mess. + The most flexible handling of opacity I've seen is in Christian + Collberg's PhD Thesis, "Flexible Encapsulation". It was published Dec + 5, 1992 by the CS Dept at Lund University, Lund Sweden. If I remember + correctly, his system was capable of deferring all checks and + decisions imposed by opaque declarations until link time. Index: m3/pm3/intro/src/questions/vtalarm.html diff -c /dev/null m3/pm3/intro/src/questions/vtalarm.html:1.1.1.1 *** /dev/null Tue Feb 10 23:29:06 1998 --- m3/pm3/intro/src/questions/vtalarm.html Sat Jan 31 14:47:15 1998 *************** *** 0 **** --- 1,12 ---- +
Problems with threads, fork and VTALARM? +Problems with threads, fork and VTALARM?
++ The threads are implemented using the virtual timer interrupt. Normally, + the run time environment will catch the interrupt and determine if + thread switching is appropriate. However, if a new process is created with + fork, it will have the virtual timer activated and no interrupt handler + to receive it, resulting in a core dump. If you use the standard procedure + Process.Create to fork new processes, this will be handled automatically + for you. If you insist on using fork, you need to disable the timer, + fork and then reenable the timer. +
Index: m3/pm3/intro/src/questions/whatism3.html diff -c /dev/null m3/pm3/intro/src/questions/whatism3.html:1.1.1.1 *** /dev/null Tue Feb 10 23:29:06 1998 --- m3/pm3/intro/src/questions/whatism3.html Sat Jan 31 14:47:15 1998 *************** *** 0 **** --- 1,29 ---- + +
+What is Modula-3? + + +What is Modula-3?
+ ++ Modula-3 is a systems programming language that descends from Mesa, + Modula-2, Cedar, and Modula-2+. It also resembles its cousins + Object Pascal, Oberon, and Euclid. + +
The goal of Modula-3 is to be as simple and safe as it can be while + meeting the needs of modern systems programmers. Instead of + exploring new features, we studied the features of the Modula + family of languages that have proven themselves in practice and + tried to simplify them into a harmonious language. We found that + most of the successful features were aimed at one of two main + goals: greater robustness, and a simpler, more systematic type + system. + +
+ Modula-3 retains one of Modula-2's most successful features, the + provision for explicit interfaces between modules. It adds objects + and classes, exception handling, garbage collection, lightweight + processes (or threads), and the isolation of unsafe features. + + + Index: m3/pm3/intro/src/questions/whereused.html diff -c /dev/null m3/pm3/intro/src/questions/whereused.html:1.1.1.1 *** /dev/null Tue Feb 10 23:29:06 1998 --- m3/pm3/intro/src/questions/whereused.html Sat Jan 31 14:47:15 1998 *************** *** 0 **** --- 1,17 ---- + +
+Where is Modula-3 used? Is it used in industry? + + +Where is Modula-3 used? Is it used in industry?
+ ++ A number of programming teams selected Modula-3 for + industrial and research projects, and for teaching. It encourages good + programming practices and comes with excellent libraries for + distributed programming and graphical user interfaces. + A non exhaustive list is available at + [Modula-3 at Work]. + + + Index: m3/pm3/intro/src/questions/xnotfound.html diff -c /dev/null m3/pm3/intro/src/questions/xnotfound.html:1.1.1.1 *** /dev/null Tue Feb 10 23:29:06 1998 --- m3/pm3/intro/src/questions/xnotfound.html Sat Jan 31 14:47:15 1998 *************** *** 0 **** --- 1,11 ---- +
X libraries not found? +X libraries not found?
++ The position of X libraries is stored, for instance for + pre-compiled PM3 LINUXELF binaries, in the template file + m3config/src/LINUXELF as well as in X11/LINUXELF/.M3EXPORTS + (m3build/templates/LINUXELF, and X11R4/LINUXELF/.M3EXPORTS for + SRC-M3). + Thus you may want to edit these files if your X libraries are + located in an uncommon place. +
Index: m3/pm3/language/m3obliq/src/index.html diff -c /dev/null m3/pm3/language/m3obliq/src/index.html:1.2 *** /dev/null Tue Feb 10 23:29:14 1998 --- m3/pm3/language/m3obliq/src/index.html Tue Feb 10 22:56:00 1998 *************** *** 0 **** --- 1,79 ---- +
+Obliq a lightweight language for network objects + + + ++ Michel Dagenais + Michel Dagenais, GNU General Public License, 1998 + + michel.dagenais@polymtl.ca+
+ Ecole Polytechnique
+ C.P. 6079, Succ. Centre-Ville
+ Montreal, Quebec, H3C 3A7 + 18 January 1998 + interpreter + distributed + language + clone + agent +Obliq a lightweight language for network objects
+ +++ ++ Libraries and interpreters for the Obliq language. + Obliq may be described as: + +
+
+Obliq is a small, statically scoped, untyped language. It is + object-oriented, higher-order, and distributed. State is + local to an address space, while computation can migrate + over the network. The distributed computation mechanism is + based on Modula-3 Network Objects. +
-
+
- obliq
- + The main obliq interpreter. +
- visualobliq
- + A visual programming environment for obliq. +
- vocgi
- + Support for executing visual obliq programs in web servers +
- vorun
- + Support for starting visual obliq programs. +
- voquery
- + Simple application used by vorun. +
- obliqbin3D
- + Obliq interpreter with the anim3D module. +
- obliqbinanim
- + Obliq interpreter with the anim (2D) module. +
- obliqbinmin
- + Obliq interpreter with no optional module. +
- obliqbinstd
- + Obliq interpreter with the standard library module. +
- obliqbinui
- + Obliq interpreter with the trestle (ui) module. +
- obliqlib3D
- + Library for interfacing anim3D to obliq. +
- obliqlibanim
- + Library for interfacing anim (2D) to obliq. +
- obliqlibm3
- + Library for interfacing libm3 to obliq. +
- obliqlibui
- + Library for interfacing trestle to obliq. +
- obliqparse
- + Library for parsing obliq code. +
- obliqprint
- + Library for printing obliq values. +
- obliqrt
- + Obliq run time. +
- obliqsrvstd
- + Obliq computation server with standard libraries. +
- obliqsrvui
- + Obliq server with trestle. +
Quake + + + +=Quake
+ ++ Quake is a simple, specialized + language drawing on elements of the C language, the + Bourne shell, and the C pre-processor. +
+ + Quake was designed to be a component of + m3build. + Building a complete, general-purpose language was not + one of the goals. M3build + reads a set of quake language templates that define some + operators, then executes an m3makefile in this context. The templates + define procedures to build lists of modules, libraries, and so on. + +
Values
++ + Quake is designed to make it easy to assemble arrays and tables of + strings. The value space is strings, arrays of strings, and tables of + strings. An array is a list of elements, and a table is a set of + key/value pairs where the keys in a table are all distinct. +
+ +
Strings
++ + A string is a sequence (delimited by `"') of characters excluding + newline and double quote. Several special characters may be quoted + (with `\') as follows: +
+ new-line ignored + \\ \ + \n new-line + \r return + \t tab + \b backspace + \f formfeed + \" double quote +
++ +
Arrays
++ + An array is constructed using `[' and `]'. `[]' is the empty array, + `["a"]' is an array of the single string "a". Elements are separated by + `,'. Thus `["a", "b"]' is an array of two elements---the strings "a" + and "b". +
+ + Arrays are flattened whenever they are referenced. This means that + `["a", ["b", "c"]]' is converted the the array `["a", "b", "c"]'. This + means that an array can never be the element of another array. +
+ + Arrays are accessed by an integer index. `a[2]' is the third element of + the array a. The index expression may also be a string which will be + converted to an integer. The range of the index is checked at run-time. +
+ +
Tables
++ + A table is constructed using `{' and `}'. `{}' is the empty table. + Elements of a table are given as key/value pairs. An empty value may be + omitted. `{"a", "b"}' is a table containing two keys---the strings "a" + and "b". `{"p" : "q"}' is the constructor for a table with the single + key "p" whose value is the string "q". Missing values are returned as + "". +
+ + Tables are accessed using expressions of the form `s{"a"}'. This + evaluates to the value of the key "a" in the table s. +
+ +
Names
++ + Names in quake start with an letter (`a'..`z', `A'..`Z') or an + underscore (`_'), followed by those characters, digits (`0'..`9'), + hyphens (`-'), or periods (`.'). +
+ + If the lookup for a name fails (it is undefined in any of the enclosing + scopes) it is installed in the current scope with an initial string + value of the text of the name. +
+ +
Comments
++ + C-style comments are supported (delimited by `/*' and `*/') and do not + nest. +
+ + Single-line comments are introduced with `%' and terminated with a new-line. +
+ +
Conditionals
++ + A Boolean value is represented as a string. The empty string is false, + and any other string is true. +
+ +
Expressions
++ + An expression is: +
+ string: "baz" + name: foo + environment variable: $CPU_TYPE + array selector: array[5] + array constructor: ["a", "b"] + table selector: t{"a"} + table constructor: {"a" : "p", b} + function call: f(a, "b") + parentheses: a and (b or f(c)) +++ + Operators are all left-associative, precedence is decreases from top to + bottom in the following list. +
+ & string catenation (`"Hello, " & foo') + contains table inclusion (`s contains "a"') + not logical negation (`not a') + and logical conjunction (`c and not d') + or logical disjunction (`a or b') +
++ + A note on string catenation. Operands of `&' are converted to strings + whenever required and possible. Arrays and tables are converted to + strings by catenating their elements (for tables, their keys) separated + by a single spaces. For example, the expression +
+ "a" & " " & ["b", "c"] +
+evaluates to the string "a b c". + +
Statements
++ + A statement is either an assignment, a procedure definition, a procedure + invocation, a conditional statement, or a loop. + +
Assignment
++ Assign an expression (the string "bar") to the variable `foo' with +
+ foo = "bar" +
++ + If `foo' already exists, and is an array, then +
+ foo += "baz" +
+extends the array to include a new final element; the string "baz". + + +
Scope
++ + Quake has a global name space, but local scopes are always introduced + when a procedure is called, and a `foreach' loop is executed. +
+ + Scopes are searched from innermost to outermost each time a name is + looked up. The outermost scope is always the global scope. +
+ + Assignments can be made local to the innermost scope by prefixing the + assignment statement with the keyword `local'. For example, +
+ local foo = "bog" +
+In which case the values of any other instances of `foo' in other scopes + are hidden. The previous value of `foo' is restored once the local scope + is released by exiting the procedure or `foreach' loop. +
+ + To protect a name in the current scope, use +
+ readonly dec = "digital" +
+ +Procedures
++ + Procedures may be defined in the global scope only. Here is the + definition of a procedure `simple', taking two arguments bound to the + local names `prefix' and `suffix' in the procedure's local scope. +
+ proc simple(prefix, suffix) is + q = prefix & "." & suffix + end +
++ The string `prefix & "." & suffix' is assigned to the global variable + `q'. +
+ + This procedure can then be invoked with +
+ simple("Hello", "m3") +++ + Procedures can return values, in which case they become functions. For + example, +
+ proc combine(prefix, suffix) is + return prefix & "." & suffix + end +
+defines a function `combine' which catenates and returns the three + strings `prefix', ".", and `suffix'. Now the function `combine' can be + used in an expression, for example +
+ q = combine("Hello", "m3") ++assigns the string "Hello.m3" to `q'. + +
Conditional Statements
++ + Values may be tested using the `if' statement. For example, +
+ if compiling + message = "compiling" + end +
++ + If statements may have an else part, for example +
+ if not (ready or interested) + return + else + message = "congratulations" + end +
+returns from the current procedure if the test succeeds, otherwise + executes the assignment statement. + +
Loops
++ + `Foreach' statements iterate over the string values in an array or in a + table. For example, +
+ foreach file in [".login", ".profile", ".Xdefaults"] + write("Copying " & file & " to " & backup_dir & "0) + copy_file(file, backup_dir) + end ++binds the name `file' to each of ".login", ".profile", and ".Xdefaults" + in turn in a local scope. This example assumes that the procedures + `copy_file', and the variable `backup_dir' have already been defined. +
+ + Here is a function `squeeze' to remove duplicates from an array +
+ proc squeeze(array) is + local t = {} + + foreach i in array + t{i} = "" + end + + return [t] + end +++ +
Keywords
++ + Here is a list of reserved words in quake: +
+ and contains else end foreach if in + is local not or proc readonly return +
+ +Built-in Procedures
++ + Quake has a small collection of built-in procedures. Built-ins cannot + be redefined. The built-ins `write' and `exec' are variadic. + +
-
+
+
- write(...) + Writes its arguments to the current output stream. Unlike the + conversion of arrays to strings, there are no extra spaces inserted + between arguments. + +
- error(...) + Writes its argument to the standard error stream and stops running + quake with an error return value. + +
- include(file) + The contents of `file' is interpreted by quake in place of the call + to `include'. This is analogous the `#include' directive in the C + preprocessor. Calls to `include' nest until you run out of file + descriptors or something equally bad. + +
- cp_if(src, dest) + If the file `src' differs from the file `dest', or `dest' is missing, + copy `src' to `dest'. +
Built-in Functions
+ +-
+
- arglist(pfx, array)
+ This function may be used to avoid the problems of limited space
+ for argument lists in some command interpreters. Some commands
+ (notably `m3', the Modula-3 driver program) are prepared to accept
+ arguments from a file. The syntax for this is `-Ffile'.
+
+ + Thus, `arglist("-F", really_huge_array)' + returns either the original array if it's not really all that huge, + or it creates a temporary file containing a list of the strings in + the array (one to a line) and returns the string "-Ftemp" where + `temp' is the name of the temporary file. + +
- defined(foo) + Returns true if `foo' is defined, otherwise returns false. Remember + that the Boolean values false and true are represented as empty and + non-empty strings respectively. In this example, `foo' looks like + a name, and is evaluated before begin passed to `defined'. So if + you really want to find out whether `foo' is defined, use + `defined("foo")'. + +
- empty(foo) + Returns true if the string, array, or table is empty, false + otherwise. + +
- equal(foo, bar) + Returns true if the strings `foo' and `bar' are equivalent. + +
- exec(cmd,io,wd,env) + executes the child process specified in cmd and returns the child + return code. Cmd is an array containing the executable command followed + by the individual command line arguments. The following arguments + are optional. An array of file names is used for io to specify + the standard input, output and error. Empty names refer to the + existing standard files. When wd is present, it specifies the + working directory. Finally, env is a vector of text which must have + the form "NAME=VALUE". + +
- escape(s) + Returns the string `s' with backslash characters doubled. + +
- format(s, a...) + Returns the string `s' with each instance of `%s' replaced by + successive `a' arguments. The number of `a' arguments + must match the number of `%s's. + +
- normalize(p, q) + If the path `p' is a prefix of the path `q', returns the path + from directory `p' to file `q'. Otherwise, returns `q'. + +
- path() + Returns the directory of the currently executing file as a string. + +
- stale(target, deps) + `target' is interpreted as a file name, as is `deps' (or the + elements of `deps' if it's an array). If the files `target' or + `deps' cannot be found, or if (one of) `deps' is more recent than + `target', `stale' returns true, otherwise false. + +
- unlink_file(f) + Deletes the file `f'. +
Output Redirection
+ ++ Output (from the `write' built-in procedure) may be temporarily + redirected as follows: +
+ > "foo.txt" in + write("Hello, world0) + end ++The output of the calls to `write' is written to the file `foo.txt'. + +
+ Output may be appended to a file by using `>>' in place of `>'. + +
+ The special file names `_stdout' and `_stderr' are special and are bound + to the file descriptors corresponding to normal and error terminal + output respectively. + +
+ The default for output is the normal terminal stream. + +
Notes
++ + Quake does not garbage collect. Reckless copying of large arrays can + bloat the heap. + +
Author
++ + + Stephen Harrison + (sharrison@broadvision.com). +
+ + + + + Index: m3/pm3/language/modula3/m3compiler/m3bootstrap/src/m3makefile diff -c m3/pm3/language/modula3/m3compiler/m3bootstrap/src/m3makefile:1.5 m3/pm3/language/modula3/m3compiler/m3bootstrap/src/m3makefile:1.6 *** m3/pm3/language/modula3/m3compiler/m3bootstrap/src/m3makefile:1.5 Tue Jan 27 15:25:35 1998 --- m3/pm3/language/modula3/m3compiler/m3bootstrap/src/m3makefile Tue Feb 10 22:56:19 1998 *************** *** 55,60 **** --- 55,66 ---- % Write the global bootstrap makefile readonly proc CreateMakefile(file,target,header,options) is + local exportrpath = "-DEXPORTRPATH=binaries/" & target + + if equal(target,"NT386GNU") + exportrpath = "-DEXPORTRPATH=binaries\\\\" & target + end + > file in write(header,CR,CR) *************** *** 69,75 **** write("exportpackages:", CR) write("\tboot-" & target & "/" & "m3build" & "/" & target & "/" & "m3build -T ../m3config/src -DRECURSIVE -DBOOTSTRAP=TRUE " & ! "-DEXPORTRPATH=binaries/" & target , CR, CR) write("boot:", CR) WriteMakefileLine("m3core",target,options) --- 75,81 ---- write("exportpackages:", CR) write("\tboot-" & target & "/" & "m3build" & "/" & target & "/" & "m3build -T ../m3config/src -DRECURSIVE -DBOOTSTRAP=TRUE " & ! exportrpath, CR, CR) write("boot:", CR) WriteMakefileLine("m3core",target,options) *************** *** 224,231 **** else write("option(\"optimization\",\"T\")",CR) end ! write("option(\"debuginfo\",\"\")",CR) write("HOST=\"" & host & "\"",CR) write("setDefault(\"\",\"\")",CR) write("BACKEND=[\"" & path() & SL & ".." & SL & host & SL & "pm3-" & target & SL & "m3cgc1-" & target & --- 230,238 ---- else write("option(\"optimization\",\"T\")",CR) end ! write("option(\"debuginfo\",\"" & BOOTDEBUG & "\")",CR) write("HOST=\"" & host & "\"",CR) + write("USE_M3DOC=\"\"",CR) write("setDefault(\"\",\"\")",CR) write("BACKEND=[\"" & path() & SL & ".." & SL & host & SL & "pm3-" & target & SL & "m3cgc1-" & target & *************** *** 240,245 **** --- 247,253 ---- % Build all the packages required for m3build and m3ship % to obtain a bootstrap m3build and m3ship. + BootstrapPkg("../../../../../text/sgmltools","m3doc",target,host) BootstrapPkg("../../../../../libs","m3core",target,host) BootstrapPkg("../../../../../libs","libm3",target,host) BootstrapPkg("../..","m3middle",target,host) *************** *** 251,256 **** --- 259,265 ---- BootstrapPkg("../../../../..","m3config",target,host) BootstrapPkg("../..","m3build",target,host) BootstrapPkg("../..","m3ship",target,host) + CleanPkg("m3doc",target) CleanPkg("m3core",target) CleanPkg("libm3",target) CleanPkg("m3middle",target) *************** *** 272,278 **** if equal(target,"NT386GNU") header = header & ! "EXTRALIBS=-lkernel32 -luser32 -lgdi32 -ladvapi32 -lnetapi32 -lm" & CR else header = header & "EXTRALIBS=-lm" & CR end --- 281,287 ---- if equal(target,"NT386GNU") header = header & ! "EXTRALIBS=-ladvapi32" & CR else header = header & "EXTRALIBS=-lm" & CR end *************** *** 299,304 **** --- 308,314 ---- % CACHE_CROSS_COMPILERS = lookup("CACHE_CROSS_COMPILERS","") + BOOTDEBUG = lookup("BOOTDEBUG","") if defined("BOOTTARGET") BootstrapTarget(BOOTTARGET) Index: m3/pm3/language/modula3/m3compiler/m3build/src/index.html diff -c /dev/null m3/pm3/language/modula3/m3compiler/m3build/src/index.html:1.2 *** /dev/null Tue Feb 10 23:29:20 1998 --- m3/pm3/language/modula3/m3compiler/m3build/src/index.html Tue Feb 10 22:56:26 1998 *************** *** 0 **** --- 1,51 ---- + +
+m3build + + + +m3build
+ ++ The Modula-3 compiler, m3build, contains a + quake + interpreter to process platform dependent templates and package + descriptions, m3makefile. It performs a much finer grained + dependency analysis than make, thus reducing + needless recompilation. + +
-
+
- Packages +
- m3build command line options +
- Error reporting +
- Package descriptions in m3makefiles +
- A simple example +
- m3build processing steps +
- A tour of the compiler internals +
+ When SRC Modula-3 is configured and installed, several public + repositories are identified. In these web pages we refer to them with + the following short names: + +
-
+
- /bin
- shared executable programs (e.g. /usr/local/bin). +
- /lib
- shared libraries (e.g. /usr/local/lib/m3/LINUXELF). +
- /doc
- shared documentation (e.g. /usr/local/lib/m3/doc). +
- /pkg
- public packages (e.g. /usr/local/lib/m3/pkg). +
- /emacs
- shared gnuemacs lisp code (e.g. /usr/local/lib/elisp). +
- /man
- installed man pages (e.g. /usr/local/man). +
- /html
- installed HTML sources (e.g. /usr/local/lib/m3/www). +
+ Last modified on Thu Mar 7 18:08:53 PST 1996 by heydon + modified on Fri Jul 22 07:57:04 PDT 1994 by kalsow + modified on Wed May 19 11:36:32 PDT 1993 by mjordan + modified on Tue Oct 13 16:39:21 PDT 1992 by muller + modified on Tue Sep 22 08:36:57 PDT 1992 by mhb +
+ + + Index: m3/pm3/language/modula3/m3compiler/m3build/src/m3makefile diff -c m3/pm3/language/modula3/m3compiler/m3build/src/m3makefile:1.6 m3/pm3/language/modula3/m3compiler/m3build/src/m3makefile:1.7 *** m3/pm3/language/modula3/m3compiler/m3build/src/m3makefile:1.6 Wed Dec 17 15:53:29 1997 --- m3/pm3/language/modula3/m3compiler/m3build/src/m3makefile Tue Feb 10 22:56:26 1998 *************** *** 8,17 **** --- 8,21 ---- import ("m3quake") import ("m3templates") import ("m3config") + import("m3doc") implementation ("Main") option("standalone","T") + + include_dir("html") + HtmlFile("index") Program ("m3build") Index: m3/pm3/language/modula3/m3compiler/m3build/src/html/build-generics.html diff -c /dev/null m3/pm3/language/modula3/m3compiler/m3build/src/html/build-generics.html:1.2 *** /dev/null Tue Feb 10 23:29:20 1998 --- m3/pm3/language/modula3/m3compiler/m3build/src/html/build-generics.html Tue Feb 10 22:56:30 1998 *************** *** 0 **** --- 1,138 ---- + + +Instantiating generics + + + +Instantiating generics
++ + These procedures generate derived interfaces and modules for + instantiating generic interfaces and modules, respectively. +
+ + build_generic_intf (nm, generic, args, vis) + Generate a derived interface named (in the file "nm.i3") that + instantiates the generic interface named "generic" with the + argument interfaces named in the list "args". The "vis" parameter + controls the visibility of the derived interface, and should + be one of the readonly constants
VISIBLEor +HIDDEN. ++ + build_generic_unsafe_intf (nm, generic, args, vis) + Like build_generic_intf, but the generated file + instantiates an
UNSAFEINTERFACE. ++ + build_generic_impl (nm, generic, args) + Generate a derived module name "nm" (in the file "nm.m3") that + instantiates the generic module named "generic" with the + argument interfaces named in the list "args". +
+ + build_generic_unsafe_impl (nm, generic, args) + Like build_generic_impl, but the generated file + instantiates an
UNSAFEMODULE. ++ +
Example
+ +The above quake procedures are most commonly used in quake templates + associated with packages that export generic interfaces and + implementations. For example, consider the template file "list.tmpl", + which provides procedures for instantiating the generic "List" and + "ListSort" interfaces and modules. First, the procedures for + instantiating "List": + +
+ readonly proc _list (nm, elt, vis) is + local list = nm & "List" + build_generic_intf (list, "List", [elt], vis) + build_generic_impl (list, "List", [elt]) + end + + readonly proc List (nm, elt) is _list (nm, elt, VISIBLE) end + readonly proc list (nm, elt) is _list (nm, elt, HIDDEN) end +
+ +The last two procedures are meant to be used by clients. They come + in two forms: "List" instantiates a visible interface, and "list" + instantiates a hidden one. These two procedures take the name to be + used for the prefix of the instantiated files and the name of the + actual interface to use in the instantiation. Often, "nm" and "elt" + will be the same, but this design allows "nm" to be an abbreviated + form of the full interface name. For example, the standard lists are + instantiated by the following calls: + +
+ List ("Atom", "Atom") + List ("Int", "Integer") + List ("Ref", "Refany") + List ("Text", "Text") ++ +After these calls, a client can
IMPORTthe interfaces + namedAtomList,IntList, +RefList, andTextList. The m3makefile will + automatically generate the files named "AtomList.i3", "AtomList.m3", + "IntList.i3", IntList.m3", etc. in the derived directory. For example, + the contents of the file "IntList.i3" will be: + ++ (* generated by m3build *) + INTERFACE IntList = List (Integer) END IntList. +
+ +The "list.tmpl" template also defines procedures for instantiating + the generic "ListSort" interface: + +
+ readonly proc _list_sort (nm, elt, vis) is + local list = nm & "List" + local listsort = nm & "ListSort" + build_generic_intf (listsort, "ListSort", [elt, list], vis) + build_generic_impl (listsort, "ListSort", [elt]) + end + + readonly proc List_sort (nm, elt) is _list_sort (nm, elt, VISIBLE) end + readonly proc list_sort (nm, elt) is _list_sort (nm, elt, HIDDEN) end +
+ +These procedures are similar to the ones above except that the + generic "ListSort" interface takes two parameters: the first is + the interface that defines the type
Tused as the list's + element type, and the second is the name of theListtype + ranging over that type. + +There are analogous calls in the list package's m3makefile for + instantiating standard instances of this type: + +
+ List_sort ("Atom", "Atom") + List_sort ("Int", "Integer") + List_sort ("Ref", "Refany") + List_sort ("Text", "Text") ++ +This produces files named "AtomListSort.i3", "AtomListSort.m3", + "IntListSort.i3", "IntListSort.m3", etc. in the derived directory. + Here is the contents of the generated file "IntListSort.i3": + +
+ (* generated by m3build *) + INTERFACE IntListSort = ListSort (Integer, IntList) END IntListSort. +
+ +Several packages define new quake procedure for instantiating + generics, such as generic lists, queues, + sequences, and tables. To see how these are coded, look at the + ".tmpl" template files in the "src" directory of the relevant packages. +
+ +
+ Last modified on Mon Feb 12 17:08:02 PST 1996 by heydon +
+ + + Index: m3/pm3/language/modula3/m3compiler/m3build/src/html/compiler.html diff -c /dev/null m3/pm3/language/modula3/m3compiler/m3build/src/html/compiler.html:1.1.1.1 *** /dev/null Tue Feb 10 23:29:20 1998 --- m3/pm3/language/modula3/m3compiler/m3build/src/html/compiler.html Sat Jan 31 14:47:11 1998 *************** *** 0 **** --- 1,152 ---- + + +A tour of the compiler internals + + + +A tour of the compiler internals
++ + This section contains a brief introduction to the internal structure + of the compiler. This introduction is neither + comprehensive nor tutorial; it is merely intended as a stepping stone + for the courageous. +
+ + The compiler has undergone much evolution. It started as a project to + build a simple and easy to maintain compiler. Somewhere along the way + we decided to compile Modula-3. Much later we decided to generate C. + Now it generates native code directly. +
+ + The initial observation was that most compilers' data structures were + visible and complex. This situation makes it necessary to understand + a compiler in its entirety before attempting non-trivial enhancements + or bug fixes. By keeping most of the compiler's primary data + structures hidden behind opaque interfaces, we hoped to avoid this + pitfall. So far, bugs have been easy to find. During early + development, it was relatively easy to track the weekly language + changes. +
+ + The compiler is decomposed by language feature rather than the more + traditional compiler passes. We attempted to confine each language + feature to a single module. For example, the parsing, name binding, + type checking and code production for each statement is in its own + module. This separation means that only the CaseStmt module + needs to know what data structures exist to implement + CASE statements. + Other parts of the compiler need only know that the CASE + statement is a statement. This fact is captured by the object subtype + hierarchy. A CaseStmt.T is a subtype of a Stmt.T. +
+ + The main object types within the compiler are: values, statements, + expressions, and types. ``Values'' is a misnomer; ``bindings'' would + be better. This object class include anything that can be named: + modules, procedures, variables, exceptions, constants, types, + enumeration elements, record fields, methods, and procedure formals. + Statements include all of the Modula-3 statements. Expressions include + all the Modula-3 expression forms that have a special syntax. And + finally, types include the Modula-3 types. +
+ + The compiler retains the traditional separation + of input streams, scanner, symbol table, and output stream. +
+ + The compilation process retains the usual phases. Symbols are scanned + as needed by the parser. A recursive descent parser reads the entire + source and builds the internal syntax tree. All remaining passes + simply add decorations to this tree. The next phase binds all + identifiers to values in scopes. + Modula-3 allows arbitrary forward references so it is necessary + to accumulate all names within a scope before binding any identifiers + to values. The next phase divides the types into structurally + equivalent classes. This phase actually occurs in two steps. First, + the types are divided into classes such that each class will have a + unique C representation. Then, those classes are refined into what + Modula-3 defines as structurally equivalent types. After the types + have been partitioned, the entire tree is checked for type errors. + Finally, the IL is emitted. +
+ + The intermediate language is defined as a sequence of calls on an + M3CG.T object. In the compiler front end there is a thin + veneer interface, CG, that makes the actual calls. The veneer + converts between the bit-level addressing used in the front end + and the byte-level addressing used by the back ends. There are + several implementations of M3CG.T. The one that we + currently use is M3CG_Wr. It converts the stream of + calls into a parseable stream of ASCII characters. +
+ + The current back end is constructed as gcc front end. + It reads the M3CG output of the front end and produces + the tree structures needed by gcc's back end. +
+ + The front end is in the compiler package. + Within that package the following directories exist: +
+ builtinOps ABS, ADR, BITSIZE, ... + builtinTypes INTEGER, CHAR, REFANY, ... + builtinWord Word.And, Word.Or, ... + exprs +, -, [], ^, AND, OR, ... + main main program + misc scanner, symbol tables, ... + stmts :=, IF, TRY, WHILE, ... + types ARRAY, BITS FOR, RECORD, ... + values MODULE, PROCEDURE, VAR, ... +
++ + The intermediate language is in the m3cg package. +
+ + The back end is in the m3cc package. The single file that + implements the M3CG reader is gcc/m3.c. +
+ +
Linking
+ ++ SRC Modula-3 uses a special two-phase linker. + The first phase of the linker checks that all version stamps are + consistent. It then generates in m3main + declarations for the runtime type structures, + and initialization code for the collection of objects to be linked. + The second phases calls the host + system's linker to actually link the program. +
+ The information needed by the first phase is generated by the compiler + in a file ending in .m3x. + For every symbol X.Z exported or imported by a module, the + compiler generates a version stamp. + These stamps are used to ensure that + all modules linked into a single program agree on the type of X.Z. + The linker will refuse to link programs with inconsistent + version stamps. + +
File extensions
++ SRC Modula-3 uses files with the following customizable suffixes: + +
-
+
- .i3 (.m3)
- Modula-3 interface (module) sources. +
- .ig (.mg)
- generic interface (module) sources. +
- .ic (.mc)
- M3CG intermediate language files. +
- .is (.ms)
- intermediate assembly files. +
- .io (.mo)
- object files. +
- .c
- C source files. +
- .h
- C header files. +
- .s
- foreign assembly source files. +
- .o
- foreign object files. +
- .a
- library archives. +
- .m3x
- pre-linker information including version stamps. +
Emacs support + + + +Emacs support
++ + The following functions support building and installing + GNU emacs lisp code. +
+ + Gnuemacs(X) + exports source file X.el to /emacs. +
+ + CompiledGnuemacs(X) + exports the source file X.el and compiles and + exports the derived file X.elc to /emacs. +
+ +
+ Last modified on Thu Jan 4 11:07:55 PST 1996 by heydon + modified on Thu Jul 21 17:06:07 PDT 1994 by kalsow + modified on Thu Jan 7 18:40:57 PST 1993 by muller +
+ + + + Index: m3/pm3/language/modula3/m3compiler/m3build/src/html/errors.html diff -c /dev/null m3/pm3/language/modula3/m3compiler/m3build/src/html/errors.html:1.1.1.1 *** /dev/null Tue Feb 10 23:29:20 1998 --- m3/pm3/language/modula3/m3compiler/m3build/src/html/errors.html Sat Jan 31 14:47:11 1998 *************** *** 0 **** --- 1,25 ---- + + +Error reporting + + + +Error reporting
++ Errors encountered while processing the templates and m3makefiles + are immediately reported and stop m3build. + When processing the source files, (compiling to intermediate language, + translating to assembly, producing object code), if errors are encountered + they are reported and subsequent compilation phases for the offending file are + suppressed. The processing continues with the other files, + but the final link step is skipped. +
+ The compiler's error recovery is limited; it is often the case that errors + following the first one are bogus or redundant. + Error messages ending with a question mark are internal errors, and + probably represent compiler bugs. +
+ + + + Index: m3/pm3/language/modula3/m3compiler/m3build/src/html/example.html diff -c /dev/null m3/pm3/language/modula3/m3compiler/m3build/src/html/example.html:1.1.1.1 *** /dev/null Tue Feb 10 23:29:20 1998 --- m3/pm3/language/modula3/m3compiler/m3build/src/html/example.html Sat Jan 31 14:47:11 1998 *************** *** 0 **** --- 1,87 ---- + +
+A simple example + + + +A simple example
++ + Here's a simple program composed of a main module, + an imported interface and its implementation. +
+ + To begin, create a fresh directory for the package and within that + directory, a directory for the source files: +
+ > mkdir hello + > cd hello + > mkdir src +
++ + Create the following source files in the src directory: +
+ + In the file src/Main.m3: +
+ MODULE Main; + IMPORT A; + BEGIN + A.DoIt (); + END Main. +
++ + In the file src/A.i3: +
+ INTERFACE A; + PROCEDURE DoIt (); + END A. +
++ + In the file src/A.m3: +
+ MODULE A; + IMPORT Wr, Stdio; + + PROCEDURE DoIt () = + <*FATAL ANY*> + BEGIN + Wr.PutText (Stdio.stdout, "Hello world.\n"); + Wr.Close (Stdio.stdout); + END DoIt; + + BEGIN + END A. +
++ + In the file src/m3makefile: +
+ import ("libm3") + implementation ("Main") + module ("A") + program ("foo") +++ + Finally, from the package directory, hello, run + m3build. + If the compiler is installed correctly, + it will compile the three source files and link them with the + standard libraries. The derived files will be placed in a directory + that names the architecture. On a 80x86 Linux machine, + the directory is called LINUXELF. The executable program + will be named foo in the derived directory. + +
+ Last modified on Thu Jan 4 11:08:07 PST 1996 by heydon + modified on Tue Jan 3 07:38:22 PST 1995 by kalsow + modified on Thu Jan 7 18:40:57 PST 1993 by muller +
+ + + + Index: m3/pm3/language/modula3/m3compiler/m3build/src/html/exports.html diff -c /dev/null m3/pm3/language/modula3/m3compiler/m3build/src/html/exports.html:1.1.1.1 *** /dev/null Tue Feb 10 23:29:20 1998 --- m3/pm3/language/modula3/m3compiler/m3build/src/html/exports.html Sat Jan 31 14:47:11 1998 *************** *** 0 **** --- 1,72 ---- + + +Exporting files + + + +Exporting files
++ + These functions should be used to export files to the + public directories. +
+ + BinExport(X) + exports source file X to /bin. +
+ + BindExport(X) + exports derived file X to /bin. +
+ + DocExport(X) + exports source file X to /doc. +
+ + DocdExport(X) + exports derived file X to /doc. +
+ + EmacsExport(X) + exports source file X to /emacs. +
+ + EmacsdExport(X) + exports derived file X to /emacs. +
+ + HtmlExport(X) + exports source file X to /html. +
+ + LibExport(X) + exports source file X to /lib. +
+ + LibdExport(X) + exports derived file X to /lib. +
+ + ManExport(X,sec) + exports source file X.sec to section sec + of /man. +
+ + MandExport(X,sec) + exports derived file X.sec to section sec + of /man. +
+ + As mentioned earlier, + the actual paths bound to /bin, /lib, ... + depend on your installation's specific configuration. + +
+ Last modified on Thu Jan 4 11:07:54 PST 1996 by heydon + modified on Thu Jul 21 15:53:06 PDT 1994 by kalsow + modified on Thu Jan 7 18:40:57 PST 1993 by muller +
+ + + + Index: m3/pm3/language/modula3/m3compiler/m3build/src/html/foreign.html diff -c /dev/null m3/pm3/language/modula3/m3compiler/m3build/src/html/foreign.html:1.1.1.1 *** /dev/null Tue Feb 10 23:29:20 1998 --- m3/pm3/language/modula3/m3compiler/m3build/src/html/foreign.html Sat Jan 31 14:47:11 1998 *************** *** 0 **** --- 1,32 ---- + + +Importing foreign object files and libraries + + + +Importing foreign object files and libraries
++ + These procedures allow foreign objects and/or libraries to be included + in a Modula-3 program. +
+ + import_lib(X, P) + If P/libX.a is a library, includes -LP -lX + in the final link command. Otherwise, includes -lX + in the final link command. +
+ + import_obj(X) + Include X in the final link command. +
+ +
+ Last modified on Thu Jan 4 11:07:54 PST 1996 by heydon + modified on Mon Jun 20 14:51:17 PDT 1994 by kalsow + modified on Thu Jan 7 18:40:57 PST 1993 by muller +
+ + + + Index: m3/pm3/language/modula3/m3compiler/m3build/src/html/generics.html diff -c /dev/null m3/pm3/language/modula3/m3compiler/m3build/src/html/generics.html:1.2 *** /dev/null Tue Feb 10 23:29:20 1998 --- m3/pm3/language/modula3/m3compiler/m3build/src/html/generics.html Tue Feb 10 22:56:30 1998 *************** *** 0 **** --- 1,157 ---- + + +Generic support + + + +Generic support
++ + SRC Modula-3 includes both quake functions + you can use in your m3makefile for instantiating generics, and + basic type interfaces you can supply as + arguments to those functions. + +
Generic Instantiation Functions
+ +Many of the packages that export generic interfaces and modules + also define m3build procedures that will instantiate + the generic source and add it to the list of Modula-3 sources + to be compiled. The instantiated interfaces and modules are created in + the build directory, so they won't clutter up your source directory. +
+ + array_sort(nm, elt) + instantiates the ArraySort generics to produce + nmArraySort.i3 and nmArraySort.m3 which implement + a sort for arrays of elt.T values. +
+ + Array_sort(nm, elt) + like array_sort, but also makes the interface available + to importers outside the current package. +
+ + list(nm, elt) + instantiates the List generics to produce + nmList.i3 and nmList.m3 which implement + linked lists of elt.T values. +
+ + List(nm, elt) + like list, but also makes the interface available + to importers outside the current package. +
+ + list_sort(nm, elt) + instantiates the ListSort generics to produce + nmListSort.i3 and nmListSort.m3 which implement + a sorting procedure for lists of elt.T values. This + procedure assumes that list(nm,elt) has been called. +
+ + List_sort(nm, elt) + like list_sort, but also makes the interface available + to importers outside the current package. +
+ + pqueue(nm, elt) + instantiates the PQueue generics to produce + nmPQ.i3 and nmPQ.m3 which implement + a priority queue of elt.T values. +
+ + Pqueue(nm, elt) + like pqueue, but also makes the interface available + to importers outside the current package. +
+ + sequence(nm, elt) + instantiates the Sequence generics to produce + nmSeq.i3, nmSeqRep.i3 and + nmSeq.m3 which implement + a sequence of elt.T values. +
+ + Sequence(nm, elt) + like sequence, but also makes the interfaces available + to importers outside the current package. +
+ + sorted_table(nm, key, value) + instantiates the SortedTable generics to produce + nmSortedTbl.i3 and nmSortedTbl.m3 which implement + a sorted table mapping from type key.T to value.T. +
+ + Sorted_table(nm, key, value) + like sorted_table, but also makes the interface available + to importers outside the current package. +
+ + table(nm, key, value) + instantiates the Table generics to produce + nmTbl.i3 and nmTbl.m3 which implement + a table mapping from type key.T to value.T. +
+ + Table(nm, key, value) + like table, but also makes the interface available + to importers outside the current package. +
+ +
Interfaces for Basic Types
+ +Many generic interfaces, such as + Table + and + Sequence, + require one or more of their argument interfaces to have a certain + form. For example, the expect the principle type of the argument + interface to be named "
T", and they expect the interface + to define certain constants and procedures. The basic Modula-3 library + defines the following interfaces for basic types that can be used as + arguments to such generics (each interface's principle type is shown + in parentheses): + +-
+
-
+ Text
+ (
TEXT) + -
+ Atom
+ (
Atom.T) + -
+ Refany
+ (
REFANY) + -
+ Char
+ (
CHAR) + -
+ Boolean
+ (
BOOLEAN) + -
+ Integer
+ (
INTEGER) + -
+ RealType
+ (
REAL) + -
+ LongrealType
+ (
LONGREAL) +
But you aren't limited to these interfaces in your generic + instantiations. You can also supply your own interface as an argument + to a generic instantiation, so long as it meets all of the generic's + requirements. + +
+ Last modified on Wed Aug 21 14:23:18 PDT 1996 by heydon + modified on Thu Jun 1 08:18:55 PDT 1995 by kalsow + modified on Thu Jan 7 18:40:57 PST 1993 by muller +
+ + + + Index: m3/pm3/language/modula3/m3compiler/m3build/src/html/hiding.html diff -c /dev/null m3/pm3/language/modula3/m3compiler/m3build/src/html/hiding.html:1.1.1.1 *** /dev/null Tue Feb 10 23:29:20 1998 --- m3/pm3/language/modula3/m3compiler/m3build/src/html/hiding.html Sat Jan 31 14:47:11 1998 *************** *** 0 **** --- 1,51 ---- + + +Hiding and exporting + + + +Hiding and exporting
++ + The folowing procedures can be used in two ways. First to provide a + clearer indication of visibility than is given by the capitalization + convention (which exists partly to support old style m3makefiles). + Second, to change the visibility of imported components. + Generally, it's much better to convince the owners of the exporting + package to give their sources the correct visibility rather than + overriding their initial decision. +
+ + hide_interface(X) + sets the visibility of interface X.i3 to hidden. + +
+ + export_interface(X) + sets the visibility of interface X.i3 to visible. + +
+ + There are also variants that hide or export programs and generics, + hide_program, + hide_generic_interface, + hide_generic_implementation, + export_program, + export_generic_interface, + and + export_generic_implementation. +
+ + Hidden program are not copied to the /bin + directory, exported ones are. +
+ +
+ Last modified on Thu Jan 4 11:07:54 PST 1996 by heydon + modified on Thu Apr 21 16:49:58 PDT 1994 by kalsow + modified on Thu Jan 7 18:40:57 PST 1993 by muller +
+ + + + Index: m3/pm3/language/modula3/m3compiler/m3build/src/html/imports.html diff -c /dev/null m3/pm3/language/modula3/m3compiler/m3build/src/html/imports.html:1.1.1.1 *** /dev/null Tue Feb 10 23:29:20 1998 --- m3/pm3/language/modula3/m3compiler/m3build/src/html/imports.html Sat Jan 31 14:47:11 1998 *************** *** 0 **** --- 1,49 ---- + + +Importing packages + + + +Importing packages
++ + import(P) + The library and visible sources of package P are + available to satisfy IMPORT requests in the current + compilation. The imported sources are not recompiled. + +
+ + import_version(P, BuildDir) + Like import(P), but the library and visible sources of + package P are selected from building directory BuildDir + rather than the default building directory for the current platform. + +
+ + include_dir(D) + Recursively include the sources named in the m3makefile + in subdirectory D of the current directory. + +
+ + include_pkg(P) + Include the sources named in package P's + src/m3makefile. The location of P may be + overridden. +
+ + Import reflects the fact that programs are built from separately + compiled pieces, rather than being compiled as a whole. If we always + compiled from source, include would suffice. +
+ +
+ Last modified on Thu Jan 4 11:07:54 PST 1996 by heydon + modified on Thu Apr 21 16:47:18 PDT 1994 by kalsow + modified on Thu Jan 7 18:40:57 PST 1993 by muller +
+ + + + Index: m3/pm3/language/modula3/m3compiler/m3build/src/html/m3buildsteps.html diff -c /dev/null m3/pm3/language/modula3/m3compiler/m3build/src/html/m3buildsteps.html:1.2 *** /dev/null Tue Feb 10 23:29:20 1998 --- m3/pm3/language/modula3/m3compiler/m3build/src/html/m3buildsteps.html Tue Feb 10 22:56:31 1998 *************** *** 0 **** --- 1,88 ---- + + +m3build processing steps + + +m3build processing steps
++ When m3build is invoqued, it initializes the quake interpreter + with values for BUILD_DIR (defaults to the platform name unless + specified on the command line), PACKAGE (the name of the current + directory), and PACKAGE_DIR (the full path of the current directory). + The build_target is also defined as _build_target. + It defaults to all (_all), and clean is the other + typical value. +
+ The second step is to find and interpret the platform dependent template, + specified in BUILD_DIR. + The template directory may be specified on the command line, + in the M3TEMPLATES environment variable, and defaults to + m3config/src within the directory specified in PKG_USE + when m3build was compiled. As a last resort, directory + ../lib/m3/pkg/m3config/src is searched relative to the directory + where the m3build executable may be found. +
+ The next step is to insert all the definitions, + and to interpret all the files, specified as command + line options. +
+ At this point, a number of quake variables are extracted by the compiler + before the processing of the m3makefile starts. The host + and target in these descriptions refer to platform types and + differ only when cross compiling. + +
-
+
- NAMING_CONVENTIONS
- Vector containing all the host dependent + file extensions (.s, .c, .o, .exe...). +
- TARGET_NAMING_CONVENTIONS
- Vector containing all the target dependent + file extensions. +
- CRship
- End of line for .M3SHIP files. +
- SLship
- Path separator for .M3SHIP files. +
- PKG_USE, BIN_USE, LIB_USE
- Location of packages, program executables, + and libraries. +
- PKG_INSTALL, BIN_INSTALL, LIB_INSTALL, MAN_INSTALL, EMACS_INSTALL, + DOC_INSTALL, HTML_INSTALL
- Where to install packages, program + executables, libraries, man pages, emacs lisp files, postscript files, + and html files. In most cases the USE and INSTALL directories are the + same. +
- HOST_OS_TYPE
- The host operating system type (POSIX or WIN32). +
+ The m3makefile is then processed, and the list of sources built, + until the ending Library(), Program(), or + OtherPackage() quake function is encountered. + At this point, the before_do_m3_hook() quake function is + called to set things up before the compilation proceeds. + More quake variables are then extracted by m3build. + +
-
+
- Options
- Table containing compilation options values. +
- TARGET
- Target machine. +
- M3_COVERAGE_LIB
- Library required for coverage analysis. +
- INTERNAL_BACKEND, M3_BACKEND_OUTPUT
- Whether to use the internal backend. +
- OPTION_GUI
- Whether to create a gui WIN32 application. +
The compilation then proceeds and m3build calls back a number of + template defined quake procedures for various platform dependent tasks: + +
-
+
- m3_compile_c
- Compile a C file. +
- m3_link
- Link a program. +
- m3_make_lib
- Create static and dynamic libraries. +
- m3_note_shlib
- Add libraries in the list of derived files. +
- m3_assemble
- Assemble an assembly file. +
- m3_backend
- Convert the intermediate language into assembly. +
- install_file
- Install a file during m3ship. +
- emacs_compile
- Compile and emacs lisp file. +
+ In all cases, m3build creates or updates the files + .M3EXPORTS (exported files), .M3IMPTAB (location of all imported files), + .M3SHIP (files to ship with m3ship), and .M3WEB (information for + the browser m3browser). With the all default + build_target, the actual compilation is performed. With the clean + build_target, the list of derived files (which would have been created + by the compilation) is used to clean the build directory. + + Index: m3/pm3/language/modula3/m3compiler/m3build/src/html/m3makefile diff -c /dev/null m3/pm3/language/modula3/m3compiler/m3build/src/html/m3makefile:1.1.1.1 *** /dev/null Tue Feb 10 23:29:20 1998 --- m3/pm3/language/modula3/m3compiler/m3build/src/html/m3makefile Sat Jan 31 14:47:11 1998 *************** *** 0 **** --- 1,25 ---- + HtmlFile("build-generics") + HtmlFile("compiler") + HtmlFile("emacs") + HtmlFile("errors") + HtmlFile("example") + HtmlFile("exports") + HtmlFile("foreign") + HtmlFile("generics") + HtmlFile("hiding") + HtmlFile("imports") + HtmlFile("m3buildsteps") + HtmlFile("m3makefile") + HtmlFile("m3options") + HtmlFile("machine") + HtmlFile("manpage") + HtmlFile("misc") + HtmlFile("netobj") + HtmlFile("options") + HtmlFile("overrides") + HtmlFile("packages") + HtmlFile("profiling") + HtmlFile("progs") + HtmlFile("resources") + HtmlFile("sources") + HtmlFile("zeus") Index: m3/pm3/language/modula3/m3compiler/m3build/src/html/m3makefile.html diff -c /dev/null m3/pm3/language/modula3/m3compiler/m3build/src/html/m3makefile.html:1.1.1.1 *** /dev/null Tue Feb 10 23:29:20 1998 --- m3/pm3/language/modula3/m3compiler/m3build/src/html/m3makefile.html Sat Jan 31 14:47:11 1998 *************** *** 0 **** --- 1,39 ---- + +
+Package descriptions in m3makefiles + + +Package descriptions in m3makefiles
+ ++ The procedures defined by m3build that are available in all + m3makefiles fit into + the following categories: +
-
+
- specifying sources +
- importing packages +
- building programs and libraries +
- changing compiler options +
- compiling for profiling and coverage analysis +
- overriding package locations +
- importing foreign object files and libraries +
- exporting other files +
- explicitly setting interface visibility +
- instantiating generics +
- machine and operating system dependencies +
- misc. builtins +
+ + The more specialized procedures are: +
-
+
- emacs support +
- generic lists, queues, tables, ... +
- man pages +
- network objects +
- resources: arbitrary binary data +
- zeus animations +
Changing compiler options + + + +Changing compiler options
++ + option(name,value) + sets the option name to the specified value. + An empty string is the boolean FALSE value. A non empty + string, typically "T", represents the boolean TRUE value. +
+ + Important: For the specified compiler options to take effect, your + option lines must preceed any program or + library directives in the m3makefile. + +
The recognized options are: + +
-
+
- optimization
- Produce optimized code. +
- debuginfo
- Produce debugging information (default). +
- coverage
- Produce code to generate coverage information. +
- profiling
- Produce code to generate profiling information. +
- shared_lib
- Create dynamic (shared) libraries (default). +
- static_lib
- Create static libraries (default). +
- standalone
- Link with static libraries to produce a standalone + executable program. +
- gui
- Create a gui non console program on Win32. +
- times
- Produce statistics about compilation time. +
- msg_level
- Determine the level of verbosity for the compilation + from 0 to 4 (Silent, Explain, Commands, Verbose, Debug) +
- warning_level
- Determine the compiler propension to issue + warnings, from 0 to 3 +
- internal_backend
- Use the faster internal backend, if available + (default). +
Other options are available for compilation debugging and performance + analysis, or for internal use. These options are not for the + casual user. + +
-
+
- keep_files
- Keep temporary files for debugging. +
- bootstrap
- Create a bootstrap distribution. +
- dump_config
- Print compiler configuration parameter. +
- heap_stats
- Print heap usage statistics. +
- keep_cache
- Persistent cache, (not usable). +
- no_make
- Do not really build. +
- compile_once
- Do not recompile for new opaque info. +
- skip_link
- Do not link. +
- m3main_in_C
- Generate the main program as a C file. +
- NoChecks
- Disable runtime checks. +
- NoAsserts
- Disable assertion checking. +
- NoNarrowChk
- Disable runtime Narrow checks. +
- NoRangeChk
- Disable runtime Range checks. +
- NoReturnChk
- Disable runtime Return checks. +
- NoCaseChk
- Disable runtime CASE statement checks. +
- NoTypeCaseChk
- Disable runtime TYPECASE statement checks. +
- NoNilChk
- Disable runtime NIL checks. +
- NoRaisesChk
- Disable runtime RAISES checks. +
- InitFloats
- Initialize floats to 0.0. +
- vsdebug
- Debug version stamps. +
- builtins
- Internal. +
- load_map
- Internal. +
- unfold_nested_procs
- Internal. +
Machine and operating system dependencies + + + +Machine and operating system dependencies
++ + m3build contains some built-in support for machine and + operating system dependencies. The package structure makes provision + for separate build directories for different machine and operating + system combinations. The default behaviour of m3build is to + generate the compiled object files, libaries and programs in the build + directory corresponding to the machine and operating system on which + m3build is executing. +
+ + The following set of variables exist to allow m3makefiles to be + parameterised by machine and operating system. + +
-
+
- TARGET
- + This variable defines the machine type on which the library or + program being built will execute. It is chosen from the standard + set of machine types on which Modula-3 runs. Check the runtime + or m3build packages for the complete set. +
- OS_TYPE
- + This variable defines the operating system under which the library + or program being built will execute. Currently, Modula-3 supports + two operating system variants, POSIX and WIN32. The former breaks + down further into specific variants, but this variation is not made + available to clients. [There is a way if you absolutely need it, + see the unix package.] +
- BUILD_DIR
- + This names the package sub-directory in which object files, + libraries and programs will be built. It is usually, but not + always, the same as TARGET. +
+ + The net effect of the above allows a single package to build a family + of architectural variants, in different build sub-directories, where + each variant uses the same set of m3makefiles, parameterized by + the above variables. If this degree of flexibility is insufficient, + then the extra variation must be specified in a separate package, + which can use include_pkg to access the shared sources. + + + + Index: m3/pm3/language/modula3/m3compiler/m3build/src/html/manpage.html diff -c /dev/null m3/pm3/language/modula3/m3compiler/m3build/src/html/manpage.html:1.1.1.1 *** /dev/null Tue Feb 10 23:29:21 1998 --- m3/pm3/language/modula3/m3compiler/m3build/src/html/manpage.html Sat Jan 31 14:47:11 1998 *************** *** 0 **** --- 1,40 ---- + +
+Man pages + + + +Man pages
++ + The following calls format and install man pages. +
+ + manPage(name,sec) + formats man page name.sec. +
+ + ManPage(name,sec) + is like manPage, but also exports the man page to section + sec of /man. +
+ + ManExport(X,s) + exports source file X.s to section s of /man + without further formatting. +
+ + MandExport(X,s) + export derived file X.s to section s of /man + without further formatting. +
+ +
+ Last modified on Thu Jan 4 11:07:52 PST 1996 by heydon + modified on Thu Jul 21 16:28:04 PDT 1994 by kalsow + modified on Thu Jan 7 18:40:57 PST 1993 by muller +
+ + + + Index: m3/pm3/language/modula3/m3compiler/m3build/src/html/misc.html diff -c /dev/null m3/pm3/language/modula3/m3compiler/m3build/src/html/misc.html:1.1.1.1 *** /dev/null Tue Feb 10 23:29:21 1998 --- m3/pm3/language/modula3/m3compiler/m3build/src/html/misc.html Sat Jan 31 14:47:11 1998 *************** *** 0 **** --- 1,48 ---- + + +Miscellaneous procedures + + + +Miscellaneous declarations
++ + The declarations in this section are typically only needed by + specialised applications, for example the Modula-3 compiler or + other quake templates. +
+ + source(X) + declares that X contains non-compilable source. +
+ + derived_interface(X,V) + adds the derived interface X.i3 to the list of + files to be compiled. V must be either VISIBLE + or HIDDEN to indicate whether the interface should be + available to importers outside this package. +
+ + derived_implementation(X) + adds the derived module X.m3 to the list of + files to be compiled. +
+ + derived_c(X) + adds the derived C code X.c to the list of + files to be compiled. +
+ + derived_h(X) + adds the derived include file X.h to the list of + include files available to the compiler. +
+ +
+ Last modified on Mon Feb 12 11:35:36 PST 1996 by heydon + modified on Thu Jul 21 16:57:42 PDT 1994 by kalsow + modified on Thu Jan 7 18:40:57 PST 1993 by muller +
+ + + Index: m3/pm3/language/modula3/m3compiler/m3build/src/html/netobj.html diff -c /dev/null m3/pm3/language/modula3/m3compiler/m3build/src/html/netobj.html:1.2 *** /dev/null Tue Feb 10 23:29:21 1998 --- m3/pm3/language/modula3/m3compiler/m3build/src/html/netobj.html Tue Feb 10 22:56:31 1998 *************** *** 0 **** --- 1,33 ---- + + +Network object support + + + +Network object support
++ + The following procedures are used to build programs using + network objects. +
+ + netobj(X,T) + runs the network objects stub generator on the interface X.i3 + to produce the network object glue needed to manipulate objects + of type X.T. The resulting source files are included + in the current build. +
+ + Netobj(X,T) + Like netobj, but also exports the resulting interface. +
+ +
+ Last modified on Thu Jan 4 11:07:52 PST 1996 by heydon + modified on Thu Jul 21 16:51:11 PDT 1994 by kalsow + modified on Thu Jan 7 18:40:57 PST 1993 by muller +
+ + + + Index: m3/pm3/language/modula3/m3compiler/m3build/src/html/options.html diff -c /dev/null m3/pm3/language/modula3/m3compiler/m3build/src/html/options.html:1.1.1.1 *** /dev/null Tue Feb 10 23:29:21 1998 --- m3/pm3/language/modula3/m3compiler/m3build/src/html/options.html Sat Jan 31 14:47:11 1998 *************** *** 0 **** --- 1,53 ---- + + +m3build command line options + + + +m3build command line options
+ ++ The syntax for invoking m3build, within a package directory, is +
+ m3build [options] [target ...] +
++ If no target is specified, all is assumed. It causes the + specified program or library to be built. The only other + target that is supported in all + m3makefiles is clean + which removes any derived files created by m3build all. +
+ + The following options are interpreted by m3build. + +
-
+
- -b dir
- + Use the dir configuration and build in the directory + named dir. The default build directory is configured + into m3build when it is installed. +
- -d dir
- + Change the current directory to dir before doing anything. + This option is most useful when you're editing in the src + subdirectory and compile command you need is m3build -d ... +
- -F file
- + Read the quake code in file before the package + m3makefile. +
- -T dir
- + Read templates from dir instead of the default location. The new + directory must include the full set of templates (e.g. COMMON, + PLATFORMS, ...). +
- -S
- + Generate derived objects regardless of the current directory's + name. Normally, if the current working directory is src, + m3build will refuse to build derived objects. +
- -O
- + Read the m3overrides file if present. +
- -Dname=value
- + Bind the value to name before reading the + m3makefile. +
Overriding package locations + + + +Overriding package locations
++ + override(P, D) + Use the version of package P in directory D/P + instead of the one in /pkg/P. While D must + be an absolute path, a relative path RD may be used with + the path_of function as override(P, path_of(RD)). + +
+ + override alters the behaviour of the include_pkg and + import procedures, and must be executed prior to any such calls + to have an effect. +
+ + To help ensure that the public repositories are consistent, + m3ship will refuse to install any package built using overrides. +
+ + When the -O option is specified, m3build looks for a file + named m3overrides in the src directory and, if one + exists, executes it immediately prior to executing m3makefile. + By keeping all override calls in an m3overrides file + and not in an m3makefile, you can build both private and public + versions of packages without editting any files. +
+ + The overrides in effect when a package was built are automatically + carried forward into importers of the package, so there is no need to + restate the complete set of overrides at every level, only of those + packages that are directly imported into a given package. +
+ + + + + Index: m3/pm3/language/modula3/m3compiler/m3build/src/html/packages.html diff -c /dev/null m3/pm3/language/modula3/m3compiler/m3build/src/html/packages.html:1.1.1.1 *** /dev/null Tue Feb 10 23:29:21 1998 --- m3/pm3/language/modula3/m3compiler/m3build/src/html/packages.html Sat Jan 31 14:47:11 1998 *************** *** 0 **** --- 1,71 ---- + +
+Packages + + + +Packages
+ ++ PM3 is distributed as a set of packages. Each package + is contained in a single directory, named after the package, + which conforms to a standard structure. + The top level directory should contain + a src subdirectory containing Modula-3 source + files. The compiler, m3build, + also creates a derived platform directory for each platform on + which the package + is built. Besides the src and platforms subdirectories, + a package may contain other packages to form a package hierarchy. + These other packages are often tutorials or tests related to the + containing package. + +
+ There are three primary types of packages: program, library, and other. + An other package contains + a collection of sources, often documentation; it builds nothing. + A program package constructs a single executable program by compiling + and linking the contents of a set of source packages. + Similarly, a library package constructs a + single library from a set of source packages. +
+ + The m3makefile, that describes the package, resides in the + src subdirectory of the package. Although it is common for all the + Modula-3 sources to also reside in the src directory, they may be + distributed in a more complex directory structure rooted at src. +
+ The m3makefile for a source package simply lists the pieces of + source that are to be included in programs or libraries that include the + source package. It ends with a single OtherPackage() invocation. +
+ The m3makefile for a program package names the sources + needed to build the program, and the packages that it uses to + satisfy its imports. It ends with a + single program() or Program() invocation. + See the example. +
+ The m3makefile for a library package names the sources to be + included in the library, and the packages that it uses to + satisfy its imports. It ends with a single + library() or Library() invocation. +
+ + Note that as in a program, all the imports of a package must be + satisfied. If a package A builds a library and any of the objects in + that library import interfaces from another library package B, then + import(B) must be specified in A's m3makefile. + +
+ A package, once compiled with m3build, may have its + exported (visible) files installed in a + package repository with m3ship. + By default, m3ship installs packages in the public + repository (e.g. /usr/local/lib/m3/pkg). + Note that on some systems, you must have special privileges to install + public packages. +
+ + + + Index: m3/pm3/language/modula3/m3compiler/m3build/src/html/profiling.html diff -c /dev/null m3/pm3/language/modula3/m3compiler/m3build/src/html/profiling.html:1.2 *** /dev/null Tue Feb 10 23:29:21 1998 --- m3/pm3/language/modula3/m3compiler/m3build/src/html/profiling.html Tue Feb 10 22:56:31 1998 *************** *** 0 **** --- 1,87 ---- + +
+Compiling for profiling and coverage analysis + + + +Compiling for profiling and coverage analysis
+ +On most Unix systems, the programs prof(1), gprof(1), and + analyze_coverage(1) can be used to profile your Modula-3 program's + performance or to analyze which source lines of your program have been + executed. However, in order to use these tools, you must compile your + program with certain compiler options. + +
Profiling
+ +To profile your program for use with prof(1) or gprof(1), add + the following compiler option to your + m3makefile: + +
+ option("profiling","T") ++ +This will cause your program to be compiled and linked for profiling. + If you have + already built your program without profiling, and you want to turn + profiling on, delete the object files and executable program + and rebuild. +
+ When you run your program, a file named "mon.out" (for prof(1)) or + "gmon.out" (for gprof(1)) will be created. To view the profile, run + the prof(1) or gprof(1) program using the command-line: + +
+ prof prog mon.out + gprof prog gmon.out +
+ +where prog is the filename of your program's binary. + +
Coverage Analysis
+ +To determine how many times each source line and procedure of your + Modula-3 program were exececuted on a particular run, you need to + compile it to be used with the analyze_coverage(1) tool. To do + this, add the following compiler option + to your m3makefile: + +
+ option("coverage","T") ++ +Coverage data will be available only for those modules that have been + compiled with this option, so if you want coverage analysis for all + your sources and you have just turned this option on, you will need to + delete your derived directory and recompile everything. To produce the + coverage data, you must also link your program with this option. + +
Once you've compiled your program for coverage analysis, just run it. + By default, this will produce a file named "coverage.out" in the + current directory (you can set the environment variable + COVERAGE_DATABASE to the name of a different file if you + prefer). This file is the coverage database. The coverage information + is accumulated in this file from run to run, so if you want to + see what your program does on a single run, you should delete the + coverage database file before running your program. For the same + reason, the profiling data file is rather large; furthermore, as it is + augmented by each execution of the program, you may want to compress + it from time to time (see analyze_coverage(1) for more + details). +
+ Once you've run your program, you can use the analyze_coverage(1) tool + to show you what's in the coverage database. For this tool to work, + you must point it to the directories containing your source files. You + can do this by setting the COVERAGE_PATH environment + variable, or by supplying the "-S" option to analyze_coverage(1). + Again, see the analyze_coverage(1) man page for details. +
+ Note that because of the extensive data collection performed by this mode of + profiling, the execution time of the program can be significantly larger when + it is enabled; thus, simultaneous time profiling can produce erroneous + results. + + + + Index: m3/pm3/language/modula3/m3compiler/m3build/src/html/progs.html diff -c /dev/null m3/pm3/language/modula3/m3compiler/m3build/src/html/progs.html:1.1.1.1 *** /dev/null Tue Feb 10 23:29:21 1998 --- m3/pm3/language/modula3/m3compiler/m3build/src/html/progs.html Sat Jan 31 14:47:11 1998 *************** *** 0 **** --- 1,36 ---- + +
+Building programs, libraries, and other packages + + + +Building programs, libraries, and other packages
++ +
-
+
- library(X)
- + compile the sources and build a + library, X, from the resulting compiled object files. + The visibility of the library is hidden. + + +
- Library(X)
- + The same as library, but X is exported. + + +
- program(X)
- + constructs an executable program named X from the given + sources. + +
- Program(X)
- + like program, but X is exported to /bin. + + +
- OtherPackage(X)
- + processes the m3makefile but without producing a program or library. + This is typically used for packages containing only documentation. +
Resources + + + +Resources
++ + The following procedures support the inclusion of arbitrary data, + known as a resource, in a program. +
+ + resource(file) + is shorthand for resource_named(file,file). +
+ + resource_named(rd,file) + declares that file is a resource file. It will be + accessible via the reader rd if a bundle is built. +
+ + bundle(m) + declares that the module m is to be built as a bundle + of the files specified by the prior calls to resource and + resource_named. +
+ + For a description of how to access resources from your running + program, see the + Bundle + and + Rsrc + interfaces. +
+ + + + Index: m3/pm3/language/modula3/m3compiler/m3build/src/html/sources.html diff -c /dev/null m3/pm3/language/modula3/m3compiler/m3build/src/html/sources.html:1.1.1.1 *** /dev/null Tue Feb 10 23:29:21 1998 --- m3/pm3/language/modula3/m3compiler/m3build/src/html/sources.html Sat Jan 31 14:47:11 1998 *************** *** 0 **** --- 1,97 ---- + +
+Specifying sources + + + +Specifying sources
++ + The most primitive declarations in an m3makefile are those that + identify source files. They can be Modula-3, C or assembler files. A + source file has three attributes: a package, the subdirectory within + the package where the declaration occurs, and a visibility. The + visibility has two values, visible and hidden. + When a package A + imports a package B, only the visible sources in B are available to + compilations that occur in A. By default all sources are visible. + However, it is possible to explicitly control the visibility of + Modula-3 interfaces. +
+ + Source files are named relative to the m3makefile that mentions them. +
+ + The following calls define source files: +
+ + interface(X) declares that the file X.i3 contains an interface. +
+ + implementation(X) declares that the file X.m3 contains a module. +
+ + module(X) declares both the interface X.i3 and the module X.m3. +
+ + generic_interface(X) declares that the file X.ig contains + a generic interface. +
+ + generic_implementation(X) declares that the file X.mg + contains a generic module. +
+ + generic_module(X) declares both a generic interface and module. +
+ + h_source(X) declares that the file X.h contains a C include + file. +
+ + c_source(X) declares that the file X.c contains a C module. +
+ + s_source(X) declares that the file X.s contains an assembly + module. +
+ + pgm_source(X) declares that the file X contains compilable + source (e.g. .ic, .mc, .is or + .ms files). +
+ + With the exception of h_source, each of the procedures above + defines a hidden source file. + There are capitalized variants Interface, Module, + Generic_interface, Generic_implementation, and + Generic_module that identify their sources as visible. Remember, + only those interfaces that are marked as visible will be available to + importers of your library or package. +
+ + With the exception of generic_interface, + generic_implementation, and h_source, all other calls + add their argument to the set PGM_SOURCES. This set is + compiled by this invocation of m3build, either by the + Modula-3 compiler or the C compiler, as appropriate. +
+ + template(X) + declares that the file X.tmpl contains quake code + that is to be included in this build, and in all builds that import this + package. +
+ + The template call is used to extend the set of available + procedures. For example, the table package includes a template that + defines the table procedure which + instantiates the generic table module. See also the predefined + general-purpose procedures for instantiating + generics that you can use to define procedures in your own templates + for instantiating your own generic modules. +
+ + + + Index: m3/pm3/language/modula3/m3compiler/m3build/src/html/zeus.html diff -c /dev/null m3/pm3/language/modula3/m3compiler/m3build/src/html/zeus.html:1.1.1.1 *** /dev/null Tue Feb 10 23:29:21 1998 --- m3/pm3/language/modula3/m3compiler/m3build/src/html/zeus.html Sat Jan 31 14:47:11 1998 *************** *** 0 **** --- 1,49 ---- + +
+Zeus animations + + + +Zeus animations
++ + The following procedures support building Zeus animations. +
+ + zume(X) + run the Zeus event processor m3zume on the source file X.evt + to produce Modula-3 sources and other resources needed to build an + animation. The resulting sources are included in any subsequent + compilation. +
+ + zume3D(X) + like zume but with the additional support for using + the 3D libraries. +
+ + oblume(X,O) + Like zume, runs the Zeus event processor on X.evt + and also bundles the source file O.obl which is assumed + to contain Obliq code. +
+ + oblume3D(X,O) + like oblume but with the additional support for using + the 3D libraries. +
+ + junozume(X,V) + Runs the Zeus event processor on X.evt to produce stubs + to connect to a Juno(1) animation server run with the -zeus + option. There can be at most one Juno view per Zeus animation. + V is the name of the view installed in the Zeus Views + menu. See the Juno(1) man page for a more complete + description of how to write a Juno animation view for + Zeus. See the README file in the junozeus package + for instructions on how to run an example view. +
+ + + + Index: m3/pm3/language/modula3/m3compiler/m3cc/src/m3makefile diff -c m3/pm3/language/modula3/m3compiler/m3cc/src/m3makefile:1.2 m3/pm3/language/modula3/m3compiler/m3cc/src/m3makefile:1.3 *** m3/pm3/language/modula3/m3compiler/m3cc/src/m3makefile:1.2 Fri Nov 21 13:14:42 1997 --- m3/pm3/language/modula3/m3compiler/m3cc/src/m3makefile Tue Feb 10 22:56:48 1998 *************** *** 50,77 **** % figure out where we're going to build the beast local build_dir = "." % let m3build set the build directory if not equal (M3CC_HOST, M3CC_TARGET) ! build_dir = "../" & BUILD_DIR & "-" & M3CC_TARGET ! end ! % make sure the derived directory exists ! if stale (build_dir, build_dir) ! ret = exec (["mkdir", build_dir]) end if not defined ("no_config") % configure the sources ! ret = exec (["../gcc/configure", M3CC_CONFIG, "--srcdir=../gcc", "--host=" & gnu_platform (M3CC_HOST), "--build=" & gnu_platform (M3CC_BUILD), ! "--target=" & gnu_platform (M3CC_TARGET)],[],build_dir) if not equal(ret,0) error("Failed to configure m3cc") end end % misc fixups & ship commands pgms = "m3cgc1" if equal (M3CC_HOST, M3CC_TARGET) ! LibdExport ("m3cgc1") if equal (M3CC_HOST, "DS3100") or equal (M3CC_HOST, "ALPHA_OSF") pgms = "m3cgc1 mips-tfile" LibdExport ("mips-tfile") --- 50,86 ---- % figure out where we're going to build the beast local build_dir = "." % let m3build set the build directory + if not equal (M3CC_HOST, M3CC_TARGET) ! build_dir = ".." & SL & BUILD_DIR & "-" & M3CC_TARGET ! if stale (build_dir, build_dir) ! ret = exec (["mkdir", build_dir]) ! end end if not defined ("no_config") % configure the sources ! local cmd = ["../gcc/configure", M3CC_CONFIG, "--srcdir=../gcc", "--host=" & gnu_platform (M3CC_HOST), "--build=" & gnu_platform (M3CC_BUILD), ! "--target=" & gnu_platform (M3CC_TARGET)] ! if equal(OS_TYPE,"WIN32") ! > tmpsh in ! write("#! /bin/sh",CR) ! write(cmd,CR) ! end ! ret = exec(["sh","tmpsh"],[],build_dir) ! else ! ret = exec(cmd,[],build_dir) ! end if not equal(ret,0) error("Failed to configure m3cc") end end % misc fixups & ship commands pgms = "m3cgc1" if equal (M3CC_HOST, M3CC_TARGET) ! LibdExport ("m3cgc1" & NAMING_CONVENTIONS[20]) if equal (M3CC_HOST, "DS3100") or equal (M3CC_HOST, "ALPHA_OSF") pgms = "m3cgc1 mips-tfile" LibdExport ("mips-tfile") Index: m3/pm3/language/modula3/m3compiler/m3export/src/dobinaries.sh diff -c m3/pm3/language/modula3/m3compiler/m3export/src/dobinaries.sh:1.1 m3/pm3/language/modula3/m3compiler/m3export/src/dobinaries.sh:1.2 *** m3/pm3/language/modula3/m3compiler/m3export/src/dobinaries.sh:1.1 Sat Jan 17 11:52:59 1998 --- m3/pm3/language/modula3/m3compiler/m3export/src/dobinaries.sh Tue Feb 10 22:56:55 1998 *************** *** 3,8 **** --- 3,9 ---- ARCH=`arch` OS=`uname -s` REV=`uname -r` + ZZP=`cat zzp` case ${ARCH}-${OS}-${REV} in i[3456789]86-Linux-*) *************** *** 72,80 **** open m3.polymtl.ca user ftp ${TARGET}@m3.polymtl.ca site group binaries ! site gpass `cat zzp` binary ! cd /pub/m3/binaries/${TARGET} put ${VERSION}.tgz put TODO DONE EOF --- 73,81 ---- open m3.polymtl.ca user ftp ${TARGET}@m3.polymtl.ca site group binaries ! site gpass ${ZZP} binary ! cd /tmp/pm3/binaries/${TARGET} put ${VERSION}.tgz put TODO DONE EOF *************** *** 83,91 **** open m3.polymtl.ca user ftp ${TARGET}@m3.polymtl.ca site group binaries ! site gpass `cat zzp` binary ! cd /pub/m3/binaries/${TARGET} put errs.tmp NOTDONE.errs put out.tmp NOTDONE.out EOF --- 84,92 ---- open m3.polymtl.ca user ftp ${TARGET}@m3.polymtl.ca site group binaries ! site gpass ${ZZP} binary ! cd /tmp/pm3/binaries/${TARGET} put errs.tmp NOTDONE.errs put out.tmp NOTDONE.out EOF Index: m3/pm3/language/modula3/m3compiler/m3export/src/m3makefile diff -c m3/pm3/language/modula3/m3compiler/m3export/src/m3makefile:1.4 m3/pm3/language/modula3/m3compiler/m3export/src/m3makefile:1.6 *** m3/pm3/language/modula3/m3compiler/m3export/src/m3makefile:1.4 Tue Jan 27 15:26:04 1998 --- m3/pm3/language/modula3/m3compiler/m3export/src/m3makefile Tue Feb 10 22:56:55 1998 *************** *** 204,209 **** --- 204,216 ---- CheckExec(["mv", EXPORT_TMP_BINARIES & "/" & TARGET & "/" & versionName, EXPORT_BINARIES & "/" & TARGET],[],"","export binaries failed") + + CheckExec(["rm", EXPORT_TMP_BOOTSTRAP & "/" & TARGET & "/" & "TODO"],[],"", + "remove TODO failed") + + local ret = Exec(["rm", EXPORT_ROOT & "/" & "pkgf" & "/" & "pm3"],[],"") + CheckExec(["ln","-s",EXPORT_SRC & "/" & versionName, + EXPORT_ROOT & "/" & "pkgf" & "/" & "pm3"],[],"","link in pkgf failed") end % *************** *** 336,344 **** write(versionName,CR) end end - - CheckExec(["rm", EXPORT_TMP_BOOTSTRAP & "/" & TARGET & "/" & "TODO"],[],"", - "remove TODO failed") RemovePreviousVersion() --- 343,348 ---- Index: m3/pm3/language/modula3/m3compiler/m3ship/src/index.html diff -c /dev/null m3/pm3/language/modula3/m3compiler/m3ship/src/index.html:1.1.1.1 *** /dev/null Tue Feb 10 23:30:18 1998 --- m3/pm3/language/modula3/m3compiler/m3ship/src/index.html Sat Jan 31 14:47:12 1998 *************** *** 0 **** --- 1,57 ---- + +
+m3ship + + + +m3ship
++ + m3ship + will ship all the build directories (for different architectural + variants) that exist in the package. It will refuse to ship anything if + it finds a variant that was built with "overrides", unless the "-k" option + is given, in which case it will ship all the variants except those that + were built with overrides. +
+ + The syntax for invoking m3ship is +
+ m3ship [options] +
++ + The following options are interpreted by m3ship. +
-
+
+
- -k
+ Don't generate an error message if any of the .M3SHIP files are
+ missing. Keep on going.
+
+ +
- -b "dir"
+ Use the dir configuration and ship from the directory named dir.
+ The default directory is configured into m3ship when
+ it is installed.
+
+ +
- -d "dir"
+ Change the current directory to dir
+ before doing anything.
+
+ +
- -S
+ Ship derived objects regardless of the current directory's name.
+ Normally, if the current working directory is src, m3ship
+ will refuse to build derived objects in it.
+
+ +
- -T "dir" + Read templates from dir + instead of the default location. +
+ + + + Index: m3/pm3/language/modula3/m3compiler/m3ship/src/m3makefile diff -c m3/pm3/language/modula3/m3compiler/m3ship/src/m3makefile:1.4 m3/pm3/language/modula3/m3compiler/m3ship/src/m3makefile:1.5 *** m3/pm3/language/modula3/m3compiler/m3ship/src/m3makefile:1.4 Wed Dec 17 15:53:38 1997 --- m3/pm3/language/modula3/m3compiler/m3ship/src/m3makefile Tue Feb 10 22:57:02 1998 *************** *** 8,15 **** --- 8,18 ---- import ("m3quake") import ("m3templates") import ("m3config") + import("m3doc") implementation ("Main") + + HtmlFile("index") option("standalone","T") Index: m3/pm3/language/modula3/m3compiler/m3where/src/index.html diff -c /dev/null m3/pm3/language/modula3/m3compiler/m3where/src/index.html:1.2 *** /dev/null Tue Feb 10 23:31:01 1998 --- m3/pm3/language/modula3/m3compiler/m3where/src/index.html Tue Feb 10 22:57:42 1998 *************** *** 0 **** --- 1,86 ---- + +
+m3where + + + +m3where
+ ++ m3where + is a program that locates Modula-3 source files, relative to a + particular program or library package. By default it locates the given + units relative to the default build directory of the package that is + rooted at the current working directory. The -d option can be used + to specify the pathname of a particular package to be used to locate + the units. Sources that are hidden (not exported) by the + packages are not located unless option -h is set. + +
+ The syntax for invoking m3where is +
+ m3where [options] [units ...] +
+ ++ If no units are given, m3where enumerates all of the sources + associated with the package and those that it imports. Sources that are + hidden (not exported) are not shown unless option -h is set. + +
+ The units are specified as filenames of the form "Foo.xx", + where "xx" is one of the standard + Modula-3 file extensions (.i3, .m3, .ig, .mg...). + Wildcards are not supported. + +
+ Note that, in order for m3where to work, + m3build must have + been run at least once for the given package/build directory pair. + +
+ If the given units can be located, the full pathnames are output + to the standard output, otherwise an error message is output. + +
+ The following options are interpreted by m3where. + +
-
+
+
- -h + Show all sources, including the hidden ones. + +
- -b "dir" + Search the build directory named dir. + The default directory is configured into m3where when + it is installed. + +
- -d "dir" + Locate units from the package that is rooted at dir. + dir must be an absolute pathname. + +
- -T "dir" + Read templates from dir + instead of the default location. +
+ For example, +
+ m3where Pathname.i3 +
+would try to find the file Pathname.i3 from the + information in the build directory of the package rooted at the + current working directory. + +
And, +
+ m3where -b NT386GNU -d /proj/m3/pkg/libm3 PathnameWin32.m3 +
+would try to find the file PathnameWin32.m3 + using the information in the NT386GNU build directory of + the libm3 package. + + + + Index: m3/pm3/language/modula3/m3compiler/m3where/src/m3makefile diff -c m3/pm3/language/modula3/m3compiler/m3where/src/m3makefile:1.3 m3/pm3/language/modula3/m3compiler/m3where/src/m3makefile:1.4 *** m3/pm3/language/modula3/m3compiler/m3where/src/m3makefile:1.3 Fri Nov 28 09:23:59 1997 --- m3/pm3/language/modula3/m3compiler/m3where/src/m3makefile Tue Feb 10 22:57:42 1998 *************** *** 11,16 **** --- 11,19 ---- import ("m3config") implementation ("Main") + + HtmlFile("index") + Program ("m3where") Index: m3/pm3/language/modula3/m3compiler/src/gc.html diff -c /dev/null m3/pm3/language/modula3/m3compiler/src/gc.html:1.2 *** /dev/null Tue Feb 10 23:31:01 1998 --- m3/pm3/language/modula3/m3compiler/src/gc.html Tue Feb 10 22:57:47 1998 *************** *** 0 **** --- 1,58 ---- + +
+Garbage collection + + + +Garbage collection
++ + A crucial fact for clients of the garbage collector to know is that + objects in the heap move. If all references to a traced heap object + are from other traced heap objects, the collector may move the + referent. Hence, it is a bad idea to hash pointer values. References + from the stack or untraced heap into the traced heap are never + modified. +
+ + The current collector is, by default, incremental and generational. + The interruptions of service should be very small, and the overall + performance should be better than with the previous collectors. +
+ + The use of VM protection is currently implemented only for the LINUXELF, + DS3100, SOLgnu, and SPARC architectures. On other architectures, + @M3novm is the default. +
+ + Note that the new optional background collection + thread is not on by default; this may change in the future. +
+ + When you debug a Modula-3 program with + m3gdb, + you will find it simplest to + run it with the @M3novm switch. +
+ + Because of the use of VM protection by the collector, + there are some additional constraints + on what programs may legally do. For example, you cannot pass an + address on the heap as an argument to sigvec(2). These restrictions + are documented in RTHeapDepC.c. + If they seem onerous, we might be able to eliminate some. + Note also that fork() and vfork() are now + relatively expensive operations, + since they cause the current collection to finish; + this situation may improve in a future release. +
+ +
+ Last modified on Thu Jan 4 11:08:06 PST 1996 by heydon + modified on Wed May 4 08:03:11 PDT 1994 by kalsow + modified on Thu Jan 7 18:40:57 PST 1993 by muller +
+ + + + Index: m3/pm3/language/modula3/m3compiler/src/index.html diff -c /dev/null m3/pm3/language/modula3/m3compiler/src/index.html:1.1.1.1 *** /dev/null Tue Feb 10 23:31:01 1998 --- m3/pm3/language/modula3/m3compiler/src/index.html Sat Jan 31 14:47:12 1998 *************** *** 0 **** --- 1,86 ---- + +The SRC Modula-3 compiler + + ++ Michel Dagenais + Michel Dagenais, GNU General Public License, 1998 + + michel.dagenais@polymtl.ca+
+ Ecole Polytechnique
+ C.P. 6079, Succ. Centre-Ville
+ Montreal, Quebec, H3C 3A7 + 18 January 1998 + modula-3 + compiler +The SRC Modula-3 compiler
+ +++ +The DEC SRC compiler and supporting libraries. +
The Compiler
+ +-
+
- m3build
- + The Modula-3 compiler. +
- m3ship
- + The Modula-3 package installer. +
- m3where
- + An application to find the Modula-3 files used by a package. +
Language restrictions, pragmas and runtime
+ +-
+
- The Linker's Inclusion Algorithm +
- Implementation restrictions +
- Pragmas +
- Runtime arguments +
- Garbage collection +
- A tour of the runtime +
- Thread scheduling +
- Unix signals usage +
Compiler bootstrap and export procedures, and internal libraries
+ +-
+
- m3bootstrap
- + A script to generate bootstrap versions of the compiler for + the supported platforms. +
- m3export
- + A script to export source code, bootstrap packages and binaries + for the Polytechnique Montreal (PM3) distribution of the DEC SRC + Modula-3 compiler. +
- m3driver
- + Compiler driver. +
- m3front
- + Modula-3 compiler front end. +
- m3linker
- + Modula-3 pre-linker. +
- m3loader
- + Experimental program loader to compile directly into memory + for immediate execution. +
- m3middle
- + Interface between the frontend and the backend. +
- m3templates
- + Compiler specific quake functions (used by m3build to interpret + m3makefiles). +
- m3cc
- + GCC based code generator. +
- m3objfile
- + Support library for direct code generation. +
- m3back
- + Direct code generation for supported platforms. +
- m3staloneback
- + Debugging tool for code generation. +
- cg-burs
- + Experimental burs based code generator. +
- m3tests
- + Tests for the Modula-3 compiler. +
Runtime arguments + + + +Runtime arguments
++ + Command line arguments given to Modula-3 programs are divided in two + groups. Runtime parameters are those that start with the characters + @M3. They are reserved for the Modula-3 runtime and are accessible + via the + + RTParams + interface. The others are + program arguments and are accessible via the + + Params + interface. +
+ + The following runtime parameters are recognized today; + others are simply ignored. +
-
+
- @M3nogc turns the garbage collector off.
+
+ +
- @M3showheap=name activates the logging of
+ heap allocation and garbage collection events. The program forks a
+ process running the name program, and sends it these events as
+ they occur. If "=name" is ommitted, the
+ showheap
+ program is forked; this
+ program displays the status of the heap pages.
+
+ +
- @M3showthread=name activates the logging of
+ thread switching events. The program forks a
+ process running the name program, and sends it these events as
+ they occur. If "=name" is ommitted, the
+ showthread
+ program is forked; this
+ program displays the status of the various threads.
+
+ +
- @M3shownew=name activates the logging of
+ per-type heap allocations. The program forks a
+ process running the name program, and periodically sends it
+ the number and sizes of recently allocated objects.
+ If "=name" is ommitted, the
+ shownew
+ program is forked; this
+ program displays one of several bar graphs.
+
+ +
- @M3update=X sets the interval between
+ shownew updates to X seconds. X must be
+ an integer.
+
+ +
- @M3noincremental disables incremental garbage collection;
+ uses stop-and-copy instead.
+
+ +
- @M3nogenerational disables generational garbage collection.
+
+ +
- @M3novm disables the use of
+ VM protection by the garbage collector.
+ On some platforms, @M3novm is essential for
+ debugging.
+ @M3novm implies @M3noincremental and @M3nogenerational.
+
+ +
- @M3paranoidgc checks the heap for sanity after each collection.
+
+ +
- @M3stackdump causes checked runtime errors to produce a stack + dump on stderr. On systems with stack walkers ( + LINUXELF, SOLgnu, DS3100 and ALPHA_OSF) + the dump includes exception and procedure frames. On other systems only + the exception frames are dumped. + +
+ +
+ Last modified on Thu Jan 4 11:08:03 PST 1996 by heydon + modified on Thu Jun 1 08:16:06 PDT 1995 by kalsow + modified on Thu Jan 7 18:40:57 PST 1993 by muller +
+ + + + Index: m3/pm3/language/modula3/m3compiler/src/m3makefile diff -c /dev/null m3/pm3/language/modula3/m3compiler/src/m3makefile:1.2 *** /dev/null Tue Feb 10 23:31:01 1998 --- m3/pm3/language/modula3/m3compiler/src/m3makefile Tue Feb 10 22:57:48 1998 *************** *** 0 **** --- 1,15 ---- + + import("m3doc") + + HtmlFile("index") + HtmlFile("gc") + HtmlFile("m3args") + HtmlFile("pragmas") + HtmlFile("restrictions") + HtmlFile("runtime") + HtmlFile("scheduler") + HtmlFile("signals") + + include_dir("linking") + + OtherPackage("m3compiler") Index: m3/pm3/language/modula3/m3compiler/src/pragmas.html diff -c /dev/null m3/pm3/language/modula3/m3compiler/src/pragmas.html:1.2 *** /dev/null Tue Feb 10 23:31:02 1998 --- m3/pm3/language/modula3/m3compiler/src/pragmas.html Tue Feb 10 22:57:48 1998 *************** *** 0 **** --- 1,304 ---- + + +Pragmas + + + +Pragmas
++ + SRC Modula-3 recognizes the following pragmas: +
-
+
- <*EXTERNAL*> +
- <*INLINE*> +
- <*ASSERT*> +
- <*TRACE*> +
- <*FATAL*> +
- <*UNUSED*> +
- <*OBSOLETE*> +
- <*NOWARN*> +
- <*LINE*> +
- <*PRAGMA*> +
- <*calling convention*> +
+ +
<*EXTERNAL*>
+ ++ The pragma <*EXTERNAL N:L*> may precede an interface + or a procedure or variable declaration in an interface. It asserts + that the following entity is named ``N'' and implemented in language ``L'' + (or uses calling convention ``L''). + If ``N'' is omitted, the external name is the Modula-3 name. The default + and only recognized value for ``L'' are platform dependent. + The ``:'' is only + required when specifying ``L''. ``N'' and ``L'' may be + Modula-3 identifiers or string literals. +
+ On Unix platforms, the default and only recognized language is C. +
+ On Windows/NT, two calling standards are supported, + __cdecl and __stdcall. They are treated + as languages by the <*EXTERNAL*> pragma. + C and WINAPIV are aliases for __cdecl. + WINAPI, CALLBACK, APIENTRY, + APIPRIVATE, and PASCAL are + aliases for __stdcall. The default is C. +
+ The names of external procedures and variables are passed through + the back end unchanged. The types of external variables, the + types of formal parameters, the types of results, and the raises + clauses of external procedures are all assumed to be correct and + are not checked + against their external implementation. +
+ Beginning an interface with <*EXTERNAL*> declares all of the + procedures and variables in that interface external. +
+ For example: +
+ <*EXTERNAL*> INTERFACE OS; + VAR errno: INTEGER; + PROCEDURE exit (i: INTEGER); + END OS. +
+allows importers of OS to access the standard Unix symbols + errno and exit through the names OS.errno and + OS.exit respectively. +
+ Alternatively, the following interface provides access to + the same two symbols, but uses a more conventional Modula-3 name + for the procedure: +
+ INTERFACE OS; + <*EXTERNAL errno:C *> VAR errno: INTEGER; + <*EXTERNAL exit:C *> PROCEDURE Exit (i: INTEGER); + END OS. +
++ If several variables are declared within a single <*EXTERNAL*> VAR + declaration, they are all assumed to be external. +
+ The external pragma may optionally specify a name different from the + Modula-3 name. + For example: +
+ INTERFACE Xt; + <*EXTERNAL "_XtCheckSubclassFlag" *> + PROCEDURE CheckSubclassFlag (...); + ... +
+defines a procedure named Xt.CheckSubclassFlag in Modula-3 + and named _XtCheckSubclassFlag in the generated C. + +
<*INLINE*>
++ The pragma <*INLINE*> may precede a procedure + declaration. The pragma is allowed in interfaces and modules. + SRC Modula-3 parses but ignores this pragma. + +
+ For example: +
+ INTERFACE X; + <*INLINE*> PROCEDURE P (i: INTEGER); + <*INLINE*> PROCEDURE Q (); + END X. +
+declares X.P and X.Q to be inlined procedures. + +
<*ASSERT*>
++ The pragma <*ASSERT expr*> may appear anywhere a statement + may appear. It is a static error if ``expr'' is not of type BOOLEAN. + At runtime ``expr'' is evaluated. It is a checked + runtime error if the result is FALSE. +
+ Assertion checking can be disabled with the -a compiler + switch. + +
<*TRACE*>
++ The pragma <*TRACE expr*> may appear at the end of any variable + or formal declaration. This pragma will generate tracing calls whenever + the declared variable is modified. +
+ The ``expr'' must evaluate to a procedure of two arguments. + The first argument is the name of the traced variable, a TEXT. + The second argument is the traced variable. + Note that any of the formal passing modes may be used with the + second argument. +
+ For example: +
+ MODULE M; + VAR x: Foo <*TRACE MyTrace.FooChanged*>; +
+will cause +
+ MyTrace.FooChanged ("M.x", x) ++to be generated after each statement that modifies x. + Variable aliasing is not tracked, so +
+ WITH alias = x DO INC(alias) END +
+will not generate any tracing. +
+ + The pieces of Modula-3 grammar affected by <*TRACE expr*> are: +
+ VariableDecl = IdList (":" Type & ":=" Expr) V_TRACE. + Formal = [Mode] IdList (":" Type & ":=" ConstExpr) V_TRACE. + ForSt = FOR Id V_TRACE ":=" Expr TO Expr [BY Expr] DO S END. + Handler = QualId {"," QualId} ["(" Id V_TRACE ")"] "=>" S. + TCase = Type {"," Type} ["(" Id V_TRACE ")"] "=>" S. + Binding = Id V_TRACE "=" Expr. + V_TRACE = [ "<*" TRACE Expr "*>" ]. +++ + The pragma <*TRACE stmt-list*> may appear immediately after any + BEGIN. The specified ``stmt-list'' will be inserted after each + statement of the block started by the BEGIN. For example: +
+ BEGIN <* TRACE INC(cnt); MyTrace(cnt) *> + i := j; + j := i; + END; +
+will generate INC(cnt); MyTrace(cnt) after each of + the assignment statements. + +
<*FATAL*>
++ + The pragma <*FATAL id-list*> may appear anywhere a + declaration may appear. It asserts that the exceptions named + in ``id-list'' may be raised, but unhandled in the containing scope. + If they are, it's fatal and the program should crash. Effectively, + the <*FATAL*> pragma disables a specific set of + ``potentially unhandled exception'' warnings. If ``id-list'' is ANY, + the pragma applies to all exceptions. The effects of the + <*FATAL*> pragma are limited to its containing scope --- + they cannot be imported from interfaces. +
+ + For example: +
+ EXCEPTION InternalError; + <*FATAL InternalError*> +
+at the top-level of a module M means that no warnings will be + generated for procedures in M that raise but don't list + InternalError in their RAISES clauses. +
+ + Similarly, +
+ PROCEDURE X() RAISES {} = + BEGIN + ... + <*FATAL ANY*> BEGIN + List.Walk (list, proc); + END; + ... + END X; ++specifies that although X raises no exceptions and List.Walk + may, no warnings should be generated. + +
<*UNUSED*>
++ + The pragma <*UNUSED*> may precede any declaration. It asserts + that the entity in the following declaration is not used and no + warnings should be generated. +
+ + For example, the procedures that implement the default methods + for an object may not need all of the actual parameters: +
+ PROCEDURE DefaultClose (<*UNUSED*> wr: Wr.T) = + BEGIN (* do nothing *) END DefaultClose; +
+ +<*OBSOLETE*>
++ + The pragma <*OBSOLETE*> may precede any declaration + (e.g. <*OBSOLETE*> PROCEDURE P ();). A warning is emitted in + any module that references an obsolete symbol. This feature is used + to warn clients of an evolving interface that they are using + features that will disappear in the future. +
+ +
<*NOWARN*>
++ + The pragma <*NOWARN*> may appear anywhere. It prevents warning + messages from being issued for the line containing the pragma. It is + probably better to use this pragma in a few places and enable + all warnings with the -w1 switch than to ignore all warnings. +
+ +
<*LINE*>
++ + For the benefit of preprocessors that generate Modula-3 programs, the + compiler recognizes a <*LINE ... *> pragma, in two forms: +
+ <*LINE number filename *> + <*LINE number *> +
+where number is an integer literal and filename is a + text literal. + This pragma causes the compiler to believe, for purposes of error + messages and debugging, that the line number of the following source line is + number and that the current input file is filename. + If filename is omitted, it is assumed to be unchanged. + <*LINE ... *> may appear between any two Modula-3 tokens; it + applies to the source line following the line on which it appears. + Here's an example: <*LINE 32 "SourceLoc.nw" *>. + +
<*PRAGMA*>
++ + The pragma <*PRAGMA id-list*> may appear anywhere. It notifies + the compiler that pragmas beginning with the identifiers in ``id-list'' + may occur in this compilation unit. Since the compiler is free to + ignore any pragma, the real effect of <*PRAGMA*> is to tell + the compiler that pragmas it doesn't implement are coming, but they + shouldn't cause ``unrecognized pragma'' warnings. + +
<*calling convention*>
++ + Any of the ``languages'' allowed in the <*EXTERNAL*> + pragma may be used to indicate the calling convention associated + with a procedure or procedure type. The pragma must appear + immediately prior to the PROCEDURE keyword. + For example: +
+ TYPE WindowsCallBack = <*CALLBACK*> PROCEDURE (h: HANDLE); + + <*CALLBACK*> PROCEDURE Foo (h: HANDLE) = + BEGIN .... +
+declares a procedure and procedure type that use the Windows/NT + CALLBACK (i.e. __stdcall) calling convention. +
+ + The SRC Modula-3 compiler treats procedure types that are equal + except for their calling conventions as different types. + +
+ Last modified on Thu Jan 4 11:07:59 PST 1996 by heydon + modified on Wed Dec 21 14:47:24 PST 1994 by kalsow + modified on Thu Jan 7 18:40:57 PST 1993 by muller +
+ + + + Index: m3/pm3/language/modula3/m3compiler/src/restrictions.html diff -c /dev/null m3/pm3/language/modula3/m3compiler/src/restrictions.html:1.2 *** /dev/null Tue Feb 10 23:31:02 1998 --- m3/pm3/language/modula3/m3compiler/src/restrictions.html Tue Feb 10 22:57:48 1998 *************** *** 0 **** --- 1,106 ---- + + +Implementation restrictions + + + +Implementation restrictions
++ + With a few exceptions, SRC Modula-3 implements the + Modula-3 language definition. +
+ +
Arithmetic checking
++ + SRC Modula-3 does not generate any special checking for integer arithmetic + overflow or underflow. You get whatever checking gcc gives you. + Depending on your machine, the + FloatMode interface may be used to control floating point exceptions. +
+ +
Packed types
++ + Packed types are restricted. The compiler enforces the rule that every scalar + field (packed or unpacked) can be loaded by a simple ``load, shift, and mask'' + sequence on the machine. So, for example, its not possible to + have a 32-bit integer that crosses a 32-bit alignment boundary + on a machine which only supports aligned 32-bit loads. + +
Stack overflow checking
++ + SRC Modula-3 does not reliably detect thread stack overflows. Stacks + are only checked for overflow on procedure entry. No checking is done + on external procedures. Thread stacks are allocated in fixed size + chunks. The required Thread + interface has been augmented with + the SizedClosure type to allow arbitrary sized stacks. The default + size can be adjusted with Thread.MinDefaultStackSize and + Thread.IncDefaultStackSize. + +
Exception semantics
++ + On some platforms (ALPHA_OSF and DS3100), exceptions scopes + are delimited by tables of PCs and exceptions are dispatched by a + runtime routine that's able to unwind the stack. +
+ + On all other platforms, + SRC Modula-3 uses C's setjmp/longjmp mechanism to + unwind the stack when raising an exception. A problem can + occur: assignments may appear to be undone. + For example, consider +
+ TRY + i := 3; + P (); + EXCEPT E: + j := i; + END; +
+where P raises exception E. + The compiler generates a setjmp at the beginning of + the try statement. If the C compiler allocates variable i + to a register, the assignment of 3 may be lost during the + longjmp and branch that gets to the handler. + +
Method constants
++ + The language definition says that if T is an object type + and m one of its methods, T.m denotes the procedure + value that implements that method and that this value is a constant. + In SRC Modula-3, T.m denotes the correct procedure constant, + but since the compiler generates runtime code to locate the method, + some uses of the constant that the C compiler must resolve at link + time will cause C errors. + For example, +
+ CONST P = T.m; BEGIN P (...) ... +
+will work, since no initialized C storage is allocated for P. + But the following generates initialized storage and will fail +
+ CONST X = ARRAY [0..2] OF Proc { T.m, ..}; +++ + Similarly, although Modula-3 allows it, the following cannot be + evaluated at compile time +
+ CONST X = (T.m = MyProcedure); +
+ ++ Last modified on Thu Jan 4 11:07:59 PST 1996 by heydon + modified on Thu Jun 1 08:16:29 PDT 1995 by kalsow + modified on Thu Jan 7 18:40:57 PST 1993 by muller +
+ + + + Index: m3/pm3/language/modula3/m3compiler/src/runtime.html diff -c /dev/null m3/pm3/language/modula3/m3compiler/src/runtime.html:1.2 *** /dev/null Tue Feb 10 23:31:02 1998 --- m3/pm3/language/modula3/m3compiler/src/runtime.html Tue Feb 10 22:57:48 1998 *************** *** 0 **** --- 1,93 ---- + + +A tour of the runtime + + + +A tour of the runtime
++ + This section contains a brief introduction to the internal structure + of the runtime system. This introduction is neither + comprehensive nor tutorial; it is merely intended as a stepping stone + for the courageous. +
+ + The runtime itself implements the + garbage collector, + Modula-3 startup code and a few miscellaneous functions. The runtime + exists in the libm3/src/runtime directory. +
+ + The allocator and + garbage collector + are based on Joel Bartlett's + ``mostly copying collector''. + Since that paper, we've made a few + modifications to support a growing heap and to use extra information + that the Modula-3 compiler generates. +
+ + On some platforms + (e.g. DS3100 and ALPHA_OSF) exceptions are + implemented by PC tables and a stack walker. + On all other platforms, exceptions are implemented with setjmp + and longjmp. The + jump buffers and scope descriptors are chained together to form a + stack. + The ThreadF + interface holds the head of the chain. + There is a distinct chain for each thread. When an exception is + raised, the chain is searched. If a handler for the exception is + found, the exception is allowed to unwind the stack, otherwise a + runtime error is signaled. To unwind the stack, a longjmp is + done to the first handler on the stack. It does whatever cleanup is + necessary and passes control on up the stack to the next handler until + the exception is actually handled. +
+ + Reference types are represented at runtime by a ``typecell''. Due to + separate compilation, opaque types and revelations, it is not possible + to fully initialize typecells at compile time. Typecell + initialization is finished at link time. A typecell contains a type's + typecode, a pointer to its parent typecell, the size of the types + referent and method list if any, the type's brand, the number of open + array dimensions, the type's fingerprint, and procedures to initialize + the typecell, initialize new instances of the type, print instances of + the type and trace the type for garbage collection. +
+ + At the beginning of the execution of the program, all global variables + are initialized, and the main bodies of the modules are invoked. The + table that lists the module to be initialized is + generated by the linker part of the driver. +
+ + Other parts of the runtime, such as threads, are actually implemented + in the base library. +
+ + On Unix, Thread switching + is implemented with setjmp and longjmp. + A timer interrupt (signal) + is used to cause preemptive thread + switching. The global variable + ThreadPosix.self + points to the + currently running thread. The integer + RT0u.inCritical + is used by the runtime to prevent thread switching during garbage + collection and other ``atomic'' runtime operations. +
+ + On Windows/NT, Modula-3 threads are implemented as Win32 kernel threads. + +
+ Last modified on Thu Jan 4 11:07:58 PST 1996 by heydon + modified on Thu Jun 1 08:16:58 PDT 1995 by kalsow + modified on Tue Feb 18 13:23:15 PST 1992 by muller +
+ + + + Index: m3/pm3/language/modula3/m3compiler/src/scheduler.html diff -c /dev/null m3/pm3/language/modula3/m3compiler/src/scheduler.html:1.1.1.1 *** /dev/null Tue Feb 10 23:31:02 1998 --- m3/pm3/language/modula3/m3compiler/src/scheduler.html Sat Jan 31 14:47:12 1998 *************** *** 0 **** --- 1,91 ---- + + +Thread scheduling + + + +Thread scheduling
++ + SRC Modula-3 has a flexible scheduling algorithm. + Here is a rough explanation of its behaviour. +
+ + All threads are kept in a circular list. This list is + modified only when new threads are created or when they exit; that + is, the relative order of threads in this list is never modified. +
+ + When the scheduler comes into action, the list of threads is scanned + starting with the thread following the one currently running, until + a thread that can execute is found: +
-
+
- if it was preempted by the scheduler or called + Scheduler.Yield, + it can execute + +
- if it is waiting for a condition or a mutex that is now free, + it can execute + +
- if it has blocked because of a call to + Thread.Pause + (or a similar procedure), it can execute iff the timeout has expired + +
- if it has blocked because of a call to + SchedulerPosix.IOWait, + (or a similar procedure), it can execute iff the timeout is now expired + or a polling select(2) returns a non-zero value. +
+ + If such a thread is found, it becomes active. +
+ + If no thread can execute, and there are no threads blocked in a + Thread.Pause + or a + SchedulerPosix.IOWait, + a deadlock situation is detected + and reported. Otherwise, a combination of the file descriptors sets + (OR of all the file descriptors sets) and timeouts (MIN of all the + timeouts) is formed, select(2) is called with those arguments + and the whole process of searching for an executable thread is redone. + This ensures that the Unix process does not consume CPU resources while + waiting. +
+ + The scheduler is activated when the running thread tries to acquire a + mutex which is locked, waits for a condition, calls + Thread.Pause + (or a similar procedure) with a future time, calls + SchedulerPosix.IOWait + (or a similar procedure) with a non-zero valued timeout and no files + are ready at the time of the call, or the time allocated to the thread + has expired (preemption). +
+ + Preemption is implemented using the Unix virtual interval timer. + SRC Modula-3 does not use the real time interval + timer nor the profiling interval timer for thread scheduling; these + are available to the program. +
+ + Because of the preemption implementation, Unix kernel calls + will block the process (i.e. the Unix process sleeps even though + some threads could run). However, + Thread.Pause + and + SchedulerPosix.IOWait + provide functional equivalents of + sigpause(2) and + select(2) that do not cause the process to block. +
+
+ Last modified on Thu Jan 4 11:07:58 PST 1996 by heydon + modified on Thu Jun 1 08:17:53 PDT 1995 by kalsow + modified on Thu Jan 7 18:40:57 PST 1993 by muller +
+ + + + Index: m3/pm3/language/modula3/m3compiler/src/signals.html diff -c /dev/null m3/pm3/language/modula3/m3compiler/src/signals.html:1.1.1.1 *** /dev/null Tue Feb 10 23:31:02 1998 --- m3/pm3/language/modula3/m3compiler/src/signals.html Sat Jan 31 14:47:12 1998 *************** *** 0 **** --- 1,56 ---- + + +Unix signals usage + + + +Unix signals usage
++ + On Unix the Modula-3 runtime catches seven signals: + SIGHUP, + SIGINT, + SIGTERM, + SIGQUIT, + SIGSEGV, + SIGPIPE, + and + SIGVTALRM. + Otherwise, the runtime leaves the default Unix signal handlers unaltered. +
+ + SIGHUP(``hang up''), SIGINT(``interrupt''), + and SIGTERM(``terminate'') all indicate that the + program is to stop. The Modula-3 runtime calls its usual + clean-up routines and exits. +
+ + SIGQUIT is like the above, except the runtime + prints the error message ``aborted'', and attempts + to crash with a ``core file''. +
+ + SIGSEGV indicates a ``segmentation violation'' and is often + signaled when a process dereferences NIL. + The runtime catches SIGSEGV, prints an error message, and attempts + to crash with a ``core file''. +
+ + SIGPIPE indicates a ``broken pipe''. The runtime ignores the + signal and when next accessed, any reader(writer) that was using the pipe + will raise Rd.Failure(Wr.Failure). +
+ + SIGVTALRM is the ``virtual timer alarm''. It is used to periodically + preempt the running thread. +
+ +
+ Last modified on Thu Jan 4 11:07:57 PST 1996 by heydon + modified on Fri Apr 22 11:45:04 PDT 1994 by kalsow + modified on Thu Jan 7 18:40:57 PST 1993 by muller +
+ + + + Index: m3/pm3/language/modula3/m3compiler/src/linking/Example1.gif Index: m3/pm3/language/modula3/m3compiler/src/linking/Example2.gif Index: m3/pm3/language/modula3/m3compiler/src/linking/Example3.gif Index: m3/pm3/language/modula3/m3compiler/src/linking/Example4.gif Index: m3/pm3/language/modula3/m3compiler/src/linking/LinkingLibs.html diff -c /dev/null m3/pm3/language/modula3/m3compiler/src/linking/LinkingLibs.html:1.1.1.1 *** /dev/null Tue Feb 10 23:31:02 1998 --- m3/pm3/language/modula3/m3compiler/src/linking/LinkingLibs.html Sat Jan 31 14:47:12 1998 *************** *** 0 **** --- 1,18 ---- + + +Linking Library Packages + + + +Linking Library Packages
++ + When you build a library package, no reachability graph is + constructed. The only requirement on a library package is that any + interface IMPORTed or EXPORTed by each of the library's root units + must either be a root, or a visible interface in some imported + package.
+ + + + Index: m3/pm3/language/modula3/m3compiler/src/linking/LinkingProgs.html diff -c /dev/null m3/pm3/language/modula3/m3compiler/src/linking/LinkingProgs.html:1.1.1.1 *** /dev/null Tue Feb 10 23:31:02 1998 --- m3/pm3/language/modula3/m3compiler/src/linking/LinkingProgs.html Sat Jan 31 14:47:12 1998 *************** *** 0 **** --- 1,39 ---- + +
+The Linker's Inclusion Algorithm + + + +The Linker's Inclusion Algorithm
++ + When you build a program package or library package that imports one + or more library packages, the interfaces you IMPORT from within those + imported packages must be visible. However, there are other + requirements you must satisfy when building a program.
+ + The Modula-3 language definition defines a complete program to + be "a collection of modules and interfaces that contains every + interface imported or exported by any of its modules or interfaces, + and in which no procedure, module, or interface is multiply defined" + (Section 2.5, page 42). There are other requirements on a complete + program as well. For example, every declared procedure must have an + implementation, and every opaque type must have a concrete + revelation.
+ + When you build a program that imports library packages, not all of the + interfaces and modules in those libraries are necessarily included by + the linker. In fact, only those interfaces and modules that satisfy a + reachability requirement are linked into the final program.
+ +
More Information
+ + + + + + Index: m3/pm3/language/modula3/m3compiler/src/linking/ReachabilityExs.html diff -c /dev/null m3/pm3/language/modula3/m3compiler/src/linking/ReachabilityExs.html:1.2 *** /dev/null Tue Feb 10 23:31:02 1998 --- m3/pm3/language/modula3/m3compiler/src/linking/ReachabilityExs.html Tue Feb 10 22:57:52 1998 *************** *** 0 **** --- 1,142 ---- + + +Linker Reachability Examples + + + +Reachability Examples
++ + These examples were suggested by Umesh Maheshwari + (umesh@note.lcs.mit.edu). + +
Example 1
+ +Our first example consists of a program built from two packages: a + library package named LibPkg and a program package named + ProgPkg. +
+ The LibPkg package consists of three source files: "X.i3", + "Y.i3", and "Y.m3".
+ +
+ INTERFACE X; INTERFACE Y; + TYPE T <: ROOT; END Y. + END X. + + MODULE Y; + IMPORT X; + REVEAL X.T = ROOT BRANDED OBJECT c: CHAR END; + BEGIN END Y. +
+ +The m3makefile for package LibPkg is:
+ +
+ import(libm3) + Interface(X) + Module(Y) + Library(LibPkg) +
+ +The ProgPkg package consists of a single source file, + "Main.m3". + +
+ MODULE Main; + IMPORT X; + BEGIN END Main. +
+ +The m3makefile for package ProgPkg is:
+ +
+ override(LibPkg, "../..") + import(libm3) + import(LibPkg) + implementation(Main) + program(Prog) +
+ +The unit graph constructed by the linker when it builds the + ProgPkg program looks like this:
+ +
![[ Image for Figure 1 ]](Example1.gif)
+ +
In this and subsequent figures, the roots are colored red, the + reachable non-roots are colored blue, and the edges are labeled "I" or + "E" to denote that the edge is due to an IMPORT or EXPORTS relation, + respectively. Hence, the colored nodes correspond to the units + included in the final build.
+ +
Since the units "Y.m3" and "Y.i3" are not reachable from the single + root "Main.m3", the linker does not include them in the build. Hence, + the linker does not find a concrete revelation for the type "X.T". + When we run m3build on the ProgPkg package, the compiler + prints out the following error message:
+ +
+ -> linking Prog + opaque type never revealed: _tb81ca1e6 + defined in X.i3 +
+ +The problem can be avoided in a number of ways, as shown in the + following three examples. + +
Example 2
+ +If we change "Main.m3" so that it imports "Y" as well as "X", the unit + graph changes to look like this:
+ +
![[ Image for Figure 2 ]](Example2.gif)
+ + Now, both "Y.i3" and "Y.m3" are reachable from the root, so the linker + finds a concrete revelation for "X.T", and the program builds + successfully. + +
Example 3
+ +Starting from Example 1, we can instead export the interface "X" in + the module "Y", like this:
+ +
+ MODULE Y EXPORTS X, Y; + IMPORT X; + REVEAL X.T = ROOT BRANDED OBJECT c: CHAR END; + BEGIN END Y. +
+ +This adds a new EXPORTS edge to the unit graph:
+ +
![[ Image for Figure 3 ]](Example3.gif)
+ +
Now, "Y.m3" has become reachable from the root "Main.m3" through + "X.i3", so the linker again finds a concrete revelation for "X.T", and + the program builds successfully.
+ +
Example 4
+ +Starting from the source files of Example 1, we can move all of the + LibPkg sources into the ProgPkg package. The + m3makefile for the ProgPkg then becomes:
+ +
+ import(libm3) + interface(X) + module(Y) + implementation(Main) + program(Prog) +
+ +This doesn't change the unit graph from Example 1, but it does + makes all four of the sources roots:
+ +
![[ Image for Figure 4 ]](Example4.gif)
+ +
Hence, "Y.m3" is once again seen by the linker, and the program builds + successfully.
+ + + + Index: m3/pm3/language/modula3/m3compiler/src/linking/ReachabilityReq.html diff -c /dev/null m3/pm3/language/modula3/m3compiler/src/linking/ReachabilityReq.html:1.2 *** /dev/null Tue Feb 10 23:31:02 1998 --- m3/pm3/language/modula3/m3compiler/src/linking/ReachabilityReq.html Tue Feb 10 22:57:52 1998 *************** *** 0 **** --- 1,44 ---- + +
+The Reachability Requirement + + + +The Reachability Requirement
++ + When building a program, the linker determines which units (interfaces + and modules) to include by traversing a directed graph. The nodes of + the graph correspond to program units, and certain nodes of the graph + are designated as roots. A unit u is included in the + build if and only if u is reachable from some root, that is, if + there exists a (possibly empty) path in the graph from some root + r to u. We must now describe how the linker determines + the set of roots and the set of edges in this graph.
+ + Each program's m3makefile specifies a set of sources via quake + calls like interface(X), implementation(X), and + module(X). Each of these calls adds the name of the source file + (or unit) to the set of program sources. + These program sources constitute the set of roots used + to start the traversal. Notice that source files included via + include_dir(D) or include_pkg(P) will get added to this + list, but not those imported via import(P).
+ + The edges of the graph are determined by the IMPORT and EXPORTS + relations among the units. An edge exists in the graph from the unit + A to the unit B if and only if:
+ +
-
+
- A IMPORTs B, +
- A EXPORTS B, or +
- B EXPORTS A. +
That is, if A IMPORTs B, then there is a directed edge from A to B in + the graph, but if A EXPORTS B, then there is a bi-directional edge + between A and B.
+ + + + Index: m3/pm3/language/modula3/m3compiler/src/linking/m3makefile diff -c /dev/null m3/pm3/language/modula3/m3compiler/src/linking/m3makefile:1.1.1.1 *** /dev/null Tue Feb 10 23:31:02 1998 --- m3/pm3/language/modula3/m3compiler/src/linking/m3makefile Sat Jan 31 14:47:12 1998 *************** *** 0 **** --- 1,9 ---- + + HtmlTextFile("Example1.gif") + HtmlTextFile("Example2.gif") + HtmlTextFile("Example3.gif") + HtmlTextFile("Example4.gif") + HtmlFile("LinkingLibs") + HtmlFile("LinkingProgs") + HtmlFile("ReachabilityExs") + HtmlFile("ReachabilityReq") Index: m3/pm3/language/modula3/m3tools/coverage/src/m3makefile diff -c m3/pm3/language/modula3/m3tools/coverage/src/m3makefile:1.5 m3/pm3/language/modula3/m3tools/coverage/src/m3makefile:1.6 *** m3/pm3/language/modula3/m3tools/coverage/src/m3makefile:1.5 Wed Dec 17 15:57:00 1997 --- m3/pm3/language/modula3/m3tools/coverage/src/m3makefile Tue Feb 10 22:57:57 1998 *************** *** 28,34 **** if defined ("_all") if stale (pgm, src) ! ret = m3_compile_c(src,obj,["../src"]) if not equal(ret, 0) error("command failed with error code: ", ret) end ret = m3_link(pgm,[obj],[]) if not equal(ret, 0) error("command failed with error code: ", ret) end --- 28,34 ---- if defined ("_all") if stale (pgm, src) ! ret = m3_compile_c(src,obj,[".." & SL & "src"]) if not equal(ret, 0) error("command failed with error code: ", ret) end ret = m3_link(pgm,[obj],[]) if not equal(ret, 0) error("command failed with error code: ", ret) end Index: m3/pm3/language/modula3/m3tools/gnuemacs/src/index.html diff -c /dev/null m3/pm3/language/modula3/m3tools/gnuemacs/src/index.html:1.2 *** /dev/null Tue Feb 10 23:31:06 1998 --- m3/pm3/language/modula3/m3tools/gnuemacs/src/index.html Tue Feb 10 22:58:02 1998 *************** *** 0 **** --- 1,148 ---- + +
+GNU emacs support + + + +GNU emacs support
+ ++ SRC Modula-3 comes with a mode for editing Modula-3 programs under + gnuemacs. Here is a list of the main features this mode + provides: + +
-
+
- Indenting/pretty-printing
+
+ + Modula-3 mode provides two methods of formatting code, one ``batch'' + and one ``interactive.'' The batch method invokes the program m3pp, which takes a program unit such + as a procedure and formats it completely. The gnuemacs + commands (and their keyboard shortcuts) that invoke m3pp are:
- M-x + m3::pp-buffer (C-c b)
- Pretty prints the current buffer.
+
- M-x m3::pp-region (C-c r)
- Pretty-prints the code
+ between mark and point.
- M-x m3::pp-unit (C-c u)
- + Pretty-prints the ``unit'' containing the cursor. (A unit is a + top-level construct such as CONST, TYPE, + VAR, or PROCEDURE.)
+ The other method of formatting text is a more traditional one for + gnuemacs, in which the language mode provides a key that + indents the current line appropriately. In keeping with the + convention used in modes for other languages such as Lisp and C, the + key used is TAB. Typing TAB on a line indents the + current line in a way that is (we hope) appropriate given the lines + that precede it. + +
+ The two formatting methods are not mutually exclusive; perhaps + you like the way m3pp lines up columns in declarations, + but you also like to keep things indented while you type. You + can use the electric mode to get things close, then invoke + m3pp when you're done. + +
- Avoidance of typing
+
+ + Modula-3 mode offers some aid if you don't like typing a lot of + uppercase keywords. The TAB actually serves double + duty; it not only indents the current line, but when invoked at + the end of a word, it attempts to complete the current word as a + keyword. For example b TAB expands the b to + BEGIN, provided the b appears in a context where + BEGIN may be a valid keyword. There are some fairly extensive + rules governing the contexts in which a given keyword is a valid + completion; the net result is that it is seldom necessary to type + more than one letter to get the correct completion. If you + specify a non-unique prefix of a set of keywords, it chooses the + first in an ordering intended to capture frequency of use; it + also presents the other choices, and typing TAB repeatedly + cycles through these choices. +
+ A pair of related features are ``END-completion'' and + ``END-matching.'' If the elisp variable + m3::electric-end is set to 'all, completing the + keyword END has the additional effect of finding the + construct that the END completes. If that construct is a + an interface, module, or procedure, it fills in the name of the + completed construct after the END; otherwise, it inserts a + comment containing the keyword of the completed construct. If + m3::electric-end is 'proc-mod, it only fills in + real names, never keyword comments. Independently, a non-nil + value of the elisp variable m3::blink-end-matchers causes + completion of END to blink the cursor briefly at the + beginning of the completed construct. + +
- Finding files
+
+ The key C-c i is bound to m3::show-interface, which + expects the point to be in an interface name, and attempts to + find that interface and display it in another window. + It uses a built-in list of directories. The + default value of this list is the one used at SRC; other + sites will probably need to modify this. +
+ + The key C-c m is bound to m3::show-implementation. This + attempts to find the module that implements the interface in the + current buffer. As distributed, this function relies on SRC-specific + conventions. Obviously, this may not work outside of SRC, and + m3::show-implementation may need to be re-implemented or abandoned. +
+ To have the Modula-3 mode automatically invoked when visiting a + Modula-3 source file, you should put in your .emacs: + +
+ (autoload 'modula-3-mode "modula3") + (setq auto-mode-alist + (append '(("\\.ig$" . modula-3-mode) + ("\\.mg$" . modula-3-mode) + ("\\.i3$" . modula-3-mode) + ("\\.m3$" . modula-3-mode)) + auto-mode-alist)) ++ ++ It is also convenient to have the lines: + +
+ (setq completion-ignored-extensions + (append '(".mo" ".mx" ".mc" ".io" ".ix") completion-ignored-extensions)) +++ so that you don't get the files with those extensions offered as + possible completions. + +
+ Your system administrator may have inserted these lines in the default + macro files for your system. + +
Tags
+ ++ There is also a program to build tags file for Modula-3 programs: + m3tags; see the manpage for the details. When the system is + installed, a tag file for the public interfaces is built. To access + it, you need in your .emacs (or in the system initialization file) + the line: +
+ (visit-tags-table "LIB_USE/FTAGS") +
++ where LIB_USE is the place where the Modula-3 libraries have + been installed. + +
+ Last modified on Mon Jul 22 12:51:08 PDT 1996 by heydon + modified on Fri Apr 22 11:35:32 PDT 1994 by kalsow + modified on Thu Jan 7 18:40:57 PST 1993 by muller +
+ + + + Index: m3/pm3/language/modula3/m3tools/gnuemacs/src/m3makefile diff -c m3/pm3/language/modula3/m3tools/gnuemacs/src/m3makefile:1.4 m3/pm3/language/modula3/m3tools/gnuemacs/src/m3makefile:1.5 *** m3/pm3/language/modula3/m3tools/gnuemacs/src/m3makefile:1.4 Wed Dec 17 15:54:43 1997 --- m3/pm3/language/modula3/m3tools/gnuemacs/src/m3makefile Tue Feb 10 22:58:02 1998 *************** *** 6,13 **** % modified on Fri Nov 5 16:41:57 PST 1993 by detlefs % modified on Mon Jan 18 19:09:20 PST 1993 by muller - m3_option("-commands") - VERBOSE="TRUE" if equal (TARGET, "LINUX") or equal (TARGET, "LINUXELF") include_dir ("flex-bison") --- 6,11 ---- *************** *** 20,31 **** import_lib("c", "/lib") c_source ("m3tags") h_source ("hash") - C_program ("m3tags") ManPage ("m3tags", 1) CompiledGnuemacs ("m3tags") CompiledGnuemacs ("modula3") CompiledGnuemacs ("ispell19-3.0") % CompiledGnuemacs ("m3-debug") % CompiledGnuemacs ("shell-compile") --- 18,32 ---- import_lib("c", "/lib") c_source ("m3tags") h_source ("hash") ManPage ("m3tags", 1) + import("m3doc") + HtmlFile("index") CompiledGnuemacs ("m3tags") CompiledGnuemacs ("modula3") CompiledGnuemacs ("ispell19-3.0") % CompiledGnuemacs ("m3-debug") % CompiledGnuemacs ("shell-compile") + + C_program ("m3tags") Index: m3/pm3/language/modula3/m3tools/m3gdb/src/index.html diff -c /dev/null m3/pm3/language/modula3/m3tools/m3gdb/src/index.html:1.1.1.1 *** /dev/null Tue Feb 10 23:31:40 1998 --- m3/pm3/language/modula3/m3tools/m3gdb/src/index.html Sat Jan 31 14:47:12 1998 *************** *** 0 **** --- 1,116 ---- + + +Modula-3 Debugging + + + +Modula-3 Debugging
++ + A Modula-3 aware version of gdb may be used to debug Modula-3 code. + It understands Modula-3 types, declarations, and expressions. It also + supports threads. The usual gdb commands may be used. This document + discusses three areas where special care is required: + garbage collection, threads, and calling non standard procedures. + + While gdb tries to determine automatically the language for + the current frame (procedure), you may sometimes want to + explicitely set the current language: +
+ (m3gdb) set language m3 + (m3gdb) set language c +
+ +Garbage collection
+ ++ On some platforms, a VM synchronized version of the garbage collector + uses SIGSEGV signals. By default, gdb stops and prints a message each + time SIGSEGV is received. This behavior may be changed with the + handle command. + The simplest way to avoid these signals + is to disable the VM synchronized garbage collector, using the + @M3novm command line option: + +
+ cassis> m3gdb myprog + (m3gdb) run @M3novm ...other arguments... +
+ ++ If you prefer to keep the VM synchronized collector while debugging, + you may use: + +
+ (m3gdb) handle SIGSEGV noprint pass +
+ ++ However, you will then not be able to examine the protected memory regions. + You may unprotect the memory with: + +
+ (m3gdb) call RTCollectorSRC.FinishVM() +
+ ++ You may disable the memory protection for the rest of the execution with: + +
+ (m3gdb) call RTCollectorSRC.DisableVM() +
+ +Threads
+ ++ On platforms where Modula-3 uses native threads (NT), the + gdb thread commands may be used (info thread, and thread) + to list the threads and switch to another thread. + +
+ On other platforms, m3gdb provides threads to list the + threads, and switch id to switch to another thread indicated by + id. You must switch back to the thread where the program + stopped before continuing the execution (i.e. the first thread + listed by the threads). + If the switch command is interrupted, the state of + m3gdb is essentially random and it will most likely crash. + The current language must be m3 for the threads + and switch commands to work. +
+ +
Calling procedures from m3gdb
+ ++ Modula-3 procedures are mapped as closely as possible into C procedures + and may be called by gdb using call. + Two differences exist: "large" results and nested procedures. + +
+ First, procedures that return structured values (i.e. records, arrays + or sets) take an extra parameter. The last parameter is a pointer to + the memory that will receive the returned result. This parameter was + necessary because some C compilers return structured results by + momentarily copying them into global memory. The global memory scheme + works fine until it's preempted by the Modula-3 thread scheduler. + +
+ Second, nested procedures are passed an extra parameter, the ``static link''. + The exact details of how that parameter are passed are system dependent. + When a nested procedure is passed as a parameter, the address of the + corresponding C procedure and its extra parameter are packaged + into a small closure record. The address of this record is actually + passed. Any call through a formal procedure parameter first checks to + see whether the parameter is a closure or not and then makes the + appropriate call. Likewise, assignments of formal procedure + parameters to variables perform runtime checks for closures. +
+ + <*EXTERNAL*> + procedures have no extra parameters. + except if they return large results?? +
+ + + + Index: m3/pm3/language/modula3/m3tools/m3gdb/src/m3makefile diff -c m3/pm3/language/modula3/m3tools/m3gdb/src/m3makefile:1.2 m3/pm3/language/modula3/m3tools/m3gdb/src/m3makefile:1.3 *** m3/pm3/language/modula3/m3tools/m3gdb/src/m3makefile:1.2 Fri Nov 28 09:24:19 1997 --- m3/pm3/language/modula3/m3tools/m3gdb/src/m3makefile Tue Feb 10 22:58:21 1998 *************** *** 45,59 **** if not equal(ret,0) error("Failed to build m3gdb") end else % configure the sources & compile ! ret = exec (["../gdb/configure", % M3GDB_CONFIG, ! "--srcdir=../gdb", "--disable-gdbtk", gnu_platform (M3GDB_HOST)]) ret = exec ([M3GDB_MAKE, ARG0, ARG1]) if not equal(ret,0) error("Failed to build m3gdb") end end % finally, build the exportable link and man page and export them ! ret = exec(["mv","gdb/gdb", "m3gdb"]) if not equal(ret,0) error("Failed to rename gdb to m3gdb") end BindExport ("m3gdb") ManPage ("m3gdb","1") --- 45,75 ---- if not equal(ret,0) error("Failed to build m3gdb") end else % configure the sources & compile ! local cmd = [".." & "/" & "gdb" & "/" & "configure", % M3GDB_CONFIG, ! "--srcdir=../gdb", "--disable-gdbtk", gnu_platform (M3GDB_HOST)] ! if equal(OS_TYPE,"WIN32") ! > "tmpsh" in ! write("#! /bin/sh",CR) ! write(cmd,CR) ! end ! ret = exec(["sh","tmpsh"]) ! else ! ret = exec (cmd) ! end ret = exec ([M3GDB_MAKE, ARG0, ARG1]) if not equal(ret,0) error("Failed to build m3gdb") end end % finally, build the exportable link and man page and export them ! ret = exec(["mv","gdb/gdb" & NAMING_CONVENTIONS[20], ! "m3gdb" & NAMING_CONVENTIONS[20]) if not equal(ret,0) error("Failed to rename gdb to m3gdb") end BindExport ("m3gdb") ManPage ("m3gdb","1") + + import("m3doc") + HtmlFile("index") + + OtherPackage("m3gdb") + Index: m3/pm3/language/modula3/m3tools/m3ide/src/index.html diff -c m3/pm3/language/modula3/m3tools/m3ide/src/index.html:1.1.1.1 m3/pm3/language/modula3/m3tools/m3ide/src/index.html:1.2 *** m3/pm3/language/modula3/m3tools/m3ide/src/index.html:1.1.1.1 Tue Jan 27 13:56:26 1998 --- m3/pm3/language/modula3/m3tools/m3ide/src/index.html Tue Feb 10 22:58:25 1998 *************** *** 17,26 **** The first step is set your emacs path to include /usr/local/pm3-1.1/lib/elisp and to load m3setup.el from your .emacs file. !
(setq load-path (append (list "/usr/local/pm3-1.1/lib/elisp") load-path)) (load-library "m3setup.el") !
This will setup the automatic loading of the m3ide (within the modula3) mode when a file ending in .i3, .m3, .ig, .mg, .fv is loaded. Then, --- 17,27 ---- The first step is set your emacs path to include /usr/local/pm3-1.1/lib/elisp and to load m3setup.el from your .emacs file. ! !
(setq load-path (append (list "/usr/local/pm3-1.1/lib/elisp") load-path)) (load-library "m3setup.el") !
This will setup the automatic loading of the m3ide (within the modula3) mode when a file ending in .i3, .m3, .ig, .mg, .fv is loaded. Then, *************** *** 56,62 **** move even more functionality into Modula-3 code. Here is a whish list. I will not have time in the foreseeable future to do any of it. Volunteers are more than welcome. Thanks to ! Lennart Staflin
-
--- 57,63 ----
move even more functionality into Modula-3 code. Here is a whish
list. I will not have time in the foreseeable future to do
any of it. Volunteers are more than welcome. Thanks to
! Lennart Staflin <lenst@lysator.liu.se> for converting the xemacs menus
to emacs and miscellaneous elisp code improvements.
-
Index: m3/pm3/language/modula3/m3tools/pp/src/index.html
diff -c /dev/null m3/pm3/language/modula3/m3tools/pp/src/index.html:1.2
*** /dev/null Tue Feb 10 23:31:51 1998
--- m3/pm3/language/modula3/m3tools/pp/src/index.html Tue Feb 10 22:58:34 1998
***************
*** 0 ****
--- 1,326 ----
+
+
+
Pretty printing + + + +Pretty printing
+ ++ SRC Modula-3 includes a pretty-printer for Modula-3 programs called + m3pp. + It will take the source code + and make decisions on where to place line breaks, how far to indent lines, + etc. to produce a supposedly more readable version of the program. + +
+ The syntax for calling m3pp is +
+ m3pp [options] [file] +
+ +The pretty-printer reads its input from the specified file. + If no file is given, then the pretty-printer reads standard + input. The formatted version is always sent to standard output. + +
+ The pretty-printer can produce text output suitable for replacing your code + (the default) or PostScript output suitable for printing. Some additional + options are availble when producing PostScript output. + +
Options
+ ++ The pretty-printer reads options from $HOME/.m3pp.pro.1, + then .m3pp.pro.1 + in the current directory, then from the command line. Single-letter + abbreviations can be used, but no others are recognized. + +
+
+ ++ -caps + Recognize keywords in either lower or upper case and + map them to upper case in the output. If this option + is not specified, keywords must appear in upper case. + +
+ -margin n + Set the margin to n. + The margin is the maximum width of an output line. + The pretty-printer occasionally exceeds this maximum, so it's usually wise + to set it a little lower than you want. If this option is not specified, a + margin of 75 is used. + +
+ -offset n + Set the offset to n. + The offset is the number of spaces by + which a construct inside another one is indented. The default + is 2 for text ouput, and 4 for PostScript output. + +
+ -xcolumn n + Set the comment column to n. + This is the column in which comments that are on + the same line as code but are not followed on that line by code will start. + To disable comment alignment, specify -xcolumn 1. + The default is 33 for text output, 80 for PostScript output. + +
+ -src + Use the SRC style of formatting (default). + +
+ -eric + Use Eric's style. "END"s are emitted at the end of lines rather + than on a line by themselves. This option cannot be abbreviated. + +
+ -callspace + This inserts blank space around function calls and array subscripts. + "f(x,y)" becomes "f (x, y)" and "a[i]" becomes "a [i]". + This option cannot be abbreviated. + +
+ -noalign + The pretty-printer attempts to align const, variable, and type declarations + into columns. This option turns off the alignment. It does not disable + the alignment of formal parameter lists when they don't fit on one line. + +
+ -whenbreak {always | early | late} + When the pretty-printer has to break a line that's too long, you have + two stylistic choices: +
+ 1: AlongFunctionCall( + withLongParameters, likeThisOne, andThisOne); + + 2: AlongFunctionCall(withLongParameters, likeThisOne, + andThisOne); +
+ ++ -whenbreak always + tells the pretty-printer to use style 1, always. Otherwise, + it will consider BOTH styles, which takes somewhat more time. If + style 1 produces fewer lines, it will use it. If they produce the + same number of lines, then: + -whenbreak early + says to use style 1, and + -whenbreak late + says to use style 2. + The arguments can be abbreviated as a, e, or l. + The default is "-whenbreak early". + +
+ -break + This is equivalent to "-whenbreak always". + +
+ -follow + Normally, the formatter assumes that comments precede declarations or code, + and formats them at the same indentation level as whatever follows. This + style can also work fine with comments that follow a declaration. This + option changes the comment indentation to more closely match the older + version of the pretty-printer, assuming that comments follow declarations. + With -follow, you get +
+ CONST + maxElements = 3; + (* limit for number of elements *) + PROCEDURE AddOne(e: INTEGER); +
+instead of +
+ CONST + maxElements = 3; + (* Add an element. *) + PROCEDURE AddOne(e: INTEGER); +
+In either case, a blank line will cause subsequent comments to be aligned + with the statements or declarations that follow. You get +
+ CONST + maxElements = 3; + + (* Add an element. *) + PROCEDURE AddOne(e: INTEGER); +
+in either mode. The chief disadvantage of this mode is that comments in + blocks of code are attached to the preceding statement and indented one + level unless they are preceded by a blank line. + +
+ -ZZ + Use emacs filter mode. The formatter loops, + accepting and formatting declarations, BEGIN-END groups, or modules. Each + chunk of code to be formatted should begin with a control-B (^B) and end + with a control-A (^A). + +
+ -ZZG + Use emacs filter mode on a single chunk (for a different Emacs package). + +
+ -text + Produce text output. This is the default. + +
+ The following options are used when producing PostScript output. Except + for -portrait, + they cannot be abbreviated. For the font options, valid font names are + PostScript names followed by an integer point size (e.g. "Helvetica9"). + +
+ -ps + Produce PostScript output suitable for printing. + +
+ -portrait + Produce one-column portrait mode output. The default is two-column + landscape mode output. + +
+ -bf font + Set the font used for formatting the body text of the program. The default + is Times-Roman10. + +
+ -kf font + Set the font used for formatting keywords. The default + is Helvetica7. + +
+ -bif font + Set the font used for formatting built-in identifiers. The default + is Times-Roman8. + +
+ -pf font + Set the font used for formatting procedure names. The default + is Times-Bold10. + +
+ -cf font + Set the font used for formatting comments. The default + is Times-Italic10. + +
+ -fcf font + Set the font used for formatting comments that aren't refilled (see below). + The default is Courier-Oblique9. + +
+ -ff font + Set the font used for formatting text and char literals. The default + is Courier9. + +
Features
+ ++ The pretty-printer fills long comments; that is, it chooses line breaks + inside long comments so as to fill up each line with words. This is + usually convenient, but occasionally disastrous: a carefully formated + table, equation, or program in the input will be reduced to a dense + paragraph in the output. To spare your formatted comments from this fate, + begin the comment with "(*|" or "(**", or begin the comment with "(*" on a + line by itself. The old style of marking each line individually is also + supported. In filled comments, lines that begin with a vertical bar ("|") + in column 1 will not be filled. + +
+ Conversely, if you want a comment to be filled, begin the comment with + "(*" and place some text on the same line as the comment start. Pragmas + are never reformatted. Pragmas and comments that are not reformatted may + still be moved left or right to an appropriate indentation level. + +
+ The pretty-printer tries hard not to add or remove blank lines from the + program. It will add and remove line breaks, however. + +
+ The formatting rule used for CASE statements is geared toward + programs in which there is no vertical bar after the last case, and + no vertical bar before the ELSE clause. The same goes for TYPECASE + and TRY statements. + +
+ In selecting elements of multi-dimensional arrays, the syntax + a[i][j] means the same thing as a[i, j]. The second version will + be handled better by the pretty-printer. + +
+ The compiler currently ignores the portion of the input file that + follows the module-terminating dot. However, the pretty-printer + requires that only properly-delimited comments appear in this + portion of the file. Therefore, if your file has any comments + there, be sure that they are enclosed within comment brackets. + +
Syntax errors
+ ++ If the input contains a syntactically valid compilation unit (that + is, a definition module, implementation module, or program module) + then the output becomes the corresponding pretty-printed version. + If the input contains a syntax error, then the output is + pretty-printed up to the lexical token that caused the syntax + error, then a line is printed consisting of the string "(* SYNTAX + ERROR *)" followed by the offending token, an error message is + printed to standard error output, and the remainder of the input is + copied unchanged into the output. Regardless of whether a syntax + error is found, m3pp + exits with status code 0. (If the syntax error + was caused by an unexpected end of file, then the string + "(* SYNTAX ERROR *)" will appear at the end of the output file.) + +
Exceptions
+ ++ String constants of more than 500 characters, or input or output + lines of more than 500 characters, will overflow internal buffers. + In case these or any other run-time errors cause the program to + abort, the output file (if specified) will not be modified. + +
Bugs
+ ++ The pretty-printer sometimes exceeds the margin limits due to details of + the formatting algorithm. The text that exceeds the limit usually consists + of closing delimiters, such as right parens and right brackets. Setting + the margin a little lower than you want usually does the trick. + +
+ The -noalign + option still uses the alignment machinery of the formatter, but tells it to + reset its idea of the column boundaries after each declaration. The bad + side effect of this is that a declaration with a large initializier can be + formatted with the initializer snaking down the right side of the page. + +
+ If you have alignment on and a record has some fields with initializers, + but the last field has no initializer and no trailing semicolon and is + followed by a comment on the same line, then the other fields may be + aligned improperly. Fix this by adding a semicolon to the last field + declaration. + +
Authors
+ ++ Bill Kalsow and Eric Muller (using the framework provided by ppmp). + David Nichols (Xerox PARC) and Jim Meehan (Adobe) made a large number of + improvements and bug fixes. + David Nichols added PostScript support, which Bill Schilit (Xerox PARC and + Columbia Univ.) ported into the current version. + +
+ Last modified on Thu Jan 4 11:08:00 PST 1996 by heydon + modified on Fri Apr 22 11:28:06 PDT 1994 by kalsow + modified on Mon Aug 19 14:46:51 1991 by Nichols@xerox.com + modified on Thu Dec 21 01:33:47 1989 by muller +
+ + + + Index: m3/pm3/language/modula3/m3tools/pp/src/m3makefile diff -c m3/pm3/language/modula3/m3tools/pp/src/m3makefile:1.2 m3/pm3/language/modula3/m3tools/pp/src/m3makefile:1.3 *** m3/pm3/language/modula3/m3tools/pp/src/m3makefile:1.2 Mon Sep 29 18:45:52 1997 --- m3/pm3/language/modula3/m3tools/pp/src/m3makefile Tue Feb 10 22:58:34 1998 *************** *** 34,39 **** --- 34,42 ---- module ("NewFormatter") implementation ("Main") + import("m3doc") + HtmlFile("index") + Program ("m3pp") ManPage ("m3pp",1) Index: m3/pm3/language/modula3/m3tools/pp/src/flex-bison/m3makefile diff -c m3/pm3/language/modula3/m3tools/pp/src/flex-bison/m3makefile:1.3 m3/pm3/language/modula3/m3tools/pp/src/flex-bison/m3makefile:1.4 *** m3/pm3/language/modula3/m3tools/pp/src/flex-bison/m3makefile:1.3 Wed Dec 3 13:12:33 1997 --- m3/pm3/language/modula3/m3tools/pp/src/flex-bison/m3makefile Tue Feb 10 22:58:40 1998 *************** *** 14,23 **** % if defined ("_all") ! if stale ("y.tab.o", "../src/flex-bison/y.tab.c") ! or stale ("y.tab.o", "../src/flex-bison/lex.yy.c") ! or stale ("y.tab.o", "../src/hash.h") ! or stale ("y.tab.o", "../src/lex_help.h") delete_file ("y.tab.o") end end --- 14,23 ---- % if defined ("_all") ! if stale ("y.tab.o", ".." & SL & "src" & SL & "flex-bison" & SL & "y.tab.c") ! or stale ("y.tab.o",".." & SL & "src" & SL & "flex-bison" & SL & "lex.yy.c") ! or stale ("y.tab.o", ".." & SL & "src" & SL & "hash.h") ! or stale ("y.tab.o", ".." & SL & "src" & SL & "lex_help.h") delete_file ("y.tab.o") end end Index: m3/pm3/language/modula3/m3tools/pp/src/lex-yacc/m3makefile diff -c m3/pm3/language/modula3/m3tools/pp/src/lex-yacc/m3makefile:1.2 m3/pm3/language/modula3/m3tools/pp/src/lex-yacc/m3makefile:1.3 *** m3/pm3/language/modula3/m3tools/pp/src/lex-yacc/m3makefile:1.2 Mon Sep 29 18:47:50 1997 --- m3/pm3/language/modula3/m3tools/pp/src/lex-yacc/m3makefile Tue Feb 10 22:58:43 1998 *************** *** 14,23 **** % if defined ("_all") ! if stale ("y.tab.o", "../src/lex-yacc/y.tab.c") ! or stale ("y.tab.o", "../src/lex-yacc/lex.yy.c") ! or stale ("y.tab.o", "../src/hash.h") ! or stale ("y.tab.o", "../src/lex_help.h") delete_file ("y.tab.o") end end --- 14,23 ---- % if defined ("_all") ! if stale ("y.tab.o", ".." & SL & "src" & SL & "lex-yacc" & SL & "y.tab.c") ! or stale ("y.tab.o", ".." & SL & "src" & SL & "lex-yacc" & SL & "lex.yy.c") ! or stale ("y.tab.o", ".." & SL & "src" & SL & "hash.h") ! or stale ("y.tab.o", ".." & SL & "src" & SL & "lex_help.h") delete_file ("y.tab.o") end end Index: m3/pm3/language/modula3/m3tools/showheap/src/index.html diff -c /dev/null m3/pm3/language/modula3/m3tools/showheap/src/index.html:1.2 *** /dev/null Tue Feb 10 23:31:52 1998 --- m3/pm3/language/modula3/m3tools/showheap/src/index.html Tue Feb 10 22:58:47 1998 *************** *** 0 **** --- 1,84 ---- + + +Showheap + + + +showheap
+ ++ The showheap program displays a map of the traced heap of running + Modula-3 program. + +
+ Normally, you should not start showheap directly. Rather, the runtime + will start showheap and feed it with the proper data when the argument + @M3showheap + is given to a Modula-3 program; for example, to + run the program foo and see the heap of that process, type: +
+ foo @M3showheap +
+A Trestle window will appear; when you + click the start button, the program foo will actually start. + +
+ The SRC Modula-3 garbage collector divides the traced heap into pages, + and showheap shows the status of each page controlled by the + collector. The page size is implementation-dependent. There are far + more possible page states than can be easily shown, but showheap + colorcodes page states as follows. + +
-
+
- Non-heap pages are shown in black. Any non-heap pages interspersed + with the traced heap were allocated for the untraced heap, or using + lower-level mechanisms. + +
- Free pages are shown in white. Free pages are available for + allocation. + +
- Previous-space pages are shown in shades of gray. These are the + pages that contained objects at the beginning of the current + collection. + +
- New-object pages are shown in shades of blue. These pages contain + objects allocated recently, that have not yet been through a + collection. + +
- Copied-object pages are shown in shades of red. These pages contain + objects copied from previous-space pages during this collection. + +
- Immobile-object pages are shown in shades of green. These are like + copied-object pages, but contain objects that could not be moved, such + as objects referenced from thread states; they are left in place by + the collector. + +
- Older-generation pages are shown in shades of magenta, when + generational collection is used. These pages contain objects that + have been through at least one collection, and that needn't be + collected again for a while. +
+ When a program use the showheap facility, a Trestle window is created + at the beginning of the execution. It shows on the right a map of the + traced heap; this map is a 2D matrix of squares, and each square + represents a page. Reading this matrix row by row, from left to + right, one finds all that pages in increasing order. Only the pages + from the first to the last page in the traced heap are displayed (the + other are non-heap pages). + +
+ Most pages can contain multiple objects; larger objects require + multiple pages, and those pages are shown as being connected. + +
+ On the left side of the window, there is legend of the hues used, + together with a count of pages in that state. The line "gc = + <number>" shows the number of garbage collections since the beginning + of the execution of the program. The line "off = <number>" is + non-zero iff collection is currently prohibited. + + + + Index: m3/pm3/language/modula3/m3tools/showheap/src/m3makefile diff -c m3/pm3/language/modula3/m3tools/showheap/src/m3makefile:1.2 m3/pm3/language/modula3/m3tools/showheap/src/m3makefile:1.3 *** m3/pm3/language/modula3/m3tools/showheap/src/m3makefile:1.2 Tue Jan 28 12:24:33 1997 --- m3/pm3/language/modula3/m3tools/showheap/src/m3makefile Tue Feb 10 22:58:47 1998 *************** *** 8,13 **** --- 8,16 ---- import ("vbtkit") implementation ("ShowHeap") + + HtmlFile("index") + Program ("showheap") ManPage ("showheap", 1) Index: m3/pm3/language/modula3/m3tools/shownew/src/index.html diff -c /dev/null m3/pm3/language/modula3/m3tools/shownew/src/index.html:1.2 *** /dev/null Tue Feb 10 23:31:52 1998 --- m3/pm3/language/modula3/m3tools/shownew/src/index.html Tue Feb 10 22:58:51 1998 *************** *** 0 **** --- 1,36 ---- + +
+Shownew + + + +shownew
+ ++ The shownew program displays a running record of the heap allocations + in a Modula-3 program. + +
+ Normally, you should not start shownew directly. Rather, the runtime + will start shownew and feed it with the proper data when the argument + @M3shownew is given to a Modula-3 + program; for example, to + run the program foo and see the allocations of that process, type: +
+ foo @M3shownew +
+A Trestle window will appear; when you + click the start option in the control menu, the program foo will + actually start. + +
+ To set the interval between updates to X seconds, add the argument + @M3update=X to the command line. + X must be an integer. For example: +
+ foo @M3shownew @M3update=5 +
+ + + + Index: m3/pm3/language/modula3/m3tools/shownew/src/m3makefile diff -c m3/pm3/language/modula3/m3tools/shownew/src/m3makefile:1.2 m3/pm3/language/modula3/m3tools/shownew/src/m3makefile:1.3 *** m3/pm3/language/modula3/m3tools/shownew/src/m3makefile:1.2 Tue Jan 28 12:24:33 1997 --- m3/pm3/language/modula3/m3tools/shownew/src/m3makefile Tue Feb 10 22:58:51 1998 *************** *** 10,15 **** --- 10,18 ---- module ("ZIO") implementation ("ShowNew") + + HtmlFile("index") + Program ("shownew") ManPage ("shownew", 1) Index: m3/pm3/language/modula3/m3tools/showthread/src/index.html diff -c /dev/null m3/pm3/language/modula3/m3tools/showthread/src/index.html:1.2 *** /dev/null Tue Feb 10 23:31:54 1998 --- m3/pm3/language/modula3/m3tools/showthread/src/index.html Tue Feb 10 22:58:54 1998 *************** *** 0 **** --- 1,53 ---- + + +Showthread + + + +showthread
+ ++ The showthread program displays the thread activity of a Modula-3 program. + +
+ Normally, you should not start showthread directly. Rather, the + runtime will start showthread and feed it with the proper + data when the argument + @M3showthread + is given to a Modula-3 program; + for example, to run the program foo and see the threads of that + process, type: +
+ foo @M3showthread +
+A Trestle window + will appear; when you click the start button, the program foo + will actually start. + +
+ Each thread in the program will be given a vertical track in the + showthread window, in which the successive states of the thread will + be displayed, using color patches. After the thread dies, the track can + be reused for another thread. + +
+ Each time the scheduler decides to stop the currently running thread and + makes a decision about what to do next, showthread will add a new row + of color patches to show the state of all the threads. + +
+ The legend in the showthread window indicates which color is used for which + state: +
+ - running: currently running + - alive: can run, but is not currently running + - waiting: waiting for a condition to be signaled + - locking: waiting for a mutex to be released + - pausing: pausing for some time (via Thread.Pause) + - blocking: waiting for I/O activity (via SchedulerPosix.IOWait) + - dying: the thread returned, but nobody joined it yet +
+ + + + Index: m3/pm3/language/modula3/m3tools/showthread/src/m3makefile diff -c m3/pm3/language/modula3/m3tools/showthread/src/m3makefile:1.2 m3/pm3/language/modula3/m3tools/showthread/src/m3makefile:1.3 *** m3/pm3/language/modula3/m3tools/showthread/src/m3makefile:1.2 Tue Jan 28 12:24:33 1997 --- m3/pm3/language/modula3/m3tools/showthread/src/m3makefile Tue Feb 10 22:58:55 1998 *************** *** 7,12 **** --- 7,15 ---- import ("ui") implementation ("Main") + + HtmlFile("index") + Program ("showthread") ManPage ("showthread", 1) Index: m3/pm3/language/modula3/m3tools/src/index.html diff -c /dev/null m3/pm3/language/modula3/m3tools/src/index.html:1.1.1.1 *** /dev/null Tue Feb 10 23:31:54 1998 --- m3/pm3/language/modula3/m3tools/src/index.html Sat Jan 31 14:47:13 1998 *************** *** 0 **** --- 1,64 ---- + +Modula-3 Programming tools + + ++ Michel Dagenais + Michel Dagenais, GNU General Public License, 1998 + + michel.dagenais@polymtl.ca+
+ Ecole Polytechnique
+ C.P. 6079, Succ. Centre-Ville
+ Montreal, Quebec, H3C 3A7 + 18 January 1998 + tools + modula-3 + programming + performance + analysis + wide audience +Modula-3 Programming tools
+ +++ +Tools for debugging, analysing and processing Modula-3 programs. +
-
+
- m3gdb
- + GDB based Modula-3 aware debugger. +
- gnuemacs
- + GNU emacs elisp files for editing Modula-3 source code. +
- pp
- + Modula-3 source code pretty printer. +
- coverage
- + Tool to analyze Modula-3 source code coverage data. +
- shownew
- + New memory allocations runtime monitoring graphical tool. +
- showthread
- + Thread runtime monitoring graphical tool. +
- m3browser
- + Modula-3 source code web based browser with full cross referencing + of packages, modules and types. +
- m3bundle
- + Tool to bundle files (resources) with an executable. +
- m3tk
- + The Modula-3 source code analysis and transformation toolkit. +
- showheap
- + Program heap runtime monitoring graphical tool. +
- recordheap
- + Recorder for showheap. +
- replayheap
- + Replay recorded showheap files. +
- m3markup
- + Library to add HTML markup to Modula-3 source files. +
- m3scan
- + Scanner for Modula-3 source files. +
- m3tohtml
- + Convert a list of Modula-3 source files into a web of html files. +
- m3totex
- + Convert Modula-3 interfaces to formattable TeX files. +
Modula-3 a simple and efficient object oriented language + + ++ Michel Dagenais + Michel Dagenais, GNU General Public License, 1998 + + michel.dagenais@polymtl.ca+
+ Ecole Polytechnique
+ C.P. 6079, Succ. Centre-Ville
+ Montreal, Quebec, H3C 3A7 + 18 January 1998 + programming language + object oriented + thread + garbage collection + wide audience +Modula-3 a simple and efficient object oriented language
+ +++ ++ As Sam Harbison writes in his book, +
+
+ +Modula-3 is a member of + the Pascal family of languages. Designed in the late 1980s at Digital + Equipment Corporation and Olivetti, Modula-3 corrects many of the + deficiencies of Pascal and Modula-2 for practical software engineering. + In particular, Modula-3 keeps the simplicity of type safety of the + earlier languages, while providing new facilities for exception + handling, concurrency, object-oriented programming, and automatic + garbage collection. Modula-3 is both a practical implementation + language for large software projects and an excellent teaching + language. +
-
+
- m3compiler
- + DEC SRC Modula-3 compiler. +
- m3tools
- + Modula-3 programming tools. +
- M3defn
- + Modula-3 Language Definition. +
- Partial Revelations +
- Description of the benefits of partial revelation, with examples. +
Partial Revelation and Modula-3 + + +Partial Revelation and Modula-3
+Importing Only Necessary Class Features
++
by Steve Freeman
++ Proponents of object-oriented programming claim that it provides + at least two benefits: code reuse and encapsulation. These + features, however, often conflict, as it is difficult to reuse + something that is hidden, and most statically typed, object- + oriented languages (those in which the type of expressions and + variables can be determined at compile time) require that + visibility and inheritance information be described early in the + class hierarchy. As experienced software writers know, it is hard + to predict from first principles how a class will eventually be + reused, so it is common to expose more features of a class than + necessary to avoid changing its definition once in use. If you + are not extremely careful, this approach increases the + dependencies on the initial implementation and makes the whole + system more brittle.
+ + Modula-3 lets you control reuse with a degree of flexibility + uncommon in strongly typed languages. The key concept is that an + object type may be divided up into partial types, each of which + describes some aspect of the object. A source file may then + import, or reveal, only those aspects of an object relevant to + the task at hand. Thus, the parts of a system that depend on a + particular object feature can be isolated and found automatically + when a change is necessary.
+ + In this article, I'll show how Modula-3's type system, with its + partial revelations, makes code reuse and encapsulation easier + compared to the statically typed, object-oriented languages. I'll then + work through an example showing the Modula-3 type system in use.
+ +
So What's the Problem?
++ Statically typed, object-oriented languages generally support + encapsulation by distinguishing between public and private + features in a type, although there may also be intermediate + states. There is a hierarchy of access in which privileged code + can see the whole structure of an object but external code can + only see the public features; see Figure 1.
+ +
![[ Image for Figure 1 ]](Figure1.gif)
+ Figure 1: Access Control in C++.
+ Access to each level of privacy includes
+ access to all the less private levels.+ + The problem with this approach is that it treats all users + of each level in the class the same way, and all-purpose code is + always difficult to write. The class designer must draw a fine + line in the class definition between exposing too little to be + useful and exposing too much to be safe. Even escape mechanisms + (such as the friend construct in C++) included in the visible + definition are liable to acquire dependencies. Once a design is + achieved, its details are embedded in every piece of code that + uses the type, so a change in a high-level class must be + propagated throughout a system; if the class is part of, say, a + commercial library, then users just have to live with the + designer's decisions. Class internals may not need to be accessed + frequently, but when they are, it is likely to be important, and + such prohibitions are doubly frustrating if the required features + are visible, but inaccessible, in the class definition.
+ +
An Associations Example
+ ++ I'll illustrate my point using the "many-to-one associations" example + in Object-Oriented Modelling and Design, by James Rumbaugh et al. + (Prentice-Hall, 1991), which shows two classes: Item and + Group. When an Item is added to a Group, + the Group object is updated to include the new Item + and the Item object is updated so that it refers to the + Group. The cross-reference attributes in both classes, + however, should be accessible only to the code that maintains the + association. If the attributes were freely available, they could be + updated separately, thus allowing inconsistencies.
+ + Most statically typed languages have some mechanism for limited + relaxation of encapsulation. C++ has the friend construct, + whereby a class gives other classes or procedures access to its + private fields. Listing One (a) allows the + Group's add and remove methods to update both sides of the + association together when links are added or removed, as in Listing One (b).
+ + Listing One (a)
+ +
+ class Item { + public: + Group* MemberOf() const {return group_; }; + private: + Group* group_; + friend void Group::AddItem(Item*); // allows methods to access + friend void Group::RemoveItem(Item*); // the group_ field + }; + + class Group { + public: + void AddItem(Item* item); + void RemoveItem(Item* item); + const ItemSet& Items() const {return itemSet_; }; + private: + ItemSet itemSet_; // a collection class to hold a set of items + }; ++ ++ +
+ void Group::AddItem(Item* item) { + item->group_ = this; + itemSet_.Add(item); + } ++ +The disadvantage of this approach is that the details of the + implementation, although protected from inconsistent access, are + specified in the class definition. This increases the cost of changing + a class once it is in use and limits the range of possible extensions. + For example, to adapt the library for multithreading, it might be + necessary to add a mutex to the Item class that is locked + while the group_ field is being set. Propagating a change in + a low-level class, such as Item, can require rebuilding large + amounts of code. Similarly, if you want to extend the Group + class so that, for example, changes in membership are logged, the + original author must have declared the add and remove methods as + virtual (that is, eligible to be overwritten in a subclass). + This approach constantly requires class designers to decide whether to + make a method virtual (and so more flexible) or not (and so more + efficient) before the class has been put to use.
+ + To defer such decisions, it's common to define an abstract type (which + includes methods but no data fields) that describes what you can do + with it, not how it is implemented; see + Listing Two (a). You then write a + concrete subclass that has data fields (that is, state) and implements + the methods defined in the parent abstract type, as in + Listing Two (b). It's also common to + provide a function that you call to create new instances of the + object. Users see objects of the abstract parent type, but these are + actually implemented by objects of the concrete child.
+ + Listing Two (a)
+ +
+ class AbstractItem { + public: + virtual AbstractGroup* MemberOf() const = 0; + }; + AbstractItem* CreateItem(); + class AbstractGroup { + public: + virtual void AddItem(AbstractItem* item) = 0; + virtual void RemoveItem(AbstractItem* item) = 0; + virtual const ItemSet& Items() const = 0; + }; + AbstractGroup* CreateGroup(...); ++ ++ +
+ class ConcreteItem: public AbstractItem { + public: + AbstractGroup* MemberOf() const {return group_; }; + private: + AbstractGroup* group_; + friend void ConcreteGroup::AddItem(AbstractItem*); + friend void ConcreteGroup::RemoveItem(AbstractItem*); + }; + AbstractItem* CreateItem() { + return (AbstractItem*)new ConcreteItem; + }; ++ +This isolates the users of a class from its implementation, but makes + reuse by inheritance difficult, as a subclass of the public + AbstractItem will not inherit from the private + ConcreteItem. Class designers may also use delegation, in + which the Item behavior is managed by an abstract object in + the public class to which the method calls are forwarded; see Listing Two (c).
+ + Listing Two (c)
+ +
+ class Item: public AbstractItem { + public: + Item() { impl_ = CreateItem(); }; + ~Item() { delete impl_; }; + Group* MemberOf() const { return impl_->MemberOf(); }; + AbstractItem* Implementation() const { return impl_; }; + private: + AbstractItem* impl_; + }; ++ +In addition, methods such as AddItem in the (public) + abstract classes must be defined in terms of other abstract + classes because the (private) concrete classes are invisible at + this level. This means that the implementations of these methods + must receive parameters as abstract types and cast them down to + their concrete subclass, which either requires an extra + consistency check or provides a potential source of pointer + errors.
+ + Other languages are more flexible. Eiffel, for example, provides a + redefine keyword that allows a subclass to override any of + its ancestor's public methods--unlike C++, in which the ancestor class + must declare the methods that may be overridden. Eiffel, however, also + requires the ancestor class to declare which other classes can access + its private fields, so our Item class is defined as + Listing Three. Again, specifying exported + features in the class definition makes it more difficult to + restructure an installed library or program. Furthermore, the controls + can be overridden by defining a new subclass of GROUP to gain + arbitrary access to the ITEM internals.
+ + Listing Three
+ +
+ class ITEM + export + member_of -- this method available to everyone + set_group{GROUP}, clear_group{GROUP} -- methods available to class GROUP + feature + mygroup: GROUP; + member_of: GROUP is do Result := mygroup end; + set_group(g: GROUP) is do mygroup := g end; + clear_group is forget(mygroup) end; + end -- ITEM ++ +Ada 95 also distinguishes between public and private features of a + type and uses its support for structured libraries to control access. + Briefly, an Ada program unit (or package) has a specification, divided + into visible and private sections, and a body. The logical interface + to a package, its abstract types and procedure declarations, is + defined in the visible section of the specification; this is what + clients of the package use. The implementation of a package is split + between the private section of the specification, which expands the + definitions of the data types, and the package body, which contains + the procedure code; the private section is accessible from the body, + but not from clients of the package. An Ada 95 specification of the + example might look like Listing Four.
+ + Listing Four
+ +
+ with Items; use Items; + package Association is + -- visible section + type Item is private; + type Item_ptr is access all Item'Class; + type Group is private; + type Group_ptr is access all Group'Class; + procedure AddItem(G: Group_ptr; I Item_ptr); + procedure RemoveItem(G: Group_ptr; I Item_ptr); + function Items(G: in Group'Class) return Items.List; + private + -- private to implementation + type Item is tagged record + group: Group_ptr; + end record; + type Group is tagged record + Items : Items.Set; + end record; + end Association; +
+ +Ada 95 supports hierarchies of packages. That is, given a package + parent, you can write a package parent.child to + extend it; the visible specification of the new package will inherit + the visible features of the parent. More importantly, the (private) + implementation of a child can see all the private features of its + ancestors, whereas the public interface to a child sees only the + ancestors' visible sections. The Ada 95 approach is a little like a + street of theaters: The public sees only what's on stage, while some + of the backstage crew have access to everything in the building. Each + theater (or library), however, is independent; the crew of one theater + is not allowed backstage next door, but can still buy tickets to see + the show. This approach supports the way software libraries are built + (or should be), but suffers from two limitations: first, the concrete + part of a data type is still held in the interface file, so it may be + difficult to predict what will need to be rebuilt when an + implementation changes; second, the package designer must still decide + exactly how it may be reused before it is put into service, so changes + to an installed library may be painful.
+ + While it is possible to separate interface and implementation in most + statically typed OO languages, engineering such a design for long-term + reuse requires skill and experience because too many details must be + committed to too early. In Modula-3, programmers do not have to put + all the details of a class in a single place, yet the benefits of a + strong type system are retained. There are two main techniques:
+ +
-
+
- Classes can be subclassed when not all of the parent class is + visible, so the private features of a class really are private, + not just inaccessible. +
- Class definitions can be divided across multiple files, so a + program unit imports only the relevant aspects of a class; this + allows fine-grain control over the visibility of the parts of an + object. +
Modula-3 Basics
+ ++ Modula-3 is a statically typed, object-oriented language with single + inheritance, integrated threads, garbage collection and exception + handling, and separate interface and implementation files. To + illustrate basic Modula-3 concepts, I'll first rewrite the + Associations example in Listing Two. Listing Five is the interface file + Association.i3 (interface files define a namespace that can + contain type definitions and procedure and variable declarations, but + no implementation code). The IMPORT statement makes the + contents of another interface file available; here, I import the type + T from the interface List to define the value + returned from the items method of the Group object. + Modula-3 objects are records that may contain variables and methods; + here, of course, the abstract types have no variable fields because + these are only defined in the implementation.
+ + Listing Five
+ +
+ INTERFACE Association; + + IMPORT List; + + TYPE + Item <: AbstractItem; + AbstractItem = OBJECT METHODS + memberOf(): Group; + END; + + Group <: AbstractGroup; + AbstractGroup = OBJECT METHODS + addItem(item: Item); + removeItem(item: Item); + items(): List.T; + END; + + END Association. +
+ +The phrase "type1 <: type2" is an example of partial + revelation. It says that type1 is a subtype of type2 + but that this is not the entire definition of type1; the rest will be + revealed in other places, possibly in other files. The + Association interface, for example, defines an Item + as a subtype of an AbstractItem, so it includes a + memberOf method, but provides no other information about its + features. The AbstractItem and AbstractGroup names + are not strictly necessary, but are introduced to save retyping the + object details in the implementation file Association.m3, as + in Listing Six.
+ + Listing Six
+ +
+ MODULE Association; + + IMPORT Set; + + REVEAL + Item = AbstractItem BRANDED OBJECT + group: Group; + OVERRIDES + memberOf := ItemMemberOf; + END; + + PROCEDURE ItemMemberOf(self: Item): Group = + BEGIN RETURN self.group; END ItemMemberOf; + + REVEAL + Group = AbstractGroup BRANDED OBJECT + itemSet: Set.T; + OVERRIDES + addItem := GroupAddItem; + removeItem := GroupRemoveItem; + items := GroupItems; + END; + + PROCEDURE GroupAddItem(self: Group; item: Item) = + BEGIN self.itemSet.add(item); END; + + PROCEDURE GroupRemoveItem(self: Group; item: Item) = + BEGIN self.itemSet.remove(item); END; + + PROCEDURE GroupItems(self: Group): Set.T = + BEGIN RETURN self.itemSet.makeList(); END; + + BEGIN (* empty module initialization block *) + END Association. +
+ +The phrase "REVEAL type1=type2" provides more information about + the structure of type1. The use of "=" shows that + this is the final revelation in the declaration of an object type; + there can be multiple partial revelations about the structure of an + object. In this case, an Item object contains a group data + field, and the memberOf method has been overridden by the + procedure ItemMemberOf; in other words, I provide a concrete + implementation. The implementation is entirely hidden from the rest of + the library (it could be replaced by relinking the application with a + new implementation module), but you can still meaningfully subclass + from the Item and Group types in the + Association interface. For example, to add logging to the add + method of Group, write the subclass in + Listing Seven.
+ + Listing Seven
+ +
+ IMPORT Association; + + TYPE + LogGroup = Association.Group OBJECT OVERRIDES + addItem := LogGroupAddItem; + END; + + PROCEDURE LogGroupAddItem(self: LogGroup; item: Assocation.Item) = + BEGIN + (* log the addition, then directly call the parent method *) + LogAddition(self, item); + Association.Group.addItem(self, item); + END; +
+ +With the addition of our new logging feature, the new + LogGroup object inherits all the hidden behavior of the + Association.Group object. This demonstrates subtyping the parent + type when not all is visible. The implementation of + Assocation.Group is entirely hidden behind its interface, so + program units that use the public type do not depend on its + private implementation. To subtype in this way in C++ or Eiffel, + for example, you would either have to write a concrete class that + exposes some implementation details or write a delegation class + that includes an abstract object to which method calls are + forwarded.
+ +
Partitioning an Object Definition
++ Class designers use partial revelation to split the definition of + an object type across multiple files, both interface and + implementation. A revelation in an interface is a mechanism for + access control; it makes some feature of an object accessible + wherever the interface is imported. A revelation in an + implementation, on the other hand, is a mechanism for + encapsulation; it is an addition to the object definition that is + visible only within that implementation.
+ +
Beyond Simple Encapsulation: Associations Revisited
++ Partial revelation really shines when used to support + sophisticated access control to the features of an object type. + To demonstrate this, I'll present an unreasonable extension of + the Association objects. We have a hypothetical new requirement + that Associations work with multiple threads, so the objects must + be protected against concurrent changes. We also want to allow a + thread to be notified when another thread has added a new item to + a group. This new requirement, however, says nothing about the + implementation of associations, so we can divide our new objects + into three aspects: The first deals with the data structures for + associating items and groups, the second deals with + multithreading issues and handles locking and notification, and + the third deals with class-wide code that is independent of + either of these specific issues. These aspects are independent of + each other, so a change of data structure need not affect the + locking scheme, and we can partition our object types to reflect + this.
+ + The first interface (see Listing Eight) + provides opaque types; it reveals only that the objects have + identifiable types and the operations the objects respond to. This + interface is for normal clients who just want to use the types without + knowing about their implementation. Next, I define abstract types for + the item and group objects; any implementation must provide code for + the methods of the object types in Listing + Nine. This interface is similar to the original version in Listing Five, except that it now includes the + opaque types ItemPrivate and GroupPrivate; I'll + explain the purpose of these types shortly. Once the library is + installed, however, I might want to write the logging subtype from Listing Seven; I can do this with the + interfaces provided so far. If I import AssocClass, I know + that any group object includes an addItem method that I can override. + I can subclass knowing very little about the how the types are + implemented and pass the new type to the procedures in Association. + Note that, so far, the multithreading features of the objects are + completely invisible.
+ + Listing Eight
+ +
+ INTERFACE Assocation; + + IMPORT List; + + TYPE Item <: ROOT; + (* ROOT is the ancestor of all garbage-collected objects *) + + TYPE Group <: ROOT; + + PROCEDURE MemberOf(i: Item): Group; + PROCEDURE AddItem(g: Group; i: Item); + PROCEDURE RemoveItem(g: Group; i: Item); + PROCEDURE ItemList(g: Group): List.T; + PROCEDURE NewItem(g: Group): Item; + (* Blocks until a new item arrives, then returns + the most recent addition. *) + + END Assocation. +
+ ++ +
+ INTERFACE AssocClass; + + IMPORT Association, List; + + TYPE ItemPrivate <: ROOT; + + REVEAL + Association.Item = ItemPrivate BRANDED OBJECT METHODS + memberOf(): Association.Group; + setGroup(g: Association.Group); + END; + + TYPE GroupPrivate <: ROOT; + + REVEAL + Association.Group = GroupPrivate BRANDED OBJECT METHODS + addItem(i: Association.Item); + removeItem(i: Association.Item); + itemList(): List.T; + END; + + END AssocClass. +
+ +The next stage is to provide an implementation of items and groups, so + I write an interface AssocImpl as a default version; see Listing Ten (a). The subtypes declared + here are still opaque, so a client knows only that they can be used + with the procedures declared in Associations. The module + AssocImpl.m3 in Listing Ten + (b) reveals more detail about these types--we are not defining a + further level of subtyping here, but adding more detail to an existing + type. This module reveals that the items are stored using a standard + Set.T type and provides implementations for the methods for + the Item and Group objects. For example, the + AddItem procedure in Listing + Ten (c) ensures that the Set field of the Group + object has been initialized and adds the new item to it. I don't need + to call the setGroup method of the item because, as you'll see below, + this will be done elsewhere.
+ + Listing Ten (a)
+ +
+ INTERFACE AssocImpl; + + IMPORT Association; + + TYPE + Item <: Association.Item; + Group <: Assocation.Group; + + END AssocImpl. +
+ ++ +
+ MODULE AssocImpl; + + IMPORT Association, AssocClass, List, Set; + + REVEAL + Item = Association.Item BRANDED OBJECT + group: Assocation.Group := NIL; + OVERRIDES + memberOf := MemberOf; + setGroup := SetGroup; + END; + + REVEAL + Group = Association.Group BRANDED OBJECT + set: Set.T := NIL; + OVERRIDES + addItem := AddItem; + removeItem := RemoveItem; + itemList := ItemList; + END; +
+ ++ +
+ PROCEDURE AddItem(self: Group; item: Association.Item) = + BEGIN + IF self.set = NIL THEN self.set := NEW(Set.T); END; + self.set.add(item); + END AddItem; +
+ +Exposing Unsafe Features
++ More-sophisticated clients know that each call of a procedure in the + Association interface involves acquiring and freeing a lock, + which may be expensive. If they had access to an appropriate level of + detail, they could batch a set of calls within a single lock, rather + than locking each time; thus, the code in Listing Eleven (a) might change to + that in Listing Eleven (b). There's + also an explicit call to notify any other waiting threads that new + items have arrived, as this is also normally provided by + Association.AddItem. Clearly, programmers working at this + level must be more careful because they can no longer rely on the + implementation to ensure, for example, that a group is locked before + an item is added to it.
+ +
+ Association.AddItem(group, item1); + Association.AddItem(group, item2); + Association.AddItem(group, item3); +
+ ++ +
+ LOCK group DO + UnsafeAddItem(group, item1); + UnsafeAddItem(group, item2); + UnsafeAddItem(group, item3); + NotifyNewItem(group, item3); + END; +
+ ++ Modula-3 distinguishes between safe and unsafe program units; unsafe + interfaces and modules allow the programmer more freedom but provide + fewer guarantees that errors will be caught by compiler analysis of + the code. An unsafe interface may only be imported by unsafe modules + and other unsafe interfaces, but an unsafe module may implement a safe + interface--which is how Modula-3 provides safe access to external (and + so uncheckable) libraries. Modula-3 supports this controlled + relaxation of its type safety to help programmers isolate and identify + code that is "dangerous."
+ + I have made the interface UnsafeAssoc unsafe because it + allows a programmer to bypass the thread-safe code provided through + the Association interface; this code is shown in Listing Twelve. UnsafeAssoc reveals + that both the item and group object types are derived from + MUTEX, a built-in mutual exclusion type, so any code that + imports this interface can lock item or group objects, as in Listing Eleven (b). The interface also + declares unsafe versions of the thread-safe procedures that implement + class-wide behavior. We know that these procedures are not concerned + with thread safety because item and group locking is done separately. + Data-structure management is defined in the AssocImpl module, + so the unsafe procedures have common behavior across all + implementations of Associations. I also use this interface to declare + a procedure that supports the notification of the arrival of new + items.
+ + Listing Twelve
+ +
+ UNSAFE INTERFACE UnsafeAssoc; + + IMPORT Association; + + REVEAL Association.Item <: MUTEX; + + PROCEDURE UnsafeMemberOf(i: Association.Item): Association.Group; + PROCEDURE UnsafeSetGroup(i: Assocation.Item; g: Assocation.Group); + + REVEAL Association.Group <: MUTEX; + + PROCEDURE UnsafeAddItem(g: Association.Group; i: Association.Item); + PROCEDURE UnsafeRemoveItem(g: Assocation.Group; i: Association.Item); + PROCEDURE UnsafeItemList(g: Association.Group): List.T; + PROCEDURE NotifyNewItem(g: Association.Group; i: Association.Item); + + END UnsafeAssoc. +
+ +Now I can write the module Assocation.m3, which provides the + final revelations about the item and group types and implements the + procedures declared in Association and UnsafeAssoc. + Listing Thirteen (a) shows the + start of the module; the EXPORTS clause says that this module + implements, and automatically imports, those interfaces. Note that + Association and AssocClass are safe, whereas + UnsafeAssoc is not. The final revelations for the item and + group object types show that there is nothing more to say about item + objects, but that groups need some extra state that will be used for + the thread-specific code. Listing + Thirteen (b) shows the implementation of two procedures from the + UnsafeAssoc interface. NotifyNewItem simply sets the + last item variable and wakes up all the threads waiting on the group's + condition variable, while UnsafeAddItem adds the item to the + group and sets the group in the item. Finally, Listing Thirteen (c) shows the code + for two of the procedures in the Association interface; this + is where all the code associated with thread safety belongs. + AddItem provides a safe wrapper for the + UnsafeAddItem call, and NewItem blocks its calling + thread until a new item has been added to the group.
+ +
+ UNSAFE MODULE Association EXPORTS Association, AssocClass, UnsafeAssoc; + + IMPORT Thread; + + (* These two revelations are extensions of those in UnsafeAssoc, so + they start with a mutex *) + + REVEAL + ItemPrivate = MUTEX BRANDED OBJECT + (* no further features *) + END; + + GroupPrivate = MUTEX BRANDED OBJECT + cond: Thread.Condition := NIL; (* for threads waiting for new items *) + lastAddition: Item := NIL; (* the last item added *) + END; +
+ ++ +
+ PROCEDURE UnsafeAddItem(group: Assocation.Group; item: Association.Item) = + BEGIN + group.addItem(item); + item.setGroup(group); + END UnsafeAddItem; + + (* etc *) + + PROCEDURE NotifyNewItem(group: Assocation.Group; item: Association.Item) = + BEGIN + group.lastAddition := item; + Thread.Broadcast(group.cond); + END NotifyNewItem; +
+ ++ +
+ PROCEDURE AddItem(group: Group; item: Item) = + BEGIN + LOCK g DO + UnsafeAddItem(group, item); + NotifyNewItem(group, item); + END; + END AddItem; + + (* etc *) + + PROCEDURE NewItem(group: Group): Item = + VAR oldItem: Item; BEGIN + LOCK group DO + oldItem := group.lastAddition; + (* wait until a new item has been added to the group *) + WHILE oldItem = group.lastAddition DO + Thread.Wait(group.cond, group); + END; + RETURN group.lastAddition; + END; + END NewItem; + + BEGIN (* empty module initialization block *) + END Association. +
+ +The Association example, although contrived, shows how + partial revelation can be used to partition an object type by + feature, rather than by the designer's conception of how it will + be used. Clients of the library can import just those features + they need, perhaps to reimplement the default implementation or + to optimize a set of calls. In this case, the object types were + divided into concerns about data structures, thread-safety, and + class-wide behavior. I can change each of these independently, + and Modula-3's import system makes dependencies on existing code + easy to find.
+ +
Summary
++ Partial revelation is a powerful technique for providing + controlled access to the features of an object type. A class + definition can be split into a set of distinct features made + accessible by importing interfaces. There is no hierarchy of + access imposed at the interface level, so each feature can be + imported independently into a program unit; see Figure 2. The + definitive structure of the type is then finally revealed in the + implementation.
+ +
![[ Image for Figure 2 ]](Figure2.gif)
+ Figure 2: The Group type hierarchy
+ as defined in the interfaces; subtypes
+ are shown above their parent types.+ + The division of an object type can be based on its essential + features, rather than on the designer's expectations about its + use and implementation concerns. Furthermore, importing the + interface localizes the dependence on features of the supertype + and makes such dependencies easy to find automatically. When an + interface is intended for use within a library's implementation + but not by its clients, privacy can be achieved by controlling + access to the interface file.
+ + Modula-3 reduces the tension between reuse and encapsulation + by allowing programmers to avoid embedding implementation details + in the visible definition of a class. A designer can concentrate + on extracting the essential features of a class, rather than + declaring in advance how it relates to other classes and + procedures. Users of a class can select only those features they + need and still reuse them by inheritance; the hidden parts of the + class are still available and can be revealed elsewhere in the + program. Partial revelation avoids the rigidity of a hierarchical + access system and provides inheritance with true encapsulation, + as opposed to simple access control, without the implementation + costs and risks of delegation.
+ + The ability to import only the necessary features of a class + means that dependencies are limited to the code that uses them + and are made explicit when they occur. This reduces code + fragility and makes it easier to develop software-management + tools. Furthermore, Modula-3's distinction between safe and + unsafe program units highlights vulnerable code and provides + language support for multiple roles in a software team.
+ + Of course, writing reusable objects is still hard and no language can + be a substitute for good ideas, but the right language can assist in + the their design and implementation. The many libraries available with + the Modula-3 distribution provide both models for how to write + well-structured software and a mine of reliable code for reuse. + There's an excellent discussion of how this technique was used for the + Modula-3 I/O library in Systems Programming with Modula-3, edited by + Greg Nelson (Prentice-Hall, 1991). "Adding Digital Video to an + Object-Oriented User Interface Toolkit," by Mark Manasse and myself + (Object-Oriented Programming, ECOOP 1994, Springer-Verlag, 1994), + describes how the type system helped during a major modification of + Trestle, the Modula-3 user interface toolkit. Modula-3 is freely + available for a wide range of platforms. Its home page is at http://www.research.digital.com/SRC/modula-3/html/home.html + and is available via anonymous ftp from gatekeeper.dec.com. + There is also a newsgroup comp.lang.modula3.
+ + Modula-3's partial revelation, especially when combined with its + interface and module structure, provides a powerful and unusual tool + for managing the trade-off between reuse and encapsulation. It doesn't + impose the hierarchical approach to encapsulation of other statically + typed object-oriented languages, so there's less need either to + subvert the type system, or to increase code dependencies to achieve + the flexibility that any substantial library or application needs. + It's an effective programming-language technology that deserves to be + better known and widely used.
+ +
Acknowledgments
++ Many thanks to Farshad Nayeri for his generous help with this + article. + +
About the author
++ Steve is a Research Scientist at the Rank Xerox Research Centre in + Grenoble, France, working on the implementation of a rule-based + coordination language. He can be reached at sfreeman@pa.dec.com.
+ +
About this article
++ This article originally appeared in Dr. + Dobb's Journal, October 1995, Volume 20, Issue 10, pages 36-42 and + pages 110-112 (code listings). Thanks to the people at Dr. Dobb's + Journal for their gracious permission to publish it electronically. It + was translated to HTML by Allan + Heydon. The figures were redrawn from the article using Juno-2, a + constraint-based drawing editor.
+ + + Index: m3/pm3/language/modula3/src/m3defn/acks.html diff -c /dev/null m3/pm3/language/modula3/src/m3defn/acks.html:1.1.1.1 *** /dev/null Tue Feb 10 23:31:55 1998 --- m3/pm3/language/modula3/src/m3defn/acks.html Sat Jan 31 14:47:13 1998 *************** *** 0 **** --- 1,59 ---- + +
+Modula-3: Acknowledgments + + + ++ +
Acknowledgments
+ ++ Modula-3 was designed by Luca Cardelli, Jim Donahue, Mick Jordan, Bill + Kalsow, and Greg Nelson, as a joint project by the Digital Equipment + Corporation Systems Research Center and the Olivetti Research Center. + Paul Rovner made many contributions as a founding member of the design + committee. The language specification was written by Lucille Glassman + and Greg Nelson, under the watchful supervision of the whole committee. +
+ Maurice Wilkes had the inspiration that sparked the project. +
+ Our technical starting point was Modula-2+, which was designed by Paul + Rovner, Roy Levin, John Wick, Andrew Birrell, Butler Lampson, and Garret + Swart. We made good use of the ruthlessly complete description of + Modula-2+ in Mary-Claire van Leunen's Modula-2+ User's Manual. + The ideas in the ``+'' part of Modula-2+ were mostly derived from the + Mesa and Cedar languages developed at Xerox PARC. +
+ Niklaus Wirth designed Modula-2, the starting point of our starting + point. He also reviewed the evolving design and made many valuable + suggestions---not one of which was a suggested addition. Indeed, he + inspired us with the courage to pull out a number of deep-rooted weeds. +
+ SRC Modula-3 was implemented by Bill Kalsow and Eric Muller. Olivetti + Modula-3 was implemented by Mick Jordan, Trevor Morris, David Chase, + Steve Glassman, and Marion Sturtevant. +
+ The language and book were greatly improved by the helpful feedback + from Bob Ayers, Andrew Black, Regis Crelier, Dan Craft, Hans Eberle, + John Ellis, Stu Feldman, Michel Gangnet, Lucille Glassman, David + Goldberg, Stephen Harrison, Sam Harbison, Jim Horning, Solange Karsenty, + Mike Kupfer, Butler Lampson, Mark Manasse, Tim Mann, Eliot Moss, Dick + Orgass, Sharon Perl, Norman Ramsey, Lyle Ramshaw, Eric Roberts, Peter + Robinson, Ed Satterthwaite, Jorge Stolfi, Garret Swart, Chuck Thacker, + and Ken Zadeck. +
+ We are grateful for the support of Digital Equipment Corporation in + general, and Bob Taylor and Sam Fuller in particular. +
+ +
+ Last modified on Wed Apr 3 09:39:14 PST 1996 by heydon + modified on Thu Apr 14 11:56:41 PDT 1994 by kalsow +
+ + Index: m3/pm3/language/modula3/src/m3defn/apply.html diff -c /dev/null m3/pm3/language/modula3/src/m3defn/apply.html:1.1.1.1 *** /dev/null Tue Feb 10 23:31:55 1998 --- m3/pm3/language/modula3/src/m3defn/apply.html Sat Jan 31 14:47:13 1998 *************** *** 0 **** --- 1,19 ---- + + +Modula-3: Function application + + + +Function application
++ + A procedure call is an expression if the procedure returns a result. + The type of the expression is the result type of the procedure. +
+ +
+ Last modified on Wed Apr 3 09:39:13 PST 1996 by heydon + modified on Mon Apr 18 14:00:21 PDT 1994 by kalsow +
+ + Index: m3/pm3/language/modula3/src/m3defn/arithmetic.html diff -c /dev/null m3/pm3/language/modula3/src/m3defn/arithmetic.html:1.2 *** /dev/null Tue Feb 10 23:31:55 1998 --- m3/pm3/language/modula3/src/m3defn/arithmetic.html Tue Feb 10 22:59:13 1998 *************** *** 0 **** --- 1,183 ---- + + +Modula-3: Arithmetic operations + + + +Arithmetic operations
++ + The basic arithmetic operations are built into the language; + additional operations are provided by the required + floating-point interfaces. +
+ + To test or set the implementation's behavior for overflow, underflow, + rounding, and division by zero, see the required interface + FloatMode. + Modula-3 arithmetic was designed + to support the + IEEE floating-point + standard, but not to require it. +
+ + To perform arithmetic operations modulo the word size, programs should + use the routines in the required interface + Word. +
+ + Implementations must not rearrange the computation of expressions in + a way that could affect the result. For example, (x+y)+z + generally cannot be computed as x+(y+z), since addition is not + associative either for bounded integers or for floating-point values. +
+ +
+ prefix + (x: INTEGER) : INTEGER + + (x: Float) : Float + + + infix + (x,y: INTEGER) : INTEGER + (x,y: Float) : Float + (x,y: Set) : Set +
++ As a prefix operator, +x returns x. + As an infix operator on numeric arguments, + + denotes addition. On sets, + denotes set union. + That is, + e IN (x + y) if and only if (e IN x) OR (e IN y). + The types of x and y must be the same, and the result + is the same type as both. + In unsafe modules, + is extended to ADDRESS. +
+ +
+ prefix - (x: INTEGER) : INTEGER + (x: Float) : Float + + infix - (x,y: INTEGER) : INTEGER + (x,y: Float) : Float + (x,y: Set) : Set +
++ As a prefix operator, -x is the negative of x. + As an infix operator on numeric arguments, - denotes subtraction. + On sets, - denotes set difference. + That is, e IN (x - y) if and only if + (e IN x) AND NOT (e IN y). + The types of x and y must be the same, and the result + is the same type as both. + In unsafe modules, - is extended to ADDRESS. +
+ +
+ infix * (x,y: INTEGER) : INTEGER + (x,y: Float) : Float + (x,y: Set) : Set +
++ On numeric arguments, * denotes multiplication. + On sets, * denotes intersection. + That is, e IN (x * y) if and only if (e IN x) AND (e IN y). + The types of x and y must be the same, and the result + is the same type as both. +
+ +
+ infix / (x,y: Float) : Float + (x,y: Set) : Set +
+On reals, / denotes division. On sets, / denotes + symmetric difference. + That is, e IN (x / y) if and only if (e IN x) # (e IN y). + The types of x and y must be the same, and the result + is the same type as both. +
+ +
+ infix DIV (x,y: INTEGER) : INTEGER + infix MOD (x,y: INTEGER) : INTEGER + MOD (x, y: Float) : Float +
+The value x DIV y is the floor of + the quotient of x and y; that is, the maximum integer + not exceeding the real number z such that z * y = x. + For integers x and y, the value of x MOD y is + defined to be x - y * (x DIV y). +
+ + This means that for positive y, the value of x MOD y + lies in the interval [0 .. y-1], regardless of + the sign of x. For negative y, the value of + x MOD y lies in the interval [y+1 .. 0], regardless + of the sign of x. +
+ + If x and y are floats, the value of x MOD y is + x - y * FLOOR(x / y). This may be computed as a Modula-3 + expression, or by a method that avoids overflow if x is much + greater than y. The types of x and y must + be the same, and the result is the same type as both. +
+ +
+ ABS (x: INTEGER) : INTEGER + (x: Float) : Float +
+ABS(x) is the absolute value of x. + If x is a float, + the type of ABS(x) is the same as the type of x. +
+ +
+ FLOAT (x: INTEGER; T: Type := REAL): T + (x: Float; T: Type := REAL): T +
+FLOAT(x, T) is a floating-point value of type T + that is equal to or very near x. + The type T must be a floating-point type; + it defaults to REAL. The exact semantics depend on the + thread's current rounding mode, as defined in the required interface + FloatMode. +
+ +
+ FLOOR (x: Float) : INTEGER + + CEILING (x: Float) : INTEGER +
+FLOOR(x) is the greatest integer not exceeding x. + CEILING(x) is the least integer not less than x. +
+ +
+ ROUND (r: Float) : INTEGER + + TRUNC (r: Float) : INTEGER +
+ROUND(r) is the nearest integer to r; ties are broken + according to the constant RoundDefault in the required interface + FloatMode. + TRUNC(r) rounds r toward zero; it equals + FLOOR(r) for positive r and CEILING(r) for + negative r. +
+ +
+ MAX, MIN (x,y: Ordinal) : Ordinal + (x,y: Float) : Float +
+MAX returns the greater of the two values x and y; + MIN returns the lesser. If x and y are ordinals, + they must have the same base type, which is the type of the result. + If x and y are floats, they must have the same type, and + the result is the same type as both. +
+ +
+ Last modified on Wed Apr 3 09:39:13 PST 1996 by heydon + modified on Mon Apr 18 14:00:35 PDT 1994 by kalsow +
+ + Index: m3/pm3/language/modula3/src/m3defn/arrays.html diff -c /dev/null m3/pm3/language/modula3/src/m3defn/arrays.html:1.2 *** /dev/null Tue Feb 10 23:31:55 1998 --- m3/pm3/language/modula3/src/m3defn/arrays.html Tue Feb 10 22:59:13 1998 *************** *** 0 **** --- 1,112 ---- + + +Modula-3: Array types + + + +Array types
++ + An array is an indexed collection of component variables, + called the elements of the array. The indexes are the values of + an ordinal type, called the index type of the array. The elements + all have the same size and the same type, called the element type + of the array. +
+ + There + are two kinds of array types, fixed and open. The + length of a fixed array is determined at compile time. The length + of an open array type is determined at runtime, when it is allocated + or bound. The length cannot be changed thereafter. +
+ + The + shape of a multi-dimensional array is the sequence of its + lengths in each dimension. More precisely, the shape of an array + is its length followed by the shape of any of its elements; the shape + of a non-array is the empty sequence. +
+ + Arrays + are assignable if they have the same element type and shape. + If either the source or target of the assignment is an open array, + a runtime shape check is required. +
+ + A + fixed array type declaration has the form: +
+ TYPE T = ARRAY Index OF Element +
+where Index is an ordinal type and Element is any type other + than an open array type. The values of type T are arrays whose + element type is Element and whose length is the number of elements + of the type Index. +
+ + If + a has type T, then a[i] designates the element + of a whose position corresponds to the position of i + in Index. For example, consider the declarations: +
+ VAR a := ARRAY [1..3] OF REAL {1.0, 2.0, 3.0}; + VAR b: ARRAY [-1..1] OF REAL := a; ++Now a = b is TRUE; + yet a[1] = 1.0 while b[1] = 3.0. + The interpretation of indexes is determined by an array's + type, not its value; the assignment b := a changes b's + value, not its type. (This example uses + variable initialization, + and + array constructors.) +
+ + An + expression of the form: +
+ ARRAY Index_1, ..., Index_n OF Element +
+is shorthand for: +
+ ARRAY Index_1 OF ... OF ARRAY Index_n OF Element +
++ + This shorthand is eliminated from the expanded type definition + used to define structural equivalence. An expression of the form + a[i_1, ..., i_n] + is shorthand for a[i_1]...[i_n]. +
+ + An + open array type declaration has the form: +
+ TYPE T = ARRAY OF Element +
+where Element is any type. The values of T are arrays + whose element type is Element and whose length is arbitrary. + The index type of an open array is the integer subrange + [0..n-1], where n is the length of the array. +
+ + An open array type can be used only as the type of a formal parameter, + the referent of a reference type, the element type of another open + array type, or as the type in an array constructor. +
+ + Examples of array types: +
+ TYPE + Transform = ARRAY [1..3], [1..3] OF REAL; + Vector = ARRAY OF REAL; + SkipTable = ARRAY CHAR OF INTEGER +
+ ++ Last modified on Wed Apr 3 09:39:13 PST 1996 by heydon + modified on Mon Apr 18 14:00:43 PDT 1994 by kalsow +
+ + Index: m3/pm3/language/modula3/src/m3defn/assign.html diff -c /dev/null m3/pm3/language/modula3/src/m3defn/assign.html:1.2 *** /dev/null Tue Feb 10 23:31:55 1998 --- m3/pm3/language/modula3/src/m3defn/assign.html Tue Feb 10 22:59:14 1998 *************** *** 0 **** --- 1,103 ---- + + +Modula-3: Assignment statements + + + +Assignment
++ + To specify the typechecking of assignment statements we need to define + "assignable", which is a relation between types and types, between + expressions and variables, and between expressions and types. +
+ + A type T is assignable to a type U if: +
-
+
- T <: U, or +
- U <: T and T is an array or a reference type other + than ADDRESS + (This restriction is lifted in + unsafe modules.), or +
- T and U are ordinal types with at least one member + in common. +
+ + An + expression e is assignable to a variable v if: +
-
+
- the type of e is assignable to the type of v, and +
- the value of e is a member of the type of v, is + not a local procedure, and if it is an array, then it has the same + shape as v. +
+ + The + first point can be checked statically; the others generally require + runtime checks. Since there is no way to determine statically whether + the value of a procedure parameter is local or global, assigning + a local procedure is a runtime rather than a static error. +
+ + An expression e is assignable to a type T + if e is assignable to some variable of type T. + (If T is not an open array type, this is the same as saying + that e is assignable to any variable of type T.) +
+ + An + assignment statement has the form: +
+ v := e +
+where v is a writable designator and e is an expression + assignable to the variable designated by v. The statement sets + v to the value of e. The order of evaluation of + v and e is undefined, but e will be evaluated before + v is updated. + In particular, if v and e are overlapping + subarrays, + the assignment is performed in such a way that no element is used + as a target before it is used as a source. +
+ + Examples of assignments: +
+ VAR + x: REFANY; + a: REF INTEGER; + b: REF BOOLEAN; + + a := b; (* static error *) + x := a; (* no possible error *) + a := x (* possible checked runtime error *) +
++ + The + same comments would apply if x had an ordinal type with + non-overlapping subranges a and b, or if x had + an object type and a and b had incompatible subtypes. + The type ADDRESS is treated differently from other reference + types, since a runtime check cannot be performed on the assignment + of raw addresses. For example: +
+ VAR + x: ADDRESS; + a: UNTRACED REF INTEGER; + b: UNTRACED REF BOOLEAN; + + a := b; (* static error *) + x := a; (* no possible error *) + a := x (* static error in safe modules *) +
++ +
+ Last modified on Wed Apr 3 09:39:12 PST 1996 by heydon + modified on Mon Apr 18 14:00:50 PDT 1994 by kalsow +
+ + Index: m3/pm3/language/modula3/src/m3defn/authors.html diff -c /dev/null m3/pm3/language/modula3/src/m3defn/authors.html:1.1.1.1 *** /dev/null Tue Feb 10 23:31:55 1998 --- m3/pm3/language/modula3/src/m3defn/authors.html Sat Jan 31 14:47:13 1998 *************** *** 0 **** --- 1,59 ---- + + +Modula-3: About the authors + + + +About the authors
+ ++ Luca Cardelli was an undergraduate in Pisa and has a Ph.D. in Computer + Science from the University of Edinburgh (1982). He worked at AT&T + Bell Labs, Murray Hill, from 1982 to 1985 before assuming his current + position at DEC SRC. His main interests are in constructive logic, + type theory, and language design and implementation. + +
+ Jim Donahue received his Ph.D. in Computer Science at the University + of Toronto (1975). He was an Assistant Professor at Cornell University + from 1975 to 1981. In 1981, he joined the Computer Science Laboratory + of the Xerox Palo Alto Research Center. In 1986, he established the + Olivetti Research Center and was its Director until 1990. He is now + a Senior Scientist and Product Manager for Teknekron Software Systems. + His interests include programming language design, distributed system + design, and database systems and applications. + +
+ Lucille Glassman is a technical writer for DEC SRC. + +
+ Mick Jordan has a Ph.D. in Computer Science from the University of + Cambridge. From 1984 to 1988 he worked at the Acorn Research Center + in Palo Alto on a programming environment for Modula-2+. Before joining + DEC SRC in 1990 he was at Olivetti Research, where he led the group + that produced the Olivetti Modula-3 implementation. His principal + current interest is in programming tools that are based on Modula-3 + Abstract Syntax Trees. + +
+ Bill Kalsow received his Ph.D. in Computer Science from the University + of Wisconsin at Madison (1986). Since then he has worked as DEC SRC. + His primary interests are programming languages and their + implementations. + +
+ Greg Nelson got his Ph.D. from Stanford in 1980, where he worked on + program verification and algorithms for mechanical theorem proving. + He was the author of the Juno constraint-based graphics system at Xerox + PARC's Computer Science Laboratory, has taught at Princeton University, + and is now a member of DEC SRC. Currently his active interests are + window systems, programming language design, and the semantic theory + of guarded commands. +
+ +
+ Last modified on Wed Apr 3 09:39:12 PST 1996 by heydon + modified on Thu Apr 14 12:21:23 PDT 1994 by kalsow +
+ + Index: m3/pm3/language/modula3/src/m3defn/block.html diff -c /dev/null m3/pm3/language/modula3/src/m3defn/block.html:1.2 *** /dev/null Tue Feb 10 23:31:55 1998 --- m3/pm3/language/modula3/src/m3defn/block.html Tue Feb 10 22:59:14 1998 *************** *** 0 **** --- 1,28 ---- + + +Modula-3: Block statements + + + +Blocks
++ + A block statement has the form: +
+ Decls BEGIN S END +
+where Decls is a sequence of declarations and S + is a statement. + The block introduces the constants, types, variables, + and procedures declared in Decls and then executes S. + The scope of the + declared names + is the block. +
+ +
+ Last modified on Wed Apr 3 09:39:12 PST 1996 by heydon + modified on Mon Apr 18 14:00:59 PDT 1994 by kalsow +
+ + Index: m3/pm3/language/modula3/src/m3defn/boolops.html diff -c /dev/null m3/pm3/language/modula3/src/m3defn/boolops.html:1.2 *** /dev/null Tue Feb 10 23:31:55 1998 --- m3/pm3/language/modula3/src/m3defn/boolops.html Tue Feb 10 22:59:14 1998 *************** *** 0 **** --- 1,33 ---- + + +Modula-3: Boolean operations + + + +Boolean operations
++ +
+ prefix NOT (p: BOOLEAN) : BOOLEAN + infix AND (p,q: BOOLEAN) : BOOLEAN + infix OR (p,q: BOOLEAN) : BOOLEAN +
+NOT p is the complement of p. +
+ + p AND q is TRUE if both p and q + are TRUE. + If p is FALSE, q is not evaluated. +
+ + p OR q is TRUE if at least one of p and q + is TRUE. + If p is TRUE, q is not evaluated. +
+ +
+ Last modified on Wed Apr 3 09:39:11 PST 1996 by heydon + modified on Mon Apr 18 14:01:10 PDT 1994 by kalsow +
+ + Index: m3/pm3/language/modula3/src/m3defn/builtin.html diff -c /dev/null m3/pm3/language/modula3/src/m3defn/builtin.html:1.2 *** /dev/null Tue Feb 10 23:31:55 1998 --- m3/pm3/language/modula3/src/m3defn/builtin.html Tue Feb 10 22:59:14 1998 *************** *** 0 **** --- 1,30 ---- + + +Modula-3: Predeclared opaque types + + + +Predeclared opaque types
++ + The language predeclares the two types: +
+ TEXT <: REFANY + MUTEX <: ROOT +
+which represent text strings and mutual exclusion semaphores, + respectively. These are + opaque types. + Their properties are specified in + the required interfaces + Text + and + Thread. +
+ +
+ Last modified on Wed Apr 3 09:39:11 PST 1996 by heydon + modified on Mon Apr 18 14:01:18 PDT 1994 by kalsow +
+ + Index: m3/pm3/language/modula3/src/m3defn/calls.html diff -c /dev/null m3/pm3/language/modula3/src/m3defn/calls.html:1.2 *** /dev/null Tue Feb 10 23:31:55 1998 --- m3/pm3/language/modula3/src/m3defn/calls.html Tue Feb 10 22:59:14 1998 *************** *** 0 **** --- 1,116 ---- + + +Modula-3: Procedure calls + + + +Procedure calls
++ + A procedure call has the form: +
+ P(Bindings) +
+where P is a procedure-valued expression and Bindings + is a list of keyword or positional bindings. A keyword + binding has the form name := actual, where actual is + an expression and name is an identifier. A positional binding + has the form actual, where actual is an expression. + When keyword and positional bindings are mixed in a call, the + positional bindings must precede the keyword bindings. If the list + of bindings is empty, the parentheses are still required. +
+ + The + list of bindings is rewritten to fit the signature of P's + type as follows: First, each positional binding actual is + converted and added to the list of keyword bindings by supplying the + name of the i'th formal parameter, where actual is the + i'th binding in Bindings. Second, for each parameter that + has a default and is not bound after the first step, + the binding name := default is added to the list of bindings, + where name + is the name of the parameter and default is its default value. + The rewritten list of bindings must bind only formal parameters and + must bind each formal parameter exactly once. + For example, suppose that the type of P is +
+ PROCEDURE(ch: CHAR; n: INTEGER := 0) +
+Then the following calls are all equivalent: +
+ P('a', 0) + P('a') + P(ch := 'a') + P(n := 0, ch := 'a') + P('a', n := 0) ++The call P() is illegal, since it doesn't bind + ch. The call P(n := 0, 'a') is illegal, since it has + a keyword parameter before a positional parameter. +
+ + For + a READONLY or VALUE parameter, the actual can be + any expression assignable to the type of the formal (except that + the prohibition against assigning local procedures is relaxed). For + a VAR parameter, the actual must be a + writable designator whose + type is the same as that of the formal, or, in case of a VAR + array parameter, assignable to that of the formal. +
+ + A + VAR formal is bound to the variable designated by the + corresponding actual; that is, it is aliased. A VALUE formal + is bound to a variable with an unused location and initialized to + the value of the corresponding actual. A READONLY formal is + treated as a VAR formal if the actual is a designator and the + type of the actual is the same as the type of the formal (or an array + type that is assignable to the type of the formal); otherwise + it is treated as a VALUE formal. +
+ + Implementations + are allowed to forbid VAR or READONLY + parameters of packed types. +
+ + To + execute the call, the procedure P and its arguments are + evaluated, the formal parameters are bound, and the body of the + procedure is executed. The order of evaluation of P and its + actual arguments is undefined. It is a checked runtime error to + call an undefined or NIL procedure. +
+ + It + is a checked runtime error for a procedure to raise an exception + not included in its raises set (If an implementation + maps this runtime error into an exception, the exception is implicitly + included in all RAISES clauses.) or for a function procedure + to fail to return a result. +
+ + A procedure call is a statement only if the procedure is proper. To + call a function procedure and discard its result, use + EVAL. +
+ + A + procedure call can also have the form: +
+ o.m(Bindings) +
+where o is an object and m names one of + o's methods. This is equivalent to: +
+ (o's m method) (o, Bindings) +
+ ++ Last modified on Wed Apr 3 09:39:11 PST 1996 by heydon + modified on Mon Apr 18 14:01:32 PDT 1994 by kalsow +
+ + Index: m3/pm3/language/modula3/src/m3defn/case.html diff -c /dev/null m3/pm3/language/modula3/src/m3defn/case.html:1.2 *** /dev/null Tue Feb 10 23:31:55 1998 --- m3/pm3/language/modula3/src/m3defn/case.html Tue Feb 10 22:59:14 1998 *************** *** 0 **** --- 1,42 ---- + + +Modula-3: Case statements + + + +Case
++ + A CASE statement has the form: +
+ CASE Expr OF + L_1 => S_1 + | ... + | L_n => S_n + ELSE S_0 + END +
+where Expr is an expression whose type is an ordinal type and + each L is a list of constant expressions or ranges of constant + expressions denoted by "e_1..e_2", which represent + the values from e_1 to e_2 inclusive. If + e_1 exceeds e_2, the range is empty. It is a static + error if the sets represented by any two L's overlap or if + the value of any of the constant expressions is not a member of the + type of Expr. The "ELSE S_0" is optional. +
+ + The + statement evaluates Expr. If the resulting value is in any + L_i, then S_i is executed. If the value is + in no L_i and "ELSE S_0" is present, then it is executed. + If the value is in no L_i and "ELSE S_0" is absent, + a checked runtime error occurs. +
+ +
+ Last modified on Wed Apr 3 09:39:10 PST 1996 by heydon + modified on Mon Apr 18 14:01:42 PDT 1994 by kalsow +
+ + Index: m3/pm3/language/modula3/src/m3defn/constants.html diff -c /dev/null m3/pm3/language/modula3/src/m3defn/constants.html:1.2 *** /dev/null Tue Feb 10 23:31:55 1998 --- m3/pm3/language/modula3/src/m3defn/constants.html Tue Feb 10 22:59:14 1998 *************** *** 0 **** --- 1,25 ---- + + +Modula-3: Constant declarations + + + +Constants
++ + If id is an identifier, T a type, + and C a constant expression, then: +
+ CONST id: T = C +
+declares id as a constant with the type T and the value + of C. The ": T" can be omitted, in which case the type + of id is the type of C. If T is present it must + contain C. + +
+ Last modified on Wed Apr 3 09:39:10 PST 1996 by heydon + modified on Fri Apr 15 13:44:22 PDT 1994 by kalsow +
+ + Index: m3/pm3/language/modula3/src/m3defn/constexpr.html diff -c /dev/null m3/pm3/language/modula3/src/m3defn/constexpr.html:1.2 *** /dev/null Tue Feb 10 23:31:55 1998 --- m3/pm3/language/modula3/src/m3defn/constexpr.html Tue Feb 10 22:59:14 1998 *************** *** 0 **** --- 1,33 ---- + + +Modula-3: Constant expressions + + + +Constant Expressions
++ + Constant expressions are a subset of the general class of expressions, + restricted by the requirement that it be possible to evaluate the + expression statically. All operations are legal in constant expressions + except for ADR, LOOPHOLE, TYPECODE, NARROW, + ISTYPE, SUBARRAY, NEW, dereferencing (explicit or + implicit), and the only procedures that can be applied are the functions + in the + Word interface. +
+ + A variable can appear in a constant expression only as an argument + to FIRST, LAST, NUMBER, BITSIZE, + BYTESIZE, or ADRSIZE, and such a variable must not + have an open array type. + Literals and top-level procedure constants are legal in constant + expressions. +
+ +
+ Last modified on Wed Apr 3 09:39:10 PST 1996 by heydon + modified on Mon Apr 18 13:46:48 PDT 1994 by kalsow +
+ + Index: m3/pm3/language/modula3/src/m3defn/construct.html diff -c /dev/null m3/pm3/language/modula3/src/m3defn/construct.html:1.2 *** /dev/null Tue Feb 10 23:31:55 1998 --- m3/pm3/language/modula3/src/m3defn/construct.html Tue Feb 10 22:59:14 1998 *************** *** 0 **** --- 1,65 ---- + + +Modula-3: Set, array, and record constructors + + + +Set, array, and record constructors
++ + A set constructor has the form: +
+ S{e_1, ..., e_n} ++where S is a set type and the e's are expressions or ranges + of the form lo..hi. The constructor denotes a value of type + S containing the listed values and the values in the listed ranges. + The e's, lo's, and hi's must be assignable + to the element type of S. +
+ + An + array constructor has the form: +
+ A{e_1, ..., e_n} ++where A is an array type and the e's are expressions. + The constructor denotes a value of type A containing the listed + elements in the listed order. The e's must be assignable to + the element type of A. This means that if A is a + multi-dimensional array, the e's must themselves be array-valued + expressions. +
+ + If A is a fixed array type and n is at least 1, then + e_n can be followed by ", .." to indicate that the + value of e_n will be replicated as many times as necessary + to fill out the array. It is a static error to provide too many or + too few elements for a fixed array type. +
+ + A + record constructor has the form: +
+ R{Bindings} ++where R is a record type and Bindings is a list of keyword + or positional bindings, exactly as in a + procedure call. + The list of bindings is rewritten to fit the list of fields and defaults + of R, exactly as for a procedure call; the record field names + play the role of the procedure formal parameters. The expression + denotes a value of type R whose field values are specified by + the rewritten binding. +
+ + The rewritten binding must bind only field names and must bind each field + name exactly once. Each expression in the binding must be assignable + to the type of the corresponding record field. + +
+ Last modified on Wed Apr 3 09:39:10 PST 1996 by heydon + modified on Mon Apr 18 14:02:28 PDT 1994 by kalsow +
+ + Index: m3/pm3/language/modula3/src/m3defn/conventions.html diff -c /dev/null m3/pm3/language/modula3/src/m3defn/conventions.html:1.2 *** /dev/null Tue Feb 10 23:31:55 1998 --- m3/pm3/language/modula3/src/m3defn/conventions.html Tue Feb 10 22:59:14 1998 *************** *** 0 **** --- 1,62 ---- + + +Modula-3: Conventions for describing operations + + + +Conventions for describing operations
++ + To describe the argument and result types of operations, + we use a notation like procedure signatures. But since most operations + are too general to be described by a true procedure signature, we + extend the notation in several ways. +
+ + The argument to an operation can be required to have a type in a particular + class, such as an ordinal type, set type, etc. In this case the formal + specifies a type class instead of a type. For example: +
+ ORD (x: Ordinal): INTEGER +
+The formal type Any specifies an argument of any type. +
+ + A + single operation name can be overloaded, which means that it denotes + more than one operation. In this case, we write a separate signature + for each of the operations. For example: +
+ ABS (x: INTEGER) : INTEGER + (x: Float) : Float +
+The particular operation will be selected so that each actual argument + type is a subtype of the corresponding formal type or a member + of the corresponding formal type class. +
+ + The argument to an operation can be an expression denoting a type. + In this case, we write Type as the argument type. For example: +
+ BYTESIZE (T: Type): CARDINAL +
+The result type of an operation can depend on its argument values + (although the result type can always be determined statically). In + this case, the expression for the result type contains the + appropriate arguments. + For example: +
+ FIRST (T: FixedArrayType): IndexType(T) +
+IndexType(T) denotes the index type of the array type + T and IndexType(a) denotes the index type of the array + a. The definitions of ElemType(T) and ElemType(a) + are similar. +
+ +
+ Last modified on Wed Apr 3 09:39:09 PST 1996 by heydon + modified on Fri Apr 15 15:24:37 PDT 1994 by kalsow +
+ + Index: m3/pm3/language/modula3/src/m3defn/decls.html diff -c /dev/null m3/pm3/language/modula3/src/m3defn/decls.html:1.2 *** /dev/null Tue Feb 10 23:31:55 1998 --- m3/pm3/language/modula3/src/m3defn/decls.html Tue Feb 10 22:59:15 1998 *************** *** 0 **** --- 1,57 ---- + + +Modula-3: Declarations + + + +Declarations
++ +
++ There are two basic methods of declaring high or low before the showdown + in all High-Low Poker games. They are (1) simultaneous declarations, + and (2) consecutive declarations .... It is a sad but true fact that + the consecutive method spoils the game. + ---John Scarne's Guide to Modern Poker +
+ + A + declaration introduces a name for a constant, type, variable, exception, + or procedure. The scope of the name is the block containing the + declaration. A block has the form: +
+ Decls BEGIN S END +
+where + Decls is a sequence of declarations and S is a + statement, the executable part of the block. A block can appear as + a statement or as the body of a module or procedure. The declarations + of a block can introduce a name at most once, though a name can be + redeclared in nested blocks, and a procedure declared in an interface + can be redeclared in a + module + exporting the interface. + The order of declarations + in a block does not matter, except to determine the order of + initialization of variables. +
+ + Each type of declaration is described below +
-
+
- Types +
- Constants +
- Variables +
- Procedures +
- Exceptions +
- Opaque types +
- Revelations +
- Recursive declarations +
+ Last modified on Tue Oct 3 17:20:24 PDT 1995 by heydon + modified on Mon Apr 18 13:47:55 PDT 1994 by kalsow +
+ + Index: m3/pm3/language/modula3/src/m3defn/defns.html diff -c /dev/null m3/pm3/language/modula3/src/m3defn/defns.html:1.1.1.1 *** /dev/null Tue Feb 10 23:31:55 1998 --- m3/pm3/language/modula3/src/m3defn/defns.html Sat Jan 31 14:47:13 1998 *************** *** 0 **** --- 1,67 ---- + + +Modula-3: Definitions + + + +Definitions
++ + A + Modula-3 program specifies a computation that acts on a sequence + of digital components called locations. A variable is a set + of locations that represents a mathematical value according to a + convention determined by the variable's type. If a value can + be represented by some variable of type T, then we say that + the value is a member of T and T contains + the value. +
+ + An + identifier is a symbol declared as a name for a variable, type, + procedure, etc. The region of the program over which a declaration + applies is called the scope of the declaration. Scopes can be + nested. The meaning of an identifier is determined by the smallest + enclosing scope in which the identifier is declared. +
+ + An + expression specifies a computation that produces a value + or variable. Expressions that produce variables are called + designators. A designator can denote either a variable or the value + of that variable, depending on the context. Some designators are + readonly, which means that they cannot be used in contexts that might + change the value of the variable. A designator that is not readonly + is called writable. Expressions + whose values can be determined statically are called constant + expressions; they are never designators. +
+ + A + static error is an error that the implementation must detect + before program execution. Violations of the language definition + are static errors unless they are explicitly classified as runtime + errors. +
+ + A + checked runtime error is an error that the implementation + must detect and report at runtime. The method for reporting such + errors is implementation-dependent. (If the implementation maps + them into exceptions, then a program could handle these exceptions + and continue.) +
+ + An + unchecked runtime error is an error that is not guaranteed + to be detected, and can cause the subsequent behavior of the + computation to be arbitrary. Unchecked runtime errors can occur + only in unsafe modules. +
+ +
+ Last modified on Wed Apr 3 09:39:09 PST 1996 by heydon + modified on Thu Apr 14 14:29:42 PDT 1994 by kalsow +
+ + Index: m3/pm3/language/modula3/src/m3defn/designators.html diff -c /dev/null m3/pm3/language/modula3/src/m3defn/designators.html:1.2 *** /dev/null Tue Feb 10 23:31:55 1998 --- m3/pm3/language/modula3/src/m3defn/designators.html Tue Feb 10 22:59:15 1998 *************** *** 0 **** --- 1,134 ---- + + +Modula-3: Designators + + + +Designators
++ + An identifier is a writable designator + if it is declared as a variable, + is a VAR or VALUE parameter, + is a local of a TYPECASE + or TRY EXCEPT statement, + or is a WITH local that is bound to a writable designator. + An identifier is a readonly designator if it is + a READONLY parameter, + a local of a FOR statement, + or a WITH local bound to a non-designator or + readonly designator. +
+ + The + only operations that produce designators are dereferencing, + subscripting, selection, and SUBARRAY. + This section defines these operations and specifies the conditions + under which they produce designators. + In unsafe modules, + LOOPHOLE + can also produce a designator. +
+ + r^ +
+
+denotes the the referent of + r; this operation is called dereferencing. The + expression r^ is always a writable designator. It is a + static error if the type of r is REFANY, + ADDRESS, NULL, an object type, or an opaque type, + and a checked runtime error if r is NIL. + The type of r^ is the referent type of r. +
+ + a[i] +
+
+denotes the (i + 1 - FIRST(a))-th element of the + array a. The expression a[i] is a designator + if a is, and is writable if a is. + The expression i + must be assignable to the index type of a. The type of + a[i] is the element type of a. +
+ + An expression of the form a[i_1, ..., i_n] is + shorthand for a[i_1]...[i_n]. If a is a reference + to an array, then a[i] is shorthand for a^[i]. +
+ + r.f, o.f, I.x, T.m, E.id +
+
+If r denotes a record, + r.f denotes its f field. In + this case r.f is a designator if r is, + and is writable if r is. + The type of r.f is the declared type of the field. +
+ + If r is a reference to a record, + then r.f is shorthand for r^.f. +
+ + If o denotes an object and f + names a data field specified + in the type of o, then o.f denotes + that data field of o. In this case o.f is a writable + designator whose type is the declared type of the field. +
+ + If I denotes an imported interface, then I.x denotes + the entity named x in the interface I. In this case + I.x is a designator if x is declared as a variable; + such a designator is always writable. +
+ + If T is an object type and m + is the name of one of + T's methods, then T.m denotes the m method of + type T. In this case T.m is not a designator. Its type + is the procedure type whose first argument has mode VALUE + and type T, and whose remaining arguments are determined by + the method declaration for m in T. The name of the first + argument is unspecified; thus in calls to T.m, this argument + must be given positionally, not by keyword. T.m is a + procedure constant. +
+ + If E is an enumerated type, + then E.id denotes its + value named id. In this case E.id is not a designator. + The type of E.id is E. +
+ + + SUBARRAY(a: Array; from, for: CARDINAL): ARRAY OF ElemType(a) + +
+
+ +SUBARRAY produces a subarray of a. It does not copy the + array; it is a designator if a is, and is writable if a + is. If a is a multi-dimensional array, SUBARRAY applies + only to the top-level array. +
+ + The operation returns the subarray that skips the + first from + elements of a and contains the next for elements. Note + that if from is zero, the subarray is a prefix of a, + whether the type of a is zero-based or not. It is a checked + runtime error if from+for exceeds NUMBER(a). +
+ + Implementations may restrict + or prohibit the SUBARRAY operation for arrays with packed + element types. +
+ Last modified on Wed Apr 3 09:39:09 PST 1996 by heydon + modified on Mon Apr 18 14:02:39 PDT 1994 by kalsow +
+ + Index: m3/pm3/language/modula3/src/m3defn/eval.html diff -c /dev/null m3/pm3/language/modula3/src/m3defn/eval.html:1.2 *** /dev/null Tue Feb 10 23:31:55 1998 --- m3/pm3/language/modula3/src/m3defn/eval.html Tue Feb 10 22:59:15 1998 *************** *** 0 **** --- 1,25 ---- + + +Modula-3: Eval statements + + + +Eval
++ + An EVAL statement has the form: +
+ EVAL e +
+where e is an expression. The effect is to evaluate e and + ignore the result. For example: +
+ EVAL Thread.Fork(p) +
+ ++ Last modified on Wed Apr 3 09:39:08 PST 1996 by heydon + modified on Fri Apr 15 08:36:48 PDT 1994 by kalsow +
+ + Index: m3/pm3/language/modula3/src/m3defn/example.html diff -c /dev/null m3/pm3/language/modula3/src/m3defn/example.html:1.1.1.1 *** /dev/null Tue Feb 10 23:31:55 1998 --- m3/pm3/language/modula3/src/m3defn/example.html Sat Jan 31 14:47:13 1998 *************** *** 0 **** --- 1,61 ---- + + +Modula-3: Example module and interface + + + +Example module and interface
++ + Here is the canonical example of a public stack with hidden representation: +
+ INTERFACE Stack; + TYPE T <: REFANY; + PROCEDURE Create(): T; + PROCEDURE Push(VAR s: T; x: REAL); + PROCEDURE Pop(VAR s: T): REAL; + END Stack. + + MODULE Stack; + REVEAL T = BRANDED OBJECT item: REAL; link: T END; + PROCEDURE Create(): T = BEGIN RETURN NIL END Create; + + PROCEDURE Push(VAR s: T; x: REAL) = + BEGIN + s := NEW(T, item := x, link := s) + END Push; + + PROCEDURE Pop(VAR s: T): REAL = + VAR res: REAL; + BEGIN + res := s.item; s := s.link; RETURN res + END Pop; + + BEGIN + END Stack. +
++ + If the representation of stacks is required in more than one module, + it should be moved to a private interface, so that it can be imported + wherever it is required: +
+ INTERFACE Stack (* ... as before ... *) END Stack. + + INTERFACE StackRep; IMPORT Stack; + REVEAL Stack.T = BRANDED OBJECT item: REAL; link: Stack.T END + END StackRep. + + MODULE Stack; IMPORT StackRep; + (* Push, Pop, and Create as before *) + BEGIN + END Stack. +
++ +
+ Last modified on Wed Apr 3 09:39:08 PST 1996 by heydon + modified on Mon Apr 18 13:26:15 PDT 1994 by kalsow +
+ + Index: m3/pm3/language/modula3/src/m3defn/exceptions.html diff -c /dev/null m3/pm3/language/modula3/src/m3defn/exceptions.html:1.2 *** /dev/null Tue Feb 10 23:31:55 1998 --- m3/pm3/language/modula3/src/m3defn/exceptions.html Tue Feb 10 22:59:15 1998 *************** *** 0 **** --- 1,26 ---- + + +Modula-3: Exception declarations + + + +Exceptions
++ + If id is an identifier and T a type other than + an open array type, then: +
+ EXCEPTION id(T) +
+declares id as an exception with argument type T. + If "(T)" is omitted, the exception takes no argument. + An exception declaration is allowed only in an interface or in the + outermost scope of a module. + All declared exceptions are distinct. + +
+ Last modified on Wed Apr 3 09:39:08 PST 1996 by heydon + modified on Fri Apr 15 13:49:33 PDT 1994 by kalsow +
+ + Index: m3/pm3/language/modula3/src/m3defn/exit.html diff -c /dev/null m3/pm3/language/modula3/src/m3defn/exit.html:1.2 *** /dev/null Tue Feb 10 23:31:55 1998 --- m3/pm3/language/modula3/src/m3defn/exit.html Tue Feb 10 22:59:15 1998 *************** *** 0 **** --- 1,44 ---- + + +Modula-3: Exit statements + + + +Exit
++ + The statement +
+ EXIT +
+raises the exit-exception. An EXIT statement must be textually + enclosed by a + LOOP, + WHILE, + REPEAT, + or + FOR + statement. +
+ + We + define EXIT and RETURN in terms of exceptions in order + to specify their interaction with the exception handling statements. + As a pathological example, consider the following code, which is an + elaborate infinite loop: +
+ LOOP + TRY + TRY EXIT FINALLY RAISE E END + EXCEPT + E => (*skip*) + END + END +
+ ++ Last modified on Wed Apr 3 09:39:07 PST 1996 by heydon + modified on Fri Apr 15 08:53:02 PDT 1994 by kalsow +
+ + Index: m3/pm3/language/modula3/src/m3defn/exprs.html diff -c /dev/null m3/pm3/language/modula3/src/m3defn/exprs.html:1.2 *** /dev/null Tue Feb 10 23:31:55 1998 --- m3/pm3/language/modula3/src/m3defn/exprs.html Tue Feb 10 22:59:15 1998 *************** *** 0 **** --- 1,51 ---- + + +Modula-3: Expressions + + + +Expressions
++ +
++ The rules of logical syntax must follow of themselves, + if we only know how every single sign signifies. + ---Ludwig Wittgenstein +
+ + An + expression prescribes a computation that produces a value or + variable. Syntactically, an expression is either an operand, or an + operation applied to arguments, which are themselves expressions. + Operands are identifiers, literals, or types. An expression is + evaluated by recursively evaluating its arguments and performing + the operation. The order of argument evaluation is undefined for + all operations except AND and OR. +
+ + The following topics are discussed below +
-
+
- Conventions for describing operations +
- Operation syntax +
- Designators +
- Numeric literals +
- Text and character literals +
- Nil +
- Function application +
- Set, array, and record constructors +
- New +
- Arithmetic operations +
- Relations +
- Boolean operations +
- Type operations +
- Text operations +
- Constant expressions +
+ Last modified on Tue Oct 3 19:13:52 PDT 1995 by heydon + modified on Fri Apr 15 15:21:09 PDT 1994 by kalsow +
+ + Index: m3/pm3/language/modula3/src/m3defn/float-intf.html diff -c /dev/null m3/pm3/language/modula3/src/m3defn/float-intf.html:1.2 *** /dev/null Tue Feb 10 23:31:55 1998 --- m3/pm3/language/modula3/src/m3defn/float-intf.html Tue Feb 10 22:59:15 1998 *************** *** 0 **** --- 1,132 ---- + + +Modula-3: RealFloat, LongFloat and ExtendedFloat interfaces + + + +The RealFloat, LongFloat and ExtendedFloat interfaces
++ + For definitions of the terms used in these interfaces, see the ANSI/IEEE + Standard 754-1985 for floating-point arithmetic. +
+ + These interfaces define operations that depend on the + floating-point representation. They are all are instances of a generic + interface Float: +
+ INTERFACE RealFloat = Float(Real) END RealFloat. + INTERFACE LongFloat = Float(LongReal) END LongFloat. + INTERFACE ExtendedFloat = Float(Extended) END ExtendedFloat. +
+ ++ GENERIC INTERFACE Float(R); TYPE T = R.T; +
+This generic interface provides access to the floating-point operations + required or recommended by the IEEE floating-point standard. Consult + the standard for the precise specifications of the procedures, + including when their arguments are NaNs, infinities, and signed + zeros, and including what exceptions they can raise. The comments + here specify their effect when the arguments are ordinary numbers + and no exception is raised. Implementations on non-IEEE machines + that have values similar to NaNs and infinities should explain how + those values behave in an implementation guide. +
+ +
+ PROCEDURE Scalb(x: T; n: INTEGER): T; +
+Return x * 2^n. + +
+ PROCEDURE Logb(x: T): T; +
+Return the exponent of x. More precisely, return the unique + n such that the ratio ABS(x) / Base^n is in the range + [1..Base-1], unless x is denormalized, in which case + return the minimum exponent value for T. +
+ +
+ PROCEDURE ILogb(x: T): INTEGER; +
+Like Logb, but returns an integer, never raises an exception, + and always returns the n such that ABS(x) / Base^n is + in the range [1..Base-1], even for denormalized numbers. +
+ +
+ PROCEDURE NextAfter(x, y: T): T; +
+Return the next representable neighbor of x in the direction + towards y. If x = y, return x. +
+ +
+ PROCEDURE CopySign(x, y: T): T; +
+Return x with the sign of y. + +
+ PROCEDURE Finite(x: T): BOOLEAN; +
+Return TRUE if x is strictly between minus infinity and + plus infinity. This always returns TRUE on non-IEEE machines. + +
+ PROCEDURE IsNaN(x: T): BOOLEAN; +
+Return FALSE if x represents a numerical + (possibly infinite) value, + and TRUE if x does not represent a numerical value. + For example, on IEEE implementations, + returns TRUE if x is a NaN, + FALSE otherwise. + +
+ PROCEDURE Sign(x: T): [0..1]; +
+Return the sign bit of x. For non-IEEE implementations, + this is the same as ORD(x >= 0); for IEEE implementations, + Sign(-0) = 1 and Sign(+0) = 0. + +
+ PROCEDURE Differs(x, y: T): BOOLEAN; +
+Return (x < y OR y < x). Thus, for IEEE implementations, + Differs(NaN,x) is always FALSE; + for non-IEEE implementations, + Differs(x,y) is the same as x # y. + +
+ PROCEDURE Unordered(x, y: T): BOOLEAN; +
+Return NOT (x <= y OR y <= x). + +
+ PROCEDURE Sqrt(x: T): T; +
+Return the square root of T. This must be correctly rounded if + FloatMode.IEEE is TRUE. + +
+ TYPE IEEEClass = + {SignalingNaN, QuietNaN, Infinity, Normal, Denormal, Zero}; ++ ++ PROCEDURE Class(x: T): IEEEClass; +
+Return the IEEE number class containing x. + +
+ END Float. +
+ ++ Last modified on Wed Apr 3 09:39:07 PST 1996 by heydon + modified on Thu Jun 1 08:10:14 PDT 1995 by kalsow +
+ + Index: m3/pm3/language/modula3/src/m3defn/floatmode.html diff -c /dev/null m3/pm3/language/modula3/src/m3defn/floatmode.html:1.2 *** /dev/null Tue Feb 10 23:31:55 1998 --- m3/pm3/language/modula3/src/m3defn/floatmode.html Tue Feb 10 22:59:15 1998 *************** *** 0 **** --- 1,164 ---- + + +Modula-3: FloatMode interface + + + +The FloatMode interface
++ + The FloatMode interface allows you to test the behavior + of rounding and of numerical exceptions. On some implementations it + also allows you to change the behavior, on a per-thread basis. +
+ + For definitions of the terms used in this interface, see the ANSI/IEEE + Standard 754-1985 for floating-point arithmetic. +
+ +
+ INTERFACE FloatMode; + + CONST IEEE: BOOLEAN = ...; +
+TRUE for fully-compliant IEEE implementations. + +
+ EXCEPTION Failure; +
+Raised by attempts to set modes that are not supported by + the implementation. + +
+ TYPE RoundingMode = + {NearestElseEven, TowardMinusInfinity, TowardPlusInfinity, + TowardZero, NearestElseAwayFromZero, IBM370, Other}; ++Rounding modes. The first four are the IEEE modes. + +
+ CONST RoundDefault: RoundingMode = ...; +
+Implementation-dependent: the default mode for rounding arithmetic + operations, used by a newly forked thread. This also specifies + the behavior of the ROUND operation in half-way cases. + +
+ PROCEDURE SetRounding(md: RoundingMode) RAISES {Failure}; ++Change the rounding mode for the calling thread to md, or raise + the exception if this cannot be done. This affects the implicit + rounding in floating-point operations; it does not affect the + ROUND operation. Generally this can be done only on IEEE + implementations and only if md is an IEEE mode. + +
+ PROCEDURE GetRounding(): RoundingMode; +
+Return the rounding mode for the calling thread. + +
+ TYPE Flag = + {Invalid, Inexact, Overflow, Underflow, + DivByZero, IntOverflow, IntDivByZero}; ++Associated with each thread is a set of boolean status flags recording + whether the condition represented by the flag has occurred in the + thread since the flag was last reset. The meaning of the first + five flags is defined precisely in the IEEE floating point standard; + roughly they mean: +
+
+Invalid = invalid argument to an operation. +
+ + Inexact = an operation produced an inexact result. +
+ + Overflow = a floating-point operation produced a result whose + absolute value is too large to be represented. +
+ + Underflow = a floating-point operation produced a result whose + absolute value is too small to be represented. +
+ + DivByZero = floating-point division by zero. +
+ + + The meaning of the last two flags is: +
+
+IntOverflow = an integer operation produced a result whose + absolute value is too large to be represented. +
+ + IntDivByZero = integer DIV or MOD by zero. +
+ +
+ CONST NoFlags = SET OF Flags {}; ++ ++ PROCEDURE GetFlags(): SET OF Flag; +
+Return the set of flags for the current thread. + +
+ PROCEDURE SetFlags(s: SET OF Flag): SET OF Flag RAISES{Failure}; ++Set the flags for the current thread to s, and return their previous + values. + +
+ PROCEDURE ClearFlag(f: Flag); +
+Turn off the flag f for the current thread. + +
+ EXCEPTION + Trap(Flag); + + TYPE + Behavior = {Trap, SetFlag, Ignore}; ++The behavior of an operation that causes one of the flag conditions is either +
+
+ +Ignore = return some result and do nothing. +
+ + SetFlag = return some result and set the condition + flag. For IEEE implementations, the result of the operation is defined + by the standard. +
+ + + Trap = possibly set the condition flag; in any case + raise the Trap exception with the appropriate flag as the + argument. +
+ PROCEDURE SetBehavior(f: Flag; b: Behavior) RAISES {Failure}; ++Set the behavior of the current thread for the flag f + to be b, or raise Failure if this cannot be done. + +
+ PROCEDURE GetBehavior(f: Flag): Behavior; +
+Return the behavior of the current thread for the flag f. + +
+ END FloatMode. +
++ +
+ Last modified on Wed Apr 3 09:39:06 PST 1996 by heydon + modified on Thu Jun 1 08:10:29 PDT 1995 by kalsow +
+ + Index: m3/pm3/language/modula3/src/m3defn/floats.html diff -c /dev/null m3/pm3/language/modula3/src/m3defn/floats.html:1.1.1.1 *** /dev/null Tue Feb 10 23:31:55 1998 --- m3/pm3/language/modula3/src/m3defn/floats.html Sat Jan 31 14:47:13 1998 *************** *** 0 **** --- 1,22 ---- + + +Modula-3: Floating-point types + + + +Floating-point types
++ + There are three floating point types, which in order of increasing + range and precision are REAL, LONGREAL, + and EXTENDED. + The properties of these types are specified by + required interfaces. +
+ +
+ Last modified on Wed Apr 3 09:39:06 PST 1996 by heydon + modified on Mon Apr 18 14:03:08 PDT 1994 by kalsow +
+ + Index: m3/pm3/language/modula3/src/m3defn/for.html diff -c /dev/null m3/pm3/language/modula3/src/m3defn/for.html:1.2 *** /dev/null Tue Feb 10 23:31:55 1998 --- m3/pm3/language/modula3/src/m3defn/for.html Tue Feb 10 22:59:15 1998 *************** *** 0 **** --- 1,67 ---- + + +Modula-3: For statements + + + +For
++ + A FOR statement has the form: +
+ FOR id := first TO last BY step DO S END +
+where id is an identifier, first and last are + ordinal expressions with the same base type, + step is an integer-valued expression, and S is a statement. + "BY step" is optional; if omitted, step defaults to + 1. +
+ + The identifier id denotes a readonly variable whose scope is + S and whose type is the common basetype of first and + last. +
+ + If id is an integer, the statement steps id through the + values first, first+step, first+2*step, + ..., stopping when the value of id passes last. + S executes once for each value; if the sequence of values is + empty, S never executes. The expressions first, + last, and step are evaluated once, + before the loop is entered. + If step is negative, the loop iterates downward. +
+ + The case in which id is an element of an enumeration is similar. + In either case, the semantics are defined precisely by the following + rewriting, in which T is the type of id and in which + i, done, and delta stand for variables that do + not occur in the FOR statement: +
+ VAR + i := ORD(first); done := ORD(last); delta := step; + BEGIN + IF delta >= 0 THEN + WHILE i <= done DO + WITH id = VAL(i, T) DO S END; INC(i, delta) + END + ELSE + WHILE i >= done DO + WITH id = VAL(i, T) DO S END; INC(i, delta) + END + END + END +
++ + If the upper bound of the loop is LAST(INTEGER), it should be + rewritten as a WHILE loop to avoid overflow. +
+ +
+ Last modified on Wed Apr 3 09:39:06 PST 1996 by heydon + modified on Mon Apr 18 14:03:17 PDT 1994 by kalsow +
+ + Index: m3/pm3/language/modula3/src/m3defn/generics.html diff -c /dev/null m3/pm3/language/modula3/src/m3defn/generics.html:1.2 *** /dev/null Tue Feb 10 23:31:56 1998 --- m3/pm3/language/modula3/src/m3defn/generics.html Tue Feb 10 22:59:15 1998 *************** *** 0 **** --- 1,149 ---- + + +Modula-3: Generics + + + +Generics
++ + In a generic interface or module, some of the imported interface names + are treated as formal parameters, to be bound to actual interfaces + when the generic is instantiated. +
+ + A generic interface has the form +
+ GENERIC INTERFACE G(F_1, ..., F_n); + Body + END G. +
+where G is an identifier that names the generic interface, + F_1, ..., F_n is a list of identifiers, called + the formal imports of G, and Body is a sequence of imports + followed by a sequence of declarations, exactly as in a non-generic + interface. +
+ + An instance of G has the form +
+ INTERFACE I = G(A_1, ..., A_n) END I. +
+where I is the name of the instance and A_1, ..., + A_n is a list of actual interfaces to which the formal imports + of G are bound. The instance I is equivalent to an ordinary + interface defined as follows: +
+ INTERFACE I; + IMPORT A_1 AS F_1, ..., A_n AS F_n; + Body + END I. +
++ + A + generic module has the form +
+ GENERIC MODULE G(F_1, ..., F_n); + Body + END G. +
+where G is an identifier that names the generic module, + F_1, ..., F_n is a list of identifiers, called + the formal imports of G, and Body is a sequence of imports + followed by a block, exactly as in a non-generic module. +
+ + An instance of G has the form +
+ MODULE I EXPORTS E = G(A_1, ..., A_n) END I. +
+where I is the name of the instance, + E is a list of interfaces exported + by I, and A_1, ..., + A_n is a list of actual interfaces to which the formal + imports of G are bound. + "EXPORTS E" can be omitted, in which case + it defaults to "EXPORTS I". + The instance I is equivalent + to an ordinary module defined as follows: +
+ MODULE I EXPORTS E; + IMPORT A_1 AS F_1, ..., A_n AS F_n; + Body + END I. +
+Notice that the generic module itself has no exports; they are supplied + only when it is instantiated. +
+ + For + example, here is a generic stack package: +
+ GENERIC INTERFACE Stack(Elem); + (* where Elem.T is not an open array type. *) + TYPE T <: REFANY; + PROCEDURE Create(): T; + PROCEDURE Push(VAR s: T; x: Elem.T); + PROCEDURE Pop(VAR s: T): Elem.T; + END Stack. + + GENERIC MODULE Stack(Elem); + + REVEAL + T = BRANDED OBJECT n: INTEGER; a: REF ARRAY OF Elem.T END; + + PROCEDURE Create(): T = + BEGIN RETURN NEW(T, n := 0, a := NIL) END Create; + + PROCEDURE Push(VAR s: T; x: Elem.T) = + BEGIN + IF s.a = NIL THEN + s.a := NEW(REF ARRAY OF Elem.T, 5) + ELSIF s.n > LAST(s.a^) THEN + WITH temp = NEW(REF ARRAY OF Elem.T, 2 * NUMBER(s.a^)) DO + FOR i := 0 TO LAST(s.a^) DO temp[i] := s.a[i] END; + s.a := temp + END + END; + s.a[s.n] := x; + INC(s.n) + END Push; + + PROCEDURE Pop(VAR s: T): Elem.T = + BEGIN DEC(s.n); RETURN s.a[s.n] END Pop; + + BEGIN + END Stack. +
+To instantiate these generics to produce stacks of integers: +
+ INTERFACE Integer; TYPE T = INTEGER; END Integer. + INTERFACE IntStack = Stack(Integer) END IntStack. + MODULE IntStack = Stack(Integer) END IntStack. +
+Implementations are not expected to share code between different + instances of a generic module, since this will not be possible in + general. +
+ + Implementations are not required to typecheck uninstantiated generics, + but they must typecheck their instances. For example, if one made + the following mistake: +
+ INTERFACE String; TYPE T = ARRAY OF CHAR; END String. + INTERFACE StringStack = Stack(String) END StringStack. + MODULE StringStack = Stack(String) END StringStack. +
+everything would go well until the last line, when the compiler would + attempt to compile a version of Stack in which the element type + was an open array. It would then complain that the NEW call + in Push does not have enough parameters. +
+ +
+ Last modified on Wed Apr 3 09:39:52 PST 1996 by heydon + modified on Mon Apr 18 14:03:26 PDT 1994 by kalsow +
+ + Index: m3/pm3/language/modula3/src/m3defn/if.html diff -c /dev/null m3/pm3/language/modula3/src/m3defn/if.html:1.1.1.1 *** /dev/null Tue Feb 10 23:31:56 1998 --- m3/pm3/language/modula3/src/m3defn/if.html Sat Jan 31 14:47:13 1998 *************** *** 0 **** --- 1,40 ---- + + +Modula-3: If statements + + + +If
++ + An IF statement has the form: +
+ IF B_1 THEN S_1 + ELSIF B_2 THEN S_2 + ... + ELSIF B_n THEN S_n + ELSE S_0 + END +
++ + where the B's are boolean expressions and the S's are + statements. The "ELSE S_0" and each + "ELSIF B_i THEN S_i" are optional. +
+ + The statement evaluates the B's in order until some + B_i evaluates to TRUE, and then executes S_i. + If none of the expressions evaluates to TRUE and + "ELSE S_0" is present, S_0 is executed. + If none of the expressions evaluates + to TRUE and "ELSE S_0" is absent, the statement + is a no-op (except for any side-effects of the B's). +
+ +
+ Last modified on Wed Apr 3 09:39:07 PST 1996 by heydon + modified on Mon Apr 18 14:03:35 PDT 1994 by kalsow +
+ + Index: m3/pm3/language/modula3/src/m3defn/imports.html diff -c /dev/null m3/pm3/language/modula3/src/m3defn/imports.html:1.2 *** /dev/null Tue Feb 10 23:31:56 1998 --- m3/pm3/language/modula3/src/m3defn/imports.html Tue Feb 10 22:59:15 1998 *************** *** 0 **** --- 1,60 ---- + + +Modula-3: Import statements + + + +Import statements
++ + There are two forms of import statements. All imports of both forms + are interpreted simultaneously: their order doesn't matter. +
+ + + The first form is + +
+ IMPORT I AS J +
+which imports the interface whose global name is I and gives + it the local name J. The entities and revelations declared in + I become accessible in the importing module or interface, but + the entities and revelations imported into I do not. To refer + to the entity declared with name N in the interface I, + the importer must use the qualified identifier J.N. +
+ + The statement IMPORT I is short for IMPORT I AS I. +
+ + The + second form is +
+ FROM I IMPORT N +
+which introduces N as the local name for the entity declared + as N in the interface I. + A local binding for I takes + precedence over a global binding. + For example, +
+ IMPORT I AS J, J AS I; FROM I IMPORT N +
+simultaneously introduces local names J, I, and N + for the entities whose global names are I, J, + and J.N, respectively. +
+ + It is illegal to use the same local name twice: +
+ IMPORT J AS I, K AS I; +
+is a static error, even if J and K are the same. + +
+ Last modified on Wed Apr 3 09:39:05 PST 1996 by heydon + modified on Mon Apr 18 13:27:38 PDT 1994 by kalsow +
+ + Index: m3/pm3/language/modula3/src/m3defn/incdec.html diff -c /dev/null m3/pm3/language/modula3/src/m3defn/incdec.html:1.2 *** /dev/null Tue Feb 10 23:31:56 1998 --- m3/pm3/language/modula3/src/m3defn/incdec.html Tue Feb 10 22:59:16 1998 *************** *** 0 **** --- 1,38 ---- + + +Modula-3: Inc and Dec statements + + + +Inc and Dec
++ + INC and DEC statements have the form: +
+ INC(v, n) + DEC(v, n) +
+where v designates a variable of an ordinal type + and n is an optional integer-valued argument. If omitted, + n defaults to 1. The statements increment and decrement + v by n, respectively. + The statements are equivalent to: +
+ WITH x = v DO x := VAL(ORD(x) + n, T) END + WITH x = v DO x := VAL(ORD(x) - n, T) END +
+where T is the type of v and x stands for + a variable that does not appear in n. As a + consequence, the statements check for range errors. +
+ + In unsafe modules, + INC and DEC are extended to ADDRESS. +
+ +
+ Last modified on Wed Apr 3 09:39:05 PST 1996 by heydon + modified on Mon Apr 18 14:03:44 PDT 1994 by kalsow +
+ + Index: m3/pm3/language/modula3/src/m3defn/init.html diff -c /dev/null m3/pm3/language/modula3/src/m3defn/init.html:1.2 *** /dev/null Tue Feb 10 23:31:56 1998 --- m3/pm3/language/modula3/src/m3defn/init.html Tue Feb 10 22:59:16 1998 *************** *** 0 **** --- 1,37 ---- + + +Modula-3: Initialization + + + +Initialization
++ + The order of execution of the modules in a program is constrained by + the following rule: +
+ + If module M depends on module N and N + does not depend on M, then N's body will be + executed before M's body, + where: +
-
+
- A module M depends on a module N if M + uses an interface that N exports or if M depends on a + module that depends on N. +
- A module M uses an interface I if M + imports or exports I or if M uses an interface that + imports I. +
+ + Except for this constraint, the order of execution is + implementation-dependent. +
+ +
+ Last modified on Wed Apr 3 09:39:04 PST 1996 by heydon + modified on Mon Apr 18 13:28:21 PDT 1994 by kalsow +
+ + Index: m3/pm3/language/modula3/src/m3defn/interfaces.html diff -c /dev/null m3/pm3/language/modula3/src/m3defn/interfaces.html:1.2 *** /dev/null Tue Feb 10 23:31:56 1998 --- m3/pm3/language/modula3/src/m3defn/interfaces.html Tue Feb 10 22:59:16 1998 *************** *** 0 **** --- 1,29 ---- + + +Modula-3: Interfaces + + + +Interfaces
++ + An interface has the form: +
+ INTERFACE id; + Imports; + Decls + END id. +
+where id is an identifier that names the interface, + Imports is a sequence of import statements, and Decls is + a sequence of declarations that contains no procedure bodies or + non-constant variable initializations. The names declared in + Decls and the visible imported names must be distinct. It is a static + error for two or more interfaces to form an import cycle. + +
+ Last modified on Wed Apr 3 09:39:04 PST 1996 by heydon + modified on Mon Apr 18 14:04:10 PDT 1994 by kalsow +
+ + Index: m3/pm3/language/modula3/src/m3defn/intfs.html diff -c /dev/null m3/pm3/language/modula3/src/m3defn/intfs.html:1.2 *** /dev/null Tue Feb 10 23:31:56 1998 --- m3/pm3/language/modula3/src/m3defn/intfs.html Tue Feb 10 22:59:16 1998 *************** *** 0 **** --- 1,58 ---- + + +Modula-3: Required interfaces + + + +Required interfaces
+ +
++ C++ has a host of operators that will be explained if and where needed. + ---The C++ Programming Language +
+ + There + are several fundamental interfaces that every + Modula-3 implementation must provide: +
+
+Text provides operations + on text strings. +
+ + Thread provides synchronization + primitives for multiple threads of control. +
+ + Word provides operations on + unsigned words. +
+ + Real, LongReal, + and ExtendedReal + define the properties of the three floating point types; + for example, their bases and ranges. +
+ + RealFloat, LongFloat, + and ExtendedFloat + provide numerical operations related to the + floating-point representation; for example, extracting the exponent + of a number. +
+ + FloatMode provides operations + for testing (and possibly setting) the behavior of the implementation + in response to numeric conditions; for example, overflow. +
+ + Implementations are free to extend the required interfaces, provided + they do not invalidate clients of the unextended interfaces. + +
+ Last modified on Tue Oct 3 17:26:49 PDT 1995 by heydon + modified on Thu Jun 1 08:11:44 PDT 1995 by kalsow +
+ + Index: m3/pm3/language/modula3/src/m3defn/intro.html diff -c /dev/null m3/pm3/language/modula3/src/m3defn/intro.html:1.2 *** /dev/null Tue Feb 10 23:31:56 1998 --- m3/pm3/language/modula3/src/m3defn/intro.html Tue Feb 10 22:59:16 1998 *************** *** 0 **** --- 1,523 ---- + + +Modula-3: Introduction + + + +Introduction
+ +
++ He that will not apply new remedies must expect new evils: for time is + the greatest innovator, and if time of course alter things to the + worse, and wisdom and counsel shall not alter them to the better, what + shall be the end? + ---Francis Bacon +
+ +
History
++ + On November 6th, 1986, Maurice Wilkes wrote to Niklaus Wirth proposing + that the Modula-2+ language be revised and standardized as a successor + to Modula-2. Wirth gave this project his blessing, and the Modula-3 + committee was born. +
+ + At the first meeting, the committee unanimously agreed to be true to + the spirit of Modula-2 by selecting simple, safe, proven features rather + than experimenting with our own untried ideas. We found that unanimity + was harder to achieve when we got to the details. +
+ + Modula-3 + supports interfaces, objects, generics, lightweight threads + of control, the isolation of unsafe code, garbage collection, + exceptions, and subtyping. Some of the more problematical features + of Modula-2 have been removed, like variant records and the built-in + unsigned numeric data type. Modula-3 is substantially simpler than other + languages with comparable power. +
+ + Modula-3 + is closely based on Modula-2+, which was designed at the + Digital Equipment Corporation Systems Research Center and used to build + the Topaz system + [McJones89, + Rovner86]. + The Modula-3 design was + a joint project by Digital and Olivetti. The language definition was + published in August 1988, and immediately followed by implementation + efforts at both companies. In January 1989, the committee revised + the language to reflect the experiences of these implementation teams. + A few final revisions were made for the publication of this book. +
+ + SRC Modula-3 + is distributed by the DEC Systems Research Center under a liberal license. + The distribution + includes a compiler for Modula-3, the Modula-3 Abstract Syntax Tree + toolkit developed at Olivetti, and a runtime system with configuration + files for DEC, IBM, HP, and Sun workstations. +
+ +
Perspective
++ + Most systems programming today is done in the BCPL family of languages, + which includes B, Bliss, and C. The beauty of these languages is the + modest cost with which they were able to take a great leap + forward from assembly language. To fully appreciate them, you must + consider the engineering constraints of machines in the 1960s. What + language designed in the 1980s has a compiler that fits into four + thousand 18-bit words, like Ken Thompson's B compiler for the PDP-7? + The most successful of these languages was C, which by the early 1970s + had almost completely displaced assembly language in the Unix system. +
+ + The BCPL-like languages are easy + to implement efficiently for the same reason they are attractive to + skeptical assembly language programmers: they present a programming + model that is close to the target machine. Pointers are identified + with arrays, and address arithmetic is ubiquitous. Unfortunately, this + low-level programming model is inherently dangerous. Many errors are + as disastrous as they would be in machine language. The type system + is scanty, and reveals enough quirks of the target machine that even + experienced and disciplined programmers sometimes write unportable + code simply by accident. The most modern language in this family, + C++, has enriched C by adding objects; but it has also given up C's + best virtue---simplicity---without relieving C's worst drawback---its + low-level programming model. +
+ + At + the other extreme are languages like Lisp, ML, Smalltalk, and CLU, + whose programming models originate from mathematics. Lisp is the hybrid + of the lambda calculus and the theory of a pairing function; ML stems + from polymorphic type theory; Smalltalk from a theory of objects and + inheritance; CLU from a theory of abstract data types. These languages + have beautiful programming models, but they tend to be difficult to + implement efficiently, because the uniform treatment of values in the + programming model invites a runtime system in which values are uniformly + represented by pointers. If the implementer doesn't take steps to + avoid it, as simple a statement as n := n + 1 could require an + allocation, a method lookup, or both. Good implementations avoid + most of the cost, and languages in this family have been used + successfully for systems programming. But their general disposition + towards heap allocation rather than stack allocation remains, and they + have not become popular with systems programmers. The runtime systems + required to make these languages efficient often isolate them in closed + environments that cannot accommodate programs written in other + languages. If you are a fan of these languages you may find Modula-3 + overly pragmatic; but read on anyway, and give us a chance to show + that pragmatic constraints do not exclude attractive solutions. +
+ + Between + the extremes of BCPL and Lisp is the Algol family of languages, + whose modern representatives include Pascal, Ada, Modula-2, and + Modula-3. These languages have programming models that reflect the + engineering constraints of random-access machines but conceal the + details of any particular machine. They give up the beauty and + mathematical symmetry of the Lisp family in order to make efficient + implementations possible without special tricks; they also have strong + type systems that avoid most of the dangerous and machine-dependent + features of the BCPL family. +
+ + In + the 1960s, the trend in the Algol family was toward features for + control flow and data structuring. In the 1970s, the trend was toward + information-hiding features like interfaces, opaque types, and generics. + More recently, the trend in the Algol family has been to adopt a careful + selection of techniques from the Lisp and BCPL families. This trend + is demonstrated by Modula-3, Oberon, and Cedar, to name three languages + that have floated portable implementations in the last few years. +
+ + Modula-3, Oberon, and Cedar all provide garbage collection, previously + viewed as a luxury available only in the closed runtime systems of + the Lisp family. But the world is starting to understand that garbage + collection is the only way to achieve an adequate level of safety, + and that modern garbage collectors can work in open runtime + environments. +
+ + At the same time, these three languages allow a small set of unsafe, + machine-dependent operations of the sort usually associated with the + BCPL family. In Modula-3, unsafe operations are allowed only in modules + explicitly labeled unsafe. The combination of garbage collection with + the explicit isolation of unsafe features produces a language suitable + for programming entire systems from the highest-level applications + down to the lowest-level device drivers. +
+ +
Features
++ + The remainder of the introduction is an overview of the most important + features of Modula-3. + +
Interfaces
++ + One of Modula-2's most successful features is the provision for explicit + interfaces between modules. Interfaces are retained with essentially + no changes in Modula-3. An interface to a module is a collection of + declarations that reveal the public parts of a module; things in the + module that are not declared in the interface are private. A module + imports the interfaces it depends on and exports the + interface (or, in Modula-3, the interfaces) that it implements. +
+ + Interfaces make separate compilation type-safe; but it does them an + injustice to look at them in such a limited way. Interfaces make it + possible to think about large systems without holding the whole system + in your head at once. +
+ + Programmers who have never used Modula-style interfaces tend to + underestimate them, observing, for example, that anything that can + be done with interfaces can also be done with C-style include files. + This misses the point: many things can be done with include files that + cannot be done with interfaces. For example, the meaning of an include + file can be changed by defining macros in the environment into which + it is included. Include files tempt programmers into shortcuts across + abstraction boundaries. To keep large programs well structured, you + either need super-human will power, or proper language support for + interfaces. +
+ +
Objects
++ + THe better we understand our programs, the bigger the building blocks + we use to structure them. After the instruction came the statement, + after the statement came the procedure, after the procedure came the + interface. The next step seems to be the abstract type. +
+ + At + the theoretical level, an abstract type is a type defined by the + specifications of its operations instead of by the representation of + its data. As realized in modern programming languages, a value of + an abstract type is represented by an "object" whose operations are + implemented by a suite of procedure values called the object's + "methods". A new object type can be defined as a subtype of + an existing type, in which case the new type has all the methods of + the old type, and possibly new ones as well (inheritance). The new + type can provide new implementations for the old methods (overriding). +
+ + Objects were invented in the mid-sixties by the farsighted designers + of Simula + [Birtwistle]. + Objects in Modula-3 are very much like + objects in Simula: they are always references, they have both data + fields and methods, and they have single inheritance but not multiple + inheritance. +
+ + Small examples are often used to get across the basic idea: truck as + a subtype of vehicle; rectangle as a subtype of polygon. Modula-3 + aims at larger systems that illustrate how object types provide + structure for large programs. In Modula-3 the main design + effort is concentrated into specifying the properties of a single + abstract type---a stream of characters, a window on the screen. Then + dozens of interfaces and modules are coded that provide useful subtypes + of the central abstraction. The abstract type provides the blueprint + for a whole family of interfaces and modules. If the central + abstraction is well-designed then useful subtypes can be produced + easily, and the original design cost will be repaid with interest. +
+ + The + combination of object types with Modula-2 opaque types produces + something new: the partially opaque type, where some of an + object's fields are visible in a scope and others are hidden. Because + the committee had no experience with partially opaque types, the first + version of Modula-3 restricted them severely; but after a year of + experience it was clear that they were a good thing, and the language + was revised to remove the restrictions. +
+ + It is possible to use object-oriented techniques even in languages + that were not designed to support them, by explicitly allocating the + data records and method suites. This approach works reasonably smoothly + when there are no subtypes; however it is through subtyping that + object-oriented techniques offer the most leverage. The approach works + badly when subtyping is needed: either you allocate the data records + for the different parts of the object individually (which is expensive + and notationally cumbersome) or you must rely on unchecked type + transfers, which is unsafe. Whichever approach is taken, the subtype + relations are all in the programmer's head: only with an object-oriented + language is it possible to get object-oriented static typechecking. +
+ +
Generics
++ + A generic module is a template in which some of the imported interfaces + are regarded as formal parameters, to be bound to actual interfaces + when the generic is instantiated. For example, a generic hash table + module could be instantiated to produce tables of integers, tables + of text strings, or tables of any desired type. The different generic + instances are compiled independently: the source program is reused, + but the compiled code will generally be different for different + instances. +
+ + To keep Modula-3 generics simple, they are confined to the module level: + generic procedures and types do not exist in isolation, and generic + parameters must be entire interfaces. +
+ + In the same spirit of simplicity, there is no separate typechecking + associated with generics. Implementations are expected to expand the + generic and typecheck the result. The alternative would be to invent + a polymorphic type system flexible enough to express the constraints + on the parameter interfaces that are necessary in order for the generic + body to compile. This has been achieved for ML and CLU, but it has + not yet been achieved satisfactorily in the Algol family of languages, + where the type systems are less uniform. (The rules associated with + Ada generics are too complicated for our taste.) +
+ +
Threads
++ + Dividing a computation into concurrent processes (or threads of control) + is a fundamental method of separating concerns. For example, suppose + you are programming a terminal emulator with a blinking cursor: the + most satisfactory way to separate the cursor blinking code from the + rest of the program is to make it a separate thread. Or suppose you + are augmenting a program with a new module that communicates over a + buffered channel. Without threads, the rest of the program will be + blocked whenever the new module blocks on its buffer, and conversely, + the new module will be unable to service the buffer whenever any other + part of the program blocks. If this is unacceptable (as it almost + always is) there is no way to add the new module without finding and + modifying every statement of the program that might block. These + modifications destroy the structure of the program by introducing + undesirable dependencies between what would otherwise be independent + modules. +
+ + The + provisions for threads in Modula-2 are weak, amounting essentially + to coroutines. Hoare's monitors + [Hoare] + are a sounder basis for + concurrent programming. Monitors were used in Mesa, where they worked + well; except that the requirement that a monitored data structure be + an entire module was irksome. For example, it is often useful for + a monitored data structure to be an object instead of a module. Mesa + relaxed this requirement, made a slight change in the details of the + semantics of Hoare's Signal primitive, and introduced the + Broadcast primitive as a convenience + [Lampson]. + The Mesa primitives were simplified in the Modula-2+ design, and the result + was successful enough to be incorporated with no substantial changes + in Modula-3. +
+ + A + threads package is a tool with a very sharp edge. A common + programming error is to access a shared variable without obtaining + the necessary lock. This introduces a race condition that can lie + dormant throughout testing and strike after the program is shipped. + Theoretical work on process algebra has raised hopes that the rendezvous + model of concurrency may be safer than the shared memory model, but + the experience with Ada, which adopted the rendezvous, lends at best + equivocal support for this hope---Ada still allows shared variables, + and apparently they are widely used. +
+ +
Safety
++ + A language feature is unsafe if its misuse can corrupt the runtime + system so that further execution of the program is not faithful to + the language semantics. An example of an unsafe feature is array + assignment without bounds checking: if the index is out of bounds, + then an arbitrary location can be clobbered and the address space can + become fatally corrupted. An error in a safe program can cause the + computation to abort with a run-time error message or to give the wrong + answer, but it can't cause the computation to crash in a rubble of + bits. +
+ + Safe programs can share the same address space, each safe from + corruption by errors in the others. To get similar protection for + unsafe programs requires placing them in separate address spaces. As + large address spaces become available, and programmers use them to + produce tightly-coupled applications, safety becomes more and more + important. +
+ + Unfortunately, it is generally impossible to program the lowest levels of + a system with complete safety. Neither the compiler nor the runtime + system can check the validity of a bus address for an I/O controller, + nor can they limit the ensuing havoc if it is invalid. This presents + the language designer with a dilemma. If he holds out for safety, + then low level code will have to be programmed in another language. + But if he adopts unsafe features, then his safety guarantee becomes + void everywhere. +
+ + The languages of the BCPL family are full of unsafe features; + the languages of the Lisp family generally have none (or none that + are documented). In this area Modula-3 follows the lead of Cedar by + adopting a small number of unsafe features + that are allowed only in + modules explicitly labeled unsafe. In a safe module, the compiler + prevents any errors that could corrupt the runtime system; in an unsafe + module, it is the programmer's responsibility to avoid them. +
+ +
Garbage Collection
++ + A classic unsafe runtime error is to free a data structure that is + still reachable by active references (or "dangling pointers"). The + error plants a time bomb that explodes later, when the storage is + reused. If on the other hand the programmer fails to free records + that have become unreachable, the result will be a "storage leak" + and the computation space will grow without bound. Problems due to + dangling pointers and storage leaks tend to persist long after other + errors have been found and removed. The only sure way to avoid + these problems is the automatic freeing of unreachable storage, or + garbage collection. +
+ + Modula-3 therefore provides "traced references", which are like + Modula-2 pointers except that the storage they point to is kept in + the "traced heap" where it will be freed automatically when all + references to it are gone. +
+ + Another great benefit of garbage collection is that it simplifies + interfaces. Without garbage collection, an interface must specify + whether the client or the implementation has the responsibility for + freeing each allocated reference, and the conditions under which it + is safe to do so. This can swamp the interface in complexity. For + example, Modula-3 supports text strings by a simple required interface + Text, rather than with a built-in type. Without garbage + collection, this approach would not be nearly as attractive. +
+ + New refinements in garbage collection have appeared continually for + more than twenty years, but it is still difficult to implement + efficiently. For many programs, the programming time saved by + simplifying interfaces and eliminating storage leaks and dangling + pointers makes garbage collection a bargain, but the lowest levels + of a system may not be able to afford it. For example, in SRC's Topaz + system, the part of the operating system that manages files and + heavy-weight processes relies on garbage collection, but the inner + "nub" that implements virtual memory and thread context switching + does not. Essentially all Topaz application programs rely on garbage + collection. +
+ + For programs that cannot afford garbage collection, Modula-3 provides + a set of reference types that are not traced by the garbage collector. + In most other respects, traced and untraced references behave + identically. +
+ +
Exceptions
++ + An exception is a control construct that exits many scopes at once. + Raising an exception exits active scopes repeatedly until a handler + is found for the exception, and transfers control to the handler. If + there is no handler, the computation terminates in some system-dependent + way---for example, by entering the debugger. +
+ + There are many arguments for and against exceptions, most of which + revolve around inconclusive issues of style and taste. One argument + in their favor that has the weight of experience behind it is that + exceptions are a good way to handle any runtime error that is usually, + but not necessarily, fatal. If exceptions are not available, each + procedure that might encounter a runtime error must return an additional + code to the caller to identify whether an error has occurred. This + can be clumsy, and has the practical drawback that even careful + programmers may inadvertently omit the test for the error return code. + The frequency with which returned error codes are ignored has become + something of a standing joke in the Unix/C world. Raising an exception + is more robust, since it stops the program unless there is an explicit + handler for it. +
+ +
Type system
++ + Like all languages in the Algol family, Modula-3 is strongly typed. + The basic idea of strong typing is to partition the value space into + types, restrict variables to hold values of a single type, and restrict + operations to apply to operands of fixed types. In actuality, strong + typing is rarely so simple. For example, each of the following + complications is present in at least one language of the Algol family: + a variable of type [0..9] may be safely assigned to an + INTEGER, but not vice-versa (subtyping). Operations like absolute + value may apply both to REALs and to INTEGERs instead of + to a single type (overloading). The types of literals (for example, + NIL) can be ambiguous. The type of an expression may be + determined by how it is used (target-typing). Type mismatches may + cause automatic conversions instead of errors (as when a fractional + real is rounded upon assignment to an integer). +
+ + We adopted several principles in order to make Modula-3's type system + as uniform as possible. First, there are no ambiguous types or + target-typing: the type of every expression is determined by its + subexpressions, not by its use. Second, there are no automatic + conversions. In some cases the representation of a value changes + when it is assigned (for example, when assigning to a packed field + of a record type) but the abstract value itself is transferred without + change. Third, the rules for type compatibility are defined in terms + of a single subtype relation. The subtype relation is required for + treating objects with inheritance, but it is also useful for defining + the type compatibility rules for conventional types. +
+ +
Simplicity
++ + In the early days of the Ada project, a general in the Ada Program + Office opined that "obviously the Department of Defense is not + interested in an artificially simplified language such as Pascal". + Modula-3 represents the opposite point of view. We used every artifice + that we could find or invent to make the language simple. +
+ + C. A. R. Hoare has suggested that as a rule of thumb a language is + too complicated if it can't be described precisely and readably in + fifty pages. The Modula-3 committee elevated this to a design + principle: we gave ourselves a "complexity budget" of fifty pages, + and chose the most useful features that we could accommodate within + this budget. In the end, we were over budget by six lines plus the + syntax equations. This policy is a bit arbitrary, but there are so + many good ideas in programming language design that some kind of + arbitrary budget seems necessary to keep a language from getting too + complicated. +
+ + In retrospect, the features that made the cut were directed toward + two main goals. Interfaces, objects, generics, and threads provide + fundamental patterns of abstraction that help to structure large + programs. The isolation of unsafe code, garbage collection, and + exceptions help make programs safer and more robust. Of the techniques + that we used to keep the language internally consistent, the most + important was the definition of a clean type system based on a subtype + relation. There is no special novelty in any one of these features + individually, but there is simplicity and power in their combination. +
+ +
+ Last modified on Wed Apr 3 09:24:01 PST 1996 by heydon + modified on Fri May 27 11:16:25 PDT 1994 by kalsow +
+ + Index: m3/pm3/language/modula3/src/m3defn/lock.html diff -c /dev/null m3/pm3/language/modula3/src/m3defn/lock.html:1.2 *** /dev/null Tue Feb 10 23:31:56 1998 --- m3/pm3/language/modula3/src/m3defn/lock.html Tue Feb 10 22:59:16 1998 *************** *** 0 **** --- 1,30 ---- + + +Modula-3: Lock statements + + + +Lock
++ + A LOCK statement has the form: +
+ LOCK mu DO S END +
+where S is a statement and mu is an expression. + It is equivalent to: +
+ WITH m = mu DO + Thread.Acquire(m); + TRY S FINALLY Thread.Release(m) END + END +
+where m stands for a variable that does not occur in S. +
+ +
+ Last modified on Wed Apr 3 09:39:03 PST 1996 by heydon + modified on Mon Apr 18 14:04:17 PDT 1994 by kalsow +
+ + Index: m3/pm3/language/modula3/src/m3defn/loop.html diff -c /dev/null m3/pm3/language/modula3/src/m3defn/loop.html:1.2 *** /dev/null Tue Feb 10 23:31:56 1998 --- m3/pm3/language/modula3/src/m3defn/loop.html Tue Feb 10 22:59:16 1998 *************** *** 0 **** --- 1,25 ---- + + +Modula-3: Loop statements + + + +Loop
++ + A statement of the form: +
+ LOOP S END +
+repeatedly executes S until it raises the exit-exception. + Informally it is like: +
+ TRY S; S; S; ... EXCEPT exit-exception => (*skip*) END +
+ ++ Last modified on Wed Apr 3 09:39:51 PST 1996 by heydon + modified on Mon Apr 18 14:04:28 PDT 1994 by kalsow +
+ + Index: m3/pm3/language/modula3/src/m3defn/m3.html diff -c /dev/null m3/pm3/language/modula3/src/m3defn/m3.html:1.2 *** /dev/null Tue Feb 10 23:31:56 1998 --- m3/pm3/language/modula3/src/m3defn/m3.html Tue Feb 10 22:59:16 1998 *************** *** 0 **** --- 1,50 ---- + + +Modula-3: Language definition + + + +Modula-3: Language definition
++ +
+ The language designer should be familiar with many alternative + features designed by others, and should have excellent judgment in + choosing the best and rejecting any that are mutually inconsistent... + One thing he should not do is to include untried ideas of his own. + His task is consolidation, not innovation. + ---C.A.R. Hoare +
+ + The original definition of Modula-3 was given in + SRC Research Report 31, + August 1988. + It was revised in + report 52, + November 1989. + And finally published in + Systems Programming with Modula-3, November 1989. + This edition of the language definition is derived from all of the above. + +
-
+
- Introduction +
- Definitions +
- Types +
- Statements +
- Declarations +
- Modules and interfaces +
- Expressions +
- Unsafe operations +
- Required interfaces +
- Syntax +
- Acknowledgments +
- About the authors +
- Index +
+ Last modified on Tue Dec 5 09:47:57 PST 1995 by heydon + modified on Wed Apr 27 11:43:11 PDT 1994 by kalsow +
+ + Index: m3/pm3/language/modula3/src/m3defn/m3index.html diff -c /dev/null m3/pm3/language/modula3/src/m3defn/m3index.html:1.1.1.1 *** /dev/null Tue Feb 10 23:31:56 1998 --- m3/pm3/language/modula3/src/m3defn/m3index.html Sat Jan 31 14:47:13 1998 *************** *** 0 **** --- 1,490 ---- + + +Modula-3: language definition: index + + + +Index
++ +
+ # operator, * + & operator, * + (* *) (comment), * + * operator, * + + operator, * + - operator, * + . operator, * + .. in set and array constructors, * * + / operator, * + <* *> (pragma), * + <: declaration, * * + = operator, * + ^ operator, * +
+ +A
+ +
+ ABS, * + abstract type, * + Ada programming language, * * * + addition, * + ADDRESS, * + ADDRESS, assignment of, * * + ADR, * + ADRSIZE, * + aggregate, see records or arrays + Algol programming language, * + aliasing, of VAR parameters, * + alignment, see packed types + allocated type, * + allocation, * + AND, * + arithmetic operations, * + arrays, * + arrays, assigning, * * * * * * * * * * + ASCII, see ISO-Latin-1 + assignable, * + assignable, READONLY/VALUE formals, * * * * * * * * * * + assignment statements, * + automatic dereferencing, * +
+ +B
+ +
+ B programming language, * + backslash, in literals, * + base type, * + BCPL programming language, * + binding power, of operators, * + bindings, in procedure call, * + bit operations, * + BITS FOR, * * * * + BITSIZE, * + Bliss programming language, * + block, * + block, module, * * * + body, of procedure, * + BOOLEAN, * + BOOLEAN, operations on, * + BRANDED, * + BYTESIZE, * +
+ +C
+ +
+ C programming language, * + C++ programming language, * + call, procedure, * + CARDINAL, * + carriage return, in literals, * + CASE statement, * + case, in keywords, * * + Cedar programming language, * + CEILING, * + CHAR, * + character literals, * * + checked runtime error, * * * * * * * * * * * * * * * * * * * + circularities, in imports lists, * * + CLU programming language, * + coercions, checked, * * + comments, * + comments, tokenizing, * + comparison operation, * + complete revelation, * + concatenating texts, * + concrete types, * + constant expression, * * + constants, * + constants, declarations, * * * + constructors, array, * * * + contain (value in type), * + conversion, enumerations and integers, * * + covers, for procedure signatures, * + cyclic imports, * +
+ +D
+ +
+ dangling pointer, * + data record, of object, * + deallocation, * + DEC, * + DEC, on addresses (unsafe), * + declaration, * + declaration, recursive, * * + default values, in record fields, * * * + delimiters, complete list, * + dereferencing, * + designators, * + designators, operators allowed in, * * * + dimension, * + DISPOSE, * + DIV, * + division by zero, * + division, real, * + double quote, in literals, * +
+ +E
+ +
+ element type, of array, * + empty type, * + enumerations, * + enumerations, first and last elements, * * * * + environment, of procedure, * + equality operator, * + errors, static and runtime, * + escape sequences, in literals, * + EVAL, * + example, pathological, * * + exceptions, * * + exceptions, RAISE, * * * * * * + EXIT, * + exit-exception, * * * + expanded definition (of type), * + exporting an interface, * + EXPORTS clause, * + expression, * * + expression, constant, * * * + EXTENDED, * + EXTENDED, literals, * + EXTERNAL, * +
+ +F
+ +
+ FALSE, * + field selection, records/objects, * + fields, of record, * + FIRST, * + fixed arrays, * * * + FLOAT, * + floating point numbers, * + floating-point interfaces, * + FLOOR, * + Fmt interface, * + FOR statement, * + fork (of a thread), * + form feed, in literals, * + formatting data as texts, * + FROM ... IMPORT, * + function procedures, * * * +
+ +G
+ +
+ garbage collection, * * + generic interface, * * * + generics, * * +
+ +H
+ +
+ handlers, for exceptions, * + hash tables, see Table interface * + hexadecimal literal, * +
+ +I
+ +
+ identifiers, * + identifiers, lexical structure, * * * * * + IF, * + import cycle, * + imports, * + IN (a set), * + INC, * * + index type, of array, * + inheritance, * + initialization, during allocation, * * * * + INLINE, * + INTEGER, * + interfaces, * * + interfaces, exporting, * * * * + intersection, set, * + intrinsically safe, * + ISO-Latin-1, * + ISTYPE, * +
+ +J
+ +
+ join (of a thread), * +
+ +K
+ +
+ keyword binding, * + keywords, complete list, * +
+ +L
+ +
+ LAST, * + Lisp programming language, * + literals, character, * * * * + local procedures, * * * + location, * + LOCK statement, * + LONGREAL, * + LONGREAL, literals, * + LOOP, * + LOOPHOLE, * +
+ +M
+ +
+ main module, * + masked field, * + MAX, * + member (value in type), * + Mesa programming language, * + method suite, * + methods, * + methods, declaring, * * * * + MIN, * + ML programming language, * + MOD, * + mode, see parameter mode + Modula-2 programming language, * + Modula-3 Abstract Syntax Trees, * + modules, * * + modules, initialization, * * + monitor, * + multi-dimensional arrays, * + multiplication, * + MUTEX, * * +
+ +N
+ +
+ NARROW, * + NEW, * + newline, in literals, * + NIL, * + normal outcome, * + NOT, * + NULL, * + NUMBER, * + numbers, literal, * +
+ +O
+ +
+ Oberon programming language, * + objects, * * + objects, accessing fields and methods, * * * * * * * * * + octal literal, * + opaque types, * + open arrays, * * * * * + operators, complete list, * * * + OR, * + ORD, * + order (<, >, ...), * * + ordinal types, * * * * + overflow, * + overloading, of operation, * + overriding, * * +
+ +P
+ +
+ package, see module + packed types, * * + parameter mode, * * + partial expansion (of type), * * * + partially opaque type, * * + Pascal programming language, * + persistent storage, see Pkl interface * + Pkl (pickle) interface, * + pointer, see reference + positional binding, * + pragmas, * + precedence, of operators, * + procedural operator, * + procedure call, * + procedures, * + procedures, RETURN, * * * * * * * * * * * * * + process algebra, * + process, see thread + program, definition of, * + proper procedure, * +
+ +Q
+ +
+ qualified identifier, * +
+ +R
+ +
+ RAISE, * + RAISES, * + raises set, of procedure, * + RAISES, dangling, * * + readonly designator, * * + READONLY parameters, * + REAL, * + real division, * + REAL, conversions to, * * * + records, * + records, constructors for, * * * + recursive declarations, * + REFANY, * + reference class, * + references, * + references, TYPECASE, * * * * * * * * + referent, * * + reflexive relation, * + relational operators, * + remainder, see MOD + REPEAT statement, * + required interfaces, * + result type, of procedure, * + RETURN, * + return-exception, * * + REVEAL, * + revelations, * + revelations, imported, * + ROOT, * + ROUND, * + rounding of arithmetic operations, * + runtime error, * +
+ +S
+ +
+ safety, * * + scale factors, in numeric literals, * + scope, * + scope, block statement, * * * * * * * * * * * + selection of fields, * + sequential composition, * + sets, * + sets, IN operator, * * * * * * * * + shape, of array, * + shared variables, * + sign inversion, * + signature, * * + signature, covers, * + single quote, in literals, * + size, of type, * + Smalltalk programming language, * + statements, * + static error, * * + storage allocation, * * * + strings, * + strings, see texts * + structural equivalence, * + SUBARRAY, * + subranges, * + subranges, subtyping rules, * + subscript operator, * + subset operation, * + subtraction, * + subtype relation, * + supertype (subtyping relation), * + symmetric set difference, * + syntax, * +
+ +T
+ +
+ tab, in literals, * + Table interface, * + task, see thread + termination of program, * + TEXT, * + Text interface, * + texts, * + texts, concatenating, * * * + Thread creation, * + threads, * + tokenizing, * + top-level procedure, * + Topaz system, * + traced, object types, * * * + transitive relation, * + TRUE, * + TRUNC, * + TRY EXCEPT, * * + type, * * * * * + type, assignable, * * * * * * * * + TYPECASE, * + TYPECODE, * +
+ +U
+ +
+ unchecked runtime errors, * * + undefined procedure, * + underflow, * + union, of sets, * + UNSAFE, * + unsafe features, * + unsigned integers, * * + UNTRACED ROOT, * + UNTRACED, in reference declarations, * * +
+ +V
+ +
+ VAL, * + value, * + VALUE parameters, * * + VAR declarations, * * * + variables, * * + variables, initialization, * * * + variant records, * + visibility, see scope +
+ +W
+ +
+ WHILE statement, * + WITH statement, * + Word interface, * + word size, of type, * + writable designator, * * +
+ +X
+ +
Y
+ +
Z
+ +
+ zero, division by, * +
+ ++ Last modified on Wed Apr 3 09:39:04 PST 1996 by heydon + modified on Mon Apr 18 14:48:58 PDT 1994 by kalsow +
+ + Index: m3/pm3/language/modula3/src/m3defn/m3makefile diff -c /dev/null m3/pm3/language/modula3/src/m3defn/m3makefile:1.1.1.1 *** /dev/null Tue Feb 10 23:31:56 1998 --- m3/pm3/language/modula3/src/m3defn/m3makefile Sat Jan 31 14:47:13 1998 *************** *** 0 **** --- 1,81 ---- + HtmlFile("acks") + HtmlFile("apply") + HtmlFile("arithmetic") + HtmlFile("arrays") + HtmlFile("assign") + HtmlFile("authors") + HtmlFile("block") + HtmlFile("boolops") + HtmlFile("builtin") + HtmlFile("calls") + HtmlFile("case") + HtmlFile("constants") + HtmlFile("constexpr") + HtmlFile("construct") + HtmlFile("conventions") + HtmlFile("decls") + HtmlFile("defns") + HtmlFile("designators") + HtmlFile("eval") + HtmlFile("example") + HtmlFile("exceptions") + HtmlFile("exit") + HtmlFile("exprs") + HtmlFile("float-intf") + HtmlFile("floatmode") + HtmlFile("floats") + HtmlFile("for") + HtmlFile("generics") + HtmlFile("if") + HtmlFile("imports") + HtmlFile("incdec") + HtmlFile("init") + HtmlFile("interfaces") + HtmlFile("intfs") + HtmlFile("intro") + HtmlFile("lock") + HtmlFile("loop") + HtmlFile("m3") + HtmlFile("m3index") + HtmlFile("modules") + HtmlFile("new") + HtmlFile("nil") + HtmlFile("numbers") + HtmlFile("objects") + HtmlFile("opaques") + HtmlFile("opsyntax") + HtmlFile("ordinal") + HtmlFile("packed") + HtmlFile("procedures") + HtmlFile("procs") + HtmlFile("raise") + HtmlFile("real-intf") + HtmlFile("records") + HtmlFile("recursion") + HtmlFile("refs") + HtmlFile("relations") + HtmlFile("repeat") + HtmlFile("return") + HtmlFile("revelations") + HtmlFile("safety") + HtmlFile("sequence") + HtmlFile("sets") + HtmlFile("stmts") + HtmlFile("subtypes") + HtmlFile("syntax") + HtmlFile("text-intf") + HtmlFile("textops") + HtmlFile("texts") + HtmlFile("thread-intf") + HtmlFile("tryexcept") + HtmlFile("tryfinally") + HtmlFile("type-decl") + HtmlFile("typecase") + HtmlFile("typeops") + HtmlFile("types") + HtmlFile("units") + HtmlFile("unsafe") + HtmlFile("variables") + HtmlFile("while") + HtmlFile("with") + HtmlFile("word-intf") Index: m3/pm3/language/modula3/src/m3defn/modules.html diff -c /dev/null m3/pm3/language/modula3/src/m3defn/modules.html:1.2 *** /dev/null Tue Feb 10 23:31:56 1998 --- m3/pm3/language/modula3/src/m3defn/modules.html Tue Feb 10 22:59:16 1998 *************** *** 0 **** --- 1,94 ---- + + +Modula-3: Modules + + + +Modules
++ + A module has the form: +
+ MODULE id EXPORTS Interfaces; + Imports; + Block id. +
+where id is an identifier that names the module, Interfaces + is a list of distinct names of interfaces exported by the module, + Imports is a list of import statements, and Block is + a block, the body of the module. The name id must be + repeated after the END that terminates the body. + "EXPORTS Interfaces" can be omitted, + in which case Interfaces defaults + to id. +
+ + If + module M exports interface I, then all declared names + in I are visible without qualification in M. Any + procedure declared in I can be redeclared in M, with + a body. The signature in M must be + covered by the signature + in I. + To determine the interpretation of keyword + bindings and parameter defaults in calls to the procedure, the + signature in M is used within M; the signature in + I is used everywhere else. +
+ + Except for the redeclaration of exported procedures, the names declared + at the top level of Block, the visible imported names, and + the names declared in the exported interfaces must be distinct. +
+ + For example, the following is illegal, since two names in exported + interfaces coincide: +
+ INTERFACE I; + PROCEDURE X(); ... + + INTERFACE J; + PROCEDURE X(); ... + + MODULE M EXPORTS I, J; + PROCEDURE X() = ...; +
++ + The following is also illegal, since the visible imported name + X coincides with the top-level name X: +
+ INTERFACE I; + PROCEDURE X(); ... + + MODULE M EXPORTS I; + FROM I IMPORT X; + PROCEDURE X() = ...; +
++ + But + the following is legal, although peculiar: +
+ INTERFACE I; + PROCEDURE X(...); ... + + MODULE M EXPORTS I; + IMPORT I; + PROCEDURE X(...) = ...; +
++ + since the only visible imported name is I, and the coincidence + between X as a top-level name and X as a name in an + exported interface is allowed, assuming the interface signature covers + the module signature. Within M, the interface declaration + determines the signature of I.X and the module declaration + determines the signature of X. + +
+ Last modified on Wed Apr 3 09:39:03 PST 1996 by heydon + modified on Mon Apr 18 14:04:34 PDT 1994 by kalsow +
+ + Index: m3/pm3/language/modula3/src/m3defn/new.html diff -c /dev/null m3/pm3/language/modula3/src/m3defn/new.html:1.2 *** /dev/null Tue Feb 10 23:31:56 1998 --- m3/pm3/language/modula3/src/m3defn/new.html Tue Feb 10 22:59:16 1998 *************** *** 0 **** --- 1,82 ---- + + +Modula-3: New + + + +New
++ + An allocation operation has the form: +
+ NEW(T, ...) +
+where T is a reference type other than REFANY, + ADDRESS, or NULL. The operation returns the address of a + newly-allocated variable of T's referent type; or if T + is an object type, a newly-allocated data record paired with a method + suite. The reference returned by NEW is distinct from all + existing references. The allocated type of the new reference is T. +
+ + It is a static error if T's referent type is empty. + If T is declared as an opaque type, + NEW(T) is legal only in scopes + where T's concrete type is known completely, + or is known to be an object type. +
+ + The initial state of the referent generally represents an arbitrary + value of its type. If T is an object type or a reference to + a record or open array then NEW takes additional arguments + to control the initial state of the new variable. +
+ + If + T is a reference to an array with k open dimensions, the + NEW operation has the form: +
+ NEW(T, n_1, ..., n_k) +
+where the n's are integer-valued expressions that specify the + lengths of the new array in its first k dimensions. The values in + the array will be arbitrary values of their type. +
+ + If + T is an object type or a reference to a record, the NEW + operation has the form: +
+ NEW(T, Bindings) +
+where Bindings is a list of keyword bindings used to initialize + the new fields. Positional bindings are not allowed. +
+ + Each binding f := v initializes the field f to the value + v. Fields for which no binding is supplied will be initialized + to their + defaults + if they have defaults; otherwise they will be + initialized to arbitrary values of their types. +
+ + The order of the field bindings makes no difference. +
+ + If T is an object type then Bindings can also include + method overrides of the form m := P, where m is a method + of T and P is a top-level procedure constant. This is + syntactic sugar for the allocation of a subtype of T that includes + the given overrides, in the given order. + For example, NEW(T, m := P) is sugar for +
+ NEW(T OBJECT OVERRIDES m := P END). +
+ ++ Last modified on Wed Apr 3 09:39:02 PST 1996 by heydon + modified on Mon Apr 18 14:04:40 PDT 1994 by kalsow +
+ + Index: m3/pm3/language/modula3/src/m3defn/nil.html diff -c /dev/null m3/pm3/language/modula3/src/m3defn/nil.html:1.1.1.1 *** /dev/null Tue Feb 10 23:31:56 1998 --- m3/pm3/language/modula3/src/m3defn/nil.html Sat Jan 31 14:47:13 1998 *************** *** 0 **** --- 1,19 ---- + + +Modula-3: Nil + + + +Nil
++ + The literal "NIL" denotes the value NIL. + Its type is NULL. +
+ +
+ Last modified on Wed Apr 3 09:39:02 PST 1996 by heydon + modified on Mon Apr 18 14:04:47 PDT 1994 by kalsow +
+ + Index: m3/pm3/language/modula3/src/m3defn/numbers.html diff -c /dev/null m3/pm3/language/modula3/src/m3defn/numbers.html:1.1.1.1 *** /dev/null Tue Feb 10 23:31:56 1998 --- m3/pm3/language/modula3/src/m3defn/numbers.html Sat Jan 31 14:47:13 1998 *************** *** 0 **** --- 1,70 ---- + + +Modula-3: Numeric literals + + + +Numeric literals
++ + Numeric literals denote constant non-negative integers or reals. + The types of these literals are INTEGER, REAL, + LONGREAL, and EXTENDED. +
+ + A literal INTEGER has the form base_digits, + where base + is one of "2", "3", ..., "16", and digits + is a non-empty sequence of the decimal digits 0 through + 9 plus the hexadecimal digits A through F. + The "base_" can be omitted, + in which case base defaults to 10. + The digits are interpreted in the given base. + Each digit must be less than base. + For example, 16_FF and 255 + are equivalent integer literals. +
+ + If no explicit base is present, the value of the literal must be at + most LAST(INTEGER). If an explicit base is present, the value + of the literal must be less than 2^Word.Size, + and its interpretation uses the convention of the + Word interface. + For example, on a sixteen-bit two's complement machine, + 16_FFFF and -1 represent the same value. +
+ + A + literal REAL has the form decimal E exponent, where + decimal is a non-empty sequence of decimal digits followed + by a decimal point followed by a non-empty sequence of decimal digits, and + exponent is a non-empty sequence of decimal digits optionally + beginning with a + or -. + The literal denotes decimal + times 10^exponent. + If "E exponent" is omitted, + exponent defaults to 0. +
+ + LONGREAL and EXTENDED + literals are like REAL literals, + but instead of E they use D and X respectively. +
+ + Case + is not significant in digits, prefixes or scale factors. Embedded + spaces are not allowed. +
+ + For example, 1.0 and 0.5 are valid, 1. + and .5 are not; + 6.624E-27 is a REAL, + and 3.1415926535d0 a LONGREAL. +
+ +
+ Last modified on Wed Apr 3 09:39:02 PST 1996 by heydon + modified on Mon Apr 18 14:04:55 PDT 1994 by kalsow +
+ + Index: m3/pm3/language/modula3/src/m3defn/objects.html diff -c /dev/null m3/pm3/language/modula3/src/m3defn/objects.html:1.2 *** /dev/null Tue Feb 10 23:31:56 1998 --- m3/pm3/language/modula3/src/m3defn/objects.html Tue Feb 10 22:59:17 1998 *************** *** 0 **** --- 1,244 ---- + + +Modula-3: Object types + + + +Object types
++ + An object is either NIL or a reference to a data + record paired with a method suite, which is a record of procedures that will + accept the object as a first argument. +
+ + An object type determines the types of a prefix of the fields of the + data record, as if "OBJECT" were "REF RECORD". But + in the case of an object type, the data record can contain additional fields + introduced by subtypes of the object type. Similarly, the object type + determines a prefix of the method suite, but the suite can contain + additional methods introduced by subtypes. +
+ + If + o is an object, then o.f designates the data field named + f in o's data record. + If m is one of o's methods, + an invocation of the form + o.m( ... ) + denotes an execution of o's m method. + An object's methods can be invoked, but not read or written. +
+ + If T is an object type and m is the name of one of + T's methods, then T.m denotes T's m method. + This notation makes it convenient for a subtype method to invoke + the corresponding method of one of its supertypes. +
+ + A + field or method in a subtype masks any field or method with the + same name in the supertype. To access such a masked field, use + NARROW to view the subtype variable as a member of the supertype, + as illustrated below. +
+ + Object assignment is reference assignment. Objects cannot be + dereferenced, since the static type of an object variable does not determine + the type of its data record. To copy the data record of one object + into another, the fields must be assigned individually. +
+ + There + are two predeclared object types: +
+ ROOT The traced object type with no fields or methods + UNTRACED ROOT The untraced object type with no fields or methods +
++ + The + declaration of an object type has the form: +
+ TYPE T = ST OBJECT + Fields + METHODS + Methods + OVERRIDES + Overrides + END +
+where ST is an optional supertype, Fields is a list of + field declarations, exactly as in a record type, Methods is a + list of method declarations and Overrides is a list of + method overrides. The fields of T consist of the fields + of ST followed by the fields declared in Fields. + The methods of T consist of the methods of ST modified by + Overrides and followed by the methods declared in Methods. + T has the same reference class as ST. +
+ + The names introduced in Fields and Methods must be distinct + from one another and from the names overridden in Overrides. + If ST is omitted, it defaults to ROOT. If ST is + untraced, then the fields must not include traced types. + (This restriction is lifted in unsafe modules.) + If ST is declared as an + opaque type, + the declaration of T is legal only in scopes where + ST's concrete type is known to be an object type. +
+ + The + keyword OBJECT can optionally be preceded by "BRANDED" + or by "BRANDED b", where b is a text constant. The meaning + is the same as in non-object reference types. +
+ + A + method declaration has the form: +
+ m sig := proc +
+where m is an identifier, sig is a procedure signature, + and proc is a top-level procedure constant. It specifies that + T's m method has signature sig + and value proc. + If ":= proc" is omitted, ":= NIL" is assumed. + If proc is non-nil, its first parameter must have mode + VALUE and + type some supertype of T, and dropping its first parameter must + result in a signature that is covered by sig. +
+ + A + method override has the form: +
+ m := proc +
+where m is the name of a method of the supertype ST and + proc is a top-level procedure constant. It specifies that the + m method for T is proc, rather than ST.m. + If proc is non-nil, + its first parameter must have mode VALUE and type some supertype + of T, and dropping its first parameter must result in a signature + that is covered by the signature of ST's m method. +
+ + Examples. Consider the following declarations: +
+ TYPE + A = OBJECT a: INTEGER; METHODS p() END; + AB = A OBJECT b: INTEGER END; + + PROCEDURE Pa(self: A) = ... ; + PROCEDURE Pab(self: AB) = ... ; +
+The procedures Pa and Pab are candidate values for + the p + methods of objects of types A and AB. For example: +
+ TYPE T1 = AB OBJECT OVERRIDES p := Pab END +
+declares a type with an AB data record and a p method + that expects an AB. + T1 is a valid subtype of AB. Similarly, +
+ TYPE T2 = A OBJECT OVERRIDES p := Pa END +
+declares a type with an A data record and a method that expects + an A. T2 is a valid subtype of A. A more + interesting example is: +
+ TYPE T3 = AB OBJECT OVERRIDES p := Pa END +
+which declares a type with an AB data record and a p method + that expects an A. Since every AB is an A, + the method is not too choosy for the objects in which it will be placed. + T3 is a valid subtype of AB. In contrast, +
+ TYPE T4 = A OBJECT OVERRIDES p := Pab END +
+attempts to declare a type with an A data record and a method + that expects an AB; since not every A is an AB, + the method is too choosy for the objects in which it would + be placed. The declaration of T4 is a static error. +
+ + The following example illustrates the difference between declaring + a new method and overriding an existing method. + After the declarations +
+ TYPE + A = OBJECT METHODS m() := P END; + B = A OBJECT OVERRIDES m := Q END; + C = A OBJECT METHODS m() := Q END; + + VAR + a := NEW(A); b := NEW(B); c := NEW(C); +
+we have that +
+ a.m() activates P(a) + b.m() activates Q(b) + c.m() activates Q(c) +
+So far there is no difference between overriding and extending. But + c's method suite has two methods, while b's has only one, + as can be revealed if b and c are viewed as members of + type A: +
+ NARROW(b, A).m() activates Q(b) + NARROW(c, A).m() activates P(c) +
+Here NARROW is used to view a variable of a subtype as a value + of its supertype. + It is more often used for the opposite purpose, when it requires a + runtime check. +
+ + The last example uses object subtyping to define reusable queues. First + the interface: +
+ TYPE + Queue = RECORD head, tail: QueueElem END; + QueueElem = OBJECT link: QueueElem END; + + PROCEDURE Insert (VAR q: Queue; x: QueueElem); + PROCEDURE Delete (VAR q: Queue): QueueElem; + PROCEDURE Clear (VAR q: Queue); +
++ + Then an example client: +
+ TYPE + IntQueueElem = QueueElem OBJECT val: INTEGER END; + VAR + q: Queue; + x: IntQueueElem; + ... + Clear(q); + x := NEW(IntQueueElem, val := 6); + Insert(q, x); + ... + x := Delete(q) +
++ + Passing x to Insert is safe, + since every IntQueueElem is a QueueElem. + Assigning the result of Delete to x cannot be + guaranteed valid at compile-time, since other subtypes + of QueueElem can be inserted into q, but the assignment + will produce a checked runtime error if the source value is not a member + of the target type. Thus IntQueueElem bears the same relation + to QueueElem as [0..9] bears to INTEGER. +
+ +
+ Last modified on Wed Apr 3 09:39:02 PST 1996 by heydon + modified on Thu Sep 15 10:44:33 PDT 1994 by kalsow +
+ + Index: m3/pm3/language/modula3/src/m3defn/opaques.html diff -c /dev/null m3/pm3/language/modula3/src/m3defn/opaques.html:1.2 *** /dev/null Tue Feb 10 23:31:56 1998 --- m3/pm3/language/modula3/src/m3defn/opaques.html Tue Feb 10 22:59:17 1998 *************** *** 0 **** --- 1,37 ---- + + +Modula-3: Opaque type declarations + + + +Opaque types
++ + An opaque type is a name that denotes an unknown subtype of some + given reference type. For example, an opaque subtype of REFANY is + an unknown traced reference type; an opaque subtype of + UNTRACED ROOT + is an unknown untraced object type. The actual type denoted by an + opaque type name is called its concrete type. +
+ + Different scopes can reveal different information about an opaque type. + For example, what is known in one scope only to be a subtype of REFANY + could be known in another scope to be a subtype of ROOT. +
+ + An opaque type declaration has the form: +
+ TYPE T <: U +
+where T is an identifier and U an expression denoting a + reference type. It introduces the name T as an opaque type and + reveals that U is a supertype of T. The concrete type of + T must be revealed elsewhere in the program. + +
+ Last modified on Wed Apr 3 09:39:01 PST 1996 by heydon + modified on Mon Apr 18 14:05:14 PDT 1994 by kalsow +
+ + Index: m3/pm3/language/modula3/src/m3defn/opsyntax.html diff -c /dev/null m3/pm3/language/modula3/src/m3defn/opsyntax.html:1.2 *** /dev/null Tue Feb 10 23:31:56 1998 --- m3/pm3/language/modula3/src/m3defn/opsyntax.html Tue Feb 10 22:59:17 1998 *************** *** 0 **** --- 1,54 ---- + + +Modula-3: Operation syntax + + + +Operation syntax
++ + The operators that have special syntax are classified and listed in order of + decreasing binding power in the following table: +
+ x.a infix dot + f(x) a[i] T{x} applicative (, [, { + p^ postfix ^ + + - prefix arithmetics + * / DIV MOD infix arithmetics + + - & infix arithmetics + = # < <= >= > IN infix relations + NOT prefix NOT + AND infix AND + OR infix OR +++ + All infix operators are left associative. Parentheses can be used + to override the precedence rules. Here are some examples of expressions + together with their fully parenthesized forms: +
+ M.F(x) (M.F)(x) dot before application + Q(x)^ (Q(x))^ application before ^ + - p^ - (p^) ^ before prefix - + - a * b (- a) * b prefix - before * + a * b - c (a * b) - c * before infix - + x IN s - t x IN (s - t) infix - before IN + NOT x IN s NOT (x IN s) IN before NOT + NOT p AND q (NOT p) AND q NOT before AND + A OR B AND C A OR (B AND C) AND before OR +
++ + Operators + without special syntax are procedural. An application + of a procedural operator has the form op(args), + where op is the operation + and args is the list of argument expressions. For example, + MAX and MIN are procedural operators. + +
+ Last modified on Wed Apr 3 09:39:01 PST 1996 by heydon + modified on Fri Apr 15 15:29:56 PDT 1994 by kalsow +
+ + Index: m3/pm3/language/modula3/src/m3defn/ordinal.html diff -c /dev/null m3/pm3/language/modula3/src/m3defn/ordinal.html:1.2 *** /dev/null Tue Feb 10 23:31:56 1998 --- m3/pm3/language/modula3/src/m3defn/ordinal.html Tue Feb 10 22:59:17 1998 *************** *** 0 **** --- 1,93 ---- + + +Modula-3: Ordinal types + + + +Ordinal types
++ + There are three kinds of ordinal types: enumerations, subranges, + and INTEGER. An enumeration type is declared like this: +
+ TYPE T = {id_1, id_2, ..., id_n} ++where the id's are distinct identifiers. The type T is an + ordered set of n values; the expression T.id_i denotes + the $'th value of the type in increasing order. The empty enumeration + { } is allowed. +
+ + Integers + and enumeration elements are collectively called ordinal values. + The base type of an ordinal value v is + INTEGER if v is an integer, otherwise it is the unique + enumeration type that contains v. +
+ + A + subrange type is declared like this: +
+ TYPE T = [Lo..Hi] +
+where Lo and Hi are two ordinal values with the same + base type, called the base type of the subrange. The values of T + are all the values from Lo to Hi inclusive. + Lo and Hi must be + constant expressions. + If Lo exceeds Hi, the subrange is empty. +
+ + The operators + ORD and VAL + convert between enumerations and integers. + The operators + FIRST, LAST, + and + NUMBER + applied to an ordinal type return the first element, last element, + and number of elements, respectively. +
+ + Here are the predeclared ordinal types: +
+ INTEGER All integers represented by the implementation + CARDINAL Behaves just like the subrange [0..LAST(INTEGER)] + BOOLEAN The enumeration {FALSE, TRUE} + CHAR An enumeration containing at least 256 elements ++The first 256 elements of type CHAR represent characters in the + ISO-Latin-1 code, which is an extension of ASCII. The language does + not specify the names of the elements of the CHAR enumeration. + The syntax for character literals is specified in the section on + literals. + FALSE and TRUE are predeclared + synonyms for BOOLEAN.FALSE and BOOLEAN.TRUE. +
+ + Each distinct enumeration type introduces a new collection of values, + but a subrange type reuses the values from the underlying type. For + example: +
+ TYPE + T1 = {A, B, C}; + T2 = {A, B, C}; + U1 = [T1.A..T1.C]; + U2 = [T1.A..T2.C]; (* sic *) + V = {A, B} ++T1 and T2 are the same type, since they have the same + expanded definition. In particular, T1.C = T2.C and therefore + U1 and U2 are also the same type. But the types T1 + and U1 are distinct, although they contain the same values, + because the expanded definition of T1 is an enumeration while the + expanded definition of U1 is a subrange. + The type V is a third type whose values V.A and V.B + are not related to the values T1.A and T1.B. + +
+ Last modified on Wed Apr 3 09:39:00 PST 1996 by heydon + modified on Mon Apr 18 15:32:23 PDT 1994 by kalsow +
+ + Index: m3/pm3/language/modula3/src/m3defn/packed.html diff -c /dev/null m3/pm3/language/modula3/src/m3defn/packed.html:1.2 *** /dev/null Tue Feb 10 23:31:56 1998 --- m3/pm3/language/modula3/src/m3defn/packed.html Tue Feb 10 22:59:17 1998 *************** *** 0 **** --- 1,36 ---- + + +Modula-3: Packed types + + + +Packed types
++ + A declaration of a packed type has the form: +
+ TYPE T = BITS n FOR Base +
+where Base is a type and n is an integer-valued constant + expression. The values of type T are the same as the values + of type Base, but variables of type T that occur in + records, objects, or arrays will occupy exactly n bits and + be packed adjacent to the preceding field or element. For example, + a variable of type +
+ ARRAY [0..255] OF BITS 1 FOR BOOLEAN +
+is an array of 256 booleans, each of which occupies one bit of storage. +
+ + The values allowed for n are implementation-dependent. An + illegal value for n is a static error. The legality of a packed + type can depend on its context; for example, an implementation could + prohibit packed integers from spanning word boundaries. + +
+ Last modified on Wed Apr 3 09:39:01 PST 1996 by heydon + modified on Mon Apr 18 14:05:35 PDT 1994 by kalsow +
+ + Index: m3/pm3/language/modula3/src/m3defn/procedures.html diff -c /dev/null m3/pm3/language/modula3/src/m3defn/procedures.html:1.2 *** /dev/null Tue Feb 10 23:31:56 1998 --- m3/pm3/language/modula3/src/m3defn/procedures.html Tue Feb 10 22:59:17 1998 *************** *** 0 **** --- 1,42 ---- + + +Modula-3: Procedure declarations + + + +Procedures
++ + There are two forms of procedure declaration: +
+ PROCEDURE id sig = B id + + PROCEDURE id sig +
+where + id is an identifier, sig is a procedure signature, and + B is a block. In both cases, the type of id is the procedure + type determined by sig. The first form is allowed only in + modules; the second form is allowed only in interfaces. +
+ + The + first form declares id as a procedure constant whose signature + is sig, whose body is B, and whose environment is the scope + containing the declaration. The parameter names are treated as if + they were declared at the outer level of B; the parameter types + and default values are evaluated in the scope containing the procedure + declaration. The procedure name id must be repeated after the + END that terminates the body. +
+ + The second form declares id to be a procedure constant whose + signature is sig. The procedure body is specified in a module + exporting the interface, by a declaration of the first form. + +
+ Last modified on Wed Apr 3 09:39:00 PST 1996 by heydon + modified on Mon Apr 18 14:05:44 PDT 1994 by kalsow +
+ + Index: m3/pm3/language/modula3/src/m3defn/procs.html diff -c /dev/null m3/pm3/language/modula3/src/m3defn/procs.html:1.2 *** /dev/null Tue Feb 10 23:31:56 1998 --- m3/pm3/language/modula3/src/m3defn/procs.html Tue Feb 10 22:59:17 1998 *************** *** 0 **** --- 1,157 ---- + + +Modula-3: Procedure types + + + +Procedure types
++ + A procedure is either NIL or a triple consisting of: +
-
+
- the body, which is a statement, +
- the signature, which specifies the procedure's formal arguments, + result type, and raises set (the set of exceptions that + the procedure can raise), +
- the environment, which is the scope with respect to which + variable names in the body will be interpreted. +
+ + A + procedure that returns a result is called a function procedure; + a procedure that does not return a result is called a + proper procedure. + A top-level procedure is a procedure declared in the outermost scope + of a module. Any other procedure is a local procedure. + A local procedure can be passed as a parameter but not assigned, since + in a stack implementation a local procedure becomes invalid when the + frame for the procedure containing it is popped. +
+ + A + procedure constant is an identifier declared as a procedure. + (As opposed to a procedure variable, which is a variable declared + with a procedure type.) +
+ + A procedure type declaration has the form: +
+ TYPE T = PROCEDURE sig +
+where + sig is a signature specification, which has the form: +
+ (formal_1; ...; formal_n): R RAISES S +
+where +
-
+
- Each formal_i is a formal parameter declaration, as + described below. +
- R is the result type, which can be any type but an + open array type. The ": R" can be omitted, making the signature + that of a proper procedure. +
- S is the raises set, which is either an explicit + set of exceptions with the syntax {E_1, ..., E_n}, or + the symbol ANY representing the set of all exceptions. + If "RAISES S" is omitted, "RAISES {}" is assumed. +
+ + A formal parameter declaration has the form +
+ Mode Name: Type := Default +
+where +
-
+
- Mode is a parameter mode, which can be VALUE, + VAR, or READONLY. If Mode is omitted, + it defaults to VALUE. +
- Name is an identifier that names the parameter. + The parameter names must be distinct. +
- Type is the type of the parameter. +
- Default is a constant expression, the default value + for the parameter. If Mode is VAR, + ":= Default" must be omitted, otherwise either + ":= Default" or " : Type" can be omitted, + but not both. If Type is omitted, it is taken to be + the type of Default. If both are present, + the value of Default must be a member of Type. +
+ + When a series of parameters share the same mode, type, and default, + name_i can be a list of identifiers separated by commas. Such + a list is shorthand for a list in which the mode, type, and + default are repeated for each identifier. That is: +
+ Mode v_1, ..., v_n: Type := Default +
+is shorthand for: +
+ Mode v_1: Type := Default; ...; Mode v_n: Type := Default +
++ + This shorthand is eliminated from the expanded definition of the type. + The default values are included. +
+ + A + procedure value P is a member of the type T + if it is NIL + or its signature is covered by the signature of T, where + signature_1 covers signature_2 if: +
-
+
- They have the same number of parameters, and corresponding parameters + have the same type and mode. +
- They have the same result type, or neither has a result type. +
- The raises set of signature_1 contains the raises + set of signature_2. +
+ + The parameter names and defaults affect the type of a procedure, but + not its value. For example, consider the declarations: +
+ PROCEDURE P(txt: TEXT := "P") = + BEGIN + Wr.PutText(Stdio.stdout, txt) + END P; + + VAR q: PROCEDURE(txt: TEXT := "Q") := P; +
+Now P = q is TRUE, yet P() prints "P" + and q() prints "Q". The interpretation of defaulted + parameters is determined by a procedure's type, not its value; the + assignment q := P changes q's value, not its type. +
+ + Examples of procedure types: +
+ TYPE + Integrand = PROCEDURE (x: REAL): REAL; + Integrator = PROCEDURE(f: Integrand; lo, hi: REAL): REAL; + + TokenIterator = PROCEDURE(VAR t: Token) RAISES {TokenError}; + + RenderProc = PROCEDURE( + scene: REFANY; + READONLY t: Transform := Identity) +++ + In + a procedure type, RAISES binds to the closest preceding + PROCEDURE. + That is, the parentheses are required in: +
+ TYPE T = PROCEDURE (): (PROCEDURE ()) RAISES {} ++ ++ Last modified on Wed Apr 3 09:39:00 PST 1996 by heydon + modified on Mon Dec 19 08:18:44 PST 1994 by kalsow +
+ + Index: m3/pm3/language/modula3/src/m3defn/raise.html diff -c /dev/null m3/pm3/language/modula3/src/m3defn/raise.html:1.2 *** /dev/null Tue Feb 10 23:31:56 1998 --- m3/pm3/language/modula3/src/m3defn/raise.html Tue Feb 10 22:59:17 1998 *************** *** 0 **** --- 1,30 ---- + + +Modula-3: Raise statements + + + +Raise
++ + A RAISE statement without an argument has the form: +
+ RAISE e +
+where e is an exception that takes no argument. The outcome + of the statement is the exception e. A RAISE statement + with an argument has the form: +
+ RAISE e(x) +
+where e is an exception that takes an argument and x is + an expression assignable to e's argument type. The outcome is + the exception e paired with the argument x. +
+ +
+ Last modified on Wed Apr 3 09:38:59 PST 1996 by heydon + modified on Mon Apr 18 14:06:00 PDT 1994 by kalsow +
+ + Index: m3/pm3/language/modula3/src/m3defn/real-intf.html diff -c /dev/null m3/pm3/language/modula3/src/m3defn/real-intf.html:1.1.1.1 *** /dev/null Tue Feb 10 23:31:56 1998 --- m3/pm3/language/modula3/src/m3defn/real-intf.html Sat Jan 31 14:47:13 1998 *************** *** 0 **** --- 1,81 ---- + + +Modula-3: Real, LongReal and Extended interfaces + + + +The Real, LongReal and Extended interfaces
++ + For definitions of the terms used in these interfaces, see the ANSI/IEEE + Standard 754-1985 for floating-point arithmetic. +
+ + These interfaces define constant attributes of the three + built-in floating-point types: +
+ +
+ INTERFACE Real; TYPE T = REAL; + CONST + Base: INTEGER = ...; + Precision: INTEGER = ...; + MaxFinite: T = ...; + MinPos: T = ...; + MinPosNormal: T = ...; + END Real. +
++ +
+ INTERFACE LongReal; TYPE T = LONGREAL; + CONST + Base: INTEGER = ...; + Precision: INTEGER = ...; + MaxFinite: T = ...; + MinPos: T = ...; + MinPosNormal: T = ...; + END LongReal. +
++ +
+ INTERFACE Extended; TYPE T = EXTENDED; + CONST + Base: INTEGER = ...; + Precision: INTEGER = ...; + MaxFinite: T = ...; + MinPos: T = ...; + MinPosNormal: T = ...; + END Extended. +
++ + The specification is the same for all three interfaces: +
+ + Base is the radix of the floating-point representation for T. +
+ + Precision is the number of base-Base digits of + precision for T. +
+ + MaxFinite is the maximum finite value in T. + For non-IEEE implementations, this is the same as LAST(T). +
+ + MinPos is the minimum positive value in T. +
+ + MinPosNormal is the minimum positive normal value in T; + it differs from MinPos only for implementations (like IEEE) with + denormalized numbers. +
+ +
+ Last modified on Wed Apr 3 09:38:59 PST 1996 by heydon + modified on Thu Jun 1 08:12:25 PDT 1995 by kalsow +
+ + Index: m3/pm3/language/modula3/src/m3defn/records.html diff -c /dev/null m3/pm3/language/modula3/src/m3defn/records.html:1.2 *** /dev/null Tue Feb 10 23:31:56 1998 --- m3/pm3/language/modula3/src/m3defn/records.html Tue Feb 10 22:59:17 1998 *************** *** 0 **** --- 1,88 ---- + + +Modula-3: Record types + + + +Record types
++ + A record is a sequence of named variables, called the + fields of the record. Different fields can have different types. + The name and type of each field is statically determined by the + record's type. The expression r.f designates the field named + f in the record r. +
+ + A record type declaration has the form: +
+ TYPE T = RECORD FieldList END +
+where FieldList is a list of field declarations, + each of which has the form: +
+ fieldName: Type := default +
+where fieldName is an identifier, + Type is any non-empty type other + than an open array type, and default is a constant expression. + The field names must be distinct. + A record is a member of T if it has fields with the given names + and types, in the given order, and no other fields. Empty records + are allowed. +
+ + The + constant default is a default value used when a record + is + constructed + or + allocated. + Either ":= default" or ": Type" + can be omitted, but not both. If Type is omitted, it is taken + to be the type of default. If both are present, the value of + default must be a member of Type. +
+ + When a series of fields shares the same type and default, + any fieldName + can be a list of identifiers separated by commas. Such a list is + shorthand for a list in which the type and default are repeated + for each identifier. That is: +
+ f_1, ..., f_m: Type := default +
+is shorthand for: +
+ f_1: Type := default; ...; f_m: Type := default +
+This shorthand is eliminated from the expanded definition + of the type. The default values are included. +
+ + Examples of record types: +
+ TYPE + Time = RECORD + seconds: INTEGER; + milliseconds: [0..999] + END; + + Alignment = {Left, Center, Right}; + + TextWindowStyle = RECORD + align := Alignment.Center; + font := Font.Default; + foreground := Color.Black; + background := Color.White; + margin, border := 2 + END +++ +
+ Last modified on Wed Apr 3 09:38:59 PST 1996 by heydon + modified on Mon Apr 18 14:06:17 PDT 1994 by kalsow +
+ + Index: m3/pm3/language/modula3/src/m3defn/recursion.html diff -c /dev/null m3/pm3/language/modula3/src/m3defn/recursion.html:1.1.1.1 *** /dev/null Tue Feb 10 23:31:56 1998 --- m3/pm3/language/modula3/src/m3defn/recursion.html Sat Jan 31 14:47:13 1998 *************** *** 0 **** --- 1,63 ---- + + +Modula-3: Recursive declarations + + + +Recursive declarations
++ + A constant, type, or procedure declaration N = E, + a variable declaration N: E, + an exception declaration N(E), + or a revelation N = E + is recursive if N + occurs in any partial expansion of E. + A variable declaration N := I where the type is omitted is recursive + if N occurs in any partial expansion of the type + E of I. + Such declarations are + allowed if every occurrence of N in any partial expansion of + E is (1) within some occurrence of the type constructor REF + or PROCEDURE, + (2) within a field or method type of the type constructor OBJECT, + or (3) within a procedure body. +
+ + Examples of legal recursive declarations: +
+ TYPE + List = REF RECORD x: REAL; link: List END; + T = PROCEDURE(n: INTEGER; p: T); + XList = X OBJECT link: XList END; + CONST N = BYTESIZE(REF ARRAY [0..N] OF REAL); + PROCEDURE P(b: BOOLEAN) = BEGIN IF b THEN P(NOT b) END END P; + EXCEPTION E(PROCEDURE () RAISES {E}); + VAR v: REF ARRAY [0..BYTESIZE(v)] OF INTEGER; +++ + Examples of illegal recursive declarations: +
+ TYPE + T = RECORD x: T END; + U = OBJECT METHODS m() := U.m END; + CONST N = N+1; + REVEAL I.T = I.T BRANDED OBJECT END; + VAR v := P(); PROCEDURE P(): ARRAY [0..LAST(v)] OF T; +
++ + Examples of legal non-recursive declarations: +
+ VAR n := BITSIZE(n); + REVEAL T <: T; +
++ +
+ Last modified on Wed Apr 3 09:38:58 PST 1996 by heydon + modified on Mon Apr 18 14:06:26 PDT 1994 by kalsow +
+ + Index: m3/pm3/language/modula3/src/m3defn/refs.html diff -c /dev/null m3/pm3/language/modula3/src/m3defn/refs.html:1.2 *** /dev/null Tue Feb 10 23:31:56 1998 --- m3/pm3/language/modula3/src/m3defn/refs.html Tue Feb 10 22:59:17 1998 *************** *** 0 **** --- 1,91 ---- + + +Modula-3: Reference types + + + +Reference types
++ + A reference value is either NIL or the address of + a variable, called the referent. +
+ + A + reference type is either traced or untraced. When + all traced references to a piece of allocated storage are gone, the + implementation reclaims the storage. Two reference types are of the + same reference class if they are both traced or both untraced. + A general type is traced if it is a traced reference type, + a record type any of whose field types is traced, an array type whose + element type is traced, or a packed type whose underlying unpacked + type is traced. +
+ + A + declaration for a traced reference type has the form: +
+ TYPE T = REF Type +
+where Type is any type. The values of T are traced + references to variables of type Type, which is called + the referent type of T. +
+ + A + declaration for an untraced reference type has the form: +
+ TYPE T = UNTRACED REF Type +
+where Type is any untraced type. + (This restriction is lifted in unsafe modules.) + The values of T are the untraced references + to variables of type Type. +
+ + In + both the traced and untraced cases, the keyword REF can + optionally be preceded by "BRANDED b" where b is + a text constant called the brand. Brands distinguish types + that would otherwise be the same; they have no other semantic effect. + All brands in a program must be distinct. If BRANDED is present + and b is absent, the implementation automatically supplies + a unique value for b. Explicit brands are useful for persistent + data storage. +
+ + The + following reference types are predeclared: +
+ REFANY Contains all traced references + ADDRESS Contains all untraced references + NULL Contains only NIL +
+The TYPECASE statement + can be used to test the referent type + of a REFANY or object, but there is + no such test for an ADDRESS. +
+ + Examples of reference types: +
+ TYPE TextLine = REF ARRAY OF CHAR; + + ControllerHandle = UNTRACED REF RECORD + status: BITS 8 FOR [0..255]; + filler: BITS 12 FOR [0..0]; + pc: BITS 12 FOR [0..4095] + END; + + T = BRANDED "ANSI-M3-040776" REF INTEGER; + + Apple = BRANDED REF INTEGER; + Orange = BRANDED REF INTEGER; +
+ ++ Last modified on Wed Apr 3 09:38:58 PST 1996 by heydon + modified on Mon Apr 18 15:32:31 PDT 1994 by kalsow +
+ + Index: m3/pm3/language/modula3/src/m3defn/relations.html diff -c /dev/null m3/pm3/language/modula3/src/m3defn/relations.html:1.2 *** /dev/null Tue Feb 10 23:31:57 1998 --- m3/pm3/language/modula3/src/m3defn/relations.html Tue Feb 10 22:59:18 1998 *************** *** 0 **** --- 1,78 ---- + + +Modula-3: Relations + + + +Relations
++ +
+ infix =, # (x, y: Any): BOOLEAN +
+The operator = returns TRUE if x and y + are equal. The operator # returns TRUE + if x and y are not equal. + It is a static error if the type of x is not + assignable to the type of y or vice versa. +
+ + Ordinals are equal if they have the same value. Floats are equal + if the underlying implementation defines them to be; for example, + on an IEEE implementation, +0 equals -0 and + NaN does not equal itself. + References are equal if they address the same location. + Procedures are equal if they agree as closures; that + is, if they refer to the same procedure body and environment. + Sets are equal if they have the same elements. + Arrays are equal if they have the same length and corresponding + elements are equal. + Records are equal if they have the same fields and corresponding fields + are equal. +
+ +
+ infix <=, >= (x,y: Ordinal) : BOOLEAN + (x,y: Float) : BOOLEAN + (x,y: ADDRESS) : BOOLEAN + (x,y: Set) : BOOLEAN +
+In the first three cases, <= returns TRUE if x + is at most as large as y. In the last case, <= returns + TRUE if every element of x is an element of y. + In all cases, it is a static error if the type of x is + not assignable to the type of y, or vice versa. + The expression x >= y is equivalent to y <= x. +
+ +
+ infix >, < (x,y: Ordinal) : BOOLEAN + (x,y: Float) : BOOLEAN + (x,y: ADDRESS) : BOOLEAN + (x,y: Set) : BOOLEAN +
+In all cases, x < y means (x <= y) AND (x # y), + and x > y means y < x. + It is a static error if the type of x is not assignable + to the type of y, or vice versa. +
+ + Warning: with IEEE floating-point, x <= y + is not the same as NOT x > y. +
+ +
+ infix IN (e: Ordinal; s: Set): BOOLEAN +
+Returns TRUE if e is an element of the set s. + It is a static error if the type of e is not assignable to + the element type of s. + If the value of e is not a member of the element type, + no error occurs, but IN returns FALSE. + +
+ Last modified on Wed Apr 3 09:38:58 PST 1996 by heydon + modified on Mon Apr 18 14:06:39 PDT 1994 by kalsow +
+ + Index: m3/pm3/language/modula3/src/m3defn/repeat.html diff -c /dev/null m3/pm3/language/modula3/src/m3defn/repeat.html:1.2 *** /dev/null Tue Feb 10 23:31:57 1998 --- m3/pm3/language/modula3/src/m3defn/repeat.html Tue Feb 10 22:59:18 1998 *************** *** 0 **** --- 1,25 ---- + + +Modula-3: Repeat statements + + + +Repeat
++ + If B is an expression of type BOOLEAN + and S is a statement: +
+ REPEAT S UNTIL B +
+is shorthand for: +
+ LOOP S; IF B THEN EXIT END END +
+ ++ Last modified on Wed Apr 3 09:38:57 PST 1996 by heydon + modified on Mon Apr 18 14:06:46 PDT 1994 by kalsow +
+ + Index: m3/pm3/language/modula3/src/m3defn/return.html diff -c /dev/null m3/pm3/language/modula3/src/m3defn/return.html:1.2 *** /dev/null Tue Feb 10 23:31:57 1998 --- m3/pm3/language/modula3/src/m3defn/return.html Tue Feb 10 22:59:18 1998 *************** *** 0 **** --- 1,58 ---- + + +Modula-3: Return statements + + + +Return
++ + A RETURN statement for a + proper procedure + has the form: +
+ RETURN +
+The statement raises the return-exception without an argument. It + is allowed only in the body of a proper procedure. +
+ + A + RETURN statement for a + function procedure + has the form: +
+ RETURN Expr +
+where Expr is an expression assignable to the result type of + the procedure. The statement raises the return-exception with the + argument Expr. It is allowed only in the body of a function + procedure. +
+ + Failure + to return a value from a function procedure is a checked runtime + error. +
+ + The effect of raising the return exception is to terminate the current + procedure activation. To be precise, a call on a proper procedure + with body B is equivalent (after binding the arguments) to: +
+ TRY B EXCEPT return-exception => (*skip*) END +
+A call on a function procedure with body B is equivalent to: +
+ TRY + B; (error: no returned value) + EXCEPT + return-exception (v) => (the result becomes v) + END +
+ ++ Last modified on Wed Apr 3 09:38:57 PST 1996 by heydon + modified on Mon Apr 18 14:06:52 PDT 1994 by kalsow +
+ + Index: m3/pm3/language/modula3/src/m3defn/revelations.html diff -c /dev/null m3/pm3/language/modula3/src/m3defn/revelations.html:1.2 *** /dev/null Tue Feb 10 23:31:57 1998 --- m3/pm3/language/modula3/src/m3defn/revelations.html Tue Feb 10 22:59:18 1998 *************** *** 0 **** --- 1,84 ---- + + +Modula-3: Revelations + + + +Revelations
++ + A revelation introduces information about an opaque type into + a scope. Unlike other declarations, revelations introduce no new names. +
+ + There are two kinds of revelations, partial and complete. + A program can contain any number of partial revelations for an opaque + type; it must contain exactly one complete revelation. +
+ + A partial revelation has the form: +
+ REVEAL T <: V +
+where V is a type expression (possibly just a name) + and T is an identifier (possibly + qualified) + declared as an opaque type. It reveals that + V is a supertype of T. +
+ + In any scope, the revealed supertypes of an opaque type must be linearly + ordered by the subtype relation. + That is, if it is revealed that T <: U1 and T <: U2, + it must also be revealed either that + U1 <: U2 or that U2 <: U1. +
+ + A complete revelation has the form: +
+ REVEAL T = V +
+where V is a type expression (not just a name) whose outermost + type constructor is a branded reference or object type and T + is an identifier (possibly qualified) that has been declared as an + opaque type. The revelation specifies that V is the concrete + type for T. It is a static error if any type revealed in any + scope as a supertype of T is not a supertype of V. + Generally this error is detected at link time. +
+ + Distinct opaque types have distinct concrete types, since V + includes a brand and all brands in a program are distinct. +
+ + A + revelation is allowed only in an interface or in the outermost scope + of a module. A revelation in an interface can be imported into any + scope where it is required, as illustrated by the + stack example. +
+ + For example, consider: +
+ INTERFACE I; TYPE T <: ROOT; PROCEDURE P(x:T): T; END I. + + INTERFACE IClass; IMPORT I; REVEAL I.T <: MUTEX; END IClass. + + INTERFACE IRep; IMPORT I; + REVEAL I.T = MUTEX BRANDED OBJECT count: INTEGER END; + END IRep. +
+ An importer of I sees I.T as an opaque subtype of + ROOT, and is limited to allocating objects of type I.T, + passing them to I.P, or declaring subtypes of I.T. + An importer of IClass sees that every I.T is a + MUTEX, and can therefore lock objects of type I.T. + Finally, an importer of IRep sees the concrete type, + and can access the count field. + +
+ Last modified on Wed Apr 3 09:38:57 PST 1996 by heydon + modified on Mon Apr 18 14:06:59 PDT 1994 by kalsow +
+ + Index: m3/pm3/language/modula3/src/m3defn/safety.html diff -c /dev/null m3/pm3/language/modula3/src/m3defn/safety.html:1.1.1.1 *** /dev/null Tue Feb 10 23:31:57 1998 --- m3/pm3/language/modula3/src/m3defn/safety.html Sat Jan 31 14:47:13 1998 *************** *** 0 **** --- 1,36 ---- + + +Modula-3: Safety + + + +Safety
++ + The keyword UNSAFE can precede the declaration of any interface + or module to indicate that it is unsafe; that is, uses the + unsafe features + of the language. + An interface or module not explicitly labeled + UNSAFE is called safe. +
+ + An + interface is intrinsically safe if there is no way to produce + an unchecked runtime error by using the interface in a safe module. + If all modules that export a safe interface are safe, the compiler + guarantees the intrinsic safety of the interface. If any of the modules + that export a safe interface are unsafe, it is the programmer, rather + than the compiler, who makes the guarantee. +
+ + It is a static error for a safe interface to import an unsafe one + or for a safe module to import or export an unsafe interface. +
+ +
+ Last modified on Wed Apr 3 09:38:56 PST 1996 by heydon + modified on Mon Apr 18 14:07:05 PDT 1994 by kalsow +
+ + Index: m3/pm3/language/modula3/src/m3defn/sequence.html diff -c /dev/null m3/pm3/language/modula3/src/m3defn/sequence.html:1.2 *** /dev/null Tue Feb 10 23:31:57 1998 --- m3/pm3/language/modula3/src/m3defn/sequence.html Tue Feb 10 22:59:18 1998 *************** *** 0 **** --- 1,30 ---- + + +Modula-3: Sequential composition + + + +Sequential composition
++ + A statement of the form: +
+ S_1; S_2 +
+executes S_1, and then if the outcome is normal, executes + S_2. If the outcome of S_1 is an exception, S_2 + is ignored. +
+ + Some programmers use the semicolon as a statement + terminator, some as a statement separator. Similarly, some + use the vertical bar in case statements as a case initiator, some + as a separator. Modula-3 allows both styles. This report + uses both operators as separators. + +
+ Last modified on Wed Apr 3 09:38:56 PST 1996 by heydon + modified on Mon Apr 18 14:07:12 PDT 1994 by kalsow +
+ + Index: m3/pm3/language/modula3/src/m3defn/sets.html diff -c /dev/null m3/pm3/language/modula3/src/m3defn/sets.html:1.2 *** /dev/null Tue Feb 10 23:31:57 1998 --- m3/pm3/language/modula3/src/m3defn/sets.html Tue Feb 10 22:59:18 1998 *************** *** 0 **** --- 1,34 ---- + + +Modula-3: Set types + + + +Set types
++ + A set is a collection of values taken from some ordinal type. + A set type declaration has the form: +
+ TYPE T = SET OF Base +
+where Base is an ordinal type. The values of T are all sets + whose elements have type Base. For example, a variable whose + type is SET OF [0..1] can assume the following + values: +
+ {} {0} {1} {0,1} +++ + Implementations are expected to use the same representation for a + SET OF T as for an ARRAY T OF BITS 1 FOR BOOLEAN. Hence, + programmers should expect SET OF [0..1023] to be practical, + but not SET OF INTEGER. + +
+ Last modified on Wed Apr 3 09:38:56 PST 1996 by heydon + modified on Mon Apr 18 14:07:20 PDT 1994 by kalsow +
+ + Index: m3/pm3/language/modula3/src/m3defn/stmts.html diff -c /dev/null m3/pm3/language/modula3/src/m3defn/stmts.html:1.2 *** /dev/null Tue Feb 10 23:31:57 1998 --- m3/pm3/language/modula3/src/m3defn/stmts.html Tue Feb 10 22:59:18 1998 *************** *** 0 **** --- 1,77 ---- + + +Modula-3: Statements + + + +Statements
++ +
++ Look into any carpenter's tool-bag and see how many different + hammers, chisels, planes and screw-drivers he keeps there---not for + ostentation or luxury, but for different sorts of jobs. + ---Robert Graves and Alan Hodge +
+ + Executing + a statement produces a computation that can halt (normal + outcome), raise an exception, cause a checked runtime error, or + loop forever. If the outcome is an exception, it can optionally + be paired with an argument. +
+ + We + define the semantics of EXIT and RETURN with exceptions + called the exit-exception and the return-exception. + The exit-exception takes no argument; the return-exception takes + an argument of arbitrary type. Programs cannot name these exceptions + explicitly. +
+ + Implementations should speed up normal outcomes at the expense of + exceptions (except for the return-exception and exit-exception). + Expending a thousand instructions per exception raised to save + one instruction per procedure call would be reasonable. +
+ + If an expression is evaluated as part of the execution of a statement, + and the evaluation raises an exception, then the exception becomes + the outcome of the statement. +
+ + The empty statement is a no-op. In this report, empty statements + are written (*skip*). +
+ + Each of the statments is described below +
-
+
- Assignment +
- Procedure call +
- Eval +
- Block statement +
- Sequential composition +
- Raise +
- Try Except +
- Try Finally +
- Loop +
- Exit +
- Return +
- If +
- While +
- Repeat +
- With +
- For +
- Case +
- Typecase +
- Lock +
- Inc and Dec +
+ Last modified on Wed Apr 3 09:38:55 PST 1996 by heydon + modified on Fri Apr 15 08:41:20 PDT 1994 by kalsow +
+ + Index: m3/pm3/language/modula3/src/m3defn/subtypes.html diff -c /dev/null m3/pm3/language/modula3/src/m3defn/subtypes.html:1.2 *** /dev/null Tue Feb 10 23:31:57 1998 --- m3/pm3/language/modula3/src/m3defn/subtypes.html Tue Feb 10 22:59:18 1998 *************** *** 0 **** --- 1,121 ---- + + +Modula-3: Subtyping rules + + + +Subtyping rules
++ + We write T <: U to indicate that T is a subtype + of U and U is a supertype of T. +
+ + If + T <: U, then every value of type T is also a value + of type U. The converse does not hold: for example, a record + or array type with packed fields contains the same values as the + corresponding type with unpacked fields, but there is no subtype + relation between them. This section presents the rules that define + the subtyping relation. +
+ + For ordinal types T and U, we have T <: + U if they have the same basetype and every member of T + is a member of U. That is, subtyping on ordinal types + reflects the subset relation on the value sets. +
+ + For array types, +
+ (ARRAY OF)^m ARRAY J_1 OF ... ARRAY J_n OF + ARRAY K_1 OF ... ARRAY K_p OF T + <: (ARRAY OF)^m (ARRAY OF)^n + ARRAY I_1 OF ... ARRAY I_p OF T + + if NUMBER(I_i) = NUMBER(K_i) for i = 1, ..., p. +
++ + That is, an array type A is a subtype of an array type + B if they have the same ultimate element type, the same + number of dimensions, and, for each dimension, either both are open + (as in the first m dimensions above), + or A is fixed and B is open + (as in the next n dimensions above), or they are + both fixed and have the same size + (as in the last p dimensions above). +
+ +
+ NULL <: REF T <: REFANY + NULL <: UNTRACED REF T <: ADDRESS +
++ + That is, REFANY and ADDRESS contain all traced and + untraced references, respectively, and NIL is a member + of every reference type. These rules also apply to branded + types. +
+ +
+ NULL <: PROCEDURE(A): R RAISES S for any A, R, and S. +
+That is, NIL is a member of every procedure type. + +
+ PROCEDURE(A): Q RAISES E <: PROCEDURE(B): R RAISES F + if signature "(B): R RAISES F" covers signature "(A): Q RAISES E". +
+That is, for procedure types, T <: U if + they are the same except for parameter names, defaults, + and raises sets, and the raises set for T is contained in the + raises set for U. +
+ +
+ ROOT <: REFANY + UNTRACED ROOT <: ADDRESS + NULL <: T OBJECT ... END <: T +
+That is, every object is a reference, + NIL is a member of every + object type, and every subtype is included in its supertype. + The third rule also applies to branded types. + +
+ BITS n FOR T <: T and T <: BITS n FOR T +
+That is, BITS FOR T has the same values as T. + +
+ T <: T for all T + T <: U and U <: V implies T <: V for all T, U, V. +
+That is, <: is reflexive and transitive. +
+ + Note that T <: U and U <: T does not imply that + T and U are the same, since the subtype relation + is unaffected by parameter names, default values, and packing. +
+ + For example, consider: +
+ TYPE + T = [0..255]; + U = BITS 8 FOR [0..255]; + AT = ARRAY OF T; + AU = ARRAY OF U; +
+The types T and U are subtypes of one another but are + not the same. The types AT and AU are + unrelated by the subtype relation. + +
+ Last modified on Wed Apr 3 09:38:55 PST 1996 by heydon + modified on Mon Apr 18 14:07:28 PDT 1994 by kalsow +
+ + Index: m3/pm3/language/modula3/src/m3defn/syntax.html diff -c /dev/null m3/pm3/language/modula3/src/m3defn/syntax.html:1.2 *** /dev/null Tue Feb 10 23:31:57 1998 --- m3/pm3/language/modula3/src/m3defn/syntax.html Tue Feb 10 22:59:18 1998 *************** *** 0 **** --- 1,331 ---- + + +Modula-3: Syntax + + + +Syntax
++ +
++ Care should be taken, when using colons and semicolons in the same + sentence, that the reader understands how far the force of each sign + carries. + ---Robert Graves and Alan Hodge +
+ +
Keywords
++ +
+ AND DO FROM NOT REPEAT UNTIL + ANY ELSE GENERIC OBJECT RETURN UNTRACED + ARRAY ELSIF IF OF REVEAL VALUE + AS END IMPORT OR ROOT VAR + BEGIN EVAL IN OVERRIDES SET WHILE + BITS EXCEPT INTERFACE PROCEDURE THEN WITH + BRANDED EXCEPTION LOCK RAISE TO + BY EXIT LOOP RAISES TRY + CASE EXPORTS METHODS READONLY TYPE + CONST FINALLY MOD RECORD TYPECASE + DIV FOR MODULE REF UNSAFE +
++ +
Reserved identifiers
++ +
+ ABS BYTESIZE EXTENDED INTEGER MIN NUMBER TEXT + ADDRESS CARDINAL FALSE ISTYPE MUTEX ORD TRUE + ADR CEILING FIRST LAST NARROW REAL TRUNC + ADRSIZE CHAR FLOAT LONGREAL NEW REFANY TYPECODE + BITSIZE DEC FLOOR LOOPHOLE NIL ROUND VAL + BOOLEAN DISPOSE INC MAX NULL SUBARRAY +
++ +
Operators
++ +
+ + < # = ; .. : + - > { } | := <: + * <= ( ) ^ , => + / >= [ ] . & +++ +
Comments
++ + A comment is an arbitrary character sequence opened by (* and closed + by *). Comments can be nested and can extend over more than one line. +
+ +
Pragmas
++ + A pragma is an arbitrary character sequence opened by <* + and closed by *>. + Pragmas can be nested and can extend over more than one line. + Pragmas are hints to the implementation; they do not affect the + language semantics. +
+ + We + recommend supporting the two pragmas <*INLINE*> and + <*EXTERNAL*>. + The pragma <*INLINE*> precedes a procedure + declaration to indicate that the procedure should be expanded at the + point of call. The pragma <* EXTERNAL N:L *> precedes an + interface or a declaration in an interface to indicate that the entity + it precedes is implemented by the language L, where it has the + name N. If ":L" is omitted, then the implementation's + default external language is assumed. If "N" is omitted, then + the external name is determined from the Modula-3 name in some + implementation-dependent way. +
+ +
Conventions for syntax
++ + We use the following notation for defining syntax: +
+ X Y X followed by Y + X|Y X or Y. + [X] X or empty + {X} A possibly empty sequence of X's + X&Y X or Y or X Y ++"Followed by" has greater binding power than | or &; + parentheses are used to override this precedence rule. Non-terminals + begin with an upper-case letter. Terminals are either keywords or + quoted operators. The symbols Ident, Number, + TextLiteral, and CharLiteral are defined in the + token grammar. + Each production is terminated by a period. + The syntax does not reflect the restrictions that revelations + and exceptions can be declared only at the top level; nor does it + include explicit productions for NEW, INC, and DEC, + which parse like procedure calls. +
+ +
Compilation unit productions
++ +
+ Compilation = [UNSAFE] (Interface | Module) | GenInf | GenMod. + + Interface = INTERFACE Id ";" {Import} {Decl} END Id "." + | INTERFACE Id "=" Id GenActls END Id ".". + Module = MODULE Id [EXPORTS IdList] ";" {Import} Block Id "." + | MODULE Id [EXPORTS IdList] "=" Id GenActls END Id ".". + + GenInf = GENERIC INTERFACE Id GenFmls ";" {Import} {Decl} END Id ".". + GenMod = GENERIC MODULE Id GenFmls ";" {Import} Block Id ".". + + Import = AsImport | FromImport. + AsImport = IMPORT ImportItem {"," ImportItem} ";". + FromImport = FROM Id IMPORT IdList ";". + Block = {Decl} BEGIN S END. + Decl = CONST {ConstDecl ";"} + | TYPE {TypeDecl ";"} + | EXCEPTION {ExceptionDecl ";"} + | VAR {VariableDecl ";"} + | ProcedureHead ["=" Block Id] ";" + | REVEAL {QualId ("=" | "<:") Type ";"}. + + GenFmls = "(" [IdList] ")". + GenActls = "(" [IdList] ")". + ImportItem = Id | Id AS Id. + ConstDecl = Id [":" Type] "=" ConstExpr. + TypeDecl = Id ("=" | "<:") Type. + ExceptionDecl = Id ["(" Type ")"]. + VariableDecl = IdList (":" Type & ":=" Expr). + ProcedureHead = PROCEDURE Id Signature. + + Signature = "(" Formals ")" [":" Type] [RAISES Raises]. + Formals = [ Formal {";" Formal} [";"] ]. + Formal = [Mode] IdList (":" Type & ":=" ConstExpr). + Mode = VALUE | VAR | READONLY. + Raises = "{" [ QualId {"," QualId} ] "}" | ANY. +++ +
Statement productions
++ +
+ Stmt = AssignSt | Block | CallSt | CaseSt | ExitSt | EvalSt | ForSt + | IfSt | LockSt | LoopSt | RaiseSt | RepeatSt | ReturnSt + | TCaseSt | TryXptSt | TryFinSt | WhileSt | WithSt. + + S = [ Stmt {";" Stmt} [";"] ]. + + AssignSt = Expr ":=" Expr. + CallSt = Expr "(" [Actual {"," Actual}] ")". + CaseSt = CASE Expr OF [Case] {"|" Case} [ELSE S] END. + ExitSt = EXIT. + EvalSt = EVAL Expr. + ForSt = FOR Id ":=" Expr TO Expr [BY Expr] DO S END. + IfSt = IF Expr THEN S {ELSIF Expr THEN S} [ELSE S] END. + LockSt = LOCK Expr DO S END. + LoopSt = LOOP S END. + RaiseSt = RAISE QualId ["(" Expr ")"]. + RepeatSt = REPEAT S UNTIL Expr. + ReturnSt = RETURN [Expr]. + TCaseSt = TYPECASE Expr OF [TCase] {"|" TCase} [ELSE S] END. + TryXptSt = TRY S EXCEPT [Handler] {"|" Handler} [ELSE S] END. + TryFinSt = TRY S FINALLY S END. + WhileSt = WHILE Expr DO S END. + WithSt = WITH Binding {"," Binding} DO S END. + + Case = Labels {"," Labels} "=>" S. + Labels = ConstExpr [".." ConstExpr]. + Handler = QualId {"," QualId} ["(" Id ")"] "=>" S. + TCase = Type {"," Type} ["(" Id ")"] "=>" S. + Binding = Id "=" Expr. + Actual = Type | [Id ":="] Expr . ++ +Type productions
++ +
+ Type = TypeName | ArrayType | PackedType | EnumType | ObjectType + | ProcedureType | RecordType | RefType | SetType | SubrangeType + | "(" Type ")". + + ArrayType = ARRAY [Type {"," Type}] OF Type. + PackedType = BITS ConstExpr FOR Type. + EnumType = "{" [IdList] "}". + ObjectType = [TypeName | ObjectType] [Brand] OBJECT Fields + [METHODS Methods] [OVERRIDES Overrides] END. + ProcedureType = PROCEDURE Signature. + RecordType = RECORD Fields END. + RefType = [UNTRACED] [Brand] REF Type. + SetType = SET OF Type. + SubrangeType = "[" ConstExpr ".." ConstExpr "]". + + Brand = BRANDED [ConstExpr]. + Fields = [ Field {";" Field} [";"] ]. + Field = IdList (":" Type & ":=" ConstExpr). + Methods = [ Method {";" Method} [";"] ]. + Method = Id Signature [":=" ConstExpr]. + Overrides = [ Override {";" Override} [";"] ]. + Override = Id ":=" ConstExpr . ++ +Expression productions
++ +
+ ConstExpr = Expr. + + Expr = E1 {OR E1}. + E1 = E2 {AND E2}. + E2 = {NOT} E3. + E3 = E4 {Relop E4}. + E4 = E5 {Addop E5}. + E5 = E6 {Mulop E6}. + E6 = {"+" | "-"} E7. + E7 = E8 {Selector}. + E8 = Id | Number | CharLiteral | TextLiteral + | Constructor | "(" Expr ")". + + Relop = "=" | "#" | "<" | "<=" | ">" | ">=" | IN. + Addop = "+" | "-" | "&". + Mulop = "*" | "/" | DIV | MOD. + + Selector = "^" | "." Id | "[" Expr {"," Expr} "]" + | "(" [ Actual {"," Actual} ] ")". + + Constructor = Type "{" [ SetCons | RecordCons | ArrayCons ] "}". + + SetCons = SetElt {"," SetElt}. + SetElt = Expr [".." Expr]. + RecordCons = RecordElt {"," RecordElt}. + RecordElt = [Id ":="] Expr. + ArrayCons = Expr {"," Expr} ["," ".."]. ++ +Miscellaneous productions
+ ++ IdList = Id {"," Id}. + QualId = Id ["." Id]. + TypeName = QualId | ROOT | UNTRACED ROOT. +++ +
Token productions
++ + To read a token, first skip all blanks, tabs, newlines, carriage + returns, vertical tabs, form feeds, comments, and pragmas. Then read the + longest sequence of characters that forms an + operator + or an Id or Literal. +
+ + An + Id is a case-significant sequence of letters, digits, and + underscores that begins with a letter. + An Id is a keyword if it appears in the + list of keywords, + a reserved identifier if it appears in the + list of reserved identifiers, + and an ordinary identifier otherwise. +
+ + In the following grammar, terminals are characters surrounded by + double-quotes and the special terminal DQUOTE represents + double-quote itself. + +
+ Id = Letter {Letter | Digit | "_"}. + + Literal = Number | CharLiteral | TextLiteral. + + CharLiteral = "'" (PrintingChar | Escape | DQUOTE) "'". + + TextLiteral = DQUOTE {PrintingChar | Escape | "'"} DQUOTE. + + Escape = "\" "n" | "\" "t" | "\" "r" | "\" "f" + | "\" "\" | "\" "'" | "\" DQUOTE + | "\" OctalDigit OctalDigit OctalDigit. + + Number = Digit {Digit} + | Digit {Digit} "_" HexDigit {HexDigit} + | Digit {Digit} "." Digit {Digit} [Exp]. + + Exp = ("E" | "e" | "D" | "d" | "X" | "x") ["+" | "-"] Digit {Digit}. + + PrintingChar = Letter | Digit | OtherChar. + + HexDigit = Digit | "A" | "B" | "C" | "D" | "E" | "F" + | "a" | "b" | "c" | "d" | "e" | "f". + + Digit = "0" | "1" | ... | "9". + + OctalDigit = "0" | "1" | ... | "7". + + Letter = "A" | "B" | ... | "Z" | "a" | "b" | ... | "z". + + OtherChar = " " | "!" | "#" | "$" | "%" | "&" | "(" | ")" + | "*" | "+" | "," | "-" | "." | "/" | ":" | ";" + | "<" | "=" | ">" | "?" | "@" | "[" | "]" | "^" + | "_" | "`" | "{" | "|" | "}" | "~" + | ExtendedChar + + ExtendedChar = any char with ISO-Latin-1 code in [8_ 240..8_ 377]. ++ ++ Last modified on Wed Apr 3 09:38:55 PST 1996 by heydon + modified on Mon Dec 19 08:18:35 PST 1994 by kalsow +
+ + Index: m3/pm3/language/modula3/src/m3defn/text-intf.html diff -c /dev/null m3/pm3/language/modula3/src/m3defn/text-intf.html:1.2 *** /dev/null Tue Feb 10 23:31:57 1998 --- m3/pm3/language/modula3/src/m3defn/text-intf.html Tue Feb 10 22:59:18 1998 *************** *** 0 **** --- 1,87 ---- + + +Modula-3: Text interface + + + +The Text interface
++ +
+ INTERFACE Text; + + TYPE + T = TEXT; +
+A non-nil TEXT represents a zero-based sequence of characters. + NIL does not represent any sequence of characters, it will not + be returned from any procedure in the interface, and it is a checked + runtime error to pass it to any procedure in the interface. + +
+ PROCEDURE Cat(t, u: T): T; +
+The concatenation of t and u. + +
+ PROCEDURE Equal(t, u: T): BOOLEAN; +
+TRUE if t and u have the same length + and (case-sensitive) contents. + +
+ PROCEDURE GetChar(t: T; i: CARDINAL): CHAR; +
+Character i of t. A checked runtime error + if i >= Length(t). + +
+ PROCEDURE Length(t: T): CARDINAL; +
+The number of characters in t. + +
+ PROCEDURE Empty(t: T): BOOLEAN; +
+TRUE if Length(t) = 0. + +
+ PROCEDURE Sub(t: T; start, length: CARDINAL): T; +
+Return a subsequence of t: empty if start >= Length(t) + or length = 0; otherwise the subsequence ranging from + start to the minimum of start+length-1 and + Length(t)-1. + +
+ PROCEDURE SetChars(VAR a: ARRAY OF CHAR; t: T); +
+For each i from 0 to MIN(LAST(a), + Length(t)-1), set a[i] to + GetChar(t, i). + +
+ PROCEDURE FromChar(ch: CHAR): T; +
+A text containing the single character ch. + +
+ PROCEDURE FromChars(READONLY a: ARRAY OF CHAR): T; +
+A text containing the characters of a. + +
+ PROCEDURE Hash(t: T): INTEGER; +
+Return a hash function of the contents of t. + +
+ END Text. +
+ ++ Last modified on Wed Apr 3 09:43:27 PST 1996 by heydon + modified on Thu Jun 1 08:12:38 PDT 1995 by kalsow +
+ + Index: m3/pm3/language/modula3/src/m3defn/textops.html diff -c /dev/null m3/pm3/language/modula3/src/m3defn/textops.html:1.2 *** /dev/null Tue Feb 10 23:31:57 1998 --- m3/pm3/language/modula3/src/m3defn/textops.html Tue Feb 10 22:59:19 1998 *************** *** 0 **** --- 1,21 ---- + + +Modula-3: Text operations + + + +Text operations
++ +
+ infix & (a,b: TEXT): TEXT +
+The concatenation of a and b, as defined by + Text.Cat. + +
+ Last modified on Wed Apr 3 09:38:54 PST 1996 by heydon + modified on Mon Apr 18 14:07:42 PDT 1994 by kalsow +
+ + Index: m3/pm3/language/modula3/src/m3defn/texts.html diff -c /dev/null m3/pm3/language/modula3/src/m3defn/texts.html:1.2 *** /dev/null Tue Feb 10 23:31:57 1998 --- m3/pm3/language/modula3/src/m3defn/texts.html Tue Feb 10 22:59:19 1998 *************** *** 0 **** --- 1,43 ---- + + +Modula-3: Text and character literals + + + +Text and character literals
++ + A character literal is a pair of single quotes enclosing either a + single ISO-Latin-1 printing character (excluding single quote) + or an escape sequence. The type of a character literal is CHAR. +
+ + A + text literal is a pair of double quotes enclosing a sequence of + ISO-Latin-1 printing characters (excluding double quote) and escape + sequences. The type of a text literal is TEXT. +
+ + Here are + are the legal escape sequences and the characters they denote: +
+ \n newline (linefeed) \f form feed + \t tab \\ backslash + \r carriage return \" double quote + \' single quote \nnn char with code 8_nnn +
+A \ followed by exactly three octal digits specifies the character + whose code is that octal value. A \ that is not a part + of one of these escape sequences is a static error. +
+ + For example, 'a' and '\'' are valid character + literals, ''' is not; "" and "Don't\n" + are valid text literals, """ is not. + +
+ Last modified on Wed Apr 3 09:38:54 PST 1996 by heydon + modified on Mon Apr 18 13:39:16 PDT 1994 by kalsow +
+ + Index: m3/pm3/language/modula3/src/m3defn/thread-intf.html diff -c /dev/null m3/pm3/language/modula3/src/m3defn/thread-intf.html:1.2 *** /dev/null Tue Feb 10 23:31:57 1998 --- m3/pm3/language/modula3/src/m3defn/thread-intf.html Tue Feb 10 22:59:19 1998 *************** *** 0 **** --- 1,123 ---- + + +Modula-3: Thread interface + + + +The Thread interface
++ + If a shared variable is written concurrently by two threads, or written + by one and read concurrently by another, the effect is to set the + variable to an implementation-dependent value of its type. + For example, if one thread writes a[0] while another + concurrently writes a[1], one of the writes might be lost. + Thus, portable programs must + use the Thread interface to provide mutual exclusion for shared + variables. + +
+ INTERFACE Thread; + + TYPE + T <: REFANY; + Mutex = MUTEX; + Condition <: ROOT; + Closure = OBJECT METHODS apply(): REFANY END; +
+A Thread.T is a handle on a thread. A Mutex is locked + by some thread, or unlocked. A Condition is a set of waiting + threads. A newly-allocated Mutex is unlocked; a newly-allocated + Condition is empty. It is a checked runtime error to pass the + NIL Mutex, Condition, or T to any + procedure in this interface. + +
+ PROCEDURE Fork(cl: Closure): T; +
+A handle on a newly-created thread executing cl.apply(). + +
+ PROCEDURE Join(t: T): REFANY; +
+Wait until t has terminated and return its result. It is a + checked error to call this more than once for any t. + +
+ PROCEDURE Wait(m: Mutex; c: Condition); +
+The calling thread must have m locked. Atomically unlocks + m and waits on c. Then relocks m and returns. + +
+ PROCEDURE Acquire(m: Mutex); +
+Wait until m is unlocked and then lock it. +
+ +
+ PROCEDURE Release(m: Mutex); +
+The calling thread must have m locked. Unlocks m. + +
+ PROCEDURE Broadcast(c: Condition); +
+All threads waiting on c become eligible to run. + +
+ PROCEDURE Signal(c: Condition); +
+One or more threads waiting on c become eligible to run. + +
+ PROCEDURE Self(): T; +
+Return the handle of the calling thread. + +
+ EXCEPTION Alerted; +
+Used to approximate asynchronous interrupts. + +
+ PROCEDURE Alert(t: T); +
+Mark t as an alerted thread. + +
+ PROCEDURE TestAlert(): BOOLEAN; +
+TRUE if the calling thread has been marked alerted. + +
+ PROCEDURE AlertWait(m: Mutex; c: Condition) RAISES {Alerted}; ++Like Wait, but if the thread is marked alerted at the time of + call or sometime during the wait, lock m and raise Alerted. + +
+ PROCEDURE AlertJoin(t: T): REFANY RAISES {Alerted}; ++Like Join, but if the calling thread is marked alerted at + the time of call or sometime during the wait, raise Alerted. + +
+ CONST + AtomicSize = ...; +
+An implementation-dependent integer constant: the number of bits in + a memory-coherent block. If two components of a record or array fall + in different blocks, they can be accessed concurrently by different + threads without locking. + +
+ END Thread. +
+ ++ Last modified on Wed Apr 3 09:38:54 PST 1996 by heydon + modified on Thu Jun 1 08:12:48 PDT 1995 by kalsow +
+ + Index: m3/pm3/language/modula3/src/m3defn/tryexcept.html diff -c /dev/null m3/pm3/language/modula3/src/m3defn/tryexcept.html:1.2 *** /dev/null Tue Feb 10 23:31:57 1998 --- m3/pm3/language/modula3/src/m3defn/tryexcept.html Tue Feb 10 22:59:19 1998 *************** *** 0 **** --- 1,73 ---- + + +Modula-3: Try except statements + + + +Try Except
++ + A TRY-EXCEPT statement has the form: +
+ TRY + Body + EXCEPT + id_1 (v_1) => Handler_1 + | ... + | id_n (v_n) => Handler_n + ELSE Handler_0 + END +
+where Body and each Handler are statements, + each id names an exception, and each v_i is an identifier. + The "ELSE Handler_0" and each "(v_i)" are optional. + It is a static error for an exception to be named more than once + in the list of id's. +
+ + The + statement executes Body. If the outcome is normal, the + except clause is ignored. If Body raises any listed exception + id_i, then Handler_i is executed. If Body + raises any other exception and "ELSE Handler_0" is present, + then it is executed. In either case, the outcome of the TRY + statement is the outcome of the selected handler. If Body + raises an unlisted exception and "ELSE Handler_0" is + absent, then the outcome of the TRY statement is the exception + raised by Body. +
+ + Each + (v_i) declares a variable whose type is the argument + type of the exception id_i and whose scope is + Handler_i. When an exception id_i paired with an + argument x is handled, v_i is initialized to + x before Handler_i is executed. It is a static error + to include (v_i) if exception id_i does not take + an argument. +
+ + If (v_i) is absent, then id_i can be a list of + exceptions separated by commas, as shorthand for a list in + which the rest of the handler is repeated for each exception. + That is: +
+ id_1, ..., id_n => Handler +
+is shorthand for: +
+ id_1 => Handler; ...; id_n => Handler +
++ + It + is a checked runtime error to raise an exception outside the dynamic + scope of a handler for that exception. A "TRY EXCEPT ELSE" + counts as a handler for all exceptions. + +
+ Last modified on Wed Apr 3 09:38:53 PST 1996 by heydon + modified on Mon Apr 18 14:08:03 PDT 1994 by kalsow +
+ + Index: m3/pm3/language/modula3/src/m3defn/tryfinally.html diff -c /dev/null m3/pm3/language/modula3/src/m3defn/tryfinally.html:1.2 *** /dev/null Tue Feb 10 23:31:57 1998 --- m3/pm3/language/modula3/src/m3defn/tryfinally.html Tue Feb 10 22:59:19 1998 *************** *** 0 **** --- 1,27 ---- + + +Modula-3: Try finally statements + + + +Try Finally
++ + A statement of the form: +
+ TRY S_1 FINALLY S_2 END +
+executes statement S_1 and then statement S_2. + If the outcome of S_1 is normal, the TRY statement + is equivalent to S_1; S_2. If the outcome of + S_1 is an exception and the outcome of S_2 is normal, + the exception from S_1 is re-raised after S_2 + is executed. If both outcomes are exceptions, the outcome of the + TRY is the exception from S_2. + +
+ Last modified on Wed Apr 3 09:38:53 PST 1996 by heydon + modified on Mon Apr 18 14:08:09 PDT 1994 by kalsow +
+ + Index: m3/pm3/language/modula3/src/m3defn/type-decl.html diff -c /dev/null m3/pm3/language/modula3/src/m3defn/type-decl.html:1.2 *** /dev/null Tue Feb 10 23:31:57 1998 --- m3/pm3/language/modula3/src/m3defn/type-decl.html Tue Feb 10 22:59:19 1998 *************** *** 0 **** --- 1,23 ---- + + +Modula-3: Type declarations + + + +Types
++ + If T is an identifier and U a type + (or type expression, since a type expression is allowed + wherever a type is required), then: +
+ TYPE T = U +
+declares T to be the type U. + +
+ Last modified on Wed Apr 3 09:38:53 PST 1996 by heydon + modified on Mon Apr 18 14:08:17 PDT 1994 by kalsow +
+ + Index: m3/pm3/language/modula3/src/m3defn/typecase.html diff -c /dev/null m3/pm3/language/modula3/src/m3defn/typecase.html:1.2 *** /dev/null Tue Feb 10 23:31:57 1998 --- m3/pm3/language/modula3/src/m3defn/typecase.html Tue Feb 10 22:59:19 1998 *************** *** 0 **** --- 1,74 ---- + + +Modula-3: Typecase statements + + + +Typecase
++ + A TYPECASE statement has the form: +
+ TYPECASE Expr OF + T_1 (v_1) => S_1 + | ... + | T_n (v_n) => S_n + ELSE S_0 + END +
+where Expr is an expression whose type is a reference type, + the S's are statements, the T's are reference types, + and the v's are identifiers. It is a static error if + Expr has type ADDRESS or if any T is not a subtype of + the type of Expr. The "ELSE S_0" + and each "(v)" are optional. +
+ + The + statement evaluates Expr. If the resulting reference value + is a member of any listed type T_i, then S_i is executed, + for the minimum such i. (Thus a NULL case is useful only if it + comes first.) If the value is a member of no listed type and + "ELSE S_0" is present, then it is executed. If the value is a member + of no listed type and "ELSE S_0" is absent, a checked runtime error + occurs. +
+ + Each (v_i) declares a variable whose type is T_i and + whose scope is S_i. If v_i is present, it is + initialized to the value of Expr before S_i is + executed. +
+ + If (v_i) is absent, then T_i can be a list of type + expressions separated by commas, as shorthand for a list in + which the rest of the branch is repeated for each type expression. + That is: +
+ T_1, ..., T_n => S +
+is shorthand for: +
+ T_1 => S | ... | T_n => S +
++ + For example: +
+ PROCEDURE ToText(r: REFANY): TEXT = + (* Assume r = NIL or r^ is a BOOLEAN or INTEGER. *) + BEGIN + TYPECASE r OF + NULL => RETURN "NIL" + | REF BOOLEAN (rb) => RETURN Fmt.Bool(rb^) + | REF INTEGER (ri) => RETURN Fmt.Int(ri^) + END + END ToText; +
+ ++ Last modified on Wed Apr 3 09:38:52 PST 1996 by heydon + modified on Mon Apr 18 14:08:25 PDT 1994 by kalsow +
+ + Index: m3/pm3/language/modula3/src/m3defn/typeops.html diff -c /dev/null m3/pm3/language/modula3/src/m3defn/typeops.html:1.2 *** /dev/null Tue Feb 10 23:31:57 1998 --- m3/pm3/language/modula3/src/m3defn/typeops.html Tue Feb 10 22:59:19 1998 *************** *** 0 **** --- 1,135 ---- + + +Modula-3: Type operations + + + +Type operations
++ +
+ ISTYPE (x: Reference; T: RefType) : BOOLEAN +
+ISTYPE(x, T) is TRUE if and only if x is a member + of T. T must be an object type or traced reference + type, and x must be assignable to T. + +
+ NARROW (x: Reference; T: RefType): T +
+NARROW(x, T) returns x after checking that x is + a member of T. If the check fails, a runtime error occurs. + T must be an object type or traced reference type, + and x must be assignable to T. +
+ +
+ TYPECODE (T: RefType) : CARDINAL + (r: REFANY) : CARDINAL + (r: UNTRACED ROOT) : CARDINAL +
+Every object type or traced reference type (including NULL) + has an associated integer code. Different types have different + codes. The code for a type is constant for any single execution + of a program, but may differ for different executions. + TYPECODE(T) returns the code for the type T and + TYPECODE(r) returns the code for the allocated type of r. + It is a static error if T is REFANY or is not an object + type or traced reference type. +
+ +
+ ORD (element: Ordinal): INTEGER + VAL (i: INTEGER; T: OrdinalType): T +
+ORD converts an element of an enumeration to the integer that + represents its position in the enumeration order. The first value + in any enumeration is represented by zero. If the type + of element is a subrange of an enumeration T, the result + is the position of the element within T, not within the subrange. +
+ + VAL is the inverse of ORD; it converts from a numeric + position i into the element that occupies that position in + an enumeration. If T is a subrange, VAL returns the + element with the position i in the original enumeration type, + not the subrange. It is a checked runtime error for the value + of i to be out of range for T. +
+ + If n is an integer, ORD(n) = VAL(n, INTEGER) = n. +
+ +
+ NUMBER (T: OrdinalType) : CARDINAL + (A: FixedArrayType) : CARDINAL + (a: Array) : CARDINAL +
+For an ordinal type T, NUMBER(T) returns the number of + elements in T. + For a fixed array type A, NUMBER(A) is defined by + NUMBER(IndexType(A)). Similarly, for an array a, + NUMBER(a) is defined by NUMBER(IndexType(a)). In + this case, the expression a will be evaluated only if it + denotes an open array. +
+ +
+ FIRST (T: OrdinalType) : BaseType(T) + (T: FloatType) : T + (A: FixedArrayType) : BaseType(IndexType(A)) + (a: Array) : BaseType(IndexType(a)) + + LAST (T: OrdinalType) : BaseType(T) + (T: FloatType) : T + (A: FixedArrayType) : BaseType(IndexType(A)) + (a: Array) : BaseType(IndexType(a)) +
+For a non-empty ordinal type T, FIRST returns the + smallest value of T and LAST returns the largest + value. If T is the empty enumeration, FIRST(T) and + LAST(T) are static errors. If T is any other empty + ordinal type, the values returned are implementation-dependent, + but they satisfy FIRST(T) > LAST(T). +
+ + For a floating-point type T, FIRST(T) and LAST(T) + are the smallest and largest values of the type, respectively. + On IEEE implementations, these are minus and plus infinity. +
+ + For a fixed array type A, FIRST(A) is defined by + FIRST(IndexType(A)) and LAST(A) by + LAST(IndexType(A)). + Similarly, for an array a, + FIRST(a) and LAST(a) are defined by + FIRST(IndexType(a)) and LAST(IndexType(a)). + The expression a will be evaluated only if it is an open array. + Note that if a is an open array, + FIRST(a) and LAST(a) + have type INTEGER. +
+ +
+ BITSIZE (x: Any) : CARDINAL + (T: Type) : CARDINAL + + BYTESIZE (x: Any) : CARDINAL + (T: Type) : CARDINAL + + ADRSIZE (x: Any) : CARDINAL + (T: Type) : CARDINAL +
+These operations return the size of the variable x or of + variables of type T. BITSIZE returns the number of bits, + BYTESIZE the number of 8-bit bytes, and ADRSIZE the number + of addressable locations. In all cases, x must be a designator + and T must not be an open array type. A designator x + will be evaluated only if its type is an open array type. + +
+ Last modified on Wed Apr 3 09:38:52 PST 1996 by heydon + modified on Mon Apr 18 13:43:59 PDT 1994 by kalsow +
+ + Index: m3/pm3/language/modula3/src/m3defn/types.html diff -c /dev/null m3/pm3/language/modula3/src/m3defn/types.html:1.2 *** /dev/null Tue Feb 10 23:31:57 1998 --- m3/pm3/language/modula3/src/m3defn/types.html Tue Feb 10 22:59:19 1998 *************** *** 0 **** --- 1,82 ---- + + +Modula-3: Types + + + +Types
++ +
++ I am the voice of today, the herald of tomorrow... + I am the leaden army that conquers the world---I am TYPE. + ---Frederic William Goudy +
+ + Modula-3 + uses structural equivalence, instead of the name equivalence + of Modula-2. Two types are the same if their definitions become the + same when expanded; that is, when all constant expressions are replaced + by their values and all type names are replaced by their definitions. + In the case of recursive types, the expansion is the infinite limit + of the partial expansions. A type expression is generally allowed + wherever a type is required. +
+ + A + type is empty if it contains no values. For example, + [1..0] is an empty type. Empty types can be used to build non-empty + types (for example, SET OF [1..0], which is not empty because + it contains the empty set). It is a static error to declare a variable + of an empty type. +
+ + Every expression has a statically-determined type, which contains + every value that the expression can produce. The type of a designator + is the type of the variable it produces. +
+ + Assignability and type compatibility are defined in terms of a single + syntactically specified subtype relation with the property that if + T is a subtype of U, then every member of T + is a member of U. The subtype relation is reflexive and transitive. +
+ + Every expression has a unique type, but a value can be a member of + many types. For example, the value 6 is a member of both + [0..9] and INTEGER. It would be ambiguous to talk + about "the type of a value". Thus the phrase "type of x" + means "type of the expression x", while "x is a + member of T" means "the value of x is a member of + T". +
+ + However, + there is one sense in which a value can be said to have + a type: every object or traced reference value includes a code + for a type, called the allocated type of the reference value. + The allocated type is tested by TYPECASE. +
+ + The type constructors and subtyping rules are discussed below +
-
+
- Ordinal types +
- Floating-point types +
- Array types +
- Record types +
- Packed types +
- Set types +
- Reference types +
- Procedure types +
- Object types +
- Subtyping rules +
- Predeclared opaque types +
+ Last modified on Wed Apr 3 09:38:54 PST 1996 by heydon + modified on Thu Apr 14 15:43:24 PDT 1994 by kalsow +
+ + Index: m3/pm3/language/modula3/src/m3defn/units.html diff -c /dev/null m3/pm3/language/modula3/src/m3defn/units.html:1.2 *** /dev/null Tue Feb 10 23:31:57 1998 --- m3/pm3/language/modula3/src/m3defn/units.html Tue Feb 10 22:59:19 1998 *************** *** 0 **** --- 1,82 ---- + + +Modula-3: Modules and interfaces + + + +Modules and interfaces
+ +
++ Art, it seems to me, should simplify. That, indeed, is very nearly + the whole of the higher artistic process; finding what conventions + of form and what detail one can do without and yet preserve the spirit + of the whole. + ---Willa Cather +
+ + A + module is like a block, except for the visibility of names. + An entity is visible in a block if it is declared in the block + or in some enclosing block; an entity is visible in a module if + it is declared in the module or in an interface that is imported + or exported by the module. +
+ + An + interface is a group of declarations. Declarations in + interfaces are the same as in blocks, except that any variable + initializations must be constant, and procedure declarations must specify + only the signature, not the body. +
+ + A module X exports an interface I to supply bodies + for one or more of the procedures declared in the interface. A module + or interface X imports an interface I to make the + entities declared in I visible in X. +
+ + A + program is a collection of modules and interfaces that contains + every interface imported or exported by any of its modules or + interfaces, and in which no procedure, module, or interface is multiply + defined. The effect of executing a program is to execute the bodies + of each of its modules. The order of execution of the modules is + constrained by the initialization rule. +
+ + The + module whose body is executed last is called the main module. + Implementations are expected to provide a way to specify the main + module, in case the initialization rule does not determine it uniquely. + The recommended rule is that the main module be the one that exports + the interface Main, whose contents are implementation-dependent. +
+ + Program + execution terminates when the body of the main module + terminates, even if concurrent threads of control are still executing. +
+ + The names of the modules and interfaces of a program are called + global names. The method for looking up global names---for example, + by file system search paths---is implementation-dependent. +
+ + The following topics are discussed below +
-
+
- Import statements +
- Interfaces +
- Modules +
- An example interface and module +
- Generics +
- Initialization +
- Safety +
+ Last modified on Tue Oct 3 17:29:56 PDT 1995 by heydon + modified on Mon Apr 18 13:44:15 PDT 1994 by kalsow +
+ + Index: m3/pm3/language/modula3/src/m3defn/unsafe.html diff -c /dev/null m3/pm3/language/modula3/src/m3defn/unsafe.html:1.2 *** /dev/null Tue Feb 10 23:31:57 1998 --- m3/pm3/language/modula3/src/m3defn/unsafe.html Tue Feb 10 22:59:19 1998 *************** *** 0 **** --- 1,115 ---- + + +Modula-3: Unsafe operations + + + + +Unsafe operations
++ +
++ There are some cases that no law can be framed to cover. + ---Aristotle +
+ + The + features defined in this section can potentially cause unchecked + runtime errors and are thus forbidden in safe interfaces and modules. +
+ + An + unchecked type transfer operation has the form: +
+ LOOPHOLE(e, T) +
+where e is an expression whose type is not an open array type + and T is a type. It denotes e's bit pattern + interpreted as a variable or value of type T. It is a designator + if e is, and is writable if e is. + An unchecked runtime error can occur if e's bit pattern + is not a legal T, or if e + is a designator and some legal bit pattern for T is not legal + for e. +
+ + If T is not an open array type, BITSIZE(e) must equal + BITSIZE(T). If T is an open array type, its element type + must not be an open array type, and e's bit pattern is interpreted + as an array whose length is BITSIZE(e) divided by + BITSIZE(the element type of T). + The division must come out even. +
+ + The + following operations are primarily used for address arithmetic: +
+ ADR (VAR x: Any) : ADDRESS + + infix + (x: ADDRESS, y:INTEGER) : ADDRESS + infix - (x: ADDRESS, y:INTEGER) : ADDRESS + infix - (x,y: ADDRESS) : INTEGER +
+ADR(x) is the address of the variable x. The actual + argument must be a designator but need not be writable. + The operations + + and - treat addresses as integers. The validity of the + addresses produced by these operations is implementation-dependent. + For example, the address of a variable in a local procedure frame + is probably valid only for the duration of the call. The address + of the referent of a traced reference is probably valid only as long + as traced references prevent it from being collected (and not even + that long if the implementation uses a compacting collector). +
+ + In + unsafe modules the INC and DEC statements apply to + addresses as well as ordinals: +
+ INC (VAR x: ADDRESS; n: INTEGER := 1) + DEC (VAR x: ADDRESS; n: INTEGER := 1) +
+These are short for x := x + n and x := x - n, except that + x is evaluated only once. +
+ + A + DISPOSE statement has the form: +
+ DISPOSE (v) +
+where v is a writable designator whose type is not REFANY, + ADDRESS, or NULL. If v is untraced, the statement + frees the storage for v's referent and sets v to + NIL. + Freeing storage to which active references remain is an unchecked + runtime error. If v is traced, the statement is equivalent to + v := NIL. If v is NIL, the statement is a no-op. +
+ + In + unsafe interfaces and modules the definition of "assignable" for + types is extended: + two reference types T and U are assignable + if T <: U or U <: T. + The only effect of this change is to allow a value of + type ADDRESS to be assigned to a variable of type + UNTRACED REF T. It is an unchecked runtime error if the value does + not address a variable of type T. +
+ + In + unsafe interfaces and modules the type constructor UNTRACED REF T + is allowed for traced as well as untraced T, and the fields of + untraced objects can be traced. If u is an untraced reference + to a traced variable t, then the validity of the traced references + in t is implementation-dependent, since the garbage collector + probably will not trace them through u. + +
+ Last modified on Wed Apr 3 09:38:52 PST 1996 by heydon + modified on Tue Jul 12 08:05:48 PDT 1994 by kalsow +
+ + Index: m3/pm3/language/modula3/src/m3defn/variables.html diff -c /dev/null m3/pm3/language/modula3/src/m3defn/variables.html:1.2 *** /dev/null Tue Feb 10 23:31:57 1998 --- m3/pm3/language/modula3/src/m3defn/variables.html Tue Feb 10 22:59:20 1998 *************** *** 0 **** --- 1,58 ---- + + +Modula-3: Variable declarations + + + +Variables
++ + If id is an identifier, T a non-empty type other than + an open array type, and E an expression, then: +
+ VAR id: T := E +
+declares id as a variable of type T whose initial value + is the value of E. Either ":= E" or ": T" + can be omitted, but not both. If T is omitted, it is taken + to be the type of E. If E is omitted, the initial value + is an arbitrary value of type T. If both are present, + E must be assignable to T. +
+ + The + initial value is a shorthand that is equivalent to inserting the + assignment id := E at the beginning of the executable + part of the block. + If several variables have initial values, their assignments are inserted + in the order they are declared. For example: +
+ VAR i: [0..5] := j; j: [0..5] := i; BEGIN S END +
+initializes i and j to the same arbitrary value + in [0..5]; + it is equivalent to: +
+ VAR i: [0..5]; j: [0..5]; BEGIN i := j; j := i; S END +
+ +If a sequence of identifiers share the same type and initial value, + id can be a list of identifiers separated by commas. Such + a list is shorthand for a list in which the type and + initial value are repeated for each identifier. + That is: +
+ VAR v_1, ..., v_n: T := E +
+is shorthand for: +
+ VAR v_1: T := E; ...; VAR v_n: T := E +
+This means that E is evaluated n times. + +
+ Last modified on Wed Apr 3 09:38:51 PST 1996 by heydon + modified on Mon Apr 18 14:08:32 PDT 1994 by kalsow +
+ + Index: m3/pm3/language/modula3/src/m3defn/while.html diff -c /dev/null m3/pm3/language/modula3/src/m3defn/while.html:1.2 *** /dev/null Tue Feb 10 23:31:57 1998 --- m3/pm3/language/modula3/src/m3defn/while.html Tue Feb 10 22:59:20 1998 *************** *** 0 **** --- 1,25 ---- + + +Modula-3: While statements + + + +While
++ + If B is an expression of type BOOLEAN + and S is a statement: +
+ WHILE B DO S END +
+is shorthand for: +
+ LOOP IF B THEN S ELSE EXIT END END +
+ ++ Last modified on Wed Apr 3 09:38:51 PST 1996 by heydon + modified on Mon Apr 18 14:08:38 PDT 1994 by kalsow +
+ + Index: m3/pm3/language/modula3/src/m3defn/with.html diff -c /dev/null m3/pm3/language/modula3/src/m3defn/with.html:1.2 *** /dev/null Tue Feb 10 23:31:57 1998 --- m3/pm3/language/modula3/src/m3defn/with.html Tue Feb 10 22:59:20 1998 *************** *** 0 **** --- 1,55 ---- + + +Modula-3: With statements + + + +With
++ + A WITH statement has the form: +
+ WITH id = e DO S END +
+where id is an identifier, e an expression, + and S a statement. + The statement declares id with scope S as an + alias for the variable e or as a readonly name for + the value e. The expression e is evaluated once, at entry + to the WITH statement. +
+ + The statement is like the procedure call P(e), where P + is declared as: +
+ PROCEDURE P(mode id: type of e) = BEGIN S END P; +
+If e is a + writable designator, + mode is VAR; otherwise, + mode is READONLY. + The only difference + between the WITH statement and the call P(e) is that free + variables, RETURNs, and EXITs that occur in the WITH + statement are interpreted in the context of the WITH statement, + not in the context of P. +
+ + A + single WITH can contain multiple bindings, which are evaluated + sequentially. That is: +
+ WITH id_1 = e_1, id_2 = e_2, ... +
+is equivalent to: +
+ WITH id_1 = e_1 DO + WITH id_2 = e_2 DO .... +
+ ++ Last modified on Wed Apr 3 09:38:51 PST 1996 by heydon + modified on Mon Dec 19 08:18:03 PST 1994 by kalsow +
+ + Index: m3/pm3/language/modula3/src/m3defn/word-intf.html diff -c /dev/null m3/pm3/language/modula3/src/m3defn/word-intf.html:1.2 *** /dev/null Tue Feb 10 23:31:57 1998 --- m3/pm3/language/modula3/src/m3defn/word-intf.html Tue Feb 10 22:59:20 1998 *************** *** 0 **** --- 1,103 ---- + + +Modula-3: Word interface + + + +The Word interface
++ +
+ INTERFACE Word; + + TYPE T = INTEGER; + + CONST Size = BITSIZE(T); +
+A Word.T w represents a sequence of Word.Size bits + w_0, ..., w_(Word.Size-1). + It also represents the unsigned number SUM (w_i * 2^i). + Finally, it also represents a signed INTEGER by some + implementation-dependent encoding (for example, two's complement). + The built-in operations of the language deal with the signed value; + the operations in this interface deal with the unsigned value or with + the bit sequence. +
+ + Here are the arithmetic operations on unsigned words: +
+ PROCEDURE Plus (x,y: T): T; (* (x + y) MOD 2^Word.Size *) + PROCEDURE Times (x,y: T): T; (* (x * y) MOD 2^Word.Size *) + PROCEDURE Minus (x,y: T): T; (* (x - y) MOD 2^Word.Size *) + PROCEDURE Divide(x,y: T): T; (* x DIV y *) + PROCEDURE Mod(x,y: T): T; (* x MOD y *) + PROCEDURE LT(x,y: T): BOOLEAN; (* x < y *) + PROCEDURE LE(x,y: T): BOOLEAN; (* x <= y *) + PROCEDURE GT(x,y: T): BOOLEAN; (* x > y *) + PROCEDURE GE(x,y: T): BOOLEAN; (* x >= y *) +
++ + And here are the logical operations on bit sequences: +
+ PROCEDURE And(x,y: T): T; (* Bitwise AND of x and y *) + PROCEDURE Or (x,y: T): T; (* Bitwise OR of x and y *) + PROCEDURE Xor(x,y: T): T; (* Bitwise XOR of x and y *) + PROCEDURE Not (x: T): T; (* Bitwise complement of x *) +
++ + And here are additional operations on bit sequences: +
+ +
+ PROCEDURE Shift(x: T; n: INTEGER): T; +
+For all i such that both i and i - n + are in the range + [0..Word.Size - 1], bit i of the result equals + bit i - n of x. + The other bits of the result are 0. + Thus shifting by n > 0 is like multiplying by 2^n. +
+ + Since Modula-3 has no exponentiation operator, Word.Shift(1, n) + is the usual way of writing 2^n in a constant expression. +
+ +
+ PROCEDURE Rotate(x: T; n: INTEGER): T; +
+Bit i of the result is bit ((i - n) MOD Word.Size) + of x. +
+ +
+ PROCEDURE Extract(x: T; i, n: CARDINAL): T; +
+Take n bits from x, with bit i as the + least significant bit, and return them as the least significant + n bits of a word whose other bits are 0. + A checked runtime error if n + i > Word.Size. +
+ +
+ PROCEDURE Insert(x: T; y: T; i, n: CARDINAL): T; +
+Result of replacing n bits of x, + with bit i as the least + significant bit, by the least significant n bits of y. + The other bits of x are unchanged. A checked runtime + error if n + i > Word.Size. +
+ +
+ END Word. +
+ ++ Last modified on Wed Apr 3 09:38:50 PST 1996 by heydon + modified on Thu Jun 1 08:12:58 PDT 1995 by kalsow +
+ + Index: m3/pm3/language/parsing/metasyntax/src/index.html diff -c /dev/null m3/pm3/language/parsing/metasyntax/src/index.html:1.1.1.1 *** /dev/null Tue Feb 10 23:32:01 1998 --- m3/pm3/language/parsing/metasyntax/src/index.html Sat Jan 31 14:47:13 1998 *************** *** 0 **** --- 1,36 ---- + +Meta Syntax parsing library + + ++ Michel Dagenais + Michel Dagenais, GNU General Public License, 1998 + + michel.dagenais@polymtl.ca+
+ Ecole Polytechnique
+ C.P. 6079, Succ. Centre-Ville
+ Montreal, Quebec, H3C 3A7 + 18 January 1998 + parsing + LL + recursive descent +Meta Syntax parsing library
+ +++ +This simple parsing library reads an LL grammar at run time and + calls user defined actions when specified grammar events are found. + It is used by the obliq interpreter. +
-
+
- metasyn
- + The Meta Syntax library. +
- synex
- + Scanner and parser for metasyn. +
- synloc
- + Library defining locations in source files. +
Parsing tools + + ++ Michel Dagenais + Michel Dagenais, GNU General Public License, 1998 + + michel.dagenais@polymtl.ca+
+ Ecole Polytechnique
+ C.P. 6079, Succ. Centre-Ville
+ Montreal, Quebec, H3C 3A7 + 18 January 1998 + parsing +Parsing tools
+ +++ +Parser generators and other parsing libraries and programs. +
-
+
- m3coco
- + The Modula-3 COCO/R LL parser generator. +
- m3tasyntax
- + The meta syntax parsing library. +
Compilers, interpreters, and parsing tools + + ++ Michel Dagenais + Michel Dagenais, GNU General Public License, 1998 + + michel.dagenais@polymtl.ca+
+ Ecole Polytechnique
+ C.P. 6079, Succ. Centre-Ville
+ Montreal, Quebec, H3C 3A7 + 18 January 1998 + programming + compiler + interpreter + parsing + wide audience +Compilers, interpreters, and parsing tools
+ +++ +Compilers, interpreters, parsing, and programming tools. +
-
+
- modula3
- + The Modula-3 simple and efficient object oriented programming language. +
- parsing
- + Parsing tools. +
- m3obliq
- + Obliq a lightweight language for network objects. +
- slisp
- + A simple LISP embeddable interpreter. +
- m3quake
- + The quake simple scripting language. +
- tcl
- + Wrapper library for the TCL scripting language. +
The Modula-3 Standard Library + + ++ Michel Dagenais + Michel Dagenais, GNU General Public License, 1998 + + michel.dagenais@polymtl.ca+
+ Ecole Polytechnique
+ C.P. 6079, Succ. Centre-Ville
+ Montreal, Quebec, H3C 3A7 + 17 January 1998 + Modula-3 + library + wide audience +The Modula-3 Standard Library
+ +++ +This library complements the Core library with + a base set of data structures, algorithms, + input/output, operating system access, and runtime support modules. +
Some Useful Modula-3 Interfaces
+ +A subset of the interfaces implemented in the m3core and + libm3 libraries was carefully selected, reviewed and + documented by the interface police in the technical + report Some Useful Modula-3 Interfaces. + +
Data Structures
+ +-
+
- types contains interfaces for the primitive types, + to be used as arguments for generic modules. + +
- sequence is a generic module for sequences, + which subsume extensible vectors, stacks and queues. + +
- atom implements TEXT sharing for efficiently + storing and comparing identifiers or other text strings. + +
- list is a generic linked list module. + +
- sx implements lists of lists, with parsing and + formatting procedures, useful to represent symbolic expressions such as + lisp like data or programs. + +
- table is a generic key/value mapping implemented as + a hash table. + +
- sortedtable is a sorted generic key/value + mapping implemented as a tree. + +
- bundleintf is used to access bundled resources + (files needed at runtime such as bitmaps which were packaged with m3bundle). + +
- pqueue is a generic priority queue. +
Algorithms
+ + + +Input/Output and Operating System Access
+ +-
+
- rw contains input output operations on files and + devices. + +
- fmtlex implements conversions between TEXT and + the other primitive types (integer, float, boolean...). + +
- os interfaces to operating system services such as + processes and files manipulations. + +
- params accesses command line parameters and + environment variables. + +
- pickle offers automated binary storage and retrieval + of graphs of objects and records in memory. + +
Numerical Support
+ +-
+
- arith interfaces to the logarithmic functions. +
- sqrt implements square roots. +
- statistics computes simple statistics such + as mean and variance. +
Miscellaneous
+ +-
+
- etimer may be used to measure the elapsed time within + various sections of a program. + +
- geometry implements basic integer 2 dimensional + geometry objects and transformations. + +
- formatter implements a pretty printing Writer. + +
- perftool is used by runtime performance monitoring + tools such as shownew. + +
- property implements property lists. Generic Tables + are more flexible and should be used instead. + +
- uid provides unique identifiers and unique + timestamps. +
Copyright: SRC Modula-3 Digital License Agreement + + +Copyright: SRC Modula-3 Digital License Agreement
++
-
+
Grant Of License. Digital Equipment Corporation, having a principal + office at 146 Main Street, Maynard, MA 01754 ("DIGITAL") grants to + you ("LICENSEE") the non-exclusive, non-transferable, royalty free + right to use, modify, reproduce and distribute SRC Modula-3 ("SOFTWARE") + subject to the terms set forth herein. Any distribution of SOFTWARE + shall include this Digital License Agreement in human readable form. + +
Title to Intellectual Property and Software. Subject to the limited + rights and licenses granted under this License Agreement, all rights, + title and interests including patent, copyright, and trademark rights + in SOFTWARE are and shall remain vested in DIGITAL to the exclusion + of LICENSEE. DIGITAL represents and warrants that DIGITAL has the + legal right to grant such licenses as are expressly granted under + this Agreement. + +
Copyright. The SOFTWARE is owned by DIGITAL or its suppliers and is + protected by United Stats copyright laws and international treaty + provisions. Therefore, you must treat the SOFTWARE like any other + copyrighted material (e.g., a book or musical recording) except + that you may use the SOFTWARE as provided in this Digital License + Agreement. + +
Improvements. LICENSEE hereby grants to DIGITAL a non-exclusive, + non-transferable, royalty free right to use, modify, reproduce + and distribute with the right to sublicense at any tier, any + improvements, enhancements, extensions, or modifications that + LICENSEE make to SOFTWARE, provided such are returned to DIGITAL + by LICENSEE. + +
DISCLAIMER OF WARRANTY. Because the SOFTWARE is a research work and + not a released product, it is provided "AS IS" WITHOUT WARRANTY OF ANY + KIND AND WITHOUT ANY SUPPORT SERVICES. EXCEPT AS SPECIFICALLY PROVIDED + ABOVE IN SECTION 2, DIGITAL FURTHER DISCLAIMS ALL OTHER EXPRESS OR + IMPLIED WARRANTIES OF MERCHANTABILITY OR OF FITNESS FOR A PARTICULAR + PURPOSE. THE ENTIRE RISK ARISING OUT OF THE USE OR PERFORMANCE OF + THE SOFTWARE REMAINS WITH YOU. + +
Limitation of Liability. IN NO EVENT SHALL DIGITAL OR ITS SUPPLIERS BE + LIABLE IN AN AMOUNT THAT EXCEEDS THE LICENSE FEE PAID BY LICENSEE FOR + ANY DAMAGES (INCLUDING, WITH LIMITATION, DAMAGES FOR LOSS OF BUSINESS + PROFITS, BUSINESS INTERRUPTION, LOSS OF BUSINESS INFORMATION, OR OTHER + PECUNIARY LOSS), REGARDLESS OF THE FORM OF CLAIM OR ACTIONS, ARISING + OUT OF THE USE OF OR INABILITY TO USE THE SOFTWARE OR DOCUMENTATION, + EVEN IF DIGITAL HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. + BECAUSE SOME STATES DO NOT ALLOW THE EXCLUSION OR LIMITATION OF LIABILITY + FOR CONSEQUENTIAL OR INCIDENTAL DAMAGES, THE ABOVE LIMITATION MAY NOT + APPLY TO YOU. + +
Acknowledgement of Allocation of Risk. LICENSEE acknowledges and agrees + that the fees charged by DIGITAL in this Agreement reflect the allocation + of risks provided by the foregoing limitation of liability. LICENSEE + acknowledges and represents that it has read and understands these + allocations of risk limiting the liability of DIGITAL and that it + understands that a modification of the allocation of risks set forth + in this agreement would affect the fees charged by DIGITAL, and that + LICENSEE, in consideration of such fees, agrees to such allocations + of risk. + +
LICENSEE INDEMNIFICATION. LICENSEE SHALL INDEMNIFY DIGITAL AGAINST + ALL COSTS AND DAMAGE JUDGEMENTS, INCLUDING ATTORNEY'S FEES AND COSTS + OF DEFENSE, INCURRED BECAUSE OF CLAIMS OF DAMAGE ARISING FROM LICENSEE'S + POSSESSION OR USE OR INABILITY TO USE SOFTWARE. + +
GOVERNMENT RESTRICTED RIGHTS. The SOFTWARE and documentation are provided + with RESTRICTED RIGHTS. Use duplication, or disclosure by the Government + is subject restrictions as set forth in subparagraph (c)(1)(ii) of The + Rights in Technical Data and Computer Software clause in DFARS + 252.227-7013, or subparagraphs (c)(i) and (2) of the Commercial Computer + Software -- Restricted Rights at 48 CFR 52.227-19, as applicable. + Manufacturer is Digital Equipment Corporation, 130 Lytton Avenue, + Palo Alto, CA 94301-1044. + +
Severability. If any provision of the Agreement is held illegal or + unenforceable by any court of competent jurisdiction, such provision + shall be deemed separable from the remaining provisions of this Agreement + and shall not affect or impair the validity or enforceability of the + remaining provisions of this Agreement. + +
Governing Law. This Agreement is governed by the laws of the + Commonwealth of Massachusetts. + +
Publicity. You my not use the name of DIGITAL in any advertisement, + press release or other publicity with reference to SRC Modula-3 + without prior written consent of DIGITAL. + +
Should you have any questions concerning this Agreement, or if you + desire to contact Digital for any reason, please do so via E-mail: + M3-REQUEST@SRC.DEC.COM. +
+ + "Invalid" = invalid argument to an operation. + + "Inexact" = an operation produced an inexact result. + + "Overflow" = a floating-point operation produced a result whose + absolute value is too large to be represented. + + "Underflow" = a floating-point operation produced a result whose + absolute value is too small to be represented. + + "DivByZero" = floating-point division by zero. +
+ + The meaning of the last two flags is: + ++ + "IntOverflow" = an integer operation produced a result outside the + representable range. + + "IntDivByZero" = integer "DIV" or "MOD" by zero. +
+ *) + + CONST NoFlags = SET OF Flag {}; + + PROCEDURE GetFlags(): SET OF Flag; + (* Return the set of flags for the current thread. *) + + PROCEDURE SetFlags(s: SET OF Flag) + : SET OF Flag RAISES {Failure}; + (* Set the flags for the current thread to "s", and return their + previous values. *) + + PROCEDURE ClearFlag(f: Flag); + (* Turn off the flag "f" for the current thread. *) + + EXCEPTION Trap(Flag); + + TYPE Behavior = {Trap, SetFlag, Ignore}; + + (* The behavior of an operation that causes one of the flag conditions + is either: + ++ + "Ignore" = return some result and do nothing. + + "SetFlag" = return some result and set the condition flag. For + IEEE implementations, the result of the operation is defined by the + standard. + + "Trap" = possibly set the condition flag; in any case raise the + "Trap" exception with the appropriate flag as the argument. +
+ *) + + PROCEDURE SetBehavior(f: Flag; b: Behavior) RAISES {Failure}; + (* Set the behavior of the current thread for the flag "f" to be "b", + or raise "Failure" if this cannot be done. *) + + PROCEDURE GetBehavior(f: Flag): Behavior; + (* Return the behavior of the current thread for the flag "f". *) + + END FloatMode. Index: m3/pm3/libs/libm3/src/html/acks.html diff -c /dev/null m3/pm3/libs/libm3/src/html/acks.html:1.1 *** /dev/null Tue Feb 10 23:32:06 1998 --- m3/pm3/libs/libm3/src/html/acks.html Tue Feb 10 22:44:45 1998 *************** *** 0 **** --- 1,53 ---- +Acknowledgments +Acknowledgments
++ This manual builds on, and incorporates, the work of many people. + We've borrowed many ideas from the literature, as documented in the + references. But many other people have helped us design, implement, + and refine the specific interfaces published in this manual: +
+ Lyle Ramshaw orchestrated a redesign of the Fmt and Lex + interfaces and the addition of the ToDecimal and + FromDecimal procedures to the Float generic interface. David + Goldberg and Jorge Stolfi consulted. Luca Cardelli designed the first + version of Lex (which he called Sift). +
+ Atom, List, Sx, and Table are similar to + Modula-2+ versions designed by John Ellis. Jim Meehan collaborated on + the design of Sx. Eric Muller and Jorge Stolfi explored the use + of object types and generic interfaces for abstractions such as + tables. +
+ Wr and Rd were designed by Mark R. Brown and Greg Nelson + and closely follow the design of the Modula-2+ streams package. +
+ Pathname borrows from an earlier version written by Eric Muller. +
+ Jim Horning and John Guttag wrote formal Larch specifications of + File.T and its subtypes, and in the process asked questions leading + to substantial improvements to the specifications in this manual. +
+ Mick Jordan helped refine the operating-system interfaces and wrote + the first implementations of them. +
+ WeakRef was greatly improved through long and spirited + discussions involving Luca Cardelli, Dave Detlefs, John Ellis, John + DeTreville, Mick Jordan, Bill Kalsow, Mark Manasse, Ted Wobber, and + Garret Swart. John DeTreville provided the implementation. +
+ John DeTreville collaborated on the design of RTCollector and + the other runtime interfaces. +
+ Mary-Claire van Leunen encouraged us to begin. +
+ Finally, this manual was greatly improved by the group of people who + read earlier drafts and participated in a running discussion on an + electronic bulletin board: Ed Balkovich, Andrew Birrell, Hans Boehm, + Marc H. Brown, Mike Burrows, Luca Cardelli, Michel Dagenais, Alan + Demers, Dave Detlefs, Mike Dixon, John DeTreville, Steve Freeman, + Michel Gangnet, David Goldberg, Judy Hall, Dave Hanson, Carl Hauser, + Allan Heydon, Chuck Jerian, Butler Lampson, Mark Manasse, Eric Muller, + Hal Murray, David Nichols, Sharon Perl, Dave Redell, Eric Roberts, + Robert Sedgewick, Mike Spreitzer, Garret Swart, Samuel Weber, and Ted + Wobber. + Index: m3/pm3/libs/libm3/src/html/algorithm.html diff -c /dev/null m3/pm3/libs/libm3/src/html/algorithm.html:1.1 *** /dev/null Tue Feb 10 23:32:06 1998 --- m3/pm3/libs/libm3/src/html/algorithm.html Tue Feb 10 22:44:45 1998 *************** *** 0 **** --- 1,15 ---- +
Algorithms +Algorithms
+ + ++ The standard instances are named IntArraySort and + TextArraySort. (There are no instances for Atom.T or + REFANY since these types don't have a standard total order.) + +
Index: m3/pm3/libs/libm3/src/html/basic.html diff -c /dev/null m3/pm3/libs/libm3/src/html/basic.html:1.1 *** /dev/null Tue Feb 10 23:32:06 1998 --- m3/pm3/libs/libm3/src/html/basic.html Tue Feb 10 22:44:45 1998 *************** *** 0 **** --- 1,12 ---- +Basic Data Types +Basic Data Types
+ + ++ Note that the interfaces Text, Real, LongReal, + Extended, and Atom (which were presented in the main body of + this report) provide Equal, Hash, and Compare + procedures. Index: m3/pm3/libs/libm3/src/html/float.html diff -c /dev/null m3/pm3/libs/libm3/src/html/float.html:1.1 *** /dev/null Tue Feb 10 23:32:06 1998 --- m3/pm3/libs/libm3/src/html/float.html Tue Feb 10 22:44:46 1998 *************** *** 0 **** --- 1,86 ---- +
Real, LongReal, and Extended +Real, LongReal, and Extended
++ For definitions of the terms used in the floating-point interfaces, + see the ANSI/IEEE Standard 754-1985, IEEE Standard for Binary + Floating-Point Arithmetic. + floating-point + IEEE floating-point +
+ The interfaces Real, LongReal, and Extended + define constant + attributes of the three built-in floating-point types: + + floating-point + representation + + +
+ INTERFACE Real; TYPE T = REAL; + CONST + Base: INTEGER = ...; + Precision: INTEGER = ...; + MaxFinite: T = ...; + MinPos: T = ...; + MinPosNormal: T = ...; + MaxExpDigits: INTEGER = ...; + MaxSignifDigits: INTEGER = ...; + END Real. + + INTERFACE LongReal; TYPE T = LONGREAL; + CONST + Base: INTEGER = ...; + Precision: INTEGER = ...; + MaxFinite: T = ...; + MinPos: T = ...; + MinPosNormal: T = ...; + MaxExpDigits: INTEGER = ...; + MaxSignifDigits: INTEGER = ...; + END LongReal. + + INTERFACE Extended; TYPE T = EXTENDED; + CONST + Base: INTEGER = ...; + Precision: INTEGER = ...; + MaxFinite: T = ...; + MinPos: T = ...; + MinPosNormal: T = ...; + MaxExpDigits: INTEGER = ...; + MaxSignifDigits: INTEGER = ...; + END Extended. +
++ The specification is the same for all three interfaces: + +
+
+ ++ Base is the base of the floating-point representation for T. +
+ Precision is the number of base-Base digits of precision for T. +
+ MaxFinite is the maximum finite value in T. For non-IEEE + implementations, this is the same as LAST(T). +
+ MinPos is the minimum positive value in T. +
+ MinPosNormal is the minimum positive normal value in T; it + differs from MinPos only for implementations (like IEEE) with + denormalized numbers. +
+ MaxExpDigits is the smallest integer with the property that + every finite number of type T can be written in base-10 + scientific notation using an exponent with at most MaxExpDigits. +
+ MaxSignifDigits is the smallest integer with the property that + for every point x along the number line, the two + floating-decimal numbers with MaxSignifDigits closest to x are + closer to each other than are the two closest numbers of type T. +
+ Typically, + +
+ MaxExpDigits = CEILING(LOG_10(LOG_10(MaxFinite))) + MaxSignifDigits = CEILING(LOG_10(Base EXP Precision)) + 1. +
Index: m3/pm3/libs/libm3/src/html/intro.html diff -c /dev/null m3/pm3/libs/libm3/src/html/intro.html:1.1 *** /dev/null Tue Feb 10 23:32:06 1998 --- m3/pm3/libs/libm3/src/html/intro.html Tue Feb 10 22:44:46 1998 *************** *** 0 **** --- 1,349 ---- +Introduction +Introduction
++ Modula-3 invites you to structure your program as a set of modules + interconnected via interfaces. Each interface typically corresponds + to an abstract data type. Some of these abstractions are particular + to the program at hand, but others are more general. This manual + describes a collection of interfaces defining abstractions that SRC's + programmers have found useful over a number of years of experience + with Modula-3 and its precursors. + abstraction +
+ This manual concentrates on basic abstractions such as the standard + interfaces required or recommended by the Modula-3 language + definition, various data structures, portable operating-system + functions, and control of the Modula-3 runtime. For building + distributed systems, see + [NetObj] . + For building user interfaces, + see + [Trestle] , + [VBTkit] , + and [FormsVBT] . + +
Naming conventions for types.
++ We generally give the name T to the main type in an interface. For + example, the main type in the Date interface is Date.T. + + type + naming conventions for + + + naming conventions + types + + + T type + T type + + + type + T + T + +
+ Most object types have a method that is responsible for initializing + the object. By convention, this method is named init, and returns + the object after initializing it, so that the object can be + initialized and used in an expression at the same time: for example, +
+ ++ VAR s := NEW(Sequence.T).init(); +
+ ++ + initializing an object + + + init method + initmethod + + If there are several different ways to initialize the object, there + will be several methods. The most basic will be named init and the + others will receive descriptive names. For example, Sequence.T.init + initializes an empty sequence; Sequence.T.fromArray initializes a + sequence from an array. +
+ Many of our types are ``abstract'' in the sense that they define the + methods of a type, but not their implementations. Various subtypes of + the abstract type define different methods corresponding to different + instances of the abstract type. For example, the type Rd.T is a + abstract reader (a stream of input characters). Its subtype + FileRd.T is a reader whose source is a file; its subtype TextRd.T + is a reader whose source is a text string. + + abstract type + + + subtype + +
+ If you allocate an object of an abstract type and attempt to use it, + you will almost certainly get a checked runtime error, since its + methods will be NIL. Therefore, you must read the interfaces to + find out which types are abstract and which are concrete. The typical + pattern is that an abstract type does not have an init method, but + each of its concrete instances does. This allows different subtypes + to be initialized differently. For example, FileRd.T has an init + method that takes a file; TextRd.T has an init method that takes a + text; and Rd.T has no init method at all. +
+ For some abstract types we choose to honor one of its subtypes as a + ``default implementation''. For example, we provide a hash table + implementation as the default for the abstract type Table.T. In + this case we vary the naming convention: instead of a separate + interface HashTable defining the concrete type HashTable.T as a + subtype of Table.T, we declare the default concrete type in the same + interface with the abstract type and give it the name Default. Thus + Table.T and Table.Default are respectively the abstract table type + and its default implementation via hash tables. If you want to + allocate a table you must allocate a Table.Default, not a Table.T. + On the other hand, if you are defining a procedure that requires a + table as a parameter, you probably want to declare the parameter as a + Table.T, not a Table.Default, to avoid excluding other table + implementations. + + Default type + Default type + + + type + Default + Default + +
+ We use abstract types only when they seem advantageous. Thus the type + Sequence.T, which represents an extensible sequence, could have been + an abstract type, since different implementations are easy to imagine. + But engineering considerations argue against multiple implementations, + so we declared Sequence.T as a concrete type. + +
Concurrency.
++ The specification of a Modula-3 interface must explain how to use the + interface in a multithreaded program. When not otherwise specified, + each procedure or method is atomic: it transforms an initial + state to a final state with no intermediate states that can be + observed by other threads. + + concurrency + + + atomic execution + of procedures and methods + + + monitored data structure + +
+ Alternatively, a data structure (the state of an entire interface, or + of a particular instance of an object type) can be specified as + unmonitored, in which case the procedures and methods operating on it + are not necessarily atomic. In this case it is the client's + responsibility to ensure that multiple threads are not accessing the + data structure at the same time---or more precisely, that this happens + only if all the concurrent accesses are read-only operations. Thus for + an unmonitored data structure, the specification must state which + procedures or methods are read-only. +
+ If all operations are read-only, there is no difference between + monitored and unmonitored data structures. + +
Aliasing.
++ The procedures and methods defined in this manual are not guaranteed + to work with aliased VAR parameters. + + aliasing of VAR parameters + aliasing of VAR parameters + + +
Exception parameters for abstract types.
++ It is often useful for an exception to include a parameter providing + debugging information of use to the programmer, especially when the + exception signals abstraction failure. Different implementations of + an abstract type may wish to supply different debugging information. + By convention, we use the type AtomList.T for this purpose. The + first element of the list is an error code; the specification of the + subsequent elements is deferred to the subtypes. Portable modules + should treat the entire parameter as an opaque type. +
+ An implementation module can minimize the probability of collision by + prefixing its module name to each atom that it includes in the list. + +
Standard generic instances.
++ Several of the interfaces in this manual are generic. Unless + otherwise specified, standard instances of these interfaces are + provided for all meaningful combinations of the formal imports ranging + over Atom, Integer, Refany, and Text. + + standard instances of generic interfaces + +
+ For each interface that is likely to be used as a generic parameter, + we define procedures Equal, Compare, and Hash. +
+ The procedure Equal must compute an equivalence relation on the + values of the type; for example, Text.Equal(t, s) tests whether t + and s represent the same string. (This is different from t = s, + which tests whether t and s are the same reference.) + + Equal procedure + Equal procedure + +
+ If there is a natural total order on a type, then we define a + Compare procedure to compute it, as follows: + + Compare procedure + Compare procedure + + +
+ PROCEDURE Compare(x, y: X): [-1..1]; + (* Return + | -1 `if` x R y `and not` Equal(x, y)`,` + | 0 `if` Equal(x, y)`, and` + | 1 `if` y R x `and not` Equal(x, y)`.` + *) +
++ (Technically, Compare represents a total order on the equivalence + classes of the type with respect to Equal.) If there is no natural + order, we define a Compare procedure that causes a checked runtime + error. This allows you to instantiate generic routines that require + an order (such as sorting routines), but requires you to pass a + compare procedure as an explicit argument when calling the generic + routine. +
+ The function Hash is a hash function mapping values of a type T to + values of type Word.T. This means that (1) it is time-invariant, + (2) if t1 and t2 are values of type T such that Equal(t1, t2), + then Hash(t1) = Hash(t2), and (3) its range is distributed uniformly + throughout Word.T. + + Hash procedure + Hash procedure + +
+ Note that it is not valid to use LOOPHOLE(r, INTEGER) as a hash + function for a reference r, since this is not time-invariant on + implementations that use copying garbage collectors. + + hashing references + + +
Sets and relations.
++ The specifications in this manual are written informally but + precisely, using basic mathematical concepts. For completeness, here + are definitions of these concepts. +
+ A set is a collection of elements, without consideration of + ordering or duplication: two sets are equal if and only if they + contain the same elements. + + set + +
+ If X and Y are sets, a map m from X to Y uniquely + determines for each x in X an element y in Y; we write y = + m(x). We refer to the set X as the domain of m, or + dom(m) for short, and the set Y as the range of m. A + partial map from X to Y is a map from some subset of X to Y. + + map + + + function: map + + + domain + + + range + +
+ If X is a set, a relation R on X is a set of ordered pairs + (x, y) with x and y elements of X. We write x R y if + (x, y) is an element of R. + + relation + +
+ A relation R on X is reflexive if x R x for every x in + X; it is symmetric if x R y implies that y R x for every + x, y in X; it is transitive if x R y and y R z imply + x R z for every x, y, z in X; and it is an equivalence + relation if it is reflexive, symmetric, and transitive. + + equivalence relation + + + relation + equivalence + +
+ A relation R on X is antisymmetric if for every x and y + in X, x = y whenever both x R y and y R x; R is a total + order if it is reflexive, antisymmetric, transitive, and if, for + every x and y in X, either x R y or y R x. + + total order + + + relation + total order + +
+ If x and y are elements of a set X that is totally ordered by a + relation R, we define the interval [x..y] as the set of all + z in X such that x R z and z R y. Note that the notation + doesn't mention R, which is usually clear from the context (e.g., + lower or equal for numbers). We say [x..y] is closed at its upper and + lower endpoints because it includes x and y. Half-open and open + intervals exclude one or both endpoints; notationally we substitute a + parenthesis for the corresponding bracket, for example [x..y) or + (x..y). + + interval + +
+ A sequence s is a map whose domain is a set of consecutive + integers. In other words, if dom(s) is not empty, there are + integers l and u, with l<=u, such that dom(s) is [l..u]. We + often write s[i] instead of s(i), to emphasize the similarity to a + Modula-3 array. If the range of s is Y, we refer to s as a + sequence of Y's. The length of a sequence s, or len(s), + is the number of elements in dom(s). + + sequence + +
+ In the specifications, we often speak of assigning to an element of a + sequence or map, which is really a shorthand for replacing the + sequence or map with a suitable new one. That is, assigning m(i) := + x is like assigning m := m', where dom(m') is the union of + dom(m) and {i}, where m'(i) = x, and where m'(j) = m(j) for + all j different from i and in dom(m). +
+ If s is a finite sequence, and R is a total order on the range of + s, then sorting s means to reorder its elements so that for + every pair of indexes i and j in dom(s), s[i] R s[j] whenever + i <= j. We say that a particular sorting algorithm is stable + if it preserves the original order of elements that are equivalent + under R. + + sorting + + + stability of sorting algorithm + + + Index: m3/pm3/libs/libm3/src/html/io.html diff -c /dev/null m3/pm3/libs/libm3/src/html/io.html:1.1 *** /dev/null Tue Feb 10 23:32:06 1998 --- m3/pm3/libs/libm3/src/html/io.html Tue Feb 10 22:44:46 1998 *************** *** 0 **** --- 1,36 ---- +
I/O Streams +I/O Streams
++ The interfaces Wr and Rd provide object-oriented output + and input streams, called writers and readers. These were + invented by Stoy and Strachey in 1972 + [OS6part2] . + The versions + presented here are slight modifications of the versions in the first + Modula-3 book [SPwM3] . + We also present related interfaces for + obtaining writers and readers connected to texts or files ( + TextWr, TextRd, FileWr, and FileRd), for accessing + standard streams (Stdio), and for performing I/O in simple + programs (IO). The interfaces FileWr and FileRd + supersede the interface FileStream in + [SPwM3] . + + + I/O + buffered streams + + + stream + + +
-
+
- The IO interface +
- The Wr interface +
- The Rd interface +
- The TextWr interface +
- The TextRd interface +
- The Stdio interface +
- The FileWr interface +
- The FileRd interface +
Operating System +Operating System
++ The interfaces in this section provide access to operating system + facilities: timekeeping, files, pathnames, directories, and processes. + The interfaces are intended to be implementable at least on POSIX + [POSIX] and Win32 + [Win32] systems. + +
-
+
- The Time interface +
- The Date interface +
- The Tick interface +
- The OSError interface +
- The File interface +
- The Pipe interface +
- The Terminal interface +
- The RegularFile interface +
- The Pathname interface +
- The FS interface +
- The Process interface +
- The Params interface +
- The Env interface +
RealFloat, LongRealFloat, and ExtendedFloat +RealFloat, LongRealFloat, and ExtendedFloat
++ The interfaces RealFloat, LongRealFloat, and ExtendedFloat + define operations that depend on the floating-point representation. + Each one is an instance of a generic interface Float: + + floating-point + operations + + +
+ INTERFACE RealFloat = Float(Real) END RealFloat. + INTERFACE LongFloat = Float(LongReal) END LongFloat. + INTERFACE ExtendedFloat = Float(Extended) END ExtendedFloat. +
+ + + Index: m3/pm3/libs/libm3/src/html/references.html diff -c /dev/null m3/pm3/libs/libm3/src/html/references.html:1.1 *** /dev/null Tue Feb 10 23:32:06 1998 --- m3/pm3/libs/libm3/src/html/references.html Tue Feb 10 22:44:46 1998 *************** *** 0 **** --- 1,202 ---- +References +References
+ +-
+
+
- [Aragon]
-
+ + Cecilia Aragon + Raimund Seidel + Randomized Search Trees + Proceedings 30th FOCS + 1989 ++ +
- [broder]
-
+ + Andrei Broder + Some Applications of Rabin's Fingerprinting Method + Sequences II: Methods in Communications, Security, + and Computer Science + Renato Capocelli and De Santis, Alfredo and Ugo Vaccaro, + editors + Springer-Verlag + 1993 + 143-152 ++ +
- [ExpProcMon]
-
+ + Butler W. Lampson + David D. Redell + Experience with Processes and Monitors in {M}esa + Communications of the ACM + 23 + 2 + February + 1980 ++ +
- [FormsVBT]
-
+ + Marc H. Brown + James R. Meehan + FormsVBT Reference Manual + Digital Equipment Corporation Systems Research Center + + Research Report, To appear. ++ +
- [Gay]
-
+ + David M. Gay + + Correctly Rounded Binary-Decimal and Decimal-Binary Conversions + AT&T Bell Laboratories + November 30 + 1990 + Numerical Analysis Manuscript + 90-10 ++ +
- [KnuthVol2]
-
+ + Donald E. Knuth + Seminumerical Algorithms + Addison Wesley + 1981 + second edition ++ +
- [NetObj]
-
+ + Andrew Birrell + Greg Nelson + Susan Owicki + Edward Wobber + Network Objects + + Proceedings of the 14th Symposium on Operating Principles + December + 1993 ++ +
- [M2+]
-
+ + Paul Rovner + Roy Levin + John Wick + + On Extending Modula-2 for building large, integrated systems + Digital Equipment Corporation Systems Research Center + + Research Report + 3 + January + 1985 ++ +
- [Monitors]
-
+ + C. A. R. Hoare + Monitors: An Operating System Structuring Concept + Communications of the ACM + 17 + 10 + October + 1974 ++ +
- [OS6part2]
-
+ + J. E. Stoy + C. Strachey + OS6-An Experimental Operating System for a Small Computer. + Part 2: Input/Output and Filing System + The Computer Journal + 15 + 3 + May + 1972 ++ +
- [POSIX]
-
+ + IEEE Technical Committee on Operating Systems + Standard Portable Operating System Interface + for Computer Environments + IEEE + Standard 1003.1-1988 + 1988, ++ +
- [Rabin]
-
+ + M. O. Rabin + Fingerprinting by Random Polynomials + Department of Computer Science, Harvard University + + Report + TR-15-81 + 1981 ++ +
- [SedgewickAlg]
-
+ + Robert Sedgewick, + Algorithms + Addison-Wesley + 1983 ++ +
- [SPwM3]
-
+ + Greg Nelson, + Systems Programming with Modula-3 + Prentice Hall + 1991 ++ +
- [Steele]
-
+ + Guy L. Steele Jr. + Jon L. White + How to Print Floating-Point Numbers Accurately + + Proceedings of the ACM SIGPLAN '90 Conference on Programming + Language Design and Implementation + 1990 ++ +
- [Trestle]
-
+ + Mark S. Manasse + Greg Nelson + Trestle Reference Manual + Digital Equipment Corporation Systems Research Center + + December + 1991 + Research Report + 68 ++ +
- [VBTkit]
-
+ + Marc H. Brown + James R. Meehan + VBTkit Reference Manual + Digital Equipment Corporation Systems Research Center + + Research Report + To appear ++ +
- [Win32]
-
+ + Microsoft Corporation + Microsoft Win32 Programmer's Reference + Microsoft Press + 1993 ++
Runtime +Runtime
+ + + ++ The remaining interfaces in this section provide the low-level + features needed to implement pickles and network objects. Most + programmers won't directly use any of these interfaces. + +
-
+
- The RTType interface +
- The RTAllocator interface +
- The RTCollector interface +
- The RTHeap interface +
- The RTTypeFP interface +
Standard interfaces +Standard interfaces
++ This section presents the interfaces required by every Modula-3 + implementation. The versions included here have some minor changes + and additions to the versions in [SPwM3] . +
+
++ Text provides operations on text strings. +
+ Thread provides synchronization primitives for multiple + threads of control. +
+ Word provides operations on unsigned words. +
+ Real, LongReal, and ExtendedReal define the + properties of the three floating-point types; for example, their + bases and ranges. +
+ RealFloat, LongRealFloat, and ExtendedFloat + provide numerical operations related to the floating-point + representation; for example, extracting the exponent of a number. +
+ FloatMode provides operations for testing (and possibly + setting) the behavior of the implementation in response to numeric + conditions; for example, overflow. +
+ This section also presents two related interfaces provided by SRC + Modula-3 and recommended to other implementers, but not required: +
+
+ ++ Lex provides for parsing numbers and other data from an + input stream. +
+ Fmt provides for textual formatting of numbers and other data. +
-
+
- The Text interface +
- The Thread interface +
- The Word interface +
- Real, LongReal, and Extended +
- RealFloat, LongRealFloat, and ExtendedFloat +
- The FloatMode interface +
- The Lex interface +
- The Fmt interface +
Data Structures +Data Structures
+ + + ++ The standard instances are named AtomSeq, IntSeq, + RefSeq, and TextSeq. + +
++ The standard instances are named AtomList, IntList, + RefList, and TextList. + +
++ The standard instances are named AtomListSort, + IntListSort, RefListSort, and TextListSort. + AtomListSort and RefListSort are useful only if you supply a + non-default comparison procedure. + +
++ The standard instances are named xyTbl, for all combinations of + x and y in the set {Atom, Int, Ref, Text}. The + instances with x = Ref are useful only if you define a subtype + overriding the keyHash and keyEqual methods. + +
++ The standard instances are named SortedxyTbl, for all + combinations of x and y in the set {Atom, Int, Ref, + Text}. The instances with x = Atom and x = Ref are + useful only if you define a subtype overriding the keyCompare + method. + +
+ Index: m3/pm3/libs/libm3/src/html/useful.html diff -c /dev/null m3/pm3/libs/libm3/src/html/useful.html:1.1 *** /dev/null Tue Feb 10 23:32:06 1998 --- m3/pm3/libs/libm3/src/html/useful.html Tue Feb 10 22:44:47 1998 *************** *** 0 **** --- 1,62 ---- + + +Some Useful Modula-3 Interfaces + + ++ Jim Horning + Bill Kalsow + Paul McJones + Greg Nelson + Digital Equipment Corporation 1993 + + Systems Research Center+
+ 130 Lytton Avenue
+ Palo Alto, California 94301 + December 25, 1993 + text + io + system + algorithm + data structure + thread + runtime + mature + wide audience + reusable +Some Useful Modula-3 Interfaces
+ +++ +-
+
- Acknowledgments +
++ +This manual describes a collection of interfaces defining abstractions + that SRC's programmers have found useful over a number of years of + experience with Modula-3 and its precursors. We hope the interfaces + will be useful as a ``starter kit'' of abstractions, and as a model + for designing and specifying abstractions in Modula-3. +
-
+
- Introduction +
- Standard interfaces +
- Data structures +
- Algorithms +
- I/O Streams +
- Operating System +
- Runtime +
- Basic Data Types +
- References +
++ + Index: m3/pm3/libs/libm3/src/os/POSIX/ProcessPosix.m3 diff -c m3/pm3/libs/libm3/src/os/POSIX/ProcessPosix.m3:1.3 m3/pm3/libs/libm3/src/os/POSIX/ProcessPosix.m3:1.4 *** m3/pm3/libs/libm3/src/os/POSIX/ProcessPosix.m3:1.3 Mon Oct 6 14:14:13 1997 --- m3/pm3/libs/libm3/src/os/POSIX/ProcessPosix.m3 Tue Feb 10 22:44:52 1998 *************** *** 82,92 **** execResult := 0; forkResult := Unix.vfork(); IF forkResult = 0 THEN (* in the child *) ! ExecChild(argx, envp, wdstr, stdin_fd, stdout_fd, stderr_fd); (* If ExecChild returns, the execve failed. Let's try to leave a note for our parent, in case we're still sharing their address space. *) - execResult := -1; execErrno := Uerror.errno; Unix.underscore_exit(99) END; --- 82,92 ---- execResult := 0; forkResult := Unix.vfork(); IF forkResult = 0 THEN (* in the child *) ! execResult := ExecChild(argx, envp, wdstr, stdin_fd, stdout_fd, ! stderr_fd); (* If ExecChild returns, the execve failed. Let's try to leave a note for our parent, in case we're still sharing their address space. *) execErrno := Uerror.errno; Unix.underscore_exit(99) END; *************** *** 227,233 **** argx: ArrCStr; (* see "AllocArgs" for layout *) envp: Ctypes.char_star_star; wdstr: Ctypes.char_star; ! stdin, stdout, stderr: INTEGER) RAISES {} = (* Modify Unix state using "stdin", ..., and invoke execve using "argx" and "envp". Do not invoke scheduler, allocator, or --- 227,233 ---- argx: ArrCStr; (* see "AllocArgs" for layout *) envp: Ctypes.char_star_star; wdstr: Ctypes.char_star; ! stdin, stdout, stderr: INTEGER): INTEGER RAISES {} = (* Modify Unix state using "stdin", ..., and invoke execve using "argx" and "envp". Do not invoke scheduler, allocator, or *************** *** 249,258 **** VAR res := 0; t: Ctypes.char_star; BEGIN IF wdstr # NIL THEN ! IF Unix.chdir(wdstr) < 0 THEN RETURN END END; IF NOT (SetFd(0, stdin) AND SetFd(1, stdout) AND SetFd(2, stderr)) THEN ! RETURN END; FOR fd := 3 TO Unix.getdtablesize() - 1 DO EVAL Unix.close(fd) (* ignore errors *) --- 249,258 ---- VAR res := 0; t: Ctypes.char_star; BEGIN IF wdstr # NIL THEN ! IF Unix.chdir(wdstr) < 0 THEN RETURN -1; END END; IF NOT (SetFd(0, stdin) AND SetFd(1, stdout) AND SetFd(2, stderr)) THEN ! RETURN -1; END; FOR fd := 3 TO Unix.getdtablesize() - 1 DO EVAL Unix.close(fd) (* ignore errors *) *************** *** 265,294 **** t := argx[0]; argx[0] := argx[2]; argx[2] := t; res := Unix.execve(BinSh, ADR(argx[1]), envp); <* ASSERT res < 0 *> ! END END ExecChild; EXCEPTION WaitAlreadyCalled; PROCEDURE Wait(p: T): ExitCode = <* FATAL WaitAlreadyCalled *> ! VAR result: Ctypes.int; status: Uexec.w_A; ! CONST Delay = 0.2D0; BEGIN IF NOT p.waitOk THEN RAISE WaitAlreadyCalled END; p.waitOk := FALSE; (* By rights, the SchedulerPosix interface should have a WaitPID procedure that is integrated with the thread scheduler. *) LOOP ! result := Uexec.waitpid(p.pid, ADR(status), Uexec.WNOHANG); IF result # 0 THEN EXIT END; Thread.Pause(Delay) END; <* ASSERT result > 0 *> ! IF Word.And(status, LAST(ExitCode)) = status THEN ! RETURN status ! ELSE ! RETURN LAST(ExitCode) ! END END Wait; PROCEDURE Exit(n: ExitCode) = --- 265,298 ---- t := argx[0]; argx[0] := argx[2]; argx[2] := t; res := Unix.execve(BinSh, ADR(argx[1]), envp); <* ASSERT res < 0 *> ! END; ! RETURN res; END ExecChild; EXCEPTION WaitAlreadyCalled; PROCEDURE Wait(p: T): ExitCode = <* FATAL WaitAlreadyCalled *> ! VAR ! result: Ctypes.int; ! statusT: Uexec.w_T; ! statusM3: Uexec.w_M3; ! CONST Delay = 0.1D0; BEGIN IF NOT p.waitOk THEN RAISE WaitAlreadyCalled END; p.waitOk := FALSE; (* By rights, the SchedulerPosix interface should have a WaitPID procedure that is integrated with the thread scheduler. *) LOOP ! result := Uexec.waitpid(p.pid, ADR(statusT), Uexec.WNOHANG); IF result # 0 THEN EXIT END; Thread.Pause(Delay) END; <* ASSERT result > 0 *> ! statusM3.w_Filler := 0; ! statusM3.w_Coredump := statusT.w_Coredump; ! statusM3.w_Termsig := statusT.w_Termsig; ! statusM3.w_Retcode := statusT.w_Retcode; ! RETURN MIN(LAST(ExitCode),LOOPHOLE(statusM3,Uexec.w_A)); END Wait; PROCEDURE Exit(n: ExitCode) = Index: m3/pm3/libs/libm3/tests/sqrt/src/m3makefile diff -c m3/pm3/libs/libm3/tests/sqrt/src/m3makefile:1.2 m3/pm3/libs/libm3/tests/sqrt/src/m3makefile:1.3 *** m3/pm3/libs/libm3/tests/sqrt/src/m3makefile:1.2 Tue Jan 28 12:22:44 1997 --- m3/pm3/libs/libm3/tests/sqrt/src/m3makefile Tue Feb 10 22:44:59 1998 *************** *** 4,10 **** % % Last modified on Wed Mar 2 08:30:57 PST 1994 by kalsow ! override ("sqrt", "../../..") import ("sqrt") build_standalone () --- 4,10 ---- % % Last modified on Wed Mar 2 08:30:57 PST 1994 by kalsow ! override ("sqrt", path_of(".." & SL & ".." & SL & "..")) import ("sqrt") build_standalone () Index: m3/pm3/libs/m3core/src/index.html diff -c /dev/null m3/pm3/libs/m3core/src/index.html:1.1 *** /dev/null Tue Feb 10 23:32:13 1998 --- m3/pm3/libs/m3core/src/index.html Tue Feb 10 22:45:03 1998 *************** *** 0 **** --- 1,94 ---- + +-
+
- Copyright +
The Modula-3 Core Library + + ++ Michel Dagenais + Michel Dagenais, GNU General Public License, 1998 + + michel.dagenais@polymtl.ca+
+ Ecole Polytechnique
+ C.P. 6079, Succ. Centre-Ville
+ Montreal, Quebec, H3C 3A7 + 17 January 1998 + Modula-3 + library + wide audience +The Modula-3 Core Library
+ +++ +This library contains the Modula-3 required interfaces, + core runtime services (garbage collection, + threads, runtime checking) and supporting modules. It encapsulates almost + all the platform specific code. +
Required Interfaces
+ +-
+
- float implements the required + interfaces for REAL, LONGREAL, and EXTENDED numbers, as well as supporting + functions. + +
- text implements the required + TEXT interface. + +
- thread implements the required + Thread interface. + +
- word implements the required + Word interface. + +
Useful Interfaces
+ +A few mature and commonly used interfaces also belong to m3core. + +
-
+
- time implements the Date, Time, + and Tick interface, serving all time related functions. + +
- weakref provides weaker references + which do not prevent objects from being garbage collected, and hooks to + have cleanup procedures to be called before an object will be + collected. + +
- fingerprint computes a + signature for a string and is used to fingerprint the type declarations + to verify their structural equivalence. + +
- runtime implements the garbage + collector, and other runtime support functions including the runtime type + information. +
Low level and platform dependent support functions
+ +-
+
- unix interfaces to all the + POSIX system calls, accounting for platforms differences. + +
- win32 interfaces to all + the Win32 system calls. + +
- C defines the correspondance + between C basic types and Modula-3 types, and interfaces to low level + C functions (string, signal handling, setjmp...). Module M3toC offers + conversions between char * and TEXT. + +
- Csupport provides support functions in C, + mostly a more consistent (across all platforms) dtoa, and bit vectors + for implementing SETs. + +
- main contains the empty Main + interface which must be exported by any program main module. + +
- convert is now replaced by + the newer Lex/Fmt modules for reading/writing numbers. + +
General Purpose Libraries + + ++ Michel Dagenais + Michel Dagenais, GNU General Public License, 1998 + + michel.dagenais@polymtl.ca+
+ Ecole Polytechnique
+ C.P. 6079, Succ. Centre-Ville
+ Montreal, Quebec, H3C 3A7 + 18 January 1998 + operating system + input/output + data structures + geometry + wide audience +General Purpose Libraries
+ +++ +This section contains general purpose libraries for Data Structures, + memory management, input output, operating system access, and miscellaneous + other topics not covered in the other sections. +
-
+
- m3core
- + Core Modula-3 library containing the runtime support procedures + as well as all the platform dependent code. +
- libm3
- + Modula-3 standard library containing commonly used data structures, + input output, and operating system access procedures. +
- realgeometry
- + Geometry procedures based on REAL numbers. +
- set
- + Set data structure. The basic data structures in libm3 may be used + for representing sets but do not offer some of the more advanced operations + such as union. +
- tempfiles
- + Library for creating and automatically cleaning up temporary files. +
- digraph
- + Data structure for representing directed graphs. +
- parseparams
- + Library for parsing command line options. +
- table-list
- + Linked list based version of the Table interface. In some cases + linked lists may be more efficient than the default hash table + based implementation. +
Mail + + ++ Michel Dagenais + Michel Dagenais, GNU General Public License, 1998 + + michel.dagenais@polymtl.ca+ + +
+ Ecole Polytechnique
+ C.P. 6079, Succ. Centre-Ville
+ Montreal, Quebec, H3C 3A7 + 18 January 1998 + mail +++ + + + + Index: m3/pm3/network/mail/src/m3makefile diff -c /dev/null m3/pm3/network/mail/src/m3makefile:1.2 *** /dev/null Tue Feb 10 23:32:45 1998 --- m3/pm3/network/mail/src/m3makefile Tue Feb 10 22:42:36 1998 *************** *** 0 **** --- 1,7 ---- + + import("m3doc") + + HtmlFile("index") + + OtherPackage("mail") + Index: m3/pm3/network/netobjects/src/index.html diff -c /dev/null m3/pm3/network/netobjects/src/index.html:1.1.1.1 *** /dev/null Tue Feb 10 23:32:49 1998 --- m3/pm3/network/netobjects/src/index.html Sat Jan 31 14:47:14 1998 *************** *** 0 **** --- 1,42 ---- + +This section contains electronic mail related applications and libraries. +
Network Objects + + ++ Michel Dagenais + Michel Dagenais, GNU General Public License, 1998 + + michel.dagenais@polymtl.ca+
+ Ecole Polytechnique
+ C.P. 6079, Succ. Centre-Ville
+ Montreal, Quebec, H3C 3A7 + 18 January 1998 + distributed + network objects + remote method invocation + rmi + wide audience +Network Objects
+ +++ +Network objects offer transparent remote method invocation on objects. + Network objects are simpler to use than remote procedure calls because + objects store the remote connection information, and the runtime handles + automatically the external data representation used to exchange + parameters during remote calls. +
-
+
- netobj
- + The network objects library. +
- netobjd
- + The network object daemon used to facilitate the exchange + of network objects between remote processes. +
- stubgen
- + The stub generator used by netobj to derive network objects + types from used defined types. +
The Package Server + + ++ Michel Dagenais + Michel Dagenais, GNU General Public License, 1998 + + michel.dagenais@polymtl.ca+
+ Ecole Polytechnique
+ C.P. 6079, Succ. Centre-Ville
+ Montreal, Quebec, H3C 3A7 + 18 January 1998 + distributed + package + server +The package server
+ +++ +The package server updates several remote package repositories in + a coherent manner. +
-
+
- pkgtool
- + Package client. +
- pkgsrv
- + Package server. +
- pkgq
- + Support library managing queues, locks and the package database. +
- pkgobj
- + Support library. +
- pkgfprint
- + Library to compare packages based on their fingerprint. +
Networking + + ++ Michel Dagenais + Michel Dagenais, GNU General Public License, 1998 + + michel.dagenais@polymtl.ca+
+ Ecole Polytechnique
+ C.P. 6079, Succ. Centre-Ville
+ Montreal, Quebec, H3C 3A7 + 18 January 1998 + network + mail + web + tcp + wide audience +Networking
+ +++ +This section contains network related applications and libraries. +
-
+
- + Mail reading programs. +
- Network Objects
- + Network objects may be used to easily build robust distributed applications + through remote method invocations. +
- Package Server
- + Replicate the content of a package repository over several sites + distributed over the network. +
- TCP Libraries
- + Libraries for accessing TCP/IP network connections and building TCP/IP + servers. +
- World Wide Web
- + World Wide Web browsers and HTTP access libraries. +
TCP Libraries + + ++ Michel Dagenais + Michel Dagenais, GNU General Public License, 1998 + + michel.dagenais@polymtl.ca+ + +
+ Ecole Polytechnique
+ C.P. 6079, Succ. Centre-Ville
+ Montreal, Quebec, H3C 3A7 + 18 January 1998 + TCP + IP + internet + protocol +++ +This section contains internet protocol (TCP/IP) related libraries. +
-
+
- TCP/IP access library
- + This library is used to establish TCP/IP network connections and transfer data. +
- TCP/IP Extras
- + A few additional less commonly used procedures for accessing TCP/IP + network connections. +
World Wide Web + + ++ Michel Dagenais + Michel Dagenais, GNU General Public License, 1998 + + michel.dagenais@polymtl.ca+
+ Ecole Polytechnique
+ C.P. 6079, Succ. Centre-Ville
+ Montreal, Quebec, H3C 3A7 + 18 January 1998 + network + www + browser +World Wide Web
+ +++ +This section contains World Wide Web libraries and applications. +
-
+
- DeckScape
- + Web Browser based on the deck of cards metaphor. +
- WebCard
- + The integration of DeckScape and Postcard to provide Web browsing, + Mail, and News reading through a single uniform graphical user interface. +
- WebScape
- + A simple Web browser. +
- WebVBT
- + A HTML viewer widget. +
- webcat
- + A command line application to download World Wide Web documents. +
- web
- + Web access library. +
- http
- + HyperText Transfer Protocol library. +
PM3: The Modula-3 distribution of Ecole Polytechnique de Montreal + + +PM3: The Modula-3 distribution of Ecole Polytechnique de Montreal
+ + + + + \ No newline at end of file Index: m3/pm3/src/m3makefile diff -c m3/pm3/src/m3makefile:1.14 m3/pm3/src/m3makefile:1.17 *** m3/pm3/src/m3makefile:1.14 Wed Jan 28 16:00:48 1998 --- m3/pm3/src/m3makefile Tue Feb 10 22:42:07 1998 *************** *** 45,51 **** --- 45,56 ---- EXPORTPATH = lookup("EXPORTPATH","") EXPORTRPATH = lookup("EXPORTRPATH","") + if EXPORTPATH + if equal(OS_TYPE,"WIN32") EXPORTPATH = p2w(EXPORTPATH) end + end + if EXPORTRPATH + if equal(OS_TYPE,"WIN32") EXPORTRPATH = p2w(EXPORTRPATH) end EXPORTPATH = path() & SL & ".." & SL & EXPORTRPATH end *************** *** 62,68 **** write("TARGET_LIB_USE = LIB_USE", CR) write("TARGET_PKG_USE = PKG_USE", CR) ! write("INSTALL_ROOT = \"" & EXPORTPATH & "\" & INSTALL_ROOT",CR) write("setInstallRoot(\"\",\"\")",CR) end end --- 67,73 ---- write("TARGET_LIB_USE = LIB_USE", CR) write("TARGET_PKG_USE = PKG_USE", CR) ! write("INSTALL_ROOT = \"" & escape(EXPORTPATH) & "\" & INSTALL_ROOT",CR) write("setInstallRoot(\"\",\"\")",CR) end end *************** *** 211,216 **** --- 216,226 ---- BuildChunk("text/sgmltools","sgmlconv") BuildChunk("text/sgmltools","sgmllinear") + %--- sgmltools --- doc ------------------------------------------------- + % SGML related tools + % requires: libm3 + BuildChunk("text","sgmltools") + %--- m3textohtml --- utility ------------------------------------------------- % Convert Modula-3 units from LaTeX markup to HTML markup % requires: libm3 *************** *** 236,242 **** % in the distribution as a sample of native Windows programming in Modula-3. % requires: libm3 if equal (OS_TYPE, "WIN32") ! BuildChunk("graphics","sil") end %--- m3middle --- library ------------------------------------------------- --- 246,252 ---- % in the distribution as a sample of native Windows programming in Modula-3. % requires: libm3 if equal (OS_TYPE, "WIN32") ! % BuildChunk("graphics","sil") end %--- m3middle --- library ------------------------------------------------- *************** *** 520,525 **** --- 530,540 ---- BuildChunk("language/modula3/m3tools","m3browser") end + %--- m3ide --- utility ------------------------------------------------- + % simple integrated development environment based on emacs + % requires: libm3 + BuildChunk("language/modula3/m3tools","m3ide") + %--- tcl --- library ------------------------------------------------- % a thin Modula-3 veneer on the TCL library (version 6.2). % requires: libm3 (TCL is required to build a shared library) *************** *** 938,942 **** --- 953,988 ---- % program that takes a URL and prints out the web document % requires: http BuildChunk("network/www","webcat") + + %------------------------------------------------------------ + % + % Intermediate "documentation" nodes in the hierarchy + % + BuildChunk(".","intro") + BuildChunk("database","stableobjects") + BuildChunk(".","database") + BuildChunk("graphics","animation") + BuildChunk("graphics","displayps") + BuildChunk("graphics","forms") + BuildChunk("graphics","games") + BuildChunk("graphics","gr-libs") + BuildChunk("graphics","lecternpkg") + BuildChunk("graphics","sharedboard") + BuildChunk(".","graphics") + BuildChunk("language","m3obliq") + BuildChunk("language/modula3","m3compiler") + BuildChunk("language/modula3","m3tools") + BuildChunk("language","modula3") + BuildChunk("language/parsing","metasyntax") + BuildChunk("language","parsing") + BuildChunk(".","language") + BuildChunk(".","libs") + BuildChunk("network","mail") + BuildChunk("network","netobjects") + BuildChunk("network","pkgserver") + BuildChunk("network","tcplibs") + BuildChunk("network","www") + BuildChunk(".","network") + BuildChunk(".","text") end Index: m3/pm3/text/sgmltools/m3doc/src/index.html diff -c m3/pm3/text/sgmltools/m3doc/src/index.html:1.1.1.1 m3/pm3/text/sgmltools/m3doc/src/index.html:1.2 *** m3/pm3/text/sgmltools/m3doc/src/index.html:1.1.1.1 Sat Jan 17 09:26:50 1998 --- m3/pm3/text/sgmltools/m3doc/src/index.html Tue Feb 10 22:41:38 1998 *************** *** 24,32 ****The M3DOC documentation system
-A printable version of this documentation is available - [m3doc]
-This system organizes the documentation of Modula-3 packages. The documentation consists in HTML hypertext files and Modula-3 interfaces --- 24,29 ---- Index: m3/pm3/text/sgmltools/m3doc/src/m3doc.tmpl diff -c m3/pm3/text/sgmltools/m3doc/src/m3doc.tmpl:1.3 m3/pm3/text/sgmltools/m3doc/src/m3doc.tmpl:1.4 *** m3/pm3/text/sgmltools/m3doc/src/m3doc.tmpl:1.3 Thu Jan 29 10:31:48 1998 --- m3/pm3/text/sgmltools/m3doc/src/m3doc.tmpl Tue Feb 10 22:41:38 1998 *************** *** 54,60 **** if defined("_all") htmlFiles += src_file end ! _install_src(src_file,dest,"0644") end end --- 54,60 ---- if defined("_all") htmlFiles += src_file end ! _install_file(nm,dest,"0644","") end end *************** *** 92,104 **** end end ! m3docOldM3Hooks = before_do_m3_hooks ! ! proc before_do_m3_hooks() is ! m3docOldM3Hooks() if callSgmlConv checkExec(sgmlConvCmd,[],"") end if callM3Sgml checkExec(m3SgmlCmd,[],"") end end readonly proc HtmlRoot (nm) is if USE_M3DOC --- 92,103 ---- end end ! proc m3doc_hook() is if callSgmlConv checkExec(sgmlConvCmd,[],"") end if callM3Sgml checkExec(m3SgmlCmd,[],"") end end + + add_m3_hook(m3doc_hook) readonly proc HtmlRoot (nm) is if USE_M3DOC Index: m3/pm3/text/sgmltools/sgml/src/index.html diff -c m3/pm3/text/sgmltools/sgml/src/index.html:1.1.1.1 m3/pm3/text/sgmltools/sgml/src/index.html:1.2 *** m3/pm3/text/sgmltools/sgml/src/index.html:1.1.1.1 Sat Jan 17 09:26:50 1998 --- m3/pm3/text/sgmltools/sgml/src/index.html Tue Feb 10 22:41:43 1998 *************** *** 19,27 ****
The SGML Parser Library
-A printable version of this documentation is available - [sgml]
-This library reads SGML document types definitions and parses SGML files --- 19,24 ---- Index: m3/pm3/text/sgmltools/sgmlconv/src/Main.m3 diff -c m3/pm3/text/sgmltools/sgmlconv/src/Main.m3:1.2 m3/pm3/text/sgmltools/sgmlconv/src/Main.m3:1.3 *** m3/pm3/text/sgmltools/sgmlconv/src/Main.m3:1.2 Thu Jan 29 10:32:05 1998 --- m3/pm3/text/sgmltools/sgmlconv/src/Main.m3 Tue Feb 10 22:41:48 1998 *************** *** 23,29 **** IMPORT SGML, SGMLPrint, Stdio, Params, Text, Wr, Rd, Thread, TextIntTbl, TextWr, TextRd, Fmt, Lex, OSError, FileRd, FileWr, TextSeq, IntSeq, ! Pathname; TYPE Translate = SGML.Application OBJECT --- 23,29 ---- IMPORT SGML, SGMLPrint, Stdio, Params, Text, Wr, Rd, Thread, TextIntTbl, TextWr, TextRd, Fmt, Lex, OSError, FileRd, FileWr, TextSeq, IntSeq, ! Pathname, Process, FS, File, RegularFile; TYPE Translate = SGML.Application OBJECT *************** *** 92,97 **** --- 92,98 ---- markedSectionEnd := MarkedSectionEndF; ignoredChars := IgnoredCharsF; generalEntity := GeneralEntityF; + error := ErrorProc; openEntityChange:= OpenEntityChangeF; END; *************** *** 212,222 **** BEGIN END GeneralEntity; ! PROCEDURE ErrorProc(self: Translate; READONLY e: SGML.ErrorEvent) = VAR position := self.getDetailedLocation(e.pos); BEGIN ! Wr.PutText(Stdio.stderr,"ERROR: " & e.message & " in file " & position.filename & " line " & Fmt.Int(position.lineNumber) & " column " & Fmt.Int(position.columnNumber)); IF position.entityName # NIL THEN --- 213,231 ---- BEGIN END GeneralEntity; ! PROCEDURE ErrorProc(self: SGML.Application; READONLY e: SGML.ErrorEvent) = VAR position := self.getDetailedLocation(e.pos); + msg: TEXT; BEGIN ! IF e.type <= SGML.ErrorType.Warning THEN ! msg := "WARNING"; ! ELSE ! msg := "ERROR"; ! INC(nbErrors); ! END; ! ! Wr.PutText(Stdio.stderr,msg & ": " & e.message & " in file " & position.filename & " line " & Fmt.Int(position.lineNumber) & " column " & Fmt.Int(position.columnNumber)); IF position.entityName # NIL THEN *************** *** 260,265 **** --- 269,282 ---- valid, plus, found: BOOLEAN; action: Special; BEGIN + IF verbose >= 2 THEN + WITH position = self.getDetailedLocation(e.pos) DO + Wr.PutText(Stdio.stdout,"In file " & position.filename & " line " & + Fmt.Int(position.lineNumber) & " column " & + Fmt.Int(position.columnNumber) & "\n"); + END; + END; + IF self.math AND (NOT self.skip) AND HTMLtoTeXtbl[self.tagStack.gethi()].action = Special.MathArgs THEN Wr.PutText(self.wr,"{"); *************** *** 1634,1639 **** --- 1651,1664 ---- action: SpecialF; n: INTEGER; BEGIN + IF verbose >= 2 THEN + WITH position = self.getDetailedLocation(e.pos) DO + Wr.PutText(Stdio.stdout,"In file " & position.filename & " line " & + Fmt.Int(position.lineNumber) & " column " & + Fmt.Int(position.columnNumber) & "\n"); + END; + END; + INC(self.depth); name := e.gi; *************** *** 1707,1728 **** DEC(self.depth); END EndElementF; ! (* Two adjustments are required for hypertext references: links to other packages must account for the hierarchy being flattened upon installation, some files are translated upon translation and their extension changes ! accordingly. The updated value of the hypertext reference is changed in place within "e". *) ! PROCEDURE AdjustHref(<*UNUSED*>self: HTMLtoHTML; ! READONLY e: SGML.StartElementEvent) = VAR ! href: TEXT; hrefLen, extLen: CARDINAL; pathseq, hrefseq, newseq: TextSeq.T; ! pkgNamePos := -1; BEGIN IF NOT GetAttributeValue(e.attributes,"HREF",href) THEN RETURN; END; (* The package hierarchy gets flattened in the installation. Links must be redirected appropriately when the -path option is set and we have a relative link which points outside of the current package. *) --- 1732,1807 ---- DEC(self.depth); END EndElementF; ! (* Three adjustments are required for hypertext references: links to other packages must account for the hierarchy being flattened upon installation, some files are translated upon translation and their extension changes ! accordingly, and links to directories may need to point to the index.html ! file within. The updated value of the hypertext reference is changed in place within "e". *) ! VAR error: TEXT; (* The optimizer does not see exceptions and tries to ! be smart with local variables... *) ! ! PROCEDURE AdjustHref(self: HTMLtoHTML; READONLY e: SGML.StartElementEvent) = VAR ! href, newref: TEXT; hrefLen, extLen: CARDINAL; pathseq, hrefseq, newseq: TextSeq.T; ! pkgNamePos, dashPos := -1; ! status: File.Status; BEGIN IF NOT GetAttributeValue(e.attributes,"HREF",href) THEN RETURN; END; + IF Text.FindChar(href,'#') = 0 THEN RETURN; END; (* internal link *) + + (* Local links (without a ':') are checked to see if they are valid and + if they refer to a directory. *) + + IF Text.FindChar(href,':') < 0 THEN + TRY + (* Local links must be relative *) + + error := "incorrect HREF (non relative link) "; + IF Pathname.Absolute(href) THEN RAISE OSError.E(NIL); END; + + (* Extract the file name (up to '#') and check if it exists relative + to the prefix of the input file name (inPrefix). *) + + error := "incorrect HREF "; + + dashPos := Text.FindChar(href,'#'); + IF dashPos >= 0 THEN + status :=FS.Status(Pathname.Join(inPrefix,Text.Sub(href,0,dashPos))); + ELSE + status := FS.Status(Pathname.Join(inPrefix,href)); + END; + + (* The file exists but is a directory. In that case, a tag address + ('#') is not acceptable. Perhaps the directory contains an + index.html file to which we should point. *) + + IF status.type = FS.DirectoryFileType THEN + IF dashPos >= 0 THEN RAISE OSError.E(NIL); END; + + newref := Pathname.Join(href,"index",".html"); + error := NIL; + status := FS.Status(Pathname.Join(inPrefix,newref)); + + (* If there is an index.html, check that it is a regular file *) + + error := "invalid HREF (not a regular file) "; + IF status.type # RegularFile.FileType THEN RAISE OSError.E(NIL);END; + href := newref; + END; + EXCEPT + | OSError.E => + IF error # NIL THEN + self.error(SGML.ErrorEvent{0,SGML.ErrorType.Warning,error + & href}); + END; + END; + END; + (* The package hierarchy gets flattened in the installation. Links must be redirected appropriately when the -path option is set and we have a relative link which points outside of the current package. *) *************** *** 1750,1756 **** added to get out of the current package. *) IF newseq # NIL THEN ! newseq.addhi(hrefseq.getlo()); (* initial NIL arc *) newseq.addhi(Pathname.Parent); (* get out of the package dir *) FOR i := 1 TO pathseq.size() - 1 DO IF NOT Text.Equal(hrefseq.get(i),Pathname.Parent) THEN --- 1829,1835 ---- added to get out of the current package. *) IF newseq # NIL THEN ! newseq.addhi(hrefseq.remlo()); (* initial NIL arc *) newseq.addhi(Pathname.Parent); (* get out of the package dir *) FOR i := 1 TO pathseq.size() - 1 DO IF NOT Text.Equal(hrefseq.get(i),Pathname.Parent) THEN *************** *** 1895,1900 **** --- 1974,1980 ---- IF file = 0 THEN in := FileRd.Open(arg); inName := arg; + inPrefix := Pathname.Prefix(inName); ELSIF file = 1 THEN out := FileWr.Open(arg); outName := arg; *************** *** 1913,1921 **** --- 1993,2008 ---- options.defaultDoctype := "HTML"; ELSIF Text.Equal (arg, "-report") THEN report := TRUE; + ELSIF Text.Equal (arg, "-keep") THEN + discard := FALSE; ELSIF Text.Equal (arg, "-v") THEN options.enableWarning := NEW(REF ARRAY OF TEXT,1); options.enableWarning[0] := "all"; + verbose := 1; + ELSIF Text.Equal (arg, "-vv") THEN + options.enableWarning := NEW(REF ARRAY OF TEXT,1); + options.enableWarning[0] := "all"; + verbose := 2; ELSIF Text.Equal (arg, "-r") THEN IF currentParam + 1 >= Params.Count THEN RAISE UsageError("Missing argument for -r"); *************** *** 1962,1972 **** END; VAR replacements := NEW(TextSeq.T).init(); dtdDirs := NEW(TextSeq.T).init(); in: Rd.T; out: Wr.T; ! inName, outName: TEXT; patterns: REF ARRAY OF Pattern; options: SGML.ParserOptions; firstParser, parser: SGML.Parser := NIL; --- 2049,2060 ---- END; VAR + verbose := 0; replacements := NEW(TextSeq.T).init(); dtdDirs := NEW(TextSeq.T).init(); in: Rd.T; out: Wr.T; ! inName, outName, inPrefix: TEXT; patterns: REF ARRAY OF Pattern; options: SGML.ParserOptions; firstParser, parser: SGML.Parser := NIL; *************** *** 1976,1987 **** --- 2064,2080 ---- rds := NEW(REF ARRAY OF Rd.T,1); path: TEXT; report := FALSE; + nbErrors: CARDINAL; + discard, noErrors := TRUE; BEGIN TRY WHILE ParseOptions() DO files[0] := inName; rds[0] := in; + IF verbose > 0 THEN + Wr.PutText(Stdio.stdout,"sgmlconv: " & inName & " -> " &outName& "\n"); + END; IF parser = NIL THEN parser := NEW(SGML.Parser); *************** *** 1996,2011 **** ELSIF Text.Equal(conversion,"htmlhtml") THEN converter := NEW(HTMLtoHTML, wr := out).init(); END; EVAL parser.run(converter); Rd.Close(in); Wr.Close(out); END; EXCEPT | UsageError(t) => Wr.PutText(Stdio.stderr, t & "\n? usage: sgmlconv [-htmltex|-htmlhtml] [-r old new] [-path p]... " & ! "[-dtd dtdSearchPath] [-report] [infile] [outfile]\n"); | Rd.Failure => Wr.PutText(Stdio.stderr,"? Unable to read file\n"); END; END Main. --- 2089,2123 ---- ELSIF Text.Equal(conversion,"htmlhtml") THEN converter := NEW(HTMLtoHTML, wr := out).init(); END; + + nbErrors := 0; EVAL parser.run(converter); Rd.Close(in); Wr.Close(out); + + IF nbErrors # 0 THEN + noErrors := FALSE; + IF discard AND out # Stdio.stdout THEN + FS.DeleteFile(outName); + END; + END; END; EXCEPT | UsageError(t) => Wr.PutText(Stdio.stderr, t & "\n? usage: sgmlconv [-htmltex|-htmlhtml] [-r old new] [-path p]... " & ! "[-dtd dtdSearchPath] [-report] [-v] [-vv] [-keep] [infile]" & ! " [outfile]\n"); | Rd.Failure => Wr.PutText(Stdio.stderr,"? Unable to read file\n"); + | OSError.E => + Wr.PutText(Stdio.stderr,"Error while processing " & inName & " to " & + outName & "\n"); END; + IF noErrors = FALSE THEN Process.Exit(1); END; END Main. + + + + + Index: m3/pm3/text/src/index.html diff -c /dev/null m3/pm3/text/src/index.html:1.1.1.1 *** /dev/null Tue Feb 10 23:33:03 1998 --- m3/pm3/text/src/index.html Sat Jan 31 14:47:15 1998 *************** *** 0 **** --- 1,39 ---- +
+Text + + ++ Michel Dagenais + Michel Dagenais, GNU General Public License, 1998 + + michel.dagenais@polymtl.ca+
+ Ecole Polytechnique
+ C.P. 6079, Succ. Centre-Ville
+ Montreal, Quebec, H3C 3A7 + 18 January 1998 + text processing + documentation + text + wide audience +Text
+ +++ +This section contains text and documentation processing libraries and + tools. +
-
+
- SGML tools
- + Standard Generalized Markup Language (SGML) and HyperText Markup Language + (HTML) based tools for documentation + processing. These libraries and tools are used, among other things, + for processing the documentation found in this Modula-3 distribution. +
- mtex
- TeX like + Markup language used to produce nroff, HTML and LaTeX documents. + Only a portion of this package is available outside DEC SRC and its use + is not recommended in PM3. +