About The A+ Reference Manual

# About This Document, the Online A+ Reference Manual

Other Sources of A+ Information
Organization of the Manual

The Index

Terms Used in the Manual

Data Type and General Type
Index Origin
Comparison; Tolerably Equal
Names and Values

Notation

Font Usage
APL Font
Backquote
Capitalization

Your Questions and Comments

> This manual describes the A+ programming environment. It is intended mainly for reference.

> It is recommended that you use Netscape Navigator, Release 4.0 or later. Some portions of these manuals may display incorrectly with other browsers. Be sure you have followed the instructions for displaying the special APL characters, so that you can see this document properly.

# Other Sources of A+ Information

> Be sure to check the A+ Home Page periodically (www.aplusdev.org). News items will be posted there from time to time. There is also a heading on the A+ Home Page marked "Documentation", which can direct you to some related material, such as tutorials.

# Organization of the Manual

> Because this manual is intended mostly for reference, the descriptions of the primitive functions, operators, system functions, system variables, and commands are listed alphabetically, by their English names, i.e., names such as Add, Rank, Expunge, Print Precision, and Load. In the text itself, the subheadings include their A+ names also. The attributes are listed alphabetically in the table "Display Attributes", with brief descriptions and links to other text where appropriate.

> Among the tables in The "Quick Reference" appendix are four that should be mentioned here. "Primitive Function and Operator Names and Links" lists the symbols for the primitive functions and operators, ordered by category (arithmetical, logical, structural, and so on), gives the corresponding names, and has links to their descriptions. A symbol's dyadic definition has been preferred to its monadic definition where the two would dictate different categories. "System Function Names and Links", "System Variable Names and Links", and "System Command Names and Links" are alphabetized by A+ name and give the corresponding English names, with links.

> To find any additional information about an item in a table that does not have a link for it, look up the item in the index.

## The Index

> All system commands, system functions, and system variables are listed in their A+ forms in the index under these three headings ("system commands", etc.). They are listed separately under their English names, as well. Primitive functions and operators are each listed under one or more English names. The A+ symbols are listed in the "Symbols" section of the index, and can also be found (with links) in tables in the "Quick Reference" appendix, as already mentioned.

> The index includes entries for commonly used alternate names of primitive functions and operators; such an entry includes the name used in this manual, shown in parenthesis, and a link to the section in which the function is defined. The entry constitutes a see reference, while giving you a direct path when all you want is the principal reference for the function. Entries for certain other terms are of this form.

> References for an entry are shown as arrows; where there are several, they are separated by commas and the principal one, if any, is indicated by an asterisk following the arrow. For long sections, where a range of pages is shown in the printed version, a link to the end of the section is indicated by "end" following the arrow. Links following "see" or "see also" or "also see" lead to other index entries.

# Terms Used in the Manual

## Data Type and General Type

> There are seven data types in A+: character, integer, floating point, null, box, symbol, and function. The term integer is always used in this manual in this strict sense, to indicate not only a domain of values but also a particular internal representation, the one identified by the A+ type integer (`int, as the Type function calls it). Integral and integral value also refer to both domain and representation.

> The term restricted whole number is used to refer to any representation, integer or floating-point, of a member of the integral domain of values - that is, of a value for which integer internal representation is possible. The floating-point representations in the set of restricted whole numbers need only be equal to integers within the comparison tolerance or be less than 1e-13 in absolute value. See "Representation of Numbers", especially its "Comparison Tolerance" section. (Put another way, a scalar x is a restricted whole number if either (1) ©x is `int or (2) ©x is `float and either Íx is less than 1e-13 or there is a y such that x=y is 1 and ©y is `int.) The chief significance of this concept, of course, is that any floating-point representation that represents a restricted whole number can always be faithfully coerced to an integer representation. All empty arrays are included in this set, as discussed below.

> Many A+ functions and operators take arguments of several types, sometimes with some limitation, and it is convenient to divide A+ data objects into three classes, as they do. These classes are called general types:

> - character, consisting of simple arrays of characters

> - numeric, consisting of simple arrays, unrestricted as to value, of floating-point numbers and integers

> - mixed, containing all other data, namely
>   - simple arrays of functions and symbols
>   - all nested arrays: box, function, and symbol
> Because the set of restricted whole numbers and the general types are used mostly to indicate inclusion in the domains of functions, and because most functions accept empty arrays of any type, all empty arrays are included in the definition of restricted whole numbers and in each general type. For efficiency, the (empty) result of a mathematical function for a Null is whatever is most convenient for the function: Null, integer, or floating point.

> These words are used in the obvious ways, such as in the terms symbol array or symbolic array or array of symbols, meaning an array every element of which has data type symbol, and numeric array, meaning an array that has no elements or has only elements whose data type is integer or has only elements whose data type is floating point. The more elaborate term array of type symbol, on the other hand, means only that the first item of the array is of type symbol - i.e., the first item of the first item of ... the first item is a symbol; the other items of the array can be of types symbol, function, or box.

## Index Origin

> A+ enumerates lists and whatnot using the integers 0, 1, 2, ...; that is to say, A+ employs 0-origin indexing. This manual uses i-th, for any letter i, in the same sense, to agree with A+. The words first, second, third, and so on, however, are intended to convey their ordinary English meanings. Hence if an element of some list is spoken of as the third element and also as the n-th element, then n has the value 2. Digits are never used in such a construction: 0-th, 2-th, and so forth never appear again in this manual.

## Comparison; Tolerably Equal

> A+ makes some comparisons using a tolerance. See "Representation of Numbers", especially its "Comparison Tolerance" section. When two objects are equal within the tolerance, they are called tolerably equal. This term is also used in a more general way, to mean equal within the tolerance for those objects to which the tolerance applies and strictly equal for all others. Tolerably equal is said only with regard to comparisons that employ the tolerance under some circumstances.

## Names and Values

> If the name x has the value 2 associated with it, one normally says simply that x is 2. This manual follows that or a similar usage, usually even in more complicated cases. For example, suppose g is the name of a function and the value associated with x is `g, the symbol form of the name g; the manual may simply say that x is a function. If x has the value "`g", which is a character string that gives the display form of the symbol form of the name g, the manual may simply say that x names g when, say, x is an argument and its role is to supply the name of a function.

# Notation

> The conventions adopted for the use of the APL font, capitalization, backquote, and quotation marks in this book are intended to promote simplicity, readability, and clarity.

## Font Usage

> APL font (Kapl) is used as described under the heading "APL Font".

> Bold Courier is used for commands and text that you must enter literally, wherever APL font is not appropriate.

> Light Courier is used for filenames, pathnames, utilities, Unix commands and command-line options, environment variables, prompts, and so on, wherever neither Bold Courier nor APL font is appropriate, as in
> for(i=0;i<n;++i) result->p[i]=ic(aobj);
> or "This function uses the system call ioctl()".

> Italic is generally used for variable text that you must enter: e.g.,
> "$load filename",
> indicating that you must enter the A+ $load command followed by the name of a file, or
> "Enter
> emacs filename"
> to indicate that you must enter the Unix emacs command followed by the name of a file.

> Bold Times Roman (or the bold weight of whatever proportional font you have selected) is used for keys and screen (GUI) elements, such as the Shift key, the combination Shift-left-arrow, and the Options menu.

## APL Font

> 1. The A+ names of system variables and functions, A+ commands, A+ defined functions and variables, and the s functions (the screen management functions is, show, etc.) and, of course, the A+ primitive function and operator symbols appear in APL font.

> 2. All multicomponent A+ expressions appear in APL font, except that `name and 'name' sometimes appear as just name, in ordinary text font, as discussed below.

> 3. The A+ keywords (if, do, etc.) appear in APL font in multicomponent A+ expressions, as required by (2), but are shown in ordinary text font elsewhere - here, for instance.

> 4. Numbers normally appear in ordinary text font. APL font is used for them, however, in these cases:

>    - the number is part of a larger A+ expression, so rule (2) applies;
>    - the number is explicitly an entry or display in an A+ session;
>    - the same number or an associated number occurs nearby in a setting that requires APL font, so consistency dictates the use of that font;
>    - the number is expressed in a form peculiar to A+ (as distinct from mathematics or ordinary English), as in 2.78e-4.

> 5. Names of attributes (for screen management) and names of the values that attributes can have are normally set in ordinary text font when they occur alone, but where a particular value is being explicitly given for an attribute, as in the "Default" column of a table, it may appear in APL font, together with a backquote or quotation marks, e.g., `center, 'kaplgallant'.

## Backquote

> The backquote (`) is used only for system variables and where the context explicitly requires a symbol. Thus, in the "Attribute" column of a table, only names appear (e.g., titlefg), and of course the response to "show `b" is described as "b is displayed."

## Capitalization

> The English names of the A+ primitive functions and operators, as contrasted to their symbols, and of the system functions, variables, and commands always appear in ordinary text font, with an uppercase initial letter and sometimes another uppercase initial: Plus, Grade up, Pi times, Natural log, Value in Context, Less than or Equal to, Inner Product, Set Attribute, Random Link, Global Objects, and so on.

> Note: Many names here, such as OLWM, Unix, Sparc, RS/6000, Helvetica, Times, and Palatino, are trademarks or registered trademarks. Except occasionally for font names, initial uppercase letters have been used for those names believed to be trademarks.

# Your Questions and Comments

> Questions, comments, and corrections are welcome. Please email them to doc@aplusdev, or, if the subject is of general interest or you seek a wider response, to aplus@aplusdev.org.