ASL Standards

Transcribed from the printed issue; not yet reviewed. Read it in the PDF of the issue, page 46

Preface¶

At the ASL conference in October, I agreed to attempt to codify the standards that have been agreed for the ASL project. These standards are formulated as fairly loose guidelines and have been drawn up as a result of discussions during the course of the project and as a result of experiences in writing the APL code for ASL. Indeed, much of the current ASL code will need considerable reorganisation to bring it into line with these standards. We hope that the main beneficiaries of this document will be those intending to submit code to the ASL project, and, of course, others producing APL systems.

Contents¶

APL language usage
Functions and error trapping
Naming conventions
APL dialect differences
ASL documentation

Appendix:
Differences in second generation APL’s — Maurice Jordan

References:

1. ISO 8485: 1989 ‘Programming Languages - APL’ (also BS7301:1990)
2. Basic Statistics Volume - Norman Thomson
3. ASLGREG - Regression and generalised linear models volume Version 1.1 - Alan Sykes
4. Error trapping tutorials - Ziemann, Eastwood, Brand. Vector 6.1 July 89
5. Error trapping in APL2/PC - Norman Thomson. Vector 6.4 April 90

APL Language Usage¶

Base dialect. It is recognised that a considerable divergence exists between the different dialects of APL, and in particular between so-called ‘first generation’ and ‘second generation’ APLs. In an attempt to minimise problems that might arise in converting between APL dialects, it is recommended that contributors to the ASL project attempt to write APL code which follows the ISO standard (Ref 1) unless some compelling reason exists to adopt a second generation feature. Simple data arrays should be used where possible.

In practical terms, the current range of APL interpreters which are used by contributors to the ASL project are:

A contributor to ASL should make it absolutely clear which version of APL is to be regarded as the master version for the contributed code. Note that the release number is also useful as some of the interpreters listed above are prone to add new language features when they are upgraded.

Index origin. Index origin 1 is the standard and functions which use Index Origin 0 should localise ⎕IO.

Global Variables. Global or semi-global variables are deprecated and should only be used if they do a statistical job.

System functions. ⎕ functions should be avoided where possible as there is a high probability of differences between APLs. Even functions as innocuous as ⎕NC can have different definitions.

Functions and Error Trapping¶

Specification Language. It is recognised that APL (or a nominated dialect of APL) is likely to be used as the specification language for ASL code, and it is also recognised that it is needlessly cumbersome to include, for example, full comments and error trapping in a specification document. The notes which follow apply to implementations of ASL.

Error trapping. For bottom shelf functions, errors should result only from misuse (using parameters beyond those specified), and thus error trapping should cut back the stack by one and signal the appropriate error message. For an analysis of the different schemes of error trapping used by APL interpreters, see Refs 4 and 5.

Direct definition. Is not used in ASL.

Naming Conventions (Function names). There is currently no rule that ASL functions should carry identifying prefixes. All names in ASL should be distinct and should be registered at the specification stage. It should be borne in mind that functions may have to be renamed (either to facilitate integration with user code) or to resolve name clashes. Use of ⍎ to construct names should therefore be avoided.

ASL function names should be meaningful without being too generic. Thus names like PRINT are not useful!

In many volumes groups of functions will fulfil related purposes and equally there will often be implementations of alternative algorithms. A suggested naming convention (Ref 2) is that function names should follow a general pattern:

<root> <inflection…>

where the dots indicate the possibility of multiple inflections. Implementations of alternative algorithms are given serial numbers as a further inflection. When a function calls a succession of auxiliary functions, the latter are named by applying successive ∆s to the root, or root+inflections. Thus full specification of a function name is thus:

[∆…]<root><inflection…><serial number>

Examples, from the Basic Statistics Volume, are:

MEAN
MEANF      mean of a frequency table

Naming Convention (Local names). A number of alternative schemes are suggested, covering function arguments, local variables and labels. The ASL contributor to should make a clear statement of the scheme used. These schemes are listed below.

1. Results

   Choose a standard name for a result (e.g. Z)

2. Arguments

   2.1 It is possible that an argument naming convention can be directly applied from statistical theory or from a suitably acknowledged reference. Whilst attractive in terms of readability for statisticians, it is highly likely that supplementary names will have to be introduced and thus recourse will have to be made to some APL naming convention (see below).

   2.2 Meaningful upper case names can be given to arguments (DF for ‘degrees of freedom’ in example below). Note that this does not relieve the author of the responsibility of describing the argument!

   2.3 Arguments names can be constructed to indicate the nature of the expected argument type (Ref 2). The word will be constructed in lower case letters. For example, the following coding is used in Ref 2:

   Prefix   Algebraic Type   Rank   Repeatability Suffix
   ne       b                s      v
   nd       n                v      m
   f        z                m      a
   s        (r)              a      2
            p
            c
            g
   

   where:

        ne     non-empty                          s     scalar
        nd     non-degenerate (non empty/scalar)  v     vector
        f      frequency                          m     matrix
        s      shape                              a     array
        b      boolean                            2     repeat twice
   only
        n      non-negative integer
        z      integer
        r      real (default)
        q      positive reals 0<q
        p      probability 0<p<1
        c      character
        g      general (character or numeric)
   

   Note that type ‘fm’ (frequency matrix) occurs frequently and describes a two column numeric matrix - class values and number of items in a class.

   2.4 Other local variables may similarly be given names which follow one of the above rules, or should use the single character names

   T, U, V, W

   Loop counters will use the sequence

   I, J, K, L

   2.5 Labels should either follow the sequence

   L1, L2, L3, …

   (using EL1,… as ‘end loop’ if required) or, preferably, use a meaningful name where one can be constructed.

   2.6 Compound arguments will often be employed. Each component is separated by an underscore and named independently (as above). Such arguments should be explicitly decomposed:

   (N A B)←N_A_B         (in a second generation APL)
   

3. Comments should follow the standard scheme illustrated below:

     ∇RES←DF CHIDEN X;Y;Z;∆ELX
[1]   ⍝ FN: RETURNS VALUES OF THE CHISQUARED PROBABILITY DENSITY
[2]   ⍝ SS: ISO/BS
[3]   ⍝ RA: VECTOR OF CHI SQUARED VALUES WHERE PROB'S ARE REQD
[4]   ⍝ LA: SCALAR INTEGER - DEG OF FREEDOM OF CHI_SQUARED DIST'N
[5]   ⍝ RE: VECTOR OF PROBABILITIES
[6]   ⍝
[7]    ∆ELX←⎕ERX ERR
[8]    RES←(X*Z)×(*-0.5×X)÷(!Z←¯1+0.5×DF)÷0.5*0.5×DF
[9]    →0
[10] ERR:'ARGUMENT ERROR' ⎕ERS 8
     ∇ 1991-10-16 0.12.36

with recommended comments and identifiers from:

Dialect differences¶

It is hoped that the attached notes covering dialect differences (see Appendix) will assist an ASL author in cultivating an awareness of areas where APL dialect differences will cause translation problems.

ASL documentation¶

Certain minimum levels of documentation should be supplied with ASL workspaces. This will cover the use of the workspace, interdependencies within the workspace and examples of usage. Since ASL workspaces can range from collections of largely stand-alone functions to complete systems, the quantity of documentation in each of the categories may vary from volume to volume.

Specification document¶

Each ASL volume should begin with a Specification Document which outlines the scope of the volume and indicates the names and syntaxes of the functions within the volume. The specification document is used to indicate names used, naming conventions applied and data structures. Reference 2 - the Bottom Shelf specification document - is a good example of this type of document. This may be the same as the:

General documentation¶

This covers the overall theory and operation of the volume, with reference, if appropriate, to suitable published reference material. The ASL Regression volume (Reference 3) provides a good example of this sort of document.

Function documentation¶

This document will include the internal comments found within ASL functions (see above) together with:

Example uses of the function with test data and expected results.

Indication of the range of operation of the function (if not internally documented).

If variants of a given function exist, a description of the variants and their differences should be included.

Workspace documentation¶

Each ASL workspace should be supplied with the following pieces of workspace documentation (or the means to produce them):

Workspace listing
Function cross reference
Global variable listing and description
List of functions for which an alias exists

Porting notes¶

Each ASL document should have some notes on porting. In the case of most workspaces this will be confined to comments regarding use of second generation APL features, and, in particular, of uses of APL features known to vary from APL system to APL system. It may also be appropriate to indicate means of testing parts of the workspace or volume as they are recoded, especially if the recoding process is not trivial.