Vocabulary/DirectDefinition
In-Place Definition of Explicit Entities
Direct Definition (DD) is a shorthand for writing an explicit definition.
2 {{ x + y }} 100 200 300
102 202 302
The text between the delimiters {{ and }} is converted to an explicit definition. Here, because it referred to both x and y, the entity is a dyadic verb. The delimiters and everything between them is replaced by the verb. In this case, that puts the verb in a position to be executed, and it is.
add =. {{ x + y }}
100 200 300 add 5
105 205 305
Here the verb was assigned to a name, and executed later.
add1to2 =: {{ 'first second' =. y
first + second }}
add1to2 100 200 300 ; 5
105 205 305
The defined entity can be as many lines long as you like.
seqs =. {{ seq =. $0
while. y~:1 do.
y =. -:`(1 3&p.)@.(2&|) y
seq =. seq,y
end. seq }}&.> 12 13 14
,. seqs
+--------------------------------------------+
|6 3 10 5 16 8 4 2 1 |
+--------------------------------------------+
|40 20 10 5 16 8 4 2 1 |
+--------------------------------------------+
|7 22 11 34 17 52 26 13 40 20 10 5 16 8 4 2 1|
+--------------------------------------------+
All the lines of the DD become the explicit entity, tying together other words on the same lines.
For compatibility, the value of an explicit definition is always displayed in (m : n) form, even if the definition was made using {{ }}:
add =. {{ x + y }}
add
4 : 'x + y '
The number indicates the part of speech: 0=noun, 1=adverb, 2=conjunction, 3=verb, 4=dyadic verb.
Where can I use DD?
DD can be used:
- From the keyboard
- Inside a script
- In text executed by 0!:xxx
- Inside a multiline explicit definition defined using (m : 0) or define
- Inside another DD
- In the argument of (". y)
DD cannot be used in an explicit definition using m : text.
DD is not available in system versions earlier than J902.
What kind of entity will DD create?
DD creates an explicit definition. The type of entity DD creates depends on the names you use:
- if n or v is used, DD creates a conjunction
- otherwise if m or u is used, DD creates an adverb
- otherwise if x is used, DD creates a dyadic or bivalent verb
- otherwise a monadic verb.
Bivalent verbs are produced if the text contains the usual separator line containing a single : character.
What is the execution environment of a DD?
It is just like any other explicit definition. The entity has its own private namespace, written to using =., and it can write to public namespaces using =:.
Can I just tell DD what kind of entity to create?
Yes. If the very first character following the leading delimiter is ), the first line contains control information and is not part of the entity being defined.
Using a first character of ) as a system escape has a long pedigree in APL.
The very first character after the ) indicates what part of speech you want:
char part of speech generated m monadic verb d dyadic verb v verb with valence depending on the names used a adverb c conjunction n noun. See below for details. * (default) depends on the names used
Non-nouns defined with {{)
If the character following {{) is not n, all following non-comment words are reserved for control information for the definition. Currently no such control information has been defined, so no other words are allowed.
Nouns defined with {{)n
Since direct definition replaces the text between {{ and }} with a quoted string, the only need for a noun form is for values that are troublesome to put into a quoted string: strings containing ' or LF.
A noun DD begins with the character immediately following the start sequence {{)n. The {{ must be a valid J word but the contents of the noun need not be.
The noun DD ends with the character before the trailing delimiter; the characters between the {{ and }} inclusive are replaced by a quoted string, set off by one space at beginning and end.
What is recognized as a trailing delimiter is given by one rule and two exceptions to it.
Rule: the trailing delimiter is the two-character sequence }} when found at the beginning of a line. Each line before the line containing the delimiter ends with an LF character.
a =. {{)n Line 1
Line 2 }}
}}
a NB. Note that }} not in column 1 is part of the value
Line 1
Line 2 }}
$a NB. a is really a literal list
18
a. i. a NB. view the ASCII codes - code 10 is LF
32 76 105 110 101 32 49 10 76 105 110 101 32 50 32 125 125 10
The text outside the noun DD is processed as J words.
'Prefix' , {{)n Line 1
Line 2
}} , 'suffix'
Prefix Line 1
Line 2
suffix
Exception 1: }} is recognized as a delimiter if it appears on the same line as the starting {{)n. The purpose of the exception is to allow you to create values that do not contain LF.
a =. {{)nCasey's Tool Works}} NB. quoted string - note no trailing LF
a
Casey's Tool Works
Exception 2: if no characters follow {{)n, the LF for the first line is omitted. The purpose of the exception is to allow values that contain }} and do not start with LF.
a =. {{)n
{{ this string is for a program that uses {{ and }} }}
}}
a NB. Note there is an ending LF but no leading LF
{{ this string is for a program that uses {{ and }} }}
Notes on {{ and }}
{{ and }} are individual J words, and are grouped as such by (;: y). If the delimiter is inflected (as in {{.), it is NOT recognized as a single word, but as the two J words { and {. .
;:'{{{ }}}'
+--+-+--+-+
|{{|{|}}|}|
+--+-+--+-+
;:'{{ }}.'
+--+-+--+
|{{|}|}.|
+--+-+--+
The linear representation of a verb does not use {{ and }}, because old code expects to see : there. {{ and }} are used for definitions found inside an explicit definition.