Function Documentation Conventions

For purposes of this manual, a function is something whose semantics are satisfactorily understood in terms of consuming some (possibly zero) number of input values from the data stack and returning some (possibly zero) number of values on the data stack. Thus, things which are not mathematical functions, such as frandom, still qualify, but things like if and -> do not, and are instead termed operators.

A typical function definition looks like

join { string string -> string }
File: job.t
Status: alpha

The join function concatenates two strings and returns the resulting string.

The first line gives the name of the function followed by the the number of values it accepts and returns, separated by ->. There may be more than one line like this if the function does several distinct tasks depending on the types of its parameters. Groups of related functions may also be listed one per line here. Operators other than functions (such as function definition, variable assignment, and control structure operators) give a synoptic usage example rather than a simple argsIn/argsOut declaration.

Argument abbreviations used include

`int'

An integer.

`flt'

A floating point number.

`#'

An number, integer or floating point.

`stg'

A string.

`obj'

Any variety of object supporting generic keyval operations.

`[]'

A stack block

The second line gives the source file implementing the function.

The third line will be one of:

`Status: temporary'

This function is needed at the moment but is scheduled to be replaced by something better. releases.

`Status: tentative'

The function is offered for discussion and perhaps experimentation, but is very likely to change in future releases.

`Status: alpha'

The function is in useful form, but is subject to change if any possible improvement becomes evident.

`Status: beta'

The function is thought to be final form, but is subject to change if significant problems are identified in actual use.

`Status: production'

The function is baselined for general use, and incompatible changes will be made only as a last resort. (Compatible extensions, such as allowing additional argument types, may still be considered.)

Go to the first, previous, next, last section, table of contents.