Debian Codegraph @

help/expressions

raw
1 ! $eterna: expressions,v 1.10 2021/03/21 04:29:43 mrg Exp $
2 !
3 ! Copyright (c) 1990-2021 Michael Sandrof, Troy Rollo, Matthew Green,
4 ! and other ircII contributors.
5 !
6 ! All rights reserved. See the HELP IRCII COPYRIGHT file for more
7 ! information.
8 !
9 This help file describes expresssions available in ${}, and the
10 @, IF, WHILE, and FOREACH commands.
11
12 Variable expressions are used to perform arithmetic, string and
13 boolean operations. Their syntax is similar to the syntax of most
14 computer languages, and is modelled on C syntax. A simple example
15 of this, is that when ${A + 2} is used, and the ASSIGNed variable
16 A has the value '3', the result is 5.
17
18 Brackets can be used in these expressions, so (A+2)*3 would give a
19 value of (3+2)*3 == 15, whereas A+2*3 would give a value of 9, because
20 multiplication is performed before addition.
21
22 Note that there is no consitency in the associatity of ircII
23 expressions, complex expressions MUST use brackets to force the
24 correct evaluation. Even a simple "5 - 2 - 1" does not work
25 as expected, as this is evaluated as "5 - (2 - 1)". This is a
26 bug and may one day be fixed but don't count on it.
27
28 The common arithmetic operations (+, -, *, /) are all available.
29 Additionally, there is a string concatenation operator (##).
30 This treats both sides as strings and pastes them together. Thus
31 if A is 3 and B is 7, "A##B" becomes "37", but "A+B" becomes 10.
32
33 The C-like increment (++) and decrement (--) operators are available.
34 The expression "A++" is like "@A = A + 1".
35
36 You can also assign values to a variable in these expressions
37 using the '=' operator. Thus if you have the expression "C = A+B",
38 it will assign the value 10 to C. This has a number of affects.
39 The most common case is the @ command, where you can enter this expression
40 literally:
41
42 @ C = A + B
43
44 The '=' operator returns the value assigned. Thus you can extend
45 this to:
46
47 @ D = C = A + B
48
49 Which will assign the value 10 to both C and D. In a $ expression,
50 you might want to assign a value to a variable, and display it at the
51 same time. Thus you might do the following:
52
53 echo The value of C is now ${C = A+B}
54
55 which would set C to 10 and display "The value of C is now 10".
56
57 Comparison operations also exist. These return 1 if the comparison is
58 valid (true) and 0 if it is invalid (false). The comparison operations
59 available are:
60
61 == (equal to)
62 > (greater than)
63 >= (greater than or equal to)
64 < (less than)
65 <= (less than or equal to)
66 != (not equal to)
67
68 Thus, the following expressions would result in the following results:
69 ( recall A = 3 and B = 7 )
70
71 A == B FALSE 0
72 A == 3 TRUE 1
73 A > 3 FALSE 0
74 A >= 3 TRUE 1
75 A != 3 TRUE 1
76
77 These expressions can be combined with || (OR), && (AND) and ^^ (XOR).
78 So (A == 3) || (B==3) would be TRUE, and (A == 2) && (B == 7) would be
79 FALSE. You can also negate expressions with ! (NOT), so !(A == 3) would
80 be FALSE. These boolean expressions are used primarily in IF and WHILE.
81
82 A string expression is considered to be true if it is non empty. So
83 if E has the value "word", then E || (A > 3) is true, because E has
84 a non empty value, and !E is false.
85
86 Functions can also appear in expressions. The arguments to functions
87 are evaluated as normal $ type expressions. Thus the following alias:
88
89 alias test echo ${ MID(3 2 $0) + 5) }
90
91 is executed with /test 123456, would give 34 (Two digits from position 3
92 in $0) + 5, giving 39. If the function returns another function name, that
93 function name can be called with another set of brackets. Thus if you have
94 the following set of aliases:
95
96 alias fptr
97 {
98 if ( [$0] )
99 { @ function_return = func1 }
100 { @ function_return = func2 }
101 }
102 alias func1 @ function_return = this is $0
103 alias func2 @ function_return = that is $0
104 alias check echo ${ fptr($0)($1) }
105
106 then /check 0 1 would print "that is 1", and /check 1 0 would print
107 "this is 0".
108
109 Array expressions can also be used in this way. For example:
110
111 assign A.1.1 One One was a racehorse
112 assign A.1.2 Two Two was one too
113 assign A.2.1 One One won one race
114 assign A.2.2 Two Two won one too
115 alias rhyme echo ${ A[$0][$1] }
116
117 would cause /rhyme 2 1 to print "One One won one race".
118
119 Function and array expressions can be combined to give a form
120 of pointer arithmetic like that seen in C. If a function
121 RhymeNum exists as follows:
122
123 alias RhymeNum @ function_return = [A]
124 and rhyme is changed to:
125 alias rhyme echo ${ RhymeNum()[$0][$1] }
126
127 /rhyme 2 1 still prints "One One won one race". This is because
128 RhymeNum returns A, and the expression then becomes A[$0][$1].
129 The $0 is expanded to 2, so it becomes A.2[$1], and the $1 is
130 expanded to 1, so it becomes A.2.1, which is then substituted as
131 a variable for "One One won one race". The reverse is also possible.
132 For example, a robot might have the following:
133
134 alias thing.0 @ function_return = laughs his silly head off
135 alias thing.1 @ function_return = growls menacingly
136 alias thing.2 @ function_return = smiles like a crocodile
137 alias thing.3 @ function_return = wails uncontrollably
138 alias something SAY WereBot ${ thing[$RANDOM(4)]() }
139
140 Will cause WereBot to say that it's laughing itself silly, growling
141 menacingly, smiling like a crocodile or wailing uncontrollably.
142 Assuming RANDOM(4) results in a value of 2, This expands to
143 thing.2(), which is then considered to be a function and substituted
144 to "smiles like a crocodile", the end result being that WereBot will
145 say "WereBot smiles like a crocodile".
146
147 Finally, there are occasions when you need to get back to the $
148 substitution level. This can be done by enclosing text to be used at
149 this level in [..]. For example, [A] substitutes to a literal 'A',
150 whereas A on its own substitutes to 3, and [$0] is needed to get
151 argument 0, because 0 on its own is taken to be the number 0.
152 Example:
153
154 alias something SAY WereBot ${ [$0][$RANDOM(4)]() }
155
156 will case /something thing to first expand [$0] to thing, giving
157 thing[$RANDOM(4)](), and if $RANDOM(4) returns 1, this becomes
158 thing.1(), which expands to "growls menacingly", and causes
159 WereBot to say "WereBot growls menacingly".
160
161
162 The following is the parse tree for expressions such as those
163
164 NU_EXPR = NU_CONJ
165 NU_CONJ = NU_CONJ && NU_CONJ |
166 NU_CONJ || NU_CONJ |
167 NU_CONJ ^^ NU_CONJ |
168 NU_ASSN
169 NU_ASSN = varexp = NU_ASSN |
170 NU_COMP
171 NU_COMP = NU_COMP == NU_COMP |
172 NU_COMP != NU_COMP |
173 NU_COMP > NU_COMP |
174 NU_COMP >= NU_COMP |
175 NU_COMP < NU_COMP |
176 NU_COMP <= NU_COMP |
177 NU_ADD
178 NU_ADD = NU_ADD + NU_ADD |
179 NU_ADD - NU_ADD |
180 NU_ADD ## NU_ADD |
181 NU_MULT
182 NU_MULT = NU_MULT * NU_MULT |
183 NU_MULT / NU_MULT |
184 NU_UNIT
185 NU_UNIT = token NUX_MODIF |
186 unaryop token |
187 ( NU_EXPR ) |
188 [ expression ] NUX_MODIF
189 NUX_MODIF = ( expression ) NUX_MODIF |
190 [ expression ] NUX_MODIF
191
192 Special cases:
193 If a (...) or {...} construct is quoted with \(...\) or \{...\}
194 then variable expansion will take place on the first available
195 parse run. However, after parsed, the \'s are eaten. e.g.
196 alias bonk echo ($0) will return "($*)" regardless of
197 the argument to the alias. No expansion takes place. However, in
198 alias bonk echo \($0\)
199 expansion takes place as the special meaning of the () is taken
200 away by \. This will return "(arguments to bonk)".