Chapter 2
© 2000, The TRAC Foundation
Primary Primitives
This chapter describes the most basic TRAC primitives.
There are seven primary primitives. Each has a single-letter mnemonic. In alphabetical order, the seven primary primitives are:
d Delete forms.
e String equality.
g Good-bye (exit).
i Input from keyboard or serial port.
o Output to terminal or serial port.
r Retrieve text string.
s Store text or node form.
2.2 Primary Primitive Reference
This reference section provides the syntax, input arguments, value string, and description for each of the seven primary primitives in alphabetical order.
Syntax
:(d,<address>,<...>)
Input Arguments
<address> The node path and name of the form to delete.
<...> Additional <address> arguments specifying other forms to delete.
Description
The null-valued delete primitive d deletes from internal memory the forms specified by the <address> arguments.
The primitive deletes forms of any type: text, macro, or node forms. For the TRAC processor to recognize a node form to delete, the node form name must have a period suffix. The d primitive accepts up to 127 address arguments of forms to delete. The forms may be scattered throughout the memory tree.
Caution: Unlike the limitations some operating systems place on deleting directories, the d primitive deletes a node form together with all the subnodes and other forms under the node, to any level. The primitive deletes the node form immediately and does not ask for confirmation before deleting.
Example
The following command creates the text form text forml and then deletes it.
:(s,textform1,Hello!)
:(d,text£orm1)'
syntax
:(e,<opl>,<op2>,<yes>,<no>)
Input Arguments
<opl > Operand 1, usually a character string.
<op2> Operand 2, usually a character string.
<yes> A user-supplied string that the primitive statement produces when <op2> exactly matches <opl >.
<no> A user-supplied string that the primitive statement produces when <op2> does not match <opl >.
Description
The value-producing equality primitive e compares the two character strings represented by <op1> and <op2>.
If the <op1> and <op2> strings match exactly, the primitive statement produces the <yes> argument as the value string. If the <op1 > and <op2> strings do not match exactly, the primitive statement produces the <no> argument as the value string. You may supply any sequence of characters as the <op1 >, <op2>, <yes>, and <no> arguments.
Example
The following command compares two strings and, since the strings do not match, produces the <no> argument as the value string. The last argument is in protective parentheses to preserve the spaces between the words.
:(e, 1, 2, matches, (Does not match.)'Does not match.
The next command compares two strings and, since the strings match, produces the <yes> argument as the value string, which in this case is :(r,cat). The TRAC processor interprets the value string because the e primitive has the i suffix.
:(s,res,matches)
:(ei,some text to compare,some text to compare,(:(r,res)),no)'matches
Syntax
:(g)
Input Arguments
None.
Description
The null-valued good-bye primitive g stops the TRAC interactive script. The processor then automatically closes any files it opened while executing a script.
You should use the g primitive to stop the TRAC script as a safety precaution when operating with files.
Example
The following command exits the TRAC interactive script.
:(g)'
syntax
:(i<j>,<N>)
Input Arguments
<j> Channel for input.
<N> Number of characters to input.
Description
The value-producing input from channel primitive i takes in <N> number of characters from the channel <j>. If the <N> argument is a null string, the primitive statement accepts input until it receives the meta character for channel <j>. The default channel, channel 1, is the keyboard of the local machine. Channel 2 is the network interface (in WTNVT) or the serial port (in Dialer). If there is no current input at the designated channel, the i primitive waits indefinitely for input.
The value string produced by an i primitive statement is the characters the primitive accepted from the input stream. The operating system may suppress certain characters during input. The processor discards the terminating meta character, so the meta character is not part of the value string this primitive returns.
By default, an apostrophe is the meta character. You can designate another character as the meta character by using the ic primitive.
If dumping has been activated, the dump character in the input string dumps the contents of the input buffer, but does not terminate the input. By default, the dump character is the @ sign. You can designate another character as the dump character, or activate or deactivate dumping, by using the ic primitive.
When you want the processor to interpret the input string as commands to process, use the i suffix, as in the following:
:(ii)'
The i primitive, unlike the other primary primitives, has many additional features that are accessed by letters following the i mnemonic name. For details of these extended features, see Chapter 6, "Extended Input and Communication Primitives."
Example
The following example takes in and interprets twenty characters from channel 2, then takes input from the default channel, and finally takes in and discards input from channel 2.
:(i2i,20):(i):(i2d)'
See Also
ic
Syntax
:(o,<j>,<text>)
Input Arguments
<j> Channel suffix character specifying output destination: not specifying a channel sends output to the local console screen; a 2 suffix sends output to the serial port (in Dialer) or the network interface (in WTNVT) and to the screen.
<text> Character string to display or transmit.
Description
The null-valued output primitive o puts out the string <text>. Table 2-1 shows the action of the o primitive specified by the <j> channel suffix.
Table 2-1 Channel Suffix Action:
Suffix Character Action of o primitivenone Output to screen. 0 Output to screen. 1 Output to screen 2 Output to serial port or network
interface and to screen.Note: Output goes to the screen unless echoing the
input has been turned off with an "if" primitive statement.
Output goes to channel <j> irrespective of any other use of the channel, such as for monitor or control purposes. If the channel is inoperative, there may be no diagnostic report to this effect.
Example
The following command sends output to the screen.
:(o, (Display this text.))'Display this text.
The next command sends output to the serial port and to the screen.
:(o2, (ATDT 9,5551234))' ITDT 9,5551234
See Also
ie, if
syntax
:(r, <address>, <par1>, <. . . >)
Input Arguments
<address> The node path and name of the text or macro form.
<par1> For macro forms only, a parameter that replaces the twiddle <1>.
<...> For macro forms only, additional parameters that replace additional twiddles in order.
Description
The value-producing recall primitive r retrieves the contents of the form at <address>. The contents of the form are the value string produced by the primitive.
If the form is a macro form (with twiddles), and if the r primitive has additional arguments, such as <par1 >, <par2> and so on, the primitive inserts the strings <par1>, <par2>, and so on, into the twiddle locations in the retrieved text of the macro.
The primitive inserts the string <par1> at the location originally marked in the source of the macro form by <1>, inserts <par2> at <2>, and so on. The primitive fills the <0> twiddle in the macro form with the string <address>. The resulting reconstituted string is the value string of the r primitive statement. You may use macro insertions of this sort in any text or script. You may have up to 126 parameters that replace twiddles in a macro form.
If the primitive r has the i suffix, the processor interprets the value string the statement produces. Because of the interpretation (and any consequent actions), the ri form of the r primitive is actually a procedure call, and the processor executes the text as a script. If the form at <address> is a macro form that contains twiddles, the processor ordinarily interprets as commands the strings that replace the twiddles.
The p suffix to the twiddle index number (as in <3p>) protects the inserted substring from interpretation for one pass of the interpreter. During the first pass the processor removes the protection, so the string is interpreted in the next pass.
An ri statement is the default TRAC primitive statement. You invoke the default primitive statement by inputting a primitive statement with a form name as the first argument instead of a primitive mnemonic. Supply the name of an existing text or macro form and, for a macro form, any parameters. The processor then retrieves and interprets the contents of the form.
Note: The default primitive statement is only activated if you do not supply a primitive mnemonic as the first argument in the statement. You therefore cannot supply as the first argument to the default primitive statement a form name that is the same as a primitive mnemonic. The mnemonic takes precedence during interpretation.
Example
The following commands store some text in a form and then recall the contents of the form. The third line of the example retrieves and interprets the contents of the form.
:(s,textform1,(:(o, Hello!)))'
:(r,textform1)':(o, Hello!)
:(ri,textform1)'Hello!
The following commands store some text in a text form and then use the default primitive to recall and interpret the contents of the form.
:(s,textform, (This is a text form.))'
:(textform)'Thisisatextform.
The following commands store a macro in a macro form and then use the default primitive to recall and interpret the contents of the form.
:(mm,macro1, ((This is the <1> form <0>.)))'
:(macro1,macro)'This is the macro form macro1.
Syntax
:(s,<address>,<text>)
Input Arguments
<address> The node path and name of the text or node form.
<text> For a text form, the character string to store at <address>.
Description
The null-valued store primitive s stores the string <text> at text node address <address>.
If the <address> has a period suffix, the TRAC processor creates a node form and primitive ignores any <text> argument.
You specify an address with a node path and name combination. For an explanation of addressing conventions, see Section 1.8, "Addressing Forms."
If the node path part of <address> is null, the processor records the form at the base level in the memory tree structure.
The s primitive overwrites any previous form of the same address.
A script stored by the s primitive may contain twiddles, such as <1>, <2>, and so on. If the text contains twiddles, you may later use the twiddle to binary mw primitive to change the text form into a macro form. In converting the text form to a macro form, the processor changes the twiddle characters into binary pointers. You can bypass this two-step procedure with the make macro primitive mm. For more information, see Chapter 7, "Memory Primitives."
Example
The following command stores some text in a text form.
:(s, textform. (Put this text into the form called textform at the base node.))'
The next example creates a node form, and stores some text in a text form at the new node. The example then converts the text form to a macro form with the mw primitive, and retrieves the contents of the macro form.
:(a, newnode1.)'
:(s, newnode1.form1, (
The quick <1> fox jumped over the <2> dog.))'
:(mw, newnode1.form1)'
:(r,newnode1.form1,brown,1azy)'
The quick brown fox jumped over the lazy dog.