[Indigo]<Cedar5.3>JaM>JaMManual.tioga!1

JaMManual.Tioga

This was converted from "JaMmanual.tex"

last edited by Leo Guibas, December 28, 1980 2:17 PM

Last Edited by Rick Beach, January 9, 1985 4:32:53 pm PST

JaM

Introduction

JaM is a simple stack-based interactive system with graphics utilities. JaM is intended to be a flexible system, giving the user rather direct control over the primitives. It is not intended to be a fault tolerant system for beginning users. This manual is written in the same spirit: the intent is to explain only those aspects of JaM which are not properties of programming languages in general. It gives explainations of all but the most obscure intrinsic functions and a sampling of the most useful external utilities.

JaM has three major components: a virtual memory, a set of primitives which perform stack manipulations much like a very powerful, flexible Hewlett-Packard calculator, and a graphics package.

All functions in JaM make use of the operand stack. This stack contains objects: integers, reals, booleans, character strings, commands, streams, dictionaries, arrays, and special stack markers. Execution proceedes by getting a token from the input stream, converting it into an object, checking whether or not it is executable and executing it. Non-executable objects are pushed onto the stack. During execution, operands may be retrieved from the stack and results are returned on the stack. This means that all input is given in postfix notation.

The graphics package is a group of functions, some written in JaM, others written directly in Cedar, which must be loaded in addition to the basic JaM system.

Basic Operation

JaM execution proceedes simply by transforming the input stream into a series of objects and processing them sequentially. There are two types of objects: nouns which are automatically placed on the operand stack, and verbs which are immediately executed. The JaM scanner parses the input stream into a series of tokens separated by tabs, carriage returns, spaces and commas. There are three types of tokens: numbers, strings and identifiers. Numbers and strings are converted directly into the corresponding objects and placed on the operand stack. Identifiers are looked up in the current dictionary (explained later) and the resulting object is processed according to whether it is a noun or a verb.

Syntactically, a string is a sequence of characters enclosed in parentheses. It may contain anything except unbalanced parentheses (even carriage returns). Any token which is neither a number nor a string is an identifier.

The system has a total of three major stacks: the operand stack, the dictionary or context stack, and the execution stack. The dictionary stack is used for keeping track of identifiers during execution. This stack functions as a series of nested contexts, much like the blocks of a block structured language. A dictionary is esentially a table of fixed size for associating identifiers with their values. When the scanner comes across an identifier, it tries to look it up in the dictionary on the top of the dictionary stack. If the lookup is successful, the value found in the dictionary is the next object returned by the scanner. Otherwise, the identifier is looked up in each of the other dictionaries on the dictionary stack in sequence, until a value is found.

The execution stack is used for keeping track of nested function calls. It contains the information necessary to implement recursive function invocations. It need not be the direct concern of the user since he cannot refer to it directly.

How to Start

Type the command jamimager'' to the CommandTool. This will create a JaM typescript for you to interact with the JaM interpreter and a JaMImager viewer for the graphics utilites. JaM gives you a prompt *'' in the typescript viewer. Initially, the operand stack is empty and the dictionary stack contains only one dictionary, the system dictionary. All the JaM intrinsic functions are defined in this dictionary. There are a number of other functions which JaM assumes exist and expects the user to define. These will be explained later when we discuss the relevent details of the system.

Commands and Utilities

This discussion is organized by function. All commands relating to a particular topic are given together along with an explanation of the particular aspect of the system to which they relate. The exact placement of arguments and results of each function on the stack is given by a diagram. For example:

.add <x><y> b <x+y> ő Add two real numbers.

The symbols in angle brackets, <x>, <y>, <x+y>, represent objects on the stack. An arrow (b) separates the condition of the operand stack before the command is executed from the condition after. Only the top-most objects on the stack are shown, the others are assumed to remain unchanged. A comment may describe the command following the symbol ő. A double vertical bar (||) will be used to mean the bottom of the stack. There are various error conditions which can occur when trying to execute a command. These are discussed in a separate section (see Error Handling) because there are special functions relating to this topic.

Arithmetic and Bit Manipulation

There are three types of numeric objects: reals, integers, and long integers. Integers and reals are 32 bits. Implicit type conversion is performed on numeric objects, but it is also possible to do these conversions explicitly (see Type Conversion).

.add <x><y> b <x+y> ő Add two real numbers.

.sub <x><y> b <x—y> ő Subtrct two real numbers.

.mul <x><y> b <xy> ő Multiply two real numbers.

.div <x><y> b <x/y> ő Real division.

.idiv <x><y> b <x/y> ő Integer division.

.neg <x> b <—x> ő

.cos <x> b <cos(x)> ő (x in degrees)

.sin <x> b <sin(x)> ő

.atan <y><x> b <p=atan(y/x)> ő (—180 < p d 180)

.exp <e> b <be> ő (result always of real type)

.log <v> b <logbv> ő

.sqrt <x> b <x> ő

.bitor <x><y> b ő (The integer p is the bitwise or of 32 bit integers x and y.)

.bitxor <x><m> b ő (p is the 32 bit exclusive or of x and y.)

.bitand <x><n> b ő (p is the 32 bit logical and of x and y.)

.bitnot <x> b ő (p is the 32 bit bitwise complement of x.)

.bitshift <x><y> b ő (The integer x is shifted left by y places. If y > 0 then the y low order bits are set to zero. If y < 0 then the —y high order bits are set to zero and y is shifted right. If |y| e 32 then p is set to zero.)

Boolean and Relational Commands

The following commands deal with boolean objects. They have two possible values represented here by .true'' and .false''. For integer comparisons, implicit type conversion occurs before comparison. If one argument is integer and the other is long integer or real, the integer is converted to that type. Similarly, long integers may be converted to real type. Strings may also be compared using lexicographic ordering. It is not legal to compare integers with strings.

.true b <.true> ő

.false b <.false> ő

.eq <x><y> b <.true> if x = y, otherwise <.false> ő

.gt <x><y> b <.true> if x > y numerically or lexicographically, else <.false> ő

.lt <x><y> b <.true> if x < y numerically or lexicographically, else <.false> ő

.not <x> b <~ x> ő

.and <x><y> b <x ' y> ő

.or <x><y> b <x ( y> ő

.xor <x><y> b <x • y> ő

Stack Manipulation Commands

It is often useful to manipulate the operand stack. It is probably not good practice, however, to try to use the stack for all temporary storage. Define local variables instead (see Dictionary Related Commands). Overuse of stack manipulation makes programs hard to read and difficult to debug. With this warning in mind, the following diagrams should make these commands clear.

.pop <x> b ő

.copy <x1><x2> ... <xi> b <x1><x2> ... <xi><x1><x2> ... <xi> ő (i must be of type integer)

.index <xn><xn—1> ... <x1> b <xi> ő ( is an integer less than n)

.count ||<x1><x2> ... <xi> b <x1><x2> ... <xi> ő

.roll <x1><x2> ... <xi><j> b <x(1—j)modi> ... <xi><x1> ... <x(—j)modi> ő (i and j are of type integer. Since we started counting from 1, not 0, by k mod i, we really mean i when i divides k.)

.dup <x> b <x><x> ő

.exch <x><y> b <y><x> ő

.clrstk ||<x1><x2> ... <xi> b || ő clears the stack

/clr ||<x1><x2> ... <xi> b || ő Clears the stack by first counting the stack and then popping each element off the stack. Defined in basic.jam.

Stack Marking and Mark Manipulation Commands

There is a special object called a stack mark. Its main purpose is for keeping variable numbers of arguments on the stack. The .loop and .rept commands (see below) use this concept internally to allow arbitrary execution inside the loop without losing track of the original condition of the operand stack.

.mark b ő (mark type object put on stack)

.cnttomrk <x1><x2> ... <xi> b <x1><x2> ... <xi> ő

.clrtomrk <x1><x2> ... <xi> b ő

Execution Control Commands

JaM has much of the execution control machinery found in Algol-like languages. This includes looping'', if-else'' and select'' constructions. There is no go to'' command, however, as this would not easily fit into the stack oriented structure of JaM. The constructions just mentioned do fit in with the stack oriented structure because they can operate on executable objects in the operand stack. For example, the .if command expects a boolean object and any other object on the operand stack. If the boolean equals .true, then the other object is executed, otherwise the .if command pops the object from the stack.

.exec <x> b ő Remove x from the operand stack and execute it as if it just came from the input stream. However x got on the stack, it is the result of some kind of execution. This means that x is effectively evaluated twice as with the eval'' function in Lisp. To reverse this effect, see Type Conversion

.if <x> b ő if b = .true then execute x

/if <x> b ő utility equivalent to: .cvx .if''

.ifelse <x><y> b ő if b = .true then execute x else execute y

/ifelse <x><y> b ő utility equivalent to: .ifelse .cvx .exec''

.rept <x> b ő execute x i times

.loop <x> b ő execute x forever

.for <j><k><x> b ő Execute xĐ(k—i)/j+1 times, with i on top of the stack the first time and i+j, i+2j, ... on top thereafter.

.exit b ő Exit from current .rept, .loop, .dictforall, or .arrayforall loop. This clears the operand and execution stack down to the marks placed upon entering the current loop.

.stop b ő Clears the execution stack, terminating all unfinished execution. To see how this affects error conditions, refer to Error Handling.

Dictionary Related Commands

Variables are stored in special objects called dictionaries. Dictionary objects are general symbol tables useful for all kinds off storage. They have a fixed maximum size specified at the time of their creation.

As mentioned earlier, there is a stack of dictionaries maintained by the system. The dictionaries in this stack are used like levels of static nesting for variable definitions in an Algol-like language. Dictionaries may be named and retrieved for later use just like other objects in JaM.

There are a few things to watch out for when dealing with dictionaries. Some of the system commands and utilities assume that there is space left in the current dictionary (the one at the top of the dictionary stack) to define temporary variables. For this reason, you should be careful about creating small dictionaries. Another problem is what to do when dictionaries get filled up. There are about four choices: push another dictionary onto the dictionary stack with .begin, remove the offending dictionary with .end, delete entries to make room, or clear the dictionary. This problem is particularly severe for users who just start defining variables without ever worrying about dictionaries. The system dictionay has a capacity of 256 entries, most of which are already filled up with system command definitions. When the system dictionary gets filled up, whatever you do, don't clear it!

In the following table, <k> refer to keys or variables and <v> refers to the corresponding values.

.curdict b <current dictionary> ő pushes the top of the dictionary stack onto the operand stack

.dict b <d> ő creates new dictionary d with capacity of i entries

.def <k><v> b ő Associate the value v with the key k in the current dictionary. To define a function, make v executable.

/def <k><s><v> b ő Equivalent to: <k><v>.def $help<k><s>.put''. The $help dictionary contains informative messages about certain functions. It provides a convenient way to document programs. To access this dictionary, see Input/Output Commands. This utility resides in the file basic.jam

/xdef <k><s><v> b ő Equivalent to: .cvx /def''.

.del <d><k> b ő deletes the key k from the dictionary d

.load <k> b <v> ő Retrieve the value associated with the key k in the current dictionary. If v is an executable string,this allows its definition to be printed. (See Type Conversion and Input/Output Commands).

.store <k><v> b ő Finds a definition of k in the current dictionary and replaces that definition with the value v. If no definition of k exists, this functions as .def

.put <d><k><v> b ő associates value v with key k in dictionary d

.get <d><k> b <v> ő retrieves the value v associated with k in dictionary d

.known <d><k> b ő <.true> if key k is in dictionary d, <.false> otherwise

.where <k> b ő <d><.true> if k is found in some dictionary d, <.false> otherwise

/dir <d> b ő Utility from basic.jam which prints all key, value pairs in the dictionary d

/kdir <d> b ő utility which prints all the keys in the dictionary d

?? <d> b ő This is a utility from basic.jam equivalent to $help /kdir. This prints all functions on which help is available. This usually includes most of the external utility functions whic have been loaded.

.clrdict <d> b ő Clear all entries from dictionary d

.dictforall <d><x> b ő Put <k><v> on the stack, and then execute <x>. This is done for every k, v pair in dictionary d

.begin <d> b ő Push d on the top of the dictionary stack. (This makes d the current dictionary)

.end .end b ő Pop current dictionary off the top of the dictionary stack.

.sysdict b <system dictionary> ő

.length <d> b ő the current number of entries in the dictionary d

.maxlength <d> b <l> ő the total capacity of dictionary d

.attachdict <d1><d2> b ő attaches dictionary d2 to dictionary d1, so that searches within dictionary d1 will find elements of dictionary d2.

.detachdict <d1><d2> b ő detaches dictionary d2 from dictionary d1.

.attachedforall <d><x> b ő Puts dictionary di on the stack and executes x for each dictionary di attached to dictionary d.

.detachall <d> b ő Removes all attached dictionaries to dictionary d.

Array Related Commands

Array objects are linear arrays of objects indexed starting at zero. They have fixed lengths determined when they are created. There are commands for creating arrays, storing into them, retrieving objects from them, etc. Most commands either expect array objects on the operand stack or return array objects. Arrays can also be made executable. (See Type Conversion)

.array b <a> ő Creates a new array a of i objects.

[ b ő Mark the operand stack for use by the ]'' utility.

] b <a> ő Put all the objects down to the first stack mark into an array a and return it on the operand stack. [ obj1 obj2 ... obji ]'' forms an i-element array.

.subarray <a><j> b <a`> ő a` is the subarray of a starting at position i and of length j. If i+j > length(a) this causes a range error.

.aput <a><v> b ő Store v in the i-th position of a, if 0 d i < length(a).

.aget <a> b <v> ő Get v from the i-th position of a, if 0 d i < length(a).

.aload <a> b <x1><x2> ... <xi—1><a> ő (where a is of length i)

.astore <x0><x1> ... <xi—1><a> b <a with x0, x1, ... , xi—1 stored in it> ő (a is of length i)

.arrayforall <a><x> b ő Puts a[i] on the stack and executes x for each object a[i] in a.

.abind <d><a> b ő Binds names in array a with values in dictionary d.

.afind <a><x> b <ok> ő Searches array a for element x and returns ok as .true if ai = x, otherwise ok is .false and does not appear on the stack.

.length <a> b ő Replaces array a with its length.

Input/Output Commands

This catagory of commands deals primarily with string and stream objects. Files are represented in JaM as special objects called streams. Commands for reading and writing files accept string type aruments and return string results.

There is always an input stream and an output stream. By default, these are both identified with the terminal. When writing strings to a file (stream), keep in mind that carriage returns can be part of strings and no implicit carriage returns are ever written to an output stream. Either the input stream or the output stream can be directed to any file. It is also possible to convert streams to strings and manipulate them that way. (see Type Conversion)

.print <s> b ő Print the string s on the current output stream

= <x> b ő Utility function from the file basic.jam which converts x to a string and prints it, followed by a carriage return. (Uses .cvis -- see Type Conversion).

/stk b ő Print the the contents of the operand stack without destroying it. This uses .print to print the entries.

== <x> b ő Utility function from the file basic.jam. It functions like = for printable strings, but it prints useful information about non-printable objects and even uses a reverse dictionary to decipher commands.

/pstk b ő Prints the operand stack like /stk, except it uses ==. This may not be good for debugging since == does a dictionary look up which could cause an error.

? <s> b ő Looks up the string s in the $help dictionary and prints the informative message it finds there. The string s should be one of the system commands and utility funcions or something defined using the /def utility (see Dictionary Related Commands).

?? b ő Print all the keys in the $help dictionary (the commands on which help is available).

.stream <file name><access> b <s> ő This command creates a byte stream with the access characteristics represented by <access> = .false for read or .true for write. Byte streams are the proper type of streams for most text files. The created stream is left on the operand stack. If access is greater than one, it becomes the current output stream. (uses .searchrules)

.killstream <t> b ő Kill the stream t. For output streams this restores the destination of .print to the terminal.

.run <file name> b ő The file is read as a byte stream and executed. This is how to read bravo files of JaM function definitions. A * prompt is printed each time the scanner comes to a carriage return. (uses .searchrules)

.loadbcd <file name> b ő Load Cedar bcd'' (binary file) and start. This is like .run except it runs a Cedar program. (uses .searchrules)

.readitem <s> b ő <item from stream><.true> if the stream s is not empty, <.false> otherwise. (An item is one byte for a bytestream or keystream and one word for a wordstream. Bytes are returned as integers, e.g. ascii codes for characters.)

.writeitem <t><s> b ő The item s (see above) is appended to the stream t.

.writebytes <t><s> b ő Write bytes in string s to stream t.

.searchrules b <s> ő Search rules for finding files.

/cr b ő Prints a carriage return.

/sp b ő Prints a space.

/tab b ő Prints a tab character.

/lp b ő Prints a left parenthesis.

/rp b ő Prints a right parenthesis.

/quote b ő Prints a quotation mark, ".

Type Conversion Commands

There are several different types of objects in JaM. String objects have a fixed length once they are created. It is possible to change existing strings (see Scanner and String Manipulation Commands) but their length remains constant. There are two numeric types: integer and real. When the scanner finds a string without any decimal point, it tries to make it an integer, then if it's too big, a long integer. Strings too long to be long integers are converted to reals. Strings containing decimal points naturaly become real type objects. It is not possible to enter numbers in exponential notation; however, one can type 6.7 10 -11 .exp .mul to get 6.7 10—11.

Type conversion commands allow the user to determine the types of objects and convert from one object type to another. Type mismatches cause run-time errors. These errors cause special error routines to be executed, which are user definable.

.type <x> b <Name of Type> ő Deliver the type of <x> on top of the operand stack. Current types include: .nil, .int (32 bits), .real (32 bits), .atom, .rope, .stream, .cmd, .op, .array, .dict, .mark, .other.

.length <x> b ő Length i of: string (in characters), array (in elements), dictionary (in entries).

.cvs <x> b <s> ő Convert to string equivalent. Applies to numbers, strings, executable strings, and streams.

.cvis <x><s> b <s> ő This is like .cvs, except for booleans and integers it destroys the string s, reusing the space for the result. If the string s is too short, JaM calls the function .sizechk to handle the error. You must define this yourself.

.cvrs <n><r> b <s> ő This is exactly like .cvs, except if n is a number it comes out in base r.

.cvos <n> b <s> ő The number n is converted to a string giving its octal representation.

.cvirs <n><r><s> b <s> ő This is like .cvrs except numbers come out in base r.

.cvi <x> b ő (converts numbers to type integer)

.cvr b <x> ő (converts numbers to real type)

.cvx <s> b <s`> ő Conversts strings or arrays to executable form. They become verbs. This is the way to get an executable string or array on the operand stack as is required by the execution control commands.

.cvlit <x> b <l> ő This converts strings and arrays into literal form (makes them nouns). This undoes the effect of .cvx.

.commandname <x> b <s> ő Returns the name of command x as a string s.

The most important type conversion is the conversion to executable. This is necessary every time a function is defined. There are two main executable forms in JaM: strings and arrays. Strings are a lot easier to use, but arrays are a lot faster. When a string is expected, the scanner must extract the objects from the string and each identifier must be looked up in the dictionary stack. When arrays are executed, they are already sequences of objects. In addition, all the identifiers have been looked up ahead of time.

Executable strings are simpler to use because it is easier to change the definitions of the functions they call and they are easier to read and print. The use of the functions .cvx, .load, and .exec when defining executable arrays can be very confusing. Recursive functions are also more difficult with arrays. The following examples illustrate the difference in format:

(average) (.add 2 .div) .cvx .def
(average) [ (.add) .load 2 (.div) .load ] .cvx .def

When using executable arrays, it is necessary to .load each function to get its definition (see Dictionary Related Commands). There is a utility called /compile to make this a little easier. Use ? (explained under Input/Output Commands) to find out about this.

String Manipulation Commands

This section had the JaM scanner commands and they are now obsolete.

.length <s> b ő Replaces the string s with its length in characters.

.substring <s><j> b <s`> ő <s`> is the j character substring of s starting at positon i. We must have 0 d i < length(s).

.search <t><s> b ő <a><s><.true> if there is a substring of t matching s, with b and a respectively the parts of t before and after the first occurrence of s, and <t><.false> if no substring of t matches s.

.asearch <t><s> b ő <a><s><.true> if a starting substring of t matches s -- a is the rest of t, <t><.false> otherwise.

Graphics Commands

The graphics commands are not part of the basic JaM system. The basic graphics commands are enabled by loading JamGraphics.bcd. There are useful extensions to these basic graphics commands in various files of utilities. The basic primitives are implemented in Cedar and provide for a display context stack. This is maintained so that transformations and other state information can easily be saved and restored. The .pushdc, .popds and .initdc commands control this stack.

State information concerning the graphics device is held in an entity called the display context. Most transformation, clipping, and painting commands alter this state. Most drawing commands both use this state and alter it.

One of the more important components of the state is the current definition of the coordinate system. Points in the graphics display are refered to by pairs of real numbers. JaM maintains a transformation matrix for converting these numbers to the coordinates used by the display divice. The translation matrix affects only the placement of new objects on the display. Changing the transformation matrix with a transformation command affects the placement of already existing objects.

The state information also contains the position of a special point called the current draw position. The line drawing commands use the draw position to define one endpoint of the line. The draw position is also used to control the placement of text within the display.

The file Graphics.jam contains definitions useful to the beginning user. There are also other definitions which are intended more for demonstration purposes. A sampling of functions from Graphics.jam will be included in the following table along with the basic commands from JamGraphics.bcd in terms of which they are defined. The commands whose names start with a period come from JamGraphics.bcd and the other commands come from Graphics.jam. It is possible to look at the definitions of the commands from Graphics.jam using .load == (see Dictionary Related Commands and Input/Output Commands). This allows you to see exactly what these commands do and examine how the more basic graphics commands are used.

There are several concepts common to many graphics commands. First of all, parametric cubic splines are used to specify curves. Cubic splines in turn are specified either in terms of the x and y coordinates of points, or by the coefficients of the actual parametric equations. Usually, the coordinates come from the mouse. A cubic spline segment may be specified by four points called its Bezier points. They have a specific mathematical relationship to the spline; informally, the spline passes through the first and fourth point, goes near the other two, and is always contained within the convex quadrilateral defined by the four points.

Many commands facilitate the building of paths made up of curves and straight lines. The path does not actually show up on the screen until a command is given to fill in the area enclosed by the path. There are commands which control how the area is filed in. In particular, some commands set up a clipping box which is intersected with the region to be filled in. There is also a painting function which controls the texture (halftone, etc.) of the shaded region.

.initdc b ő Initializes the stack of display contents.

.pushdc b ő Pushes a copy of the current display context onto the display contents stack.

.popdc b ő Replaces the current display context with that on top of the display context stack.

.translate <x><y> b ő The origin of the new coordinate system is set to the location of (x,y) in the old system.

.scale <sx><sy> b ő The coordinate system is expanded by sx in the x direction and sy in the y direction. The entire display is enlarged and lines are thickened. (Lines are normally about one unit wide).

.rotate <q> b see comment ő The coordinate system is rotated clockwise by q degrees.

.sixpoint <x0><y0><x1><y1><x2><y2><x3><y3><x4><y4><x5><y5> b ő Transform the coordinate system so that the first three points are mapped into the the last three.

.concat b ő Postmultiply the current transformation matrix by another transformation matrix.

.drawto <x><y> b ő Draw a line from the current draw position to the point (x,y). This moves the draw position too.

.rdrawto <x><y> b ő A line is drawn from the current draw position to the sum of that position and the vector (x,y). This moves the draw position as well.

.moveto <x><y> b ő The current draw position becomes the point (x,y).

.getpos b <x><y> ő Put the current draw position on the stack.

.rmoveto <x><y> b ő The vector (x,y) is added to the current draw position.

.drawboxarea <llx><lly><urx><ury> b ő A filled box is drawn with the given lower left corner and upper right corner. The draw position is left at the lower left corner.

.drawcubic <C0(x)><C0(y)><C1(x)><C1(y)><C2(x)><C2(y)><C3(x)><C3(y)> b ő A cubic is drawn with the given coeficients in its parametric equation.

.beziertocubic <x0><y0><x1><y1><x2><y2><x3><y3> b <C0(x)><C0(y)><C1(x)><C1(y)><C2(x)><C2(y)><C3(x)><C3(y)> ő Four Bezier control points are converted to the parametric form of a cubic.

.cubictobezier <C0(x)><C0(y)><C1(x)><C1(y)><C2(x)><C2(y)><C3(x)><C3(y)> b <x0><y0><x1><y1><x2><y2><x3><y3> ő The parametric form of a cubic is converted to its four Bezier control points.

.startpath b ő A path is started for the area generation machinery. Subsequent .enter, etc. commands will add to the path. The interior of the path is determined by a winding number technique.

.starteopath b ő A path is started for the area generation machinery except that even/odd parity is used to determine interior. There is a difference only in paths which cross themselves.

.enterpoint <x><y> b ő This command which must be preceded by .startpath, enters the point (x,y) in the current path. Successive .enterpoint's create polygonal paths.

path b ő Enter a path defined by i calls to the .touch function. This is equivalent to i repititions of: .touch .enterpoint''.

.enterrect <llx><lly><urx><ury> b ő The rectangle defined by the given lower left and upper right corners is entered into the current path.

rect rect b ő The rectangle defined by to calls to the .touch function (see below) is entered into the current path.

.entercubic <C0(x)><C0(y)><C1(x)><C1(y)><C2(x)><C2(y)><C3(x)><C3(y)> b ő The given cubic (represented in parametric form) is entered in the current path.

.enterspline <x0><y0><x1><y1> ... <xn><yn><n> b ő Creates an open ended curve through the n given points and enters it in the current path. This curve is a natural spline consisting of n cubics.

.entercspline <x0><y0><x1><y1> ... <xn><yn><n> b ő This is the same as enterspline, except a closed curve is formed.

spline b ő This command from the file graphics.jam is equivalent to .enterspline except the i points come from i calls to the .touch function (see below).

cspline b ő This command from the file graphics.jam is equivalent to spline except a closed curve is formed.

.newboundary b ő A new boundary is started on the current path. If the new part of the path is inside a previous boundary in the same path, it designates a hole in the center exactly when it winds in the opposite direction.

.drawarea b ő Fill the interior of the boundaries comprising the current path. The current path is then deleted.

.drawscreenarea b ő Fill in the whole screen using the current texture and painting function.

.erase .erase b ő Erase all area inside the current clipping regions.

.cliparea b ő Set the clipping region to the interiors of the boundaries comprising the current path.

.clippedcliparea .clippedcliparea b ő Set the clipping region equal to its intersection with the interiors of the boundaries comprising the current path

clip b ő Start a new polygonal path defined by i calls to the .touch function (described below) and make this the current clipping region (from graphics.jam).

cclip b ő Execute the clip command except use the intersection of the new region with the old clipping region (from graphics.jam).

clips b ő The new clipping region is the union of i rectangles each defined by to calls to .touch (see below). Each rectangle is defined by two .touch's: one at its lower left corner and the other at its upper right.

blob b ő Start a new path and enter a closed spline defined by i .touch's (like cspline) and fill it in using .drawarea (from graphics.jam).

cblob b ő Draw a blob defined by i .touch's as the blob command does except intersect it with the current clipping region (from graphics.jam).

poly b ő Draw a polygonal line defined by i calls to the .touch function (from graphics.jam).

.dot <x><y> b ő Put down a dot at the coordinates specified.

dot <x><y> b <x><y> ő This command from graphics.jam is like .dot except it copies its arguments.

area b ő Fills in polygonal area defined by i calls to .touch, putting a dot at each .touch (from graphics.jam).

.texture <n> b ő The integer n is viewed as a sixteen bit octal number. It defines a 4 4 bit pattern which is tessellated when filling in areas. By default, n=—1 is used. This causes areas to be filled in solid black.

.paint <n> b ő This function interacts with the .texture setting to determine how pixels are reset when filling in areas. The integer n is in the range 0...3, but is more convenient to use the identifiers defined in the file graphics.jam. Pixels for which the texture bit is 1 are: set to 1 (black) if n=0 (paint), inverted if n=1 (invert), set to 1 and all other pixels are set to 0 if n=2 (replace), and set to 0 (white) if n=3 (erase). The default is paint.

.touch b <x><y> ő Returns the current corrdinates of the mouse when the red'' button is pushed. Execution is halted while waiting for the user to push the button.

.mouse b <x><y> ő Returns the current coordinates of the mouse in the current coordinate system. Execution does not halt. No buttons need be pushed.

.redup b ő This is a user definable function which is executed every time the red'' mouse button is released. When this happens, execution is interrupted and the coordinates of the mouse are put on top of the stack. Then the function executed. All of these default to .pop .pop so they originally function as no-ops.

.reddown b ő similar comment

.yellowup b ő similar comment

.yellowdown b ő similar comment

.blueup b ő similar comment

.bluedown b ő similar comment

.setfont <KS-fontfile name><n> b ő Set the font for the character drawing commands, using n point type. There is no default font, so this command is required before any characters can be drawn.

.drawchar <c> b ő Draw a character at the current draw position and update the draw position to reflect the width of the character.

.erasechar b ő Erase a character at the current draw position and update the draw position by the negative of the width of the character.

.drawstring <s> b ő Draw the string s at the current draw position and update the draw position to reflect the length of the string.

.getstringbox <s> b <x0><y0><x1><y1><x2><y2><x3><y3> ő Return the four corners or the bounding box of the given string.

.getcharbox <c> b <x0><y0><x1><y1><x2><y2><x3><y3> ő Return the four corners or the bounding box of the given character.

text <x><y><dy><s> b ő Put the lines of text from the string s into the screen starting at the point (x,y). Lines are separated by carriage returns and are spaced dy below each other with a left margin at x (from graphics.jam).

.displayoff b ő Blank out the whole screen including the text window.

.displayon b ő Reverse the effect of the previous command.

Error Handling

Run time error handling routines in JaM are user definable. When such an error is detected, the appropriate function (identifier, whose value is to be executed) is called. The default definitions of these functions are found in the file errordefs.jam. Not having these defaults loaded will cause an infinite string of errors when JaM tries to call the error handling routines. These defaults may be changed, but typically they stop execution and print the stack after displaying a short message regarding the type of error.

When writing new error handling routines one must keep in mind that the operand stack and execution stack must remain intact when the error handling routine is called. One version of these routines prints the stack using /stk (see Input/Output Commands) and puts the user in a loop which reads lines from .mystream (the input stream) and executes them. This terminates when an empty line is found. Hitting carriage return causes JaM to attempt to continue execution. At various stages in this routine it is possible to get an additional (nested) error. This could be a little awkward. In this case it is a good idea to use the .stop command. The error handling routines are:

.stkundflow b ő Called when there is an attempt to get something from an empty stack.

.undefkey b ő Called when an identifier cannot be found in a dictionary.

.longname b ő A rare error caused by excessively huge file names.

.badname b ő Called when a string which was supposed to be a file name cannot be found in the directory.

.typecheck b ő Called when some argument of a function is of the wrong type. The offending primitive command is left on the stack along with its other arguments.

.dictfull b ő Called when an attempt is made to define something into a full dictionary. This may mean a system utility has tried to define its own temporary varible into a full user dictionary.

.syntaxerr b ő Called when the scanner finds an unmatched )''.

.overflow b ő Arithmetic overflow.

.stkovrflow b ő Rare, considering JaM's virtual memory. Look for infinite recursion, etc.

.rangechk b ő Something out of range, usually in an array or string manipulation command.

.sizechk b ő Occurs only in the .cvis and .cvirs commands (see Type Conversion). Warning -- this routine has been neglected in some versions of the file errordefs.jam.

The Edit Package

This package can help reduce some of the inconvenience of continually having to change a bravo file when one is debugging programs in JaM. It is possible to make minor changes in function definitions without having to exit JaM and .run an external file again. This helps prevent the virtual memory from being filled up with garbage and it can save a lot of time. The editor is necessarily rather primitive, however, and it is desirable for safety to have programs saved on external files. For these reasons, this package should not be overused.

To use this package, run edit.jam (see .run under Input/Output Commands). The commands are:

/edit <k> b ő Tell the editor to edit the value of the key k (usually a function name). <k> and its value are printed in the format of /p (see below). Subsequent calls to /p and /r refer to k.

/p b ő Print the function definition being edited. The format is: (name)(definition).

/r <s><r> b ő The first occurance of the string s in the definition being edited is replaced by the string r. If s is not found, a message is printed and the definition is unchanged. To see the effect of your change, use /p.

Programming and Use of JaM

Because JaM is quite different from other programming languages, it is appropriate to give hints on how to program and put JaM to good use.

The JaM input language has very little syntax. This attribute is both good and bad. The lack of syntax is good because a uniform representation is attained. The lack of syntax is bad because the code is hopelessly unreadable. In JaM it is almost true that any line of code can do anything (given the appropriate redefinitions of identifiers). Because of this property of JaM code, it is desirable to do several things when programming. First, document each funtion as it is written (use /def and /xdef under Dictionary Related Commands). Second, use naming conventions for functions that all belong to a given class (for example, intrinsic commands are started with .''). The latter convention will allow a person reading the code to tell what catagory a function is in by its name and may help him avoid accidentally redefining intrinsic functions.

Since JaM is a stack orientated machine, the user must mentally keep track of the contents of the stack. It is easier to program JaM if each routine performs only one function and is very short. Normally a JaM routine should be at most one or two lines long. For example, suppose we wish to use the absolute value of a given number. Then, rather than introduce the code in line, it is desirable to write an "abs" function and then use that function e.g.

(abs)(.dup 0 .lt (.neg) .cvx .if) .cvx .def

Also if complex paramerters are being passed to JaM control statements, it is better to name the parameters rather than have lines and lines full of parentheses.