q'nial dictionary version 6.3

applicative transformer

=BYKEY= =CONVERSE= =FOLD= =INNER= =OUTER= =TEAM=

apply-by-partition transformer

=BYCOLS= =BYROWS= =PARTITION= =RANK= =REDUCECOLS= =REDUCEROWS=

arithmetic operation

2 48 84 122 186 188 206 224 227 231 239 252 316 330

array generation operation

68 138 241 281 326

comparison operation

139 140 180 181 182 183 184 185 349

construction operation

14 44 47 142 163 171 212 298 301

control structure

=case=-expr 125 144 =repeat=-loop 362

control structure transformer

=FORK= =ITERATE=

conversion operation

49 50 110 126 130 218 238 312 333 334 338 339

concept

address, argument, array, by-variable, canonical, clear workspace, conform, continue workspace, curried operation, debugging, definition, dimensions, equations, expression, extent, fault triggering, fault values, functions in nial, global environment, indexing, initial subdirectory, interrupt, item, level, local environment, nested definition, numeric type hierarchy, operation, operation composition, overflow, pervasive, prelattice of atoms, profiling, program fragment, regular expression notation, role, scope of a variable, standard definitions, top level loop, transformer

constant expression

65 109 200 219 285 319 344 358

data rearrangement operation

=flip= 129 211 271 273 342

debugging command

192 270 309 310 332

display parameter

63

distributive transformer

=EACH= =EACHALL= =EACHBOTH= =EACHLEFT= =EACHRIGHT= =LEAF= =TWIG=

evaluation operation

16 22 75 77 79 100 102 131 133 134 213 276 350 351 355

feature

178

file expression

115

file operation

15 56 114 132 202 237 249 368

host direct access file operation

113 248 367

insertion operation

74 222 223

interactive input/output expression

=clearscreen= 246

interactive input/output operation

244 251 364 366 370

linear algebra operation

150 152 302

logic operation

13 83 96 198 208 348

measurement operation

7 8 10 11 12 26 78 153 154 155 156 157 158 159 =numeric= 295 346 322 354

nesting restructuring operation

29 57 60 179 187 240 274 305

nial direct access file operation

99 116 245 250 365 369

operation property

27, 28, 190, 228, 258, 347

picture operation

80 82 216 221 225 288 300

profiling expression

232 291

recursion transformer

=ACROSS= =DOWN= =RECUR=

reduction transformer

=ACCUMULATE= =reduce=

reshaping operation

172 189 215 226 =reshape= 353 =void=

scientific operation

17 18 19 66 67 103 173 177 297 299 306 323 324

search operation

118 119 145 199 282

selection operation

52 69 71 72 87 =dropright= 101 120 127 164 220 243 268 279 315 320 =takeright= 327

selection transformer

=FILTER=

set-like operation

9 170

sorting operation

137 304

sorting transformer

=grade= =sort=

string manipulation operation

260 261 262 313 314

structure testing operation

25 95 296

syntax

action, assign expression, atlas, block, bracket-comma notation, cast, comment, expression sequence, external declaration, infix notation, juxtaposition, operation form, prefix notation, reserved words, strand notation, synonym, transformer form, variable

system constant

=no_value=

system expression

32 34 36 42 55 61 85 106 141 193 194 207 269 308 328 331 337 343 357 361

system operation

33 40 41 94 98 143 169 174 175 195 263 275 280 283 284 286 287 289 290 292 293 294 317 336 352 360

system transformer

=NO_TR=

system variable

168

user defined expression

51 165

user defined operation

253

The operation 2 produces the following results when applied to atoms of the six types:

If the argument is the largest negative integer for the computer, the result is the corresponding positive real number because the corresponding positive integer is too large for representation as an integer.

abs  l  -2  3.5  `a  "abc  ??error

1 2 3.5 ?A ?A ?error

The operation 2 can be used to convert a boolean value to an integer. Its primary use is in the numeric domains, where it is used to give a positive number measuring the size of a number.

The transformer =ACCUMULATE= is similar to the concept of scan in APL. It computes the partial reductions of the initial lists of the items of A, using =REDUCE= f (a right-to-left reduction) to compute each partial result. (A reductive operation is one which when applied to an array having a number of items returns a single result.)

In the example below, the initial lists of Z are:

[13, 13 39, 13 39 92, 13 39 92 45];

and the right-to-left reduction of f on Z is equivalent to:

[f 13, 13 f 39, 13 f (39 f 92), 13 f (39 f ( 92 f 45))]

Z := 13 39 92 45 ;
ACCUMULATE pass Z

+--+-----+----------+---------------+
|13|13 39|+--+-----+|+--+----------+|
|  |     ||13|39 92|||13|+--+-----+||
|  |     |+--+-----+||  ||39|92 45|||
|  |     |          ||  |+--+-----+||
|  |     |          |+--+----------+|
+--+-----+----------+---------------+

The first example shows that accumulate builds the result values with a right-to-left reduction.

ACCUMULATE max Z

13 39 92 92

ACCUMULATE min Z

13 13 13 13

ACCUMULATE sum (count 10)

1 3 6 10 15 21 28 36 45 55

ACCUMULATE minus (count 10)

1 -1 2 -2 3 -3 4 -4 5 -5

Useful applications of =ACCUMULATE= include the accumulate sum transform used to compute a running sum, and the accumulate minus transform which gives an alternating sum.

ACCUMULATE or oollooll

oollllll

S := '  black and white'

black and white

B := not (S match ` )

oolllllolllolllll

ACCUMULATE or B sublist S

black and white

The =ACCUMULATE= 208 transform produces a bitstring that can be used with sublist to drop leading items that fail to meet a predicate.

An action is the construct that is entered in the interactive loop of the Q'Nial interpreter or accepted as an input unit within the operation loaddefs:

action ::= definition-sequence
   | expression-sequence
   | external-declaration
   | remark

definition-sequence ::= definition
   { ; definition } [ ; ]

remark ::= # < any text >

If an action is a definition-sequence, its definitions are installed in the global environment.

If an action is an expression-sequence, it is executed and a value is returned. The value returned by an expression-sequence is displayed on the screen unless it is the fault ?noexpr.

An external-declaration assigns a role to a name in the global environment so that the name can be used in other definitions before it is completely specified.

A remark is an input to the Q'Nial interpreter that is not processed. It begins with a line that has the symbol # as the first non-blank character in the line. In direct input at the top level loop, a remark ends at the end of the line unless a backslash symbol ( \ ) is used to extend the line. In a definition file, a remark ends at the first blank line. A remark cannot appear within a definition or expression-sequence.

=ACROSS= is a general recursion transformer for traversing the length of an array. It has three operation arguments: endf is applied to the end argument before starting to build the result, parta computes the left value from the argument, which is stacked, and joinf combines the left and right values as the recursion unwinds.

ACROSS [ 0 first, pass, plus ] 3 4 5 6

18

reshape [ shape, ACROSS  [pass, pass, CONVERSE append ] ] 2 15 12 4

4 12 15 2

An address is an integer or a list of integers describing the location of an item in an array. An address uses 0-origin counting, i.e. the first position in a list is at address 0. All the addresses of an array can be stored in an array of the same rectangular structure as the array itself. Such an array is called the grid of an array. Consider the following example:

            GRID OF THE ARRAY                 ARRAY
+-----+-----+-----+-----+-----+-----+ +---+---+---+---+---+---+
|+-+-+|+-+-+|+-+-+|+-+-+|+-+-+|+-+-+| |499|434|122|770|733|890|
||0|0|||0|1|||0|2|||0|3|||0|4|||0|5|| +---+---+---+---+---+---+
|+-+-+|+-+-+|+-+-+|+-+-+|+-+-+|+-+-+| |660|160| 32|808|240|584|
+-----+-----+-----+-----+-----+-----+ +---+---+---+---+---+---+
|+-+-+|+-+-+|+-+-+|+-+-+|+-+-+|+-+-+| |473|235|164|496|808|966|
||1|0|||1|1|||1|2|||1|3|||1|4|||1|5|| +---+---+---+---+---+---+
|+-+-+|+-+-+|+-+-+|+-+-+|+-+-+|+-+-+| |156|205| 34|576|236|454|
+-----+-----+-----+-----+-----+-----+ +---+---+---+---+---+---+
|+-+-+|+-+-+|+-+-+|+-+-+|+-+-+|+-+-+|
||2|0|||2|1|||2|2|||2|3|||2|4|||2|5||
|+-+-+|+-+-+|+-+-+|+-+-+|+-+-+|+-+-+|
+-----+-----+-----+-----+-----+-----+
|+-+-+|+-+-+|+-+-+|+-+-+|+-+-+|+-+-+|
||3|0|||3|1|||3|2|||3|3|||3|4|||3|5||
|+-+-+|+-+-+|+-+-+|+-+-+|+-+-+|+-+-+|
+-----+-----+-----+-----+-----+-----+

The array on the right is a 4 by 6 table of numbers. It has 24 items arranged along two directions of length 4 and 6 respectively. The address of 496 is [2,3].

The addresses of a list are integers: 0, 1, etc. For convenience, in situations where an address of a list is expected, a solitary integer is treated as an integer.

The address of a single is the empty list Null.

The operation allbools tests whether or not A is a nonempty array of boolean items. It returns true if A is not empty and all the items of A are boolean atoms, false otherwise.

allbools lool

l

allbools 1 0 1

o

allbools Null

o

The operation allchars tests whether or not A is a nonempty array of character items. It returns true if A is not empty and all the items of A are character atoms, false otherwise.

allchars 'apple pie'

l

allchars "today

o

allchars Null

o

The operation allin tests whether or not all the items of array A are also items of array B. The result is true if the test holds and false if it does not.

3 5 7 allin count 10

l

'ae' allin 'where are you?'

l

'where' allin 'hear'

o

The items of A and B are compared for exact equality, including type. The items being compared may be atoms or they may be any other array.

The operation allints tests whether or not A is a nonempty array of integer items. It returns true if A is not empty and all the items of A are integer atoms, false otherwise.

allints lool

o

allints 1 0 25

l

allints Null

o

The operation allnumeric tests whether or not A is a nonempty array with all atoms of the same numeric type. It returns true if A is not empty and all items are boolean atoms, or all are integer atoms or all are real atoms, false otherwise.

allnumeric 3.5 -2.97

l

allnumeric l 45 3.78

o

allnumeric Null

o

The operation allreals tests whether or not A is a nonempty array of real items. It returns true if A is not empty and all the items of A are real atoms, false otherwise.

allreals 2 2.5 47.9

o

allreals 2.5 -7.8 27.3

l

allreals Null

o

The operation and applied to a boolean array A does the boolean product of its items. If all items of A are true, the result is true; otherwise it is false. In binary form and implements the and-connective of logic.

If A is a simple array and has a non-boolean item, the result is the logical fault ?L. The operation extends to non-simple arrays by the multi pervasive mechanism.

l and l

l

and llllloll

o

lloo and lolo

looo

And is a reductive operation in that it reduces an array of booleans to a single boolean. If its argument is a pair of bitstrings or a list of bitstrings, and is applied to bits in corresponding positions of each item of the argument producing a bitstring of the same length as one of the items of its argument.

The operation append attaches B to the end of the list of items of A. It returns a list of length one greater than the tally of A.

(2 3 4) append (5 6 7)

+-+-+-+-----+
|2|3|4|5 6 7|
+-+-+-+-----+

append '' 'Wow'

+---+
|Wow|
+---+

The first example shows list (5 6 7) appended to list (2 3 4). The second example shows that if an array is appended to an empty list, the result is the solitary of the second argument. If append is applied to an array that is not a pair, a fault is returned.

The operation appendfile writes a list of character arrays A to the end of the file named Filename, using one line of the file for each row in the items of A. If the file does not exist, it is created by the operation. The file must not be open.

Appendfile is similar to operation putfile except that putfile overwrites an existing file. Getfile reads a file containing text records.

putfile "Mailing ['1','2','3'];
appendfile "Mailing ['Mr. Jones','123 Main St','New York NY 12345'];
getfile "Mailing

+-+-+-+---------+-----------+-----------------+
|1|2|3|Mr. Jones|123 Main St|New York NY 12345|
+-+-+-+---------+-----------+-----------------+

The operation apply carries out the application of the operation represented by the array Op to array A. Op may be a phrase or string that names a predefined or user-defined operation or it may be the cast of an operation expression.

If the operation is represented by a phrase or string giving its name, the name is sought in the environment where apply is being used.

apply "second (3 4 5)

4

The operation to be applied may also be represented by the parse tree or cast for the operation expression. If the cast is a name, it is sought in the environment where the cast appears. In the following example, !first is the cast of the operation first.

(!first apply 3 4 5)

3

apply !(first rest) (3 4 5)

4

As seen in the second example, an operation expression does not have to be named in order to be used with apply. The entire first example is enclosed in parentheses to avoid conflict with the notation for executing a host command.

The operation arccos is the inverse of cos in the numeric domain. It produces the following results when applied to atoms of the six types:

The operation arcsin is the inverse of sin in the numeric domain. It produces the following results when applied to atoms of the six types:

The operation arctan is the inverse of tan in the numeric domain. It produces the following results when applied to atoms of the six types:

arctan l -2 0.35

0.785398 -1.10715 0.336675

arctan `a "abc ??error

?arctan ?arctan ?error

arctan 2. l 1 .5

1.10715 0.785398 0.785398 0.463648

An argument is an array value supplied to an operation. All operations in Nial take a single array as the argument, but binary operations expect that argument to be a pair. When an operation is used in infix syntax, then the two array values on the left and right are combined into a pair to be supplied as the argument to the operation.

The argument to an operation-form is treated specially. If the operation-form has only one formal parameter then the argument is assigned to the parameter. If it has two or more formal parameters, then the argument is checked to see if it has the same number of items as there are parameters. If so, the items are assigned to the parameters. If not, the result is the fault ?op_parameter.

The data objects of Nial are nested rectangular arrays. Atomic data objects such as numbers and characters are included within this description by virtue of an atom being considered as a self-containing array object with no dimensions.

Atomic Arrays

There are six types of atoms in Nial. They are boolean, integer, real, character, phrase and fault. The first three are numeric types and are used for arithmetic operations. The last three are literal types and are used for text and symbol manipulation. All six types of atoms are used in comparisons.

Rectangularity Structure

An array is a collection of data objects having its items held at locations in a rectangular structure. The items are viewed as being at locations that are positioned relative to a set of directions at right angles to each other. The items may be arranged along zero, one, two or more directions. For example, the following array is a 4 by 6 table of numbers. It has 24 items arranged along two directions of length 4 and 6 respectively.

+---+---+---+---+---+---+
|499|434|122|770|733|890|
+---+---+---+---+---+---+
|660| 32|808| 24|  5|473|
+---+---+---+---+---+---+
|499|434|122|770|733|890|
+---+---+---+---+---+---+
|660| 32|808| 24|  5|473|
+---+---+---+---+---+---+

The items of an array are themselves arrays. Thus, an array can have an arbitrarily deep nesting structure.

The operation assign assigns the value of A to the variable named by Nm. Nm may be a phrase or string (e.g. "X or 'X'), in which case the named variable is sought in the current environment; or it may be the cast of a name (e.g. !X), in which case it is sought in the environment in which it was cast. If the variable is found, its value is replaced by the array A. Otherwise, a variable with that name is created in the global environment and given A as its value.

Any phrase may be used as a variable name with the operation assign. Thus, it is possible to assign a value to names which are invalid identifiers. The associated value can be retrieved using the operation value. The result of the operation is A.

assign "X (2 3 4)

2 3 4

(!Var assign 2 3 4)

2 3 4

In the first example, the variable X is assigned the list 2 3 4. If this is done in an environment where X is a local variable, the local variable is updated. If X does not exist, it is created in the global environment.

In the second example, a variable Var must exist in the environment where the cast is done. The cast can be formed in a more global environment and passed into an operation as a parameter (This technique is called by-variable parameter passing).

assign-expression ::=
      { variable }+ := expression
      | indexed-variable := expression

An assign-expression assigns an array value to one or more variables at the time of evaluation of the assign expression. The semantics of an assign expression is interpreted in two stages: when the expression is analyzed (parsed) and when it is executed.

During the parse of the assign-expression appearing in a block, each name on the variable list is sought in the local environment. If the name exists in the local environment, the assignment affects the local association. If a name does not exist in the local environment and no reference has been made to a nonlocal variable with the same name, a local variable is created in the block. An assign-expression parsed in the global environment creates a global variable if a variable with that name does not already exist.

When an assign expression is executed, the expression on the right of the assignment symbol ( := ) is evaluated. If the variable list on the left has only one name, the value of the expression is assigned to that variable. That is, the value is associated with that name.

If the variable list has several names, the items of the value are assigned to the variables in the order in which they appear. If the number of items does not match the number of variables, the fault ?assignment is returned as the value of the assign-expression. Otherwise, the value of the assign-expression is the value of the expression on the right.

When an indexed-variable is used on the left in an assign-expression, the parts of the array associated with the variable at the locations specified by the index are replaced by the values of the expression on the right.

If the index expression for an indexed-variable assignment specifies a number of locations (at-all or slice indexing), there are two cases: if the value on the right is a single, the item of the single is placed in each location; otherwise, the value on the right must have the same number of items as the index expression indicates and the corresponding locations are updated with the items of the array value.

atlas ::= [ operation-expression { , operation-expression } ]

An atlas is an operation made up of a list of component operations. The result of applying an atlas is a list of the same length as the atlas. Each operation in the atlas is applied in turn to the argument resulting in an array value that becomes the item of the result list in the corresponding position. An atlas is used by the transformers =FORK=, =INNER= and =TEAM=.

The operation atomic tests whether or not its argument is an atom. It returns true if it is and false if it is not.

atomic 3.5

l

atomic "hello

l

atomic 'hello'

o

The examples illustrate that a number and a phrase are atoms and that a string is not an atom.

An atom is a primitive concept in array theory and Nial. Atoms are distinguished from other arrays by the property that they are self nesting. The definition of atomic is based on this property.

The operation axes generates a list of axis numbers for the array A counting from zero.

axes tell 3 4 5

0 1 2

An operation is said to binary if it must have exactly two items in its argument. Many of the built-in operations of Nial are binary. They can be used in both an infix and prefix manner. If a binary operation f is used in infix syntax then the arguments on each side of f are treated as the two items of its argument.

3 reshape 5

5 5 5

In prefix usage, f can precede a single array with two items, or an explicit pair formed with strand notation or bracket-comma notation.

X := 3 5;
reshape X

5 5 5

reshape 3 5

5 5 5

reshape [3,5]

5 5 5

Each operation f in this class maps a pair of atoms to an atom.

A binary pervasive operation maps two arrays having identical structure to one with the same structure, mapping each pair of corresponding atoms by the function's behaviour on pairs of atoms.

All of the binary operations of arithmetic and logic are binary pervasive.

If a binary pervasive operation is applied to a pair of arrays that do not have the same shape, the effect is to build a conformable pair by replicating an atom or solitary item of the pair to the shape of the other item. If both items are of unequal shape and if both items are made up of more than one item, the fault ?conform is returned. The replication of an argument with one item provides binary pervasive operations with a scalar extension capability. For example,

3 4 5 6 - 5 = (3 4 5 6 - 5 5 5 5)

l

If a binary pervasive operation is applied to an array that is not a pair, a fault is returned.

The following table lists the binary pervasive operations.

The operation 29 combines the top two levels of an array B into a single level blending the axes of the second level of B into the combined level according to the axis numbers given in A. The items of B must be of the same shape.

If the array B is equivalent to A 305 C for some array C, the result of A 29 B is C.

The 322 of A is the 354 of an item of B. The items of A indicate where the axes of the items of B are placed in the shape of the result.

C := (2 4 3 reshape count 24) ;
B := 2 0 split C

+----+----+----+-----+
|1 13|4 16|7 19|10 22|
|2 14|5 17|8 20|11 23|
|3 15|6 18|9 21|12 24|
+----+----+----+-----+

C := 2 0 blend B

 1  2  3   13 14 15
 4  5  6   16 17 18
 7  8  9   19 20 21
10 11 12   22 23 24

In the example, B is a list of four tables of shape 3 2 created by a 2 0 split. The result of 2 0 blend B is the array of valence 3 that is the second argument to split.

block ::=
   { [ LOCAL { identifier-sequence }+ ; ]
[ NONLOCAL { identifier-sequence }+ ; ]
[ definition-sequence ; ]
  expression-sequence }

A block is a scope-creating mechanism that permits an expression-sequence to be created so that it has local definitions and variables which are visible only inside the block. A block may appear as a primary-expression or as the body of an operation-form.

A local environment is a collection of associations that are known within a limited section of program text. These limited sections are formed by blocks, operation-forms and transformer-forms. A name that has a local association in one of these forms is said to have local scope.

If the definition appears within a block, the association is made in the local environment. Otherwise, the association is made in the global environment and assigns a role to the name as representing that kind of expression.

If a block is used as a primary-expression, the local environment created by a block is determined by the block itself. If it is the body of an operation-form, the local environment includes the formal parameter names of the operation-form as variables.

Local and Nonlocal Declaration

The identifiers included in the local and nonlocal declarations are declared to be variables. Both forms of declarations are optional, but if both are given, local declarations must be made first. If the block is the body of a globally defined operation-form or expression, a nonlocal declaration effectively declares its variables as global ones.

A block delimits a local environment. It allows new uses of names which do not interfere with uses of those names outside the block. For example, within a block, a predefined operation name can be redefined and used for a different purpose. Only the reserved words of Q'Nial cannot be reused in this fashion.

Definitions that appear within the block have local scope. That is, the definitions can be referenced only in the body of the block. Variables assigned within the block may or may not have local scope, depending on the appearance of a local and/or a nonlocal declaration. If there is no declaration, all assigned variables have local scope. Declaring some variables as local does not change the effect on undeclared variables that are used on the left of assignment. They are automatically localized.

If a nonlocal declaration is used, an assigned name that is on the nonlocal list is sought in surrounding scopes. If the name is not found, a variable is created in the global environment.

A list may be constructed directly by using bracket-comma notation. In this notation, the items of a list are separated by commas and the list is bounded by square brackets. If an item is omitted before or after a comma, then the fault value ?noexpr is used for the value of the missing item. The notation denotes the Null if their are no items, and a solitary if there is only one item.

[2,3 4,5]

+-+---+-+
|2|3 4|5|
+-+---+-+

[,4 5]

+-------+---+
|?noexpr|4 5|
+-------+---+

[] = Null

l

['hello world']

+-----------+
|hello world|
+-----------+

[3,[4,5,6],7]

+-+-----+-+
|3|4 5 6|7|
+-+-----+-+

The execution of Break causes the interpreter to interrupt normal execution in an expression sequence and to display the current callstack. It then prompts for input with the prompt –> followed by the default command in brackets. The visible environment is that of the expression in which the break occurs. Thus, it is possible to examine the values of local variables in break mode.

At a break you can type any expression to inspect the value of a variable or to see a portion of its value. The operation see can also be used to view any of the definitions in the environment.

The debugging capability allows one to step forward in expression sequences using commands step, stepin, next or toend to control whether you step into or over other definitions or to the end of a loop or a definition. The command resume ends the break and normal execution is restarted.

In console versions of Q'Nial, break mode can also be entered by typing <Ctrl B> in response to the prompt for a read or readscreen operation or Readchar expression when in windows mode. In this case, after resume or step is entered, Q'Nial returns to the read or readscreen operation and awaits the user input. Break mode cannot be entered by typing <Ctrl B> in editwindow or when setinterrupts has been used to inhibit interrupts.

foo is op A { Break; A }
foo 3

-------------------------------------------------------------
   Break debug loop: enter debug commands, expressions or
     type: resume    to exit debug loop
     <Return> executes the indicated debug command
   current call stack :
foo
-------------------------------------------------------------
?.. A
-->[stepv]

In the example, the operation foo has a Break which is executed when foo is applied to 3. If Return is pressed at the prompt the expression A is evaluated and 3 is displayed followed by another prompt.

The operation breakin installs a break point prior to the first executable expression in a definition named by the string or phrase Defname. The named definition must be an expression or an operation form. The effect is that when the definition is executed a break interrupt occurs prior to the execution of the first expression in the expression sequence in the body of the definition.

The optional argument Mode is provided to set the internal flag explicitly. If it is omitted, the internal flag value is toggled. All breakin flags are initially false. The value of the breakin flag is retained if the definition is replaced by a loaddefs so that editing a definition and reloading it does not change its breakin status. However, if definitions are reloaded using a restart then the breakin status is set to false.

The operation returns the previous setting. If the result of breakin is assigned to a variable, the previous setting can be restored later. The names of definitions that have breakin set can be viewed by the expression Breaklist.

library ¡°labeltab

see ¡°labeltable

labeltable IS OPERATION Corner Rowlabel Columnlabel Table {
   % Combine the corner label with the column labels for first line;
  Firstrow := Corner hitch Columnlabel;
   % Hitch the row labels to the rows of the table;
   Labeledrows := Rowlabel EACHBOTH hitch rows Table;
   % Hitch the first row of labels to the labeled rows and mix them;
   mix (Firstrow hitch Labeledrows) }

X gets count 3

1 2 3

labeltable "TIMES X X (X OUTER times X)

TIMES 1 2 3
    1 1 2 3
    2 2 4 6
    3 3 6 9

breakin "labeltable

o

labeltable "TIMES X X (X OUTER times X)

-------------------------------------------------------------
    Break debug loop: enter debug commands, expressions or
     type: resume    to exit debug loop
     <Return> executes the indicated debug command
    current call stack :
labeltable
-------------------------------------------------------------
?.. Firstrow := Corner hitch Columnlabel
-->[stepv] TIMES 1 2 3
?..   % Hitch the row labels to the rows of the table
-->[stepv] resume
TIMES 1 2 3
    1 1 2 3
    2 2 4 6
    3 3 6 9

To clear all breaks use:

EACH breakin Breaklist

The execution of Breaklist prints out a list of the definition names for which the breakin flag has been set.

Its main use is to assist in clearing the breaks as debugging proceeds.

Breaklist

labeltable

To clear all breaks use:

EACH breakin Breaklist

The transformer =BYCOLS= applies an operation f to the columns of a table A, where f is an operation that maps lists to lists.

setformat '%5.3f';
BYCOLS (SORT <=)(5 6 reshape random 30)

0.726 0.009 0.210 0.385 0.123 0.119
0.851 0.448 0.384 0.476 0.193 0.384
0.880 0.449 0.536 0.603 0.455 0.498
0.882 0.729 0.631 0.819 0.639 0.521
0.911 0.893 0.810 0.961 0.940 0.672

The example generates a random table and then sorts each column.

The expression Bye is used to terminate a session of Q'Nial and to return to the host environment. The current workspace is not saved.

The transformer =BYKEY= applies an operation f to lists gathered from A, where each list is made up of items of A that have the same value in the corresponding position in K. The result is a list with as many items as there are unique items in K.

Str := 'a stitch in time saves nine';

cull Str

a stichnmev

Str BYKEY tally Str

2 5 3 2 4 1 1 3 1 3 1

Keys := 3 5 3 7 2 5 4 2 1 3 4;
Data := 23.1 14.2 13.5 18.9 22. 98. 3.5 28.7 19.3 16.5 43.2;
Keys BYKEY sum Data

53.1 112.2 18.9 50.7 46.7 19.3

average IS OP A { sum A / tally A }

Keys BYKEY average Data

17.7 56.1 18.9 25.35 23.35 19.3

In the first example =BYKEY= tally is used to count the frequency of the letters in the string Str, giving the counts in the order of cull Str. In the remaining examples, the values in Data corresponding to equal items in Keys are added and averaged in the two uses of BYKEY.

The transformer =BYROWS= applies an operation f to the rows of a table A, where f is an operation that maps lists to lists.

BYROWS reverse (5 6 reshape count 30)

 6  5  4  3  2  1
12 11 10  9  8  7
18 17 16 15 14 13
24 23 22 21 20 19
30 29 28 27 26 25

The example reverses the rows of the generated table.

One use of the operation assign is to mimic a by-variable form of parameter passing in place of Nial's by-value form. The result depends on what kind of name is provided, a phrase or a cast. If the name is provided as a phrase, the variable that is selected is determined by assign when it does the assignment by looking first in the local environment and then in the surrounding ones. If the name is provided as a cast, the variable selected is the one that exists at the point where the cast is formed. Thus, by-variable parameter passing is achieved by using the cast of the variable as an argument in the call. In the body of the operation the formal parameter is assigned using assign and evaluated using value.

foo is op A Nm {
  B := A + value Nm;
  Nm assign (B + sum count 5); }

X := 100;
foo 1000 "X;
X

1115

The operation callc provides an interface to a C-coded operation Op and executes it with arguments A. The operation is one of several in a package called P.

Q'Nial Version 6.2 for Unix provides the CallC capability. This version of Q'Nial can be extended by adding packages and operations written in C and linked into the interpreter.

A Prototype DLL calling interface has been added to the Windows versions of Q'Nial (Console, GUI and DLL version). This ability allows NIAL code to call external routines in DLL libraries. These libraries can be user written, part of the Operating System, or 3rd party DLLs.

The DLL interface routines manage an internal table that keeps track of the currently installed DLLs and their argument types and result type. This table also tracks if the actual library has been loaded (by a call to calldllfun). The table is preserved as part of the workspace, and once DLL functions have been registered in a workspace, they are still available if the workspace is saved and subsequently loaded. The CallDLL facility assures that the DLL files are loaded and unloaded appropriately.

Every time a workspace is saved all DLL libraries are unloaded and the internal table is adjusted to reflect that. When a workspace is loaded, none of the DLL libraries will be loaded until a specific call to calldllfun brings in the DLL. This process assures that resources are not wasted on registered DLL calls that are never used.

The registerdllfun routine must always be called first to enter DLL function into the internal mapping table. This table keeps track of the name and DLL file for the routine and all of the argument types and function results. The DLL file is not loaded until the routine is called with the calldllfun routine. So errors involving paths to the DLL file or other related problems are not reported until the first call to calldllfun.

The operation calldllfun provides an interface to an external routine implemented as a DLL for 32-bit Windows. The name Nm is the name associated with the routine when it was registered using registerdllfun. The use of the name with appropriate arguments causes the DLL routine to be executed and its result (if any) returned as a Nial array.

The arguments Arg0 … ArgN must agree in number and be compatible in type with the declarations made while registering the routine.

The details of argument passing and some examples are included in the entry for registerdllfun.

The expression =Callstack= displays the sequence of active definition calls at the point it is invoked. It is usually used in conjunction with =Break=. =Callstack= can be used to see the execution path by which the computation reached the current state while computation is suspended during a break.

There is a canonical way of displaying program text in Nial. This is done automatically by the routines descan and deparse used by see. The canonical form sets the case of all identifiers used in Nial program text according to their role in order to assist visual parsing of Nial text. The following table summarizes the rules:

The operation cart corresponds to the cartesian product of set theory. Its purpose is to form all possible combinations of the items of its argument and return them in a structured result having as many axes as the sum of the number of axes of the items of argument.

2 3 4 cart 5 6

+---+---+
|2 5|2 6|
+---+---+
|3 5|3 6|
+---+---+
|4 5|4 6|
+---+---+

In the example above, the cart of a triple with a pair yields a table of shape 3 2 of pairs.

cart ['abc', 4 2 reshape count 8]

+---+---+  +---+---+  +---+---+
|a 1|a 2|  |b 1|b 2|  |c 1|c 2|
+---+---+  +---+---+  +---+---+
|a 3|a 4|  |b 3|b 4|  |c 3|c 4|
+---+---+  +---+---+  +---+---+
|a 5|a 6|  |b 5|b 6|  |c 5|c 6|
+---+---+  +---+---+  +---+---+
|a 7|a 8|  |b 7|b 8|  |c 7|c 8|
+---+---+  +---+---+  +---+---+

In the above example, the shape of the result is 3 4 2, getting an axis of length 3 from the first item and axes of length 4 and 2 from the second.

The expression following case is evaluated. If the result matches one of the constants, C1 … Cn, the corresponding expression sequence is executed. If the result does not match any constant, the expression sequence following else is executed.

Example:

Month := 3 ;
CASE Month FROM
   1:   Mname := 'January'; END
   2:   Mname := 'February'; END
   3:   Mname := 'March'; END
ELSE   Mname := 'Year End';
ENDCASE ;
Mname

March

A cast is an array expression that denotes an internal representation of a valid fragment of Q'Nial program text:

cast ::= ! identifier
   | ! ( expression-sequence)
   | ! ( operation-expression )
   | ! ( transformer-expression )

The use of the exclamation symbol ! before an identifier causes Q'Nial to select the internal representation for the identifier rather than the value of the array associated with the identifier. Its use before a parenthesized program fragment selects the internal representation of the program fragment.

The major use of casts is in conjunction with the operations assign and apply. These operations mimic the Q'Nial constructs for assignment to a variable and application of an operation to an array. Casts permit passing an argument to an operation by variable name rather than by value. They also permit evaluation of a program fragment that has been stored in its internal form using the operation eval rather than requiring the use of the operation execute on the corresponding program text stored as a string.

Salary := 90000.
A gets 'Salary > 100000.' ;
Rule1 := execute A

o

Rule1 := eval !A

o

The details of the internal representation is not specified as part of the Nial language.

The cast notation !Name is used to denote the parse tree that represents the name. At the top level loop, parentheses must be included around the use of the cast notation, e.g. (!Name), to avoid ambiguity with the use of ! to indicate a host command.

The cast, because it is analyzed in the context in which it appears, refers to a variable or definition in a static way.

Q'Nial contains operations that mimic the underlying meaning of variables, expressions and operations in Q'Nial. The operations use strings, phrases or casts to represent the name of the object under consideration (except that see and getdef do not take casts).

:PROPERTY: :Class: construction operation :Usage: I catenate A catenate I A :SeeAlso: link, laminate :END:

The operation catenate joins the items of A along axis I. The items of A must conform in all other axes.

1 catenate (tell 2 3) (count 2 5)

+---+---+---+---+---+---+---+---+
|0 0|0 1|0 2|1 1|1 2|1 3|1 4|1 5|
+---+---+---+---+---+---+---+---+
|1 0|1 1|1 2|2 1|2 2|2 3|2 4|2 5|
+---+---+---+---+---+---+---+---+

The example joins two tables along the rows. Each table has two rows.

The operation ceiling produces the following results when applied to atoms of the six types:

Examples

ceiling  l  -2  3.5

1 -2 4

ceiling  `a  "abc  ??error

?A ?A ?error

ceiling  3.5  -4.6  7.0  25.3e20

4 -4 7 ?A

The operation char is used to convert an integer in the range 0 to 255 to the character that has the integer as its internal representation. The result is system dependent.

char 66

B

char 66 67 68 69

BCDE

The major purpose of char is to create special characters for a specific system. For example, the characters that control cursor motion differ from one terminal to another. Programs using char may not be portable.

The operation charrep is used to convert a character to its internal representation as an integer. This operation is system dependent.

charrep `A

65

charrep 'hello'

104 101 108 108 111

The major purpose of charrep is to permit determination of special characters for a specific system. For example, the characters that control cursor motion differ from one terminal to another.

Programs using charrep may not be portable.

Checkpoint is a user defined expression executed after a save.

When a save is executed, the current computation is ended and the Checkpoint is done in the top level environment.

If a workspace being saved contains an expression named Checkpoint, the expression is executed following the saving of the workspace and prior to restarting the top level loop. It can be used to restart a computational loop after an intermediate dump of the workspace.

The operation choose is used to select a subarray from array A specified by the array of addresses I. The result is an array of the same shape as I with items chosen from A. If an item of I is not an address of A, the corresponding position in the result is the fault ?address.

The operation choose is related to the at all notation V#I, which selects items from the array associated with the variable V. The differences are that choose may select from an array that has not been assigned to a variable and that it handles out-of-range in a different manner.

3 1 0 1 3 4 choose 'range'

garage

The following example shows that the valence of the array of addresses can be higher than that of the array from which the selection is made.

I gets (2 4 reshape tell 8)

0 1 2 3
4 5 6 7

I choose 'some words as a string'

some
 wor

Q'Nial organizes the data and code objects available for use into a logical structure called a workspace. It consists of a symbol table to hold associations between names and the predefined and user defined objects, a heap to store data and parse trees, a stack used to hold values temporarily during execution, and an atom table for uniquely storing phrases and faults.

When Q'Nial is invoked it starts the session with a clear workspace unless a specific saved workspace is requested or there is a continue.nws file in the local directory. The clear workspace is either found in the local directory, in the directory pointed at by Nialroot. The name of the clear workspace is clearws.nhs. If it is not found, then Q'Nial creates an internal clear workspace using its initialization process. A message indicates whether a clear workspace was loaded or created.

A user can tailor the initial state of Nial for their own purposes by saving a workspace with definitions in place as clearws.nws using save.

The expression =Clearprofile= is used to clear the internal data structures that are used in the gathering of profiling statistics. It should be called when one profiling session has been completed and profile has been called, before starting another one.

A detailed explanation of the profiling mechanism is given in the help entry on profiling.

The expression =Clearws= clears the current workspace, erasing all variables and user definitions. It can cause loss of valuable information. The operation save should be used prior to using Clearws if the information in the workspace will be needed again.

The expression =Restart= is similar to =Clearws= except =Restart= re-initializes the interpreter according to the initial options given on the command line in a console version or set as defaults in a GUI version.

The operation close is used to close a file previously opened with the open operation. The argument is the file designator, an integer returned previously by open for that file.

The result of close is the fault ?noexpr or a fault message indicating an error.

Fd := open "foo "w

3

close Fd
close Fd

?file is not open

In the examples above, the first use of close was successful. The second attempt to close the file resulted in the fault message.

The operation cols rearranges the axes of a table of shape M by N to form a list of length N of the columns of length M of the table. Cols is generalized to arrays of all valences as follows: if A is a list or a single, the result is single A; if A has valence three or higher, the result is an array of valence one less than the valence of A with the second last axis pushed down.

A := 3 4 reshape count 12

1  2  3  4
5  6  7  8
9 10 11 12

cols A

+-----+------+------+------+
|1 5 9|2 6 10|3 7 11|4 8 12|
+-----+------+------+------+

If only column I of a table is needed, it can be selected by I pick cols A or by A|[,I] using the at slice indexing notation. The second way is more efficient for large arrays because it avoids restructuring the array. If a table A has no columns, 57 A results in the empty list =Null=.

comment ::=
   % <any text excluding a semicolon> ;

remark ::= # < any text >

A comment is a brief section of text included in a program fragment to assist readability. Comments may be placed anywhere in a block before or after declarations, definitions or expressions. Their purpose is to provide an explanation of the program fragment for the programmer who may be required to modify the program at a later date. The value of a comment as an expression is the ?noexpr fault. Comments are retained when a definition is translated into internal form and they appear in its creation in the canonical form used by the operations see and defedit.

A remark is an input to the Q'Nial interpreter that is not processed. It begins with a line that has the symbol # as the first non-blank character in the line. In direct input at the top level loop, a remark ends at the end of the line unless a backslash symbol ( \ ) is used to extend the line. In a definition file, a remark ends at the first blank line. A remark cannot appear within a definition or expression-sequence.

The operation 211 is used in evaluating binary pervasive and multi pervasive operations. Its task is to interchange the top two levels of the argument to such operations if the items of the argument conform. For the binary case there are two items; they conform if the items have the same shape, or if one or both items have only one item. In the latter case, the item with only one item is replicated to the shape of the other item.

For the multi pervasive case, all the items that do not have only one item must be of the same shape and all the items with one item are replicated to that shape.

pack [2 3 4,10 11 12]

+----+----+----+
|2 10|3 11|4 12|
+----+----+----+

pack [2 3,10 11 12]

?conform

pack [3 4 5,3,10 11 12,[4]]

+--------+--------+--------+
|3 3 10 4|4 3 11 4|5 3 12 4|
+--------+--------+--------+

pack [tell 4 5,count 4 5]

+---------+---------+---------+---------+---------+
|+---+---+|+---+---+|+---+---+|+---+---+|+---+---+|
||0 0|1 1|||0 1|1 2|||0 2|1 3|||0 3|1 4|||0 4|1 5||
|+---+---+|+---+---+|+---+---+|+---+---+|+---+---+|
+---------+---------+---------+---------+---------+
|+---+---+|+---+---+|+---+---+|+---+---+|+---+---+|
||1 0|2 1|||1 1|2 2|||1 2|2 3|||1 3|2 4|||1 4|2 5||
|+---+---+|+---+---+|+---+---+|+---+---+|+---+---+|
+---------+---------+---------+---------+---------+
|+---+---+|+---+---+|+---+---+|+---+---+|+---+---+|
||2 0|3 1|||2 1|3 2|||2 2|3 3|||2 3|3 4|||2 4|3 5||
|+---+---+|+---+---+|+---+---+|+---+---+|+---+---+|
+---------+---------+---------+---------+---------+
|+---+---+|+---+---+|+---+---+|+---+---+|+---+---+|
||3 0|4 1|||3 1|4 2|||3 2|4 3|||3 3|4 4|||3 4|4 5||
|+---+---+|+---+---+|+---+---+|+---+---+|+---+---+|
+---------+---------+---------+---------+---------+

The operation 60 returns the list of atoms of A. The effect of content is to remove all structure from an array, returning a list of the atoms in a depth first, row-major order. The effect on an atom is to produce the solitary of the atom.

A := (2 3) (4 5 (6 7))

+---+---------+
|2 3|+-+-+---+|
|   ||4|5|6 7||
|   |+-+-+---+|
+---+---------+

content A

2 3 4 5 6 7

The expression Continue terminates a session of Q'Nial and returns control to the host environment. The workspace is saved in file continue.nws and is reloaded when Q'Nial is invoked at a later session using the same current directory.

If a Restart is executed in a session that began with a continue workspace, the current workspace will be reset to the continue workspace. If a session that began with a continue is terminated with Continue, the file continue.nws is updated with the current workspace. If it is terminated with Bye, the file continue.nws is deleted.

The file continue.nws is a workspace file that is created when a session is ended with the expression Continue. When Q'Nial is invoked from the same directory, it will use continue.nws rather than clearws.nws as the initial workspace. If the Q'Nial invocation names a workspace, that workspace will take precedence over the continue workspace.

Many of the screen related operations require a display attribute, termed a control tuple, as one of the arguments. The display attribute specifies the color or style of the characters displayed by the operation. It is display screen dependent.

Various displays are available for IBMPC systems and they can run in different modes. For a monochrome display, Q'Nial can specify normal, bold, underlined, reverse video and blinking characters. If the terminal has a color display, Q'Nial can specify foreground and background colors. Each color combination can have blinking characters.

For a Unix system, the display screen is driven by the terminfo capability table which provides the following styles: normal, standout, underlined, bold and blinking, where either standout or bold is mapped to reverse video. Not all terminals support all these capabilities. No specific allowance for color is made in the Unix version of Q'Nial.

To accommodate all these varieties, the display attribute is encoded as a triple of integers on IBMPC versions and as a single integer on Unix with the following interpretations:

The following tables fill in the detailed codes for the three forms of display attributes.

IBMPC Monochrome Display Attributes

IBMPC CGA Color Display Attributes

Color codes 8 through 15 result in high intensity display of the color.

Unix Terminal Display Attributes

With this variety of attributes, it is impossible to make programs work identically when they are ported from one system to another. To retain portability attributes should be set up in terms of variables such as Normalattribute, Highattribute, Borderattribute etc. and given values according to the system in use.

The transformer =CONVERSE= is used with a binary operation f and applies f to the pair formed by reversing the arguments of =CONVERSE= f.

at IS CONVERSE pick
'abcde' at 2

c

holds IS CONVERSE in
count 20 holds 5

l

In the above examples, at and holds are defined in terms of pick and in, respectively. The first example shows that 'abcde' at 2 gives the result expected for 2 pick 'abcde'. The second example shows that count 20 holds 5 gives the same result as 5 in (count 20). Thus, at and holds do the same work as pick and in; the former operations simply use their arguments in the reverse order.

The expression Copyright returns a message specifying ownership of the rights to Q'Nial by Queen's University at Kingston, Canada (K7L 3N6).

Copyright

Copyright (c) Queen's University 1983-97

The operation 66 implements the cosine function of mathematics. It produces the following results when applied to atoms of the six types:

cos  l  -1  0.5  `a  "abc  ??error

0.54030 0.54030 0.87758 ?cos ?cos ?error

The operation cosh implements the hyperbolic cosine function of mathematics. It produces the following results when applied to atoms of the six types:

cosh  l  -1  0.5

1.54308 1.54308 1.12763

cosh `a  "abc  ??error

?cosh ?cosh ?error

The operation 68 generates a list of integers starting at 1 and going up to and including N. It differs from tell by counting from 1 instead of from 0.

count 5

1 2 3 4 5

.1 times count 5

0.1 0.2 0.3 0.4 0.5

The first example shows count generating the sequence of integers from 1 to 5. The second example shows how count can be used to generate a sequence of five real numbers with an interval of .1 between each number.

count 2 3

+---+---+---+
|1 1|1 2|1 3|
+---+---+---+
|2 1|2 2|2 3|
+---+---+---+

The third example shows how count generalizes to other arguments in the same manner as the operation tell.

The operation cull returns a list whose items are those of A with duplicates removed. The order of the items is maintained.

cull 3 5 4 3 5 2 4

3 5 4 2

cull 'a few letters with duplicates'

a fewltrsihdupc

A curried-operation is an operation in which the left item of a two-item argument is combined with a given operation to form an operation expression. Examples are: 1+ and 3 reshape.

A curried operation can be named or grouped in parentheses as an argument to a transformer.

incr IS 1+

EACH (5 take) Lines

In general, the syntax of a curried operation is:

curried-operation ::= simple-expression simple-operation

The result of applying a curried-operation is determined by applying the simple-operation to the pair formed from the simple-expression and the argument to the curried-operation. Thus,

(1+) 5

6

is interpreted as

+ (1 5)

6

The operation 71 converts an array A into a list of items formed from the items of A according to the bitstring B. The list of items is divided where true values occur in the corresponding positions in the bitstring B. The items of A where the divisions occur are not included in the items of the result and any empty segments are not included.

A := 'The boy stood   on the burning deck' ;
`  match A cut A

+---+---+-----+--+---+-------+----+
|The|boy|stood|on|the|burning|deck|
+---+---+-----+--+---+-------+----+

B := 'Formula 1: 3,5,7,,,9';

`, match B cut B

+------------+-+-+-+
|Formula 1: 3|5|7|9|
+------------+-+-+-+

EACH equal tell 4 4 cut tell 4 4

+-----------------+-----------------+-----------------+
|+---+---+---+---+|+---+---+---+---+|+---+---+---+---+|
||0 1|0 2|0 3|1 0|||1 2|1 3|2 0|2 1|||2 3|3 0|3 1|3 2||
|+---+---+---+---+|+---+---+---+---+|+---+---+---+---+|
+-----------------+-----------------+-----------------+

Cut can be used to cut a string into a list of substrings. In the first example, the string is cut at blank characters. Several adjacent blanks are treated as one blank character. In the second example, the cut is done where commas occur. The third example shows that the items of A do not have to be atoms.

The operation 72 converts an array A into a list of items formed from the items of A according to the bitstring B. The list of items is divided where true values occur in the corresponding positions in the bitstring B. The items where the divisions occur are kept as the first item of each group.

A := 'The boy stood on the deck' ;
`  match A cutall A

+---+----+------+---+----+-----+
|The| boy| stood| on| the| deck|
+---+----+------+---+----+-----+

B := 'Formula 1: 3,5,7,,,9';
`, match B cutall B

+------------+--+--+-+-+--+
|Formula 1: 3|,5|,7|,|,|,9|
+------------+--+--+-+-+--+

EACH equal tell 4 4 cutall tell 4 4

+---------------------+---------------------+---------------------+-----+
|+---+---+---+---+---+|+---+---+---+---+---+|+---+---+---+---+---+|+---+|
||0 0|0 1|0 2|0 3|1 0|||1 1|1 2|1 3|2 0|2 1|||2 2|2 3|3 0|3 1|3 2|||3 3||
|+---+---+---+---+---+|+---+---+---+---+---+|+---+---+---+---+---+|+---+|
+---------------------+---------------------+---------------------+-----+

The operation 74 returns an array the same as A except that the array at path P is replaced by B. It is the insertion operation corresponding to the selection operation reach and generalizes the operation 222 from addresses to paths.

    A1 := 1 2 (3 4 (5 6 (7 (8 9))))
+-+-+-------------------+
|1|2|+-+-+-------------+|
| | ||3|4|+-+-+-------+||
| | || | ||5|6|+-+---+|||
| | || | || | ||7|8 9||||
| | || | || | |+-+---+|||
| | || | |+-+-+-------+||
| | |+-+-+-------------+|
+-+-+-------------------+
    A1 := "M (2 2 2 0) deepplace A1
+-+-+-------------------+
|1|2|+-+-+-------------+|
| | ||3|4|+-+-+-------+||
| | || | ||5|6|+-+---+|||
| | || | || | ||M|8 9||||
| | || | || | |+-+---+|||
| | || | |+-+-+-------+||
| | |+-+-+-------------+|
+-+-+-------------------+

The array 7 is replaced with

The operation 75 provides the semantics of the Nm@@P := A form of assignment expression. Nm must be an existing variable represented by a string, phrase or a cast; P is the path of addresses to the location to be updated; and A is the array to be placed in the variable.

Array1 := (1 2(3 4 (5 6 (7 (8 9)))))

+-+-+-------------------+
|1|2|+-+-+-------------+|
| | ||3|4|+-+-+-------+||
| | || | ||5|6|+-+---+|||
| | || | || | ||7|8 9||||
| | || | || | |+-+---+|||
| | || | |+-+-+-------+||
| | |+-+-+-------------+|
+-+-+-------------------+

deepupdate "Array1 (2 2 2 1 0) "Tom

+-+-+---------------------+
|1|2|+-+-+---------------+|
| | ||3|4|+-+-+---------+||
| | || | ||5|6|+-+-----+|||
| | || | || | ||7|Tom 9||||
| | || | || | |+-+-----+|||
| | || | |+-+-+---------+||
| | |+-+-+---------------+|
+-+-+---------------------+

The major purpose of deepupdate is to allow a selective update with a path on a global variable without forcing a copy. By passing the name of the variable to the operation that is doing the update, rather than its value, no sharing of the internal data is made and hence the update can be made "in place".

A definition in Nial is a syntactic construct that names a program fragment. The syntax is one of the three forms:

<name>  IS  <array expression>
<name>  IS  <operation expression>
<name>  IS  <transformer expression>

A definition is used to associate a name (identifier) with a program fragment that is an array expression, an operation expression or a transformer expression. If the definition appears within a block, the association is made in the local environment. Otherwise, the association is made in the global environment and assigns a role to the name as representing that kind of expression.

If the program fragment is syntactically correct, the name is associated with the program fragment in the environment and no result is given. If a syntax error is detected in the analysis of the program fragment, an explanatory fault message is returned and the name association is not made.

If the name being associated in a definition is already in use, the new definition must be for a construct of the same role and the earlier definition is replaced. The use of a defined name always refers to its most recent definition.

The operation 77 is used to convert a parse tree representation of a Nial definition or program fragment into a token stream which can be converted into text corresponding to the Nial definition. The argument to deparse must be either a cast or the result of parse or getdef.

deparse !(Pi * cos 0.5)

99 1 ( 2 Pi 2 * 2 cos 18 0.5 1 )

The principal use of deparse is in displaying Nial definitions. It is used in the definition of defedit and see.

The token stream returned by deparse also includes indicators to identify where new lines are to begin and to control indentation. The tokens corresponding to identifiers are given in the canonical form, indicating what role each token plays.

The result of deparse is implementation dependent and should be viewed as an internal representation provided as an interface to editing. It is subject to change as Q'Nial evolves.

The operation 78 returns an integer indicating the number of levels of nesting of the array. This is called the depth of the array. The depth of an atom is 0. The depth of a simple nonempty is 1. In general, the depth of an array is 1 plus the maximum of the depths of the items.

depth "abc

0

depth 3 4 5

1

depth 1 (2 3) (4 5 6)

2

depth [2, [3, 4, [5],8],24]

3

The operation 79 converts a token stream to a list of strings that represents the program fragment given by the token stream. The input to descan must be a token stream produced by scan or deparse or an equivalent list of tokens.

descan scan 'A + 32'

+-------+
|A + 32 |
+-------+

descan deparse !(Pi * cos 0.5)

+-----------------+
|( Pi * cos 0.5 ) |
+-----------------+

The principal use of descan is in displaying Nial definitions. It is used to define defedit and see. The argument to descan may also include tokens indicating the beginning of new lines and controlling indentation used to display a structured definition.

The operation 80 computes a character table that gives the fully boxed picture of A with the decoration of the atoms determined by the current setting of the decor switch. An array is displayed as a frame with cells for each item. It is arranged in two dimensions, using groupings of table frames to picture arrays of higher dimension. Each cell is large enough to hold the diagram of the corresponding item of A.

The diagram of an atom is a picture that indicates its value. The diagram of a non-atomic single has an "o" in its upper left corner.

Diagram returns the display given by the operation 221 when in diagram mode of display.

The decor or nodecor mode switch controls the display of atoms. With decor set, it gives a picture that distinguishes all atoms.

set "decor;
A := diagram (2 3 2 reshape 3 'abc' (2 1 reshape count 3) "apple 8.5
     (3 4));
set "nodecor; A

+---+----------+  +---+----------+
|  3|+--+--+--+|  |  3|+--+--+--+|
|   ||`a|`b|`c||  |   ||`a|`b|`c||
|   |+--+--+--+|  |   |+--+--+--+|
+---+----------+  +---+----------+
|+-+|"apple    |  |+-+|"apple    |
||1||          |  ||1||          |
|+-+|          |  |+-+|          |
||2||          |  ||2||          |
|+-+|          |  |+-+|          |
+---+----------+  +---+----------+
|8.5|+-+-+     |  |8.5|+-+-+     |
|   ||3|4|     |  |   ||3|4|     |
|   |+-+-+     |  |   |+-+-+     |
+---+----------+  +---+----------+

The display of the result of a picture operation, such as diagram, makes sense when it itself is pictured in sketch-nodecor mode. In other modes, the characters making up the table would be boxed and/or decorated.

The number of axes of an array is referred to as its dimensionality. In array theory terminology the dimensionality is called the valence of the array. The following terms describe arrays by their valence:

The operation 82 returns a string which, when executed, returns the value A.

set "decor; display 23.5

'23.5'

Display inserts the operation to construct values that cannot be described directly by constants. In the example below, since the phrase containing a blank character cannot be specified simply using the phrase mark, display inserts the operation phrase and the string that will create the desired phrase An answer.

display "Nm (phrase 'An answer') 'Nm'

'["Nm,(phrase 'An answer'),'Nm']'

X := "Name (2 3 (4 5) 'Queen''s' (3 2 reshape count 6))

+-----+-----------------------+
|"Name|+-+-+---+---------+---+|
|     ||2|3|4 5|'Queen's'|1 2||
|     || | |   |         |3 4||
|     || | |   |         |5 6||
|     |+-+-+---+---------+---+|
+-----+-----------------------+

display X

'["Name,[2,3,4 5,'Queen''s',3 2 reshape 1 2 3 4 5 6]]'

execute display X = X

l

In the definition of X, strand notation was used. In the display of X, brackets notation is created to represent X. The display is seen to be correct by the last example that shows that the execute of the display of X is X.

The operation 83 tests whether or not the items of A are all different. It returns true if they are and false if they are not.

diverse 2 3 5

l

diverse 'hello world'

o

diverse 2 3 (2 3)

l

In the last example, the items are all different because the last item is a pair of items (2 3) which is not the same as 2 or 3.

The operation 84 returns the result of dividing two numeric atoms. It coerces the type of the atoms to be real and gives a real number result. If B is a numeric zero, the result is the fault ?div.

If one argument is numeric and the other is a fault or if both arguments are the same fault, the answer is the fault. In all other cases when one or more of the arguments is not numeric, the result is the arithmetic fault ?A.

R gets 1 2 2.5 `a "abc ??error

1 2 2.5 `a "abc ??error

R outer divide R

    1.    0.5    0.4 ?A     ?A     ?error
    2.     1.    0.8 ?A     ?A     ?error
   2.5   1.25     1. ?A     ?A     ?error
?A     ?A     ?A     ?A     ?A     ?error
?A     ?A     ?A     ?A     ?A     ?error
?error ?error ?error ?error ?error ?error

The above example illustrates all combinations of atom types for the two arguments to divide.

The expression Dlllist provides a list of the current routines that have been registered.

=DOWN= is a general transformer that recurs over the depth of an array to some arbitrary level. DOWN has four operation arguments: test tests when the recursion has gone as deep as necessary, endf is applied to the argument that satisfies test, structf rearranges the argument before recurring on each item, and joinf combines the results of the recursion on the items.

DOWN [ atomic, 0 minus, pass, pass]  3 -4 (5 6)

+--+-+-----+
|-3|4|-5 -6|
+--+-+-----+

DOWN [ simple, dosum, pack, pass ] 3 4 5 6

18

DOWN [ atomic, 0 first, pass, 1 plus max ] [2, [3, 4, [5],8],24]

3

The operation 87 selects the items of an array after a specified number of items have been dropped. If B is a list and A is a non-negative integer, the result is the list formed from dropping A items from the front of B. If A is a negative integer, the result is formed by dropping abs A items from the right end of B.

If B is a table and A is a pair of non-negative integers, the result is lower right corner of B that remains after dropping the number of rows and columns indicated by A from the upper left corner of B. If one or both items of A are negative, the dropping occurs from the other end of the extent of the corresponding axis.

For a higher dimensional array B, tally A must equal valence B; and the result is obtained by dropping from the front or back of the extents along each axis. If B is a single and product A is zero, the result is B; otherwise the result is an empty array with valence of tally A.

2 drop "Able "Baker "Charlie "Dog

Charlie Dog

T1 := tell 2 4

+---+---+---+---+
|0 0|0 1|0 2|0 3|
+---+---+---+---+
|1 0|1 1|1 2|1 3|
+---+---+---+---+

1 2 drop T1

+---+---+
|1 2|1 3|
+---+---+

1 -2 drop T1

+---+---+
|1 0|1 1|
+---+---+

The operation =dropright= is an obsolete operation that drops items from the ends of extents. It is provided to retain compatibility with earlier versions of Q'Nial.

The transformer =EACH= forms an operation, called the =EACH= transform of f, that applies f to every item of the argument A. The shape of the result of the application of =EACH= f to A is the same shape as A.

EACH reverse ('abc' 'def' 'ghi')

+---+---+---+
|cba|fed|ihg|
+---+---+---+

EACH first tell 3 4

0 0 0 0
1 1 1 1
2 2 2 2

=EACH= is used to distribute an operation f across an entire array A. Its use avoids the need to explicitly allocate space for the result and to write an explicit loop to apply f to each item of A individually.

The transformer =EACHALL= forms an operation which applies f to arrays formed by selecting the items of the items of A in corresponding positions, assuming that the items of A are all of the same shape.

When the items of A are not all the same shape, A is examined to see if all the items with tally greater than one have the same shape. If so, all the items of tally 1 are replicated to that shape. If not, the fault ?conform is returned. =EACHALL= is implicitly applied in multi pervasive operations.

A := 9 [2] (4 4 reshape (5+tell 16))

+-+-+-----------+
|9|2| 5  6  7  8|
| | | 9 10 11 12|
| | |13 14 15 16|
| | |17 18 19 20|
+-+-+-----------+

pack A

+------+------+------+------+
|9 2 5 |9 2 6 |9 2 7 |9 2 8 |
+------+------+------+------+
|9 2 9 |9 2 10|9 2 11|9 2 12|
+------+------+------+------+
|9 2 13|9 2 14|9 2 15|9 2 16|
+------+------+------+------+
|9 2 17|9 2 18|9 2 19|9 2 20|
+------+------+------+------+

(EACH sum) pack A

16 17 18 19
20 21 22 23
24 25 26 27
28 29 30 31

EACHALL sum A

16 17 18 19
20 21 22 23
24 25 26 27
28 29 30 31

sum A

16 17 18 19
20 21 22 23
24 25 26 27
28 29 30 31

The example shows that =EACHALL= is defined in terms of pack and is implicitly used in the multi pervasive operation 316.

The transformer =EACHBOTH= forms an operation which applies f to pairs formed by selecting the items of A and B in corresponding positions, assuming that A and B have the same shape.

When A and B do not have the same shape, if either A or B has only one item, that item is replicated to the shape of the other argument; otherwise, the fault ?conform is returned.

=EACHBOTH= is used implicitly in all binary pervasive operations.

7 2 1 EACHBOTH post 4 5 3

+-+-+-+
|7|2|1|
|4|5|3|
+-+-+-+

The transformer =EACHLEFT= forms an operation which applies f to pairs formed by pairing the items of A with B. The shape of the result is the shape of A.

2 3 4 EACHLEFT reshape 5

+---+-----+-------+
|5 5|5 5 5|5 5 5 5|
+---+-----+-------+

(2 3 reshape 'abcdef') EACHLEFT hitch '123'

+----+----+----+
|a123|b123|c123|
+----+----+----+
|d123|e123|f123|
+----+----+----+

The transformer =EACHRIGHT= forms an operation which applies f to pairs formed by pairing A with the items of B. The shape of the result is the shape of B.

    2 EACHRIGHT reshape 3 4 5
+---+---+---+
|3 3|4 4|5 5|
+---+---+---+

    `X EACHRIGHT hitch (2 3 reshape 'ab' 'cd')
+---+---+---+
|Xab|Xcd|Xab|
+---+---+---+
|Xcd|Xab|Xcd|
+---+---+---+

The operation 94 passes control to the standard editor, requesting it to edit the file named by the string or phrase Filename. The editor used is determined by the environment variable EDITOR or by a default chosen for each version. When the editing task is completed, the editor returns control to Q'Nial. The result is the fault ?noexpr.

edit "test.ndf
edit 'data_records'

If edit is used to edit a file of Nial definitions, the operation 175 must be executed on return from the editor to load the definitions.

The operation 95 tests whether or not an array A has any items. If A has no items, it returns true; otherwise, false. The predefined expression Null is empty as is any array with a zero in its shape.

Since there are empty arrays with more than one dimension, it is better to test for an empty array by using empty rather than by direct comparison with =Null=.

empty Null

l

empty (0 3 2 reshape 5)

l

empty solitary 5

o

empty solitary Null

o

The last two examples show that a solitary is not empty even if the item it contains is empty.

The operation 96 is normally used to compare two arrays A and B to see whether or not they are identical. It returns true if they are equal; false otherwise. (Two nonempty arrays are identical if they have identical shapes and hold identical items at each location. Two empty arrays are identical if they have identical shapes.) Empty is extended to arbitrary arrays by returning true if all items of an array are identical.

The symbol = is a synonym for 96 and can be used in both infix and prefix application. In the Equations sections of the dictionary entries, <snial the symbol = is used to separate two sides of an equation. To test such an equation, it may be necessary to replace the expression following = with the same expression in parentheses in order to force correct parsing of the equation as a Nial expression.

2 3 4 = [2,3,4]

l

Null = ''

l

2 (3 4) = (2 3) 4

o

equal EACH shape tell 2 3 4

l

The first example shows that a triple formed using strand notation is identical to that formed using brackets notation. The second shows that =Null= is equal to the empty string. The third shows that grouping items of a list in different ways creates different arrays. The last shows the convenience of the more general form of 96.

The equations in the Nial Dictionary and in the on-line help provide an abbreviated way of stating properties of the term or object being described. They could be expanded into an explanation in English but that would lengthen the manual considerably.

The equations use variables such as A, B and C that take on array values; and variables such as f, g and h that denote operations that map arrays to arrays. An equation holds for all arrays and for all computable operations without side effects, unless a specific qualification is made. Thus, the equation:

(EACH f) (EACH g) A = EACH (f g) A

says that for all operations f and g and all arrays A, the use of the EACH transform of f on the result of the use of the EACH transform of g on A has the same value as the use of the EACH transform of the composition of f and g on A. In mathematical terms, the EACH transformer distributes over operation composition.

The symbol = is used in its mathematical sense in equations and separates two Nial expressions. The symbol = has higher precedence than the two expressions it is separating. Where the Nial equivalent to = is needed to state the equation, the term equal is used.

To test an equation using Q'Nial, in order to force the correct parsing of the equation as a Nial expression, it may be necessary to replace

Expr1 = Expr2

with

Expr1 = ( Expr2 )

The equality used in equations assumes that both sides of the equations compute without triggering a fault and produce equal arrays; or both produce the same fault value if fault triggering is off. In some cases, the equality is inexact due to roundoff errors.

The symbol f is used to denote an equality where both sides produce the same non-fault value; but in some cases one or both of the sides may fault and the equality is no longer valid.

Some of the equations are qualified by a constraint on the variables. The constraint is written in English or as a conditional expression in Nial that must hold for the equation to be true. In a statement of the form

Expr ==> Eqn

Expr is the qualification written as a Nial boolean expression, the symbol ==> is used for "implies", and Eqn is the equation that holds under the qualification.

The symbol <==> denotes an if and only if implication. Thus a statement of the form

Expr1 <==> Expr2

states that both expressions have the same truth value; either both are true or both are false.

Reading the Equations

The equations related to 2, the operation that finds the absolute value of a number, are:

abs A = EACH abs A
shape abs A = shape A
abs abs A = abs A

The first two come from the property that abs is unary pervasive. The first one says that applying abs to an array A is the same as applying abs to the items of array A. It also implies that the shape of the result of abs A is the same as shape of A since EACH transforms always preserve shape. The second equation says that the shape of the result of abs A is the same as the shape of A. The third equation indicates that subsequent applications of abs after the first do not change the result.

The equations related to minus, denoted by -, are:

A - B = EACH - pack A B
shape (A - B) = shape pack A B
A - B = A + opposite B

The first equation says that pair of arrays A and B are packed at each level of nesting to bring corresponding items together. Then, the items are subtracted.

The second equation states that the shape of the result of subtracting A from B is the shape formed by packing A and B. The third equation states that subtracting A from B is equivalent to adding the opposite of B to A.

The equations related to hitch are as follows:

A hitch B = A hitch list B
list (A hitch B) = A hitch B

The first says that hitch treats its right argument as though it were a list, and the second states that the result of hitch is a list.

The following equations illustrate the use of qualifications:

atomic A ==> single A = A
not empty A ==> mix rows A = A
diverse A <==> cull A = list A

The first equation says that if A is atomic, the single of A is equal to A. That is, the single of an atom is the atom. The second equation says that if A is not empty, forming the rows of A and applying mix to recombine them, results in the original array. The third equation says that if A is diverse, the cull of A is equal to the list of A; and that if A is not diverse, the cull of A is not equal to the list of A.

There are many identities that hold for all arrays in Nial. The equations are shown in the on-line help for each topic. Three general equations are the following:

A 347 operation f satisfies the equation:

f A = EACH f A

A 28 operation f satisfies the equation:

A f B = A EACHBOTH f B

A 190 operation f satisfies the equations:

f A = EACHALL f A
f A = REDUCE f A

:Class: system operation :Usage: erase Nm :SeeAlso: symbols :END:

The operation erase is used to remove unwanted global definitions and variables from the workspace. The argument Nm must be a phrase or string giving the object to be removed. Predefined names and names in local scopes cannot be removed.

When a name has been erased, it remains in the symbol table with its original role. It can be redefined in the same role or, if a variable, reassigned a value by a subsequent action. A name cannot change its role once established.

average IS divide[sum,tally];
calc IS EACH average;
Var3 := calc (2 3 4) (5 6 7)

3. 6.

EACH erase "average 'Var3' "sum

: ?noexpr ?noexpr ?system name

In the example above, the operation sum cannot be erased as it is a predefined operation. In the next three examples below, faults are returned because of missing variables or operations that were erased. The effect of erasing an object is not propagated to other definitions referring to the erased name.

Var3

?no_value

average count 10

?missing_op

calc (2 3 4) (5 6 7)

?missing_op ?missing_op

average := 5 6 7

?invalid assignment: AVERAGE :=  <***> 5 6

In the last example, an attempt is made to redefine the role of average and Q'Nial indicated that average is not a suitable name for such an assignment.

The operation eraserecord is used to erase component N of direct access file designated by the number Filenum. In a file with record components, eraserecord replaces the erased component with an empty string. In a file with array components, it replaces the erased component with the fault ?missing.

N may be a single record number or a list of record numbers.

If the last component in a file is erased, any immediately preceding components that are empty in a record component file or contain the fault ?missing in an array component file are also removed. The file tally, which records the number of records in the file, is adjusted accordingly.

The operation returns the fault ?noexpr or a fault indicating improper use of the operation.

File_num := open "Names "d ;
eraserecord File_num 23 ;

The operation eval provides access to the underlying expression evaluator of Q'Nial. The argument to eval must be a parse tree returned by parse or getdef, a named expression or a cast which represents a Nial expression. The effect is to evaluate the expression and return the resulting value. As seen below, the parse tree can be one formed by using the cast mechanism or one built explicitly using parse.

eval parse scan '23 + 45'

68

eval !(23 + 45)

68

The next example shows that eval can be used to evaluate a named expression using either the cast or the phrase of its name.

A := 100 ;
Addone IS (A := A + 1);
(eval !Addone)(eval "Addone)

101 102

(eval !A)(eval "A)(value "A)

102 ?not an expression 102

The last example shows that eval can be used to evaluate the cast of a variable but not a phrase naming the variable. The operation value should be used instead.

The operation except returns the list of items of A that are not in B. It corresponds to set difference if A and B are viewed as set representations. The result is a list with items in the same order as in A.

count 10 except 3 5 7

1 2 4 6 8 9 10

'a list of words' except 'aeiou'

lst f wrds

tell 2 3 except [0 0]

+---+---+---+---+---+
|0 1|0 2|1 0|1 1|1 2|
+---+---+---+---+---+

tell 2 3 except (0 0)

+---+---+---+---+---+---+
|0 0|0 1|0 2|1 0|1 1|1 2|
+---+---+---+---+---+---+

The last two examples show that if the left argument has nonatomic items, to remove a single non-atomic array, the right argument must be made into a solitary list. Otherwise the items of the right argument are used.

The operation execute evaluates a Nial expression given as a string S. The result of the evaluation is returned. The execution of the string takes place in the environment where execute is applied.

If the string contains a name, the local meaning of that name will be used if a local meaning exists. If execution of the string results in the creation of a new variable or defined name, the new object is placed in the global environment.

If a string being executed contains an integer representation that would be converted to an integer outside the range for the computer, the result is converted to the corresponding real number.

execute '23 + 40045'

40068.

A := count 5; opname := 'product';
execute link opname ' A'

120

The last example shows that Nial program text can be constructed under program control and then executed. This feature is useful in applications where responses are generated by combining text elements based on the user input and the current state of the computation. The technique is useful for applications involving computer assisted instruction and knowledge based systems.

It is more efficient to use eval to evaluate the cast of an expression than to use execute to evaluate the corresponding string. In the former approach the scan and parse is done once, whereas in the latter it is repeated on each execution.

The operation exp implements the exponential function of mathematics. It produces the following results when applied to atoms of the six types:

exp  o  1  0.5  `a  "abc  ??error

1. 2.71828 1.64872 ?exp ?exp ?error

The term expression is used in its most general sense to describe a program fragment that denotes one of the three primary objects of Nial: an array, an operation, or a transformer. However, in most contexts we use the term as an abbreviation of an array expression.

An array expression denotes an array value. That is, it is a program fragment that when evaluated in the proper context will produce an array. The predefined expressions of Q'Nial either produce a constant value, or they carry out some system action and return the fault value ?noexpr.

The control constructs of Nial are array expressions made up of keywords, simple-expressions and expression-sequences.

A named expression is either a predefined expression or an expression that has been given an explicit name using the IS definition mechanism.

An expression-sequence is the main construct used for program text that produces a value. It consists of one or more expressions separated by semi-colons and possible followed by a semi-colon.

expression-sequence ::= expression
   { ; expression } [ ; ]

The expressions in an expression-sequence are evaluated in left-to-right order. If the sequence does not terminate with a semicolon, the array returned is the result of the last expression. If the sequence does end with a semicolon, the array returned is the fault ?noexpr. At the top level loop, if the array returned is the fault ?noexpr, it is not displayed.

The expression Exprs returns a list of phrases giving the names of all user defined expressions in the workspace.

The term extent is used to describe the length of an axis of an array in a particular dimension. Thus a 4 by 6 table is said to have extent 4 in the first dimension and extent 6 in the second dimension.

external-declaration ::= identifier IS EXTERNAL ( EXPRESSION

An external declaration assigns a role to a name, allowing it to be used in a definition before its own definition is given. This mechanism is useful for creating mutually recursive definitions. An external declaration is made only in the global environment.

If the name is already defined with the same role, the declaration has no effect. If the name has another role, a fault is reported. If the name is not currently defined, a default object is associated with it.

The constant expression False denotes the boolean atom for false, which Nial also denotes by o. It is the result of comparing two arrays that are not identical for equality.

False (not False)

ol

The operation fault converts a string or phrase into the fault value with the string as its message. If the argument is not a string, phrase or a fault, the result is the fault ?type error.

Fault is used to construct faults that contain blanks or other characters than cannot appear in a literal fault or ones constructed from a message provided from the host system.

By default, fault triggering is on when the interpreter is initialized. This causes the creation of a fault to interrupt the flow of execution. The operation quiet_fault can be used to create a fault value without triggering an interrupt.

settrigger o;
fault '?missing data'

?missing data

fault "Notastring

Notastring

fault 3.4

?type error

The convention is that all faults generated by Q'Nial internally begin with the character ?. The second example shows that this is not a requirement.

Nial assumes that every computation that terminates results in an array value. However, there are many cases where a computation does not have a sensible answer. If division by zero occurs, for example, there is no suitable number to return. Nial uses special atomic arrays called faults to indicate such results. For division by zero it is ?div.

Q'Nial has two ways of handling a fault: either a trigger mechanism is executed that causes an interruption when a fault is created, or during execution of a defined operation, expression or transformer the fault is treated as a normal atomic array.

When Q'Nial is invoked, the fault triggering mechanism is turned on by default. (This effect can be suppressed by using an option in the setup for each version). During execution, the state of the triggering mechanism can be turned on or off using the operation settrigger. The operation quiet_fault can be used to create a fault without causing fault triggering.

If fault triggering is set and a fault is generated during execution of a defined operation, execution is interrupted. On an interruption caused by a fault, a display message appears giving the call stack of definitions currently executing and the line of text that caused the fault. For example, the definition:

foo is op A B { A / B + 1 }

followed by the evaluation of the expression

foo 3 0

results in the output:

-------------------------------------------------------------
    Fault interruption loop:  enter expressions or
     type: <Return>   to jump to top level
    current call stack :
foo
     ?div triggered in : ... A / B
-------------------------------------------------------------
>>>

where the string '>>>' is a special prompt indicating that a fault has occurred and execution has been interrupted. The prompt permits you to query the value of variables in the expression and its surrounding computation or to view the operation that has triggered the fault. The above session might continue as:

>>> see "foo
foo IS OPERATION A B {
    A / B + 1 }
>>> A
3
>>> B
0
>>>

A variable in a definition that called the current one can be referenced by preceding the variables name by the definition name and a colon, e.g. G:X denotes variable X in definition G. You can execute any expressions you want at the prompt. A useful thing to do is to see the definition that has interrupted. When you are ready to resume, reply to the prompt with a Return and control returns to the interactive loop.

The Role of Faults

A fault is a special kind of atomic value used by Q'Nial to signal special values or to indicate that an operation has been given an argument it cannot handle in a normal way. The special value faults are:

The operation filelength returns the length in bytes of the host file named by string or phrase Filename. It is used in conjunction with readfield and writefield in processing host files.

Len := filelength "Myfile;
Data := readfield "Myfile 0 Len;

In the example, filelength is used to determine the size of the file and readfield is used to read it in as raw byte data. If the file corresponds to a text file, the data will include end of line indications appropriate for the host system.

The operation filepath converts a list of phrases or strings giving the names of directories and a filename into the system dependent string that access the specific file. This operation is useful in writing system independent programs that will work with either UNIX or DOS (and WINDOWS) path name conventions.

Example:

filepath ".. "aitools "newfnfl "frames

returns the string

../aitools/newnfl/frames

on a UNIX version of Q'Nial, and returns

..\aitools\newnfl\frames

on a PCDOS version.

The expression Filestatus gives information on the files currently open in a Q'Nial session. It returns a list of triples, one for each open file, giving the file number as an integer, the filename as a phrase and the mode as a character.

The modes are r, w, a, d, pr, pw and c, standing for read, write, append, direct, pipe_read, pipe_write and communications respectively.

The files for standard input, standard output and standard error are opened with modes of r, w and w respectively using file numbers 0, 1 and 2.

Fnum := open "F "a;
Filestatus

+---------+----------+----------+-----+
|0 stdin r|1 stdout w|2 stderr w|3 F a|
+---------+----------+----------+-----+

The operation filetally returns the number of records in the file designated by Filenum, an integer returned by an earlier call to open. The filetally is one higher than the highest component number of a record or array that is written but not erased.

Fn := open "newfile `d;
writearray Fn (9 99) ('The' 'End');
filetally Fn

100

The transformer =FILTER= is given a predicate operation f that is used to select items from A. The result of applying =FILTER= f is to produce a list of the items of A that satisfy the predicate f.

FILTER (0<) (4 -2 3 -5)

4 3

FILTER (not isphrase) (37 4.5 "cat)

37 4.5

The operation find returns the address of the first occurrence of A as an item of B, searching B in row major order. If A does not occur in B, the result is the gage of shape B. The result of find is an integer if B is a list; and a list of integers of tally equal to valence B otherwise.

set "diagram ;
3 find 56 34 3 23 3 57 3

2

The result of find is 2.

`a find 'hello world'

11

2 3 find count 3 4

+-+-+
|1|2|
+-+-+

In the second example, the character a is not in the string 'hello world' and the result is the tally of 'hello world'. In the last example, the result is a list of two integers because the valence of count 3 4 is 2.

The operation findall returns a list of the addresses of all occurrences of A as an item of B, searching B in row major order. If A does not occur in B, the result is the empty list Null. The result of findall is a list of integers if B is a list and a list of pairs if B is a table.

3 findall 56 34 3 23 3 57 3

2 4 6

X := 3 4 reshape 1 7 3 2 3 4 3 2 6 3

1 7 3 2
3 4 3 2
6 3 1 7

3 findall X

+---+---+---+---+
|0 2|1 0|1 2|2 1|
+---+---+---+---+

`a findall 'hello world'

1 1 findall tell 3 4

+---+
|1 1|
+---+

In the first example findall returns the list of integers where 3 is found in the list; in the second a list of pairs is returned. The last example shows that if only one occurrence is found the result is a solitary list.

The operation first returns the first of the items of A. If A is empty, it returns the fault ?address.

first 4 5 6

4

first count 3 4 5

1 1 1

first Null

?address

The operation flip is a synonym for pack. It has been retained for compatibility with earlier versions.

The operation floor produces the following results when applied to atoms of the six types:

floor  l  -2  3.5  `a  "abc  ??error

1 -2 3 ?A ?A ?error

floor  3.5  -4.6  7.0  25.3e20

3 -5 7 ?A

The transformer =FOLD= modifies an operation f to one that takes a pair of arguments consisting of an integer N and an arbitrary array A. The result of applying N FOLD A is to apply f, N times, applying it first to A and subsequently to the result of the previous application.

3 FOLD rest 4 5 6 7 8 9

7 8 9

2 FOLD sum (2 3 4) (5 6 7)

27

sum sum (2 3 4) (5 6 7)

27

The transformer FORK implements a conditional functional mechanism corresponding to the if-expression. The argument to FORK must be an atlas of length two or more. The operation in the first position is a predicate. If there are exactly three items in the atlas, the first is a predicate; the second is applied to A if the predicate returns true; and the third is applied to A if the predicate returns false. That is, if f A is true, the result is g A; otherwise it is h A.

If there are more than three operations in the atlas, they are taken in pairs from left to right. The first of each pair must be a predicate and is applied to A in turn until a result is true. The result of the transform is the result of applying the second of that pair to A. If no application results in true and the number of operations in the atlas is an odd number, the last operation is evaluated. Otherwise the result is the fault ?noexpr.

FORK [atomic, opposite, 1 +] (3 -4 (5 6 7))

+-+--+-----+
|4|-3|6 7 8|
+-+--+-----+

FORK [isreal,floor,simple,sum,5+] 2 4 6

12

The FOR-loop control structure is used to execute the expression sequence ExpSeq repeatedly while variable Var takes on the values specified as items in the simple expression Exp.

FOR X WITH 1. 2. 3. DO
   write (X) (X*X) (X power X) ;
ENDFOR

1. 1. 1.
2. 4. 4.
3. 9. 27.

In the example, X takes on the values 1., 2. and 3. in successive loops and the values of X, X squared and X to the power X are displayed.

The operation 126 converts the boolean array A to a simple array of the same type as atom B.

set "decor;
fromraw oooooooooollololoolloloo `a

'345'

fromraw ooooooooooooooooooooooololollool 0

345

fromraw ooooooooooooooooooooooooooooooooolooooooolooooololoooooooooooooo 0.0

34.5

fromraw lollo l

lollo

The operation front returns a list of all items but the last of A. If A is a solitary or is empty, the result is the empty list Null.

front 3 4 5 6

3 4 5

front tell 2 3

+---+---+---+---+---+
|0 0|0 1|0 2|1 0|1 1|
+---+---+---+---+---+