Labs805/File Layout

Labs Overview File Layout Development Migration

File Layout

Lab files are ordinary text files with extension .ijt.

The file starts with a header defining various nouns. The rest of the file is organized into chapters, and sections within chapters.

Any lines beginning NB. == are comments and are ignored.

Header

The header is executed as a script in the jlab locale, and may define the following nouns. LABTITLE is required and the others are optional:

LABTITLE	Title (must be given first)
LABAUTHOR	Author (may include address, email etc.)
LABCOMMENTS	Comments
LABDEPENDS	Dependencies (see below)
LABWIDTH	Text width (default 61)

For example:

LABTITLE=: 'Fuzzy Logic'
LABAUTHOR =: 'Brian Schott'
LABDEPENDS=: 'plot'

The title and author (if given) are shown when the lab is run. Comments are not shown, and are intended only for those reading the lab source.

Text width: text output is wrapped to the LABWIDTH. The default is 61 characters, which should display on all screens with typical screen fonts. To avoid the automatic wrapping, for example when including J code, indent text by one or more spaces.

The header may also contain any other required definitions, such as initialization code that is to be run at the beginning of each chapter. You can invoke any such definitions within PREPARE keywords in the first section of the chapter (see below). Since the header is defined in the jlab locale, subsequent references must use the full locale name.

Dependencies

Dependencies are given in the same format as the argument to load, which in turn calls getscripts_j_. Use this to test dependencies, for example, given:

LABDEPENDS=: 'general/misc/pack plot'

then check that the following are valid scripts when the corresponding addons are loaded:

   > getscripts_j_ 'general/misc/pack'
/home/elmo/j8/addons/general/misc/pack.ijs
   > getscripts_j_ 'plot'
/home/elmo/j8/addons/graphics/plot/plot.ijs

Note that the Lab itself must load or require the dependencies where needed. That is, it should contain lines of the form:

  load 'general/misc/pack plot'

Chapters

Chapters are delimited by a line beginning Lab Chapter, for example:

Lab Chapter Function Rank

A Chapter has a one or more sections, and each Chapter should be able to run independently, so that the Chapters can be run in any order.

If there is only one chapter, the line Lab Chapter need not be given.

Sections

Sections are delimited by a line beginning Lab Section optionally followed by a section title. Where the section title is not given, it is assumed to be a continuation of the previous section.

Sections are in two parts, either of which may be empty. The first part is the text to be displayed, ended by a line starting with ) . Lines after the ) are J sentences that are executed. If no ) line is given, the section is assumed to be text only.

For example, the following is a lab section named "Numbers":

Lab Section Numbers
The integer function (i.) generates numbers:
)
i.10           NB. first 10 numbers
i.4 3          NB. first 12 numbers in a 4 by 3 table

The lab system displays the text and executes the J sentences. All display is normal output to the terminal, and the user has complete access to the J session.

Keywords

Lines in the second part of a Lab Section (the J sentences to be executed) may be enclosed in pairs of keywords PREPARE or SCRIPT.

PREPARE are sentences that are run silently before the rest of the section is run. For example this could load required code, or check whether it is OK to continue the lab.

SCRIPT are character strings that will be appended to the global variable SCRIPT_jlab_. For example, this can be used to build up an example script.

The PREPARE and SCRIPT keywords must occur at the beginning of the section. Any text on the same line as the keyword is ignored.

To prevent further execution of the section, signal an error. The utility assert_lab_ may be used for this purpose; the left argument is the message to display when a 0 occurs in the right argument.