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 explanations 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 proceeds 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. Refer to the JaMImager package for further information.

JaM execution proceeds 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 essentially 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.

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 utilities. 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 relevant details of the system.

Open JaMControlImpl.mesa. This is where the JaM primitives get registered. Most of the the JaM primitives are exported to JaMPrimitives.mesa; use Tioga's GetImpl to open up the file that implements a given primitive. When reading the CedarMesa implementation of a command, remember that operands get popped off in the opposite order they get pushed. The JaMImager documentation says where the Imager-related routines are implemented. If you don't find the definition of a this way, it may be defined in a JaM file (you can use the .load command to find out whether it is primitive or not). JaMBasics.JaM and JaMImager.JaM are two places to look for non-primitive definitions.

String literals are defined in either of two ways: by enclosing them in parentheses or using double-quotes, Cedar-style:

Numeric literals are pretty much standard fare:

Curly braces are used for defining special arrays of quoted literals. Example:

Percent sign causes the remainder of the line to be ignored (you can use tioga comments for whole-node comments):

Any other consecutive sequence of printing characters constitutes a name (atom).

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:

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.

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).

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.

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.

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.

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.

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 dictionary 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.

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, retrieveing 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)

This category 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 arguments 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)

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 naturally 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.

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:

There is a special syntax to combine the advantages of both. If you enclose the body in curly braces, JaM implicitly quotes everything inside and makes an array. Thus the preferred way to write the above definition is

which will have the same effect as the second example above.

Occasionally it is desirable to define a very long body that is too big for the "{. . .}" notation to handle; in this case revert to the string representation, which can handle very large objects.

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

Refer to JaMObsoleteDoc.

Refer to JaMImagerDoc.

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:

Refer to JaMObsoleteDoc.

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 function 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 category a function is in by its name and may help him avoid accidentally redefining intrinsic functions.

Since JaM is a stack oriented 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.

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