JaM is a simple stack-based language. 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.

All functions in JaM make use of the operand stack. This stack contains objects: integers, reals, booleans, character strings (ropes), identifiers (atoms), commands, 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.

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. Alternatively, strings may be enclosed in double quote marks, as in Cedar.

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

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 size hint specified at the time of their creation, but may grow to any size.

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.

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)

TJaM does not provide a set of commands for I/O, since it is meant to be used with the style machinery. Just one input-related command is provided:

There are several different types of objects in JaM. 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. 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.

Strings in TJaM are represented by Cedar ROPEs.

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, but those for Tioga are in TiogaUtils.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. The error handling routines are:

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.