-
Notifications
You must be signed in to change notification settings - Fork 152
Expand file tree
/
Copy pathprepro.tex
More file actions
2351 lines (1898 loc) · 86.1 KB
/
prepro.tex
File metadata and controls
2351 lines (1898 loc) · 86.1 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
\chapter{The preprocessor}
\label{preprocessor}
%--#[ General :
The preprocessor\index{preprocessor} is a program segment that reads and
edits\index{edit} the input, after which the processed input is offered to
the compiler\index{compiler} part of \FORM. When a module\index{module}
instruction is encountered by the preprocessor, the compilation is halted
and the module is executed. The compiler buffers are cleared and \FORM\
will continue with the next module. The preprocessor acts almost purely on
character strings. As such it does not know about the algebraic properties
of the objects it processes. Additionally the preprocessor also filters out
the commentary\index{commentary}.
The commands for the preprocessor are called instructions. Preprocessor
instructions start with the character \# as the first non-blank character
in a line. After this there are several possibilities.
\begin{description}
\item[\#:]\index{\#:} Special syntax for setup parameters at the beginning
of the program. See the chapter on the setup parameters.
\item[\#$-$, \#$+$]\index{\#$-$}\index{\#$+$} Turns the listing of the input off or
on.
\item[\#name]\index{\#name} Preprocessor command. The syntax of the various
commands will be discussed below.
\item[\#\$name]\index{\#\$name} Giving a value to a dollar variable in the
preprocessor. See chapter \ref{dollars} on dollar variables.
\end{description}
%--#] General :
%--#[ The preprocessor variables :
\section{The preprocessor variables}
\label{preprovariables}
In order to help in the edit\index{edit} function the preprocessor is
equipped with variables\index{preprocessor variables} that can be defined
or redefined by the user or by other preprocessor actions. Preprocessor
variables have regular names that are composed of strings of alphanumeric
characters of which the first one must be alphabetic. When they are defined
one just uses this name. When they are used the name should be enclosed
between a backquote\index{backquote} and a quote\index{quote} as if these
were some type of brackets. Hence `a2r' is the reference to a regular
preprocessor variable. Preprocessor variables contain strings of
characters. No interpretation is given to these strings. The
backquote/quote pairs can be nested. Hence `a`i'r' will result in the
preprocessor variable `i' to be substituted first. If this happens to be
the string "2", the result after the first substitution would be `a2r' and
then \FORM\ would look for its string value.
The use of the backquotes is different from the earlier versions of \FORM.
There the preprocessor variables would be enclosed in a pair of quotes and
no nesting\index{nesting} was possible. \FORM\ still understands this old
notation because it does not lead to ambiguities. The user is however
strongly advised to use the new notation with the backquotes, because in
future versions the old\index{old notation} notation may not be recognized
any longer.
\noindent \FORM\ has a number of built in preprocessor variables. They are:
\begin{description}
\item[VERSION\_] The current version\index{VERSION\_} as the \formmajorversion{} in
\formmajorversion.\formminorversion.
\item[SUBVERSION\_] The sub-version\index{SUBVERSION\_} as the \formminorversion{} in
\formmajorversion.\formminorversion.
\item[NAME\_] The name\index{NAME\_} of the program file.
\item[DATE\_] The date\index{DATE\_} of the current run.
\item[CMODULE\_] The number\index{CMODULE\_} of the current module.
\item[SHOWINPUT\_] If input listing\index{SHOWINPUT\_} is on: 1, if off: 0.
\item[EXTRASYMBOLS\_] The current number of extra symbols\index{EXTRASYMBOLS\_}
(see \ref{substaextrasymbols}).
\item[OLDNUMEXTRASYMBOLS\_] The number of extra symbols\index{OLDNUMEXTRASYMBOLS\_}
before the current optimization started (see chapter \ref{optimization}).
\item[OPTIMMINVAR\_] The number of the first extra symbol\index{OPTIMMINVAR\_} needed
for the current optimization (see chapter \ref{optimization}).
\item[OPTIMMAXVAR\_] The number of the last extra symbol\index{OPTIMMAXVAR\_} needed
for the current optimization (see chapter \ref{optimization}).
\item[OPTIMSCHEME\_] The best Horner scheme\index{OPTIMSCHEME\_} found
for the current optimization (see chapter~\ref{optimization}).
\item[OPTIMVALUE\_] The number of arithmetic operations\index{OPTIMVALUE\_}
in the resulting expression for the current optimization
(see chapter~\ref{optimization}).
\item[PID\_] The process identifier (PID) \index{PID} \index{PID\_} of
the running process. In \ParFORM{} (\ref{parform}), it represents
the PID of the master process in order to ensure that all the
processes in a job use the same number. A recovered session from
a checkpoint (\ref{checkpoints}) keeps using the PID of the
crushed session.
\item[STOPWATCH\_] Same as `TIMER\_'.
\item[TIME\_] The running time\index{time\_} till the moment of call in the string format
with a decimal point and two digits after the decimal point.
This is the same format as in the statistics.
\item[TIMER\_] The running time\index{timer\_} since the last reset in milliseconds. Hence,
unlike `time\_' this value can be used in the preprocessor
calculator and in numerical compares in \#if instructions.
See also the \#reset (see \ref{prereset}) instruction.
\item[NUMACTIVEEXPRS\_] The number of the current active expressions.
\item[ACTIVEEXPRNAMES\_] The list of the current active expression names
separated by commas. This can be passed to \#do lvar=\{...\}
instruction~(\ref{predo}) like:
\begin{verbatim}
#do e = {`activeexprnames_'}
#ifdef `e'
Local `e' = `e' + something;
#endif
#enddo
\end{verbatim}
\end{description}
\noindent If \FORM\ cannot find a preprocessor variable, because it has
neither been defined by the user, nor is it one of the built in variables,
it will look in the systems environment\index{environment} to see whether
there is an environment variable by that name. If this is the case its
string value will be substituted.
\noindent Preprocessor variables can have arguments and thereby become
macro's. One should consult the description of the \#define~\ref{predefine}
instruction about the delayed substitution feature to avoid the value of
the preprocessor variables in the macro would be substituted immediately
during the definition. Hence proper use is
\begin{verbatim}
#define EXCHANGE(x,y) "Multiply replace_(`~x',`~y',`~y',`~x');"
\end{verbatim}
\noindent \FORM{} has the following built in macro's:
\begin{description}
\item[TOLOWER\_(string)] in which the character string in the argument is
converted to lower case. After this it will become input.
\item[TOUPPER\_(string)] in which the character string in the argument is
converted to upper case. After this it will become input.
\end{description}
It is anticipated that some more macro's will become available to allow for
the editing of names of variables.
%--#] The preprocessor variables :
%--#[ Calculator :
\section{The preprocessor calculator}
\label{calculator}
Sometimes a preprocessor\index{preprocessor variable!numeric} variable
should be interpreted as a number and some arithmetic\index{arithmetic}
should be done with it. For this \FORM\ is equipped with what is called the
preprocessor calculator\index{calculator}. When the input reading device
encounters a left curly\index{curly bracket} bracket\index{bracket!curly}
\verb:{:, it will read till the matching right curly bracket \verb:}: and
then test whether the characters (after substitution of preprocessor
variables) can be interpreted as a numerical expression. If it is not a
valid numerical expression the whole string, including the curly brackets,
will be passed on to the later stages of the program. If it is a numerical
expression, it will be evaluated, and the whole string, including the curly
brackets, will be replaced by a textual representation of the result.
Example:
\begin{verbatim}
Local F`i' = F{`i'-1}+F{`i'-2};
\end{verbatim}
If the preprocessor variable i has the value 11, the calculator makes this
into
\begin{verbatim}
Local F11 = F10+F9;
\end{verbatim}
Valid numerical expressions can contain the characters
\begin{verbatim}
0 1 2 3 4 5 6 7 8 9 + - * / % ( ) { } & | ^ !
\end{verbatim}
The use of parentheses is as in regular arithmetic. The curly
brackets fulfil the same role, as one can nest these brackets of course.
Operators are:
\begin{description}
\item[$+$] Regular addition\index{addition}.
\item[$-$] Regular subtraction\index{subtraction}.
\item[$\ast$] Regular multiplication\index{multiplication}.
\item[$/$] Regular (integer) division\index{division}.
\item[$\%$] The remainder\index{remainder} after (integer) division as in
the language C\index{C}.
\item[$\&$] And\index{and} operator. This is a bitwise operator.
\item[$|$] Or\index{or} operator. This is a bitwise or.
\item[$\wedge$] Exponent\index{exponent} operator.
\item[$!$] Factorial\index{factorial}. This is a postfix operator.
\item[$\wedge\%$] A postfix ${}^2\!\log$. This means that it
takes\index{twolog} the ${}^2\!\log$ of the object to the left of it.
\item[$\wedge/$] A postfix square\index{square root} root. This means that
it takes the square root of the object to the left of it.
\end{description}
Note that all arithmetic\index{arithmetic} is done over the integers and
that there is a finite range. On 32\index{32 bits} bit systems this range
will be $2^{31}-1$ to $-2^{31}$, while on 64\index{64 bits} bit systems
this will be $2^{63}-1$ to $-2^{63}$. In particular this means that
\verb:{13^/}: becomes \verb:3:. The preprocessor calculator is only meant
for some simple counting and organization of the program flow. Hence there
is no large degree of sophistication. Very important is that the
comma\index{comma} character is not a legal character for the preprocessor
calculator. This can be used to avoid some problems. Suppose one needs to
make a substitution of the type:
\begin{verbatim}
id f(x?!{0}) = 1/x;
\end{verbatim}
in which the value zero should be excluded from the pattern matching (see
dynamical\index{set!dynamical} sets in chapter \ref{pattern} on pattern
matching). This would not work, because the preprocessor would make this
into
\begin{verbatim}
id f(x?!0) = 1/x;
\end{verbatim}
which is illegal syntax. Hence the proper trick is to write
\begin{verbatim}
id f(x?!{,0}) = 1/x;
\end{verbatim}
With the comma the preprocessor will leave this untouched, and hence now
the set is passed properly.
Good use of the preprocessor calculator can make life much easier for
\FORM. For example the following statements
\begin{verbatim}
id f(`i') = 1/(`i'+1);
id f(`i') = 1/{`i'+1};
\end{verbatim}
are quite different in nature. In the first statement the compiler gets an
expression with a composite denominator. The compiler never tries to
simplify expressions by doing algebra on them. Sometimes this may not be
optimal, but there are cases in which it would cause wrong results (in
particular when noncommuting and commuting functions are mixed and
wildcards are used). Hence the composite denominator has to be worked out
during run time for each term separately. The second statement has the
preprocessor work out the sum and hence the compiler gets a simple fraction
and less time will be needed during running. Note that
\begin{verbatim}
id f(`i') = {1/(`i'+1)};
\end{verbatim}
would most likely not produce the desired result, because the preprocessor
calculator works only over the integers. Hence, unless i is equal to zero
or -2, the result would be zero (excluding of course the fatal error when i
is equal to -1).
%--#] Calculator :
%--#[ ... :
\section{The triple dot operator}
\label{tripledot}
The last\index{...} stage of the actions of the preprocessor involves the
triple dot operator. It indicates a repeated pattern as in \verb:a1+...+a4:
which would expand into \verb:a1+a2+a3+a4:. This operator is used in two
different ways. First the most general way:
\begin{verbatim}
<pattern1>operator1...operator2<pattern2>
\end{verbatim}
in which the less\index{less than} than and greater\index{greater than}
than signs serve as boundaries for the patterns. The operators can be any
pair of the following:
\begin{description}
\item[+\ +]\index{+...+} Repetitions will be separated by plus signs.
\item[--\ --]\index{-...-} Repetitions will be separated by minus signs.
\item[+\ --]\index{+...-} Repetitions will be separated by alternating signs.
First will be plus.
\item[--\ +]\index{-...+} Repetitions will be separated by alternating signs.
First will be minus.
\item[$\ast\ \ast$]\index{*...*} Repetitions will be separated by $\ast$.
\item[/\ /]\index{/.../} Repetitions will be separated by /.
\item[,\ ,]\index{,...,} Repetitions will be separated by comma's.
\item[:\ :]\index{:...:} Repetitions will be separated by {\it single} dots.
%\item[+\ +]\index{.@$+\cdots+$} Repetitions will be separated by plus signs.
%\item[--\ --]\index{.@$-\cdots-$} Repetitions will be separated by minus signs.
%\item[+\ --]\index{.@$+\cdots-$} Repetitions will be separated by alternating signs.
%First will be plus.
%\item[--\ +]\index{.@$-\cdots+$} Repetitions will be separated by alternating signs.
%First will be minus.
%\item[$\ast\ \ast$]\index{.@$\ast\cdots\ast$} Repetitions will be separated by $\ast$.
%\item[/\ /]\index{.@$/\cdots/$} Repetitions will be separated by /.
%\item[,\ ,]\index{.@$,\cdots,$} Repetitions will be separated by comma's.
%\item[:\ :]\index{.@$:\cdots:$} Repetitions will be separated by {\it single} dots.
\end{description}
For such a pair of operators \FORM\ will inspect the patterns\index{pattern}
and see whether the differences between the two patterns are just numbers.
If the differences are numbers and the absolute value of the difference of
each matching pair is always the same (a difference of zero is allowed too;
it leads to no action for the pair), then \FORM\ will expand the pattern,
running from the first to the last in increments of one. For each pair the
counter can either run up or run down, depending on whether the number in
the first pattern is greater or less than the number in the second pattern.
Example:
\begin{verbatim}
Local F = <a1b6(c3)>-...+<a4b3(c6)>;
\end{verbatim}
leads to
\begin{verbatim}
Local F = a1b6(c3)-a2b5(c4)+a3b4(c5)-a4b3(c6);
\end{verbatim}
The second form is a bit simpler. It recognizes that there are special
cases that can be written in a more intuitive way. If there is only a
single number to be varied, and it is the end of the pattern, and the rest
of the patterns consists only of alphanumeric characters of which the first
is an alphabetic character, we do not need the less than/greater than
combination. This is shown in
\begin{verbatim}
Symbol a1,...,a12;
\end{verbatim}
There is one extra exception. The variables used this way may have a
question mark after them to indicate that they are wildcards:
\begin{verbatim}
id f(a1?,...,a4?) = g(a1,...,a4,a1+...+a4);
\end{verbatim}
This construction did not exist in earlier versions of \FORM\ (version 1 and
version 2). There one needed the \#do\index{\#do} instruction for many of
the above constructions, creating code that was very hard to read. The
\verb:...: operator should improve the readability of the programs very
much.
%--#] ... :
%--#[ add :
\section{\#add}
\label{preadd}
\noindent Syntax:
\#add object: "string"
\noindent See chapter \ref{dictionaries} on dictionaries.
\noindent Adds words to an open dictionary.
%--#] add :
%--#[ addseparator :
\section{\#addseparator}
\label{preaddseparator}
\noindent Syntax:
\#addseparator character
\noindent See also \#rmseparator (\ref{prermseparator}),
\#call (\ref{precall}), \#do (\ref{predo})
\noindent Adds a character\index{\#addseparator} to the list of permissible
separator characters for arguments of \#call or \#do instructions. By
default the two characters that are permitted are the comma and the
character \verb:|:. Blanks, tabs and double quotes are ignored. Note that
the comma must be specified between double quotes as in
\begin{verbatim}
#addseparator ","
\end{verbatim}
%--#] addseparator :
%--#[ append :
\section{\#append}
\label{preappend}
\noindent Syntax:
\#append $<$filename$>$
\noindent See also write (\ref{prewrite}),
close (\ref{preclose}), create (\ref{precreate}),
remove (\ref{preremove})
\noindent Opens\index{\#append} the named file for writing. The file will
be positioned at the end. The next \#write\index{\#write} instruction will
add to it.
%--#] append :
%--#[ appendpath :
\section{\#appendpath}
\label{preappendpath}
\noindent Syntax:
\#appendpath pathname
\noindent See also prependpath~(\ref{preprependpath})
\noindent Appends the given path relative to the current file to the end of
the FORM path\index{path}.
%--#] appendpath :
%--#[ break :
\section{\#break}
\label{prebreak}
\noindent Syntax:
\#break
\noindent See also switch (\ref{preswitch}),
endswitch (\ref{preendswitch}),
case (\ref{precase}),
default (\ref{predefault})
\noindent If the\index{\#break} lines before were not part of the control
flow ({\it i.e.} these lines are used for the later stages of the program),
this instruction is ignored. If they are part of the control flow, the flow
will continue after the matching \#endswitch\index{\#endswitch}
instruction. The \#break instruction must of course be inside the range of
a \#switch\index{\#switch}/\#endswitch construction.
%--#] break :
%--#[ breakdo :
\section{\#breakdo}
\label{prebreakdo}
\noindent Syntax:
\#breakdo [{\tt<}number{\tt>}]
\noindent See also \#do (\ref{predo}) and \#enddo (\ref{preenddo})
\noindent The \#breakdo\index{\#breakdo} instruction allows one to jump out
of a \#do loop. If a (nonzero integer) number is specified it indicates the
number of loops the program should terminate. Control will continue after
the \#enddo instruction of the number of loops indicated by `number'.
The default value is one. If the value is zero the statement has no effect.
%--#] breakdo :
%--#[ call :
\section{\#call}
\label{precall}
\noindent Syntax:
\#call procname(var1,...,varn)
\noindent See also procedure (\ref{preprocedure}), endprocedure
(\ref{preendprocedure})
\noindent This instruction\index{\#call} calls the
procedure\index{procedure} with the name procname. The result is that \FORM\
looks for this procedure, first in its procedure
buffers\index{buffer!procedure} (for procedures that were defined in the
regular text stream as explained under the \#procedure\index{\#procedure}
instruction), then it looks for a file by the name procname.prc in the
current directory, and if it still has not found the procedure, it looks in
the directories indicated by the path\index{path} variable in either the setup
file or at the start of the program (see chapter \ref{setup} on the setup
file). Next it looks for the -p option in the command that started \FORM\
(see the chapter on running \FORM). If this -p option has not been used \FORM\
will see whether there is an environment variable by the name
FORMPATH\index{FORMPATH}. The directories indicated there will be searched
for the file procname.prc. If \FORM\ cannot find the file, there will be an
error message and execution will be stopped immediately.
Once the procedure has been located, \FORM\ reads the whole file and then
determines whether the number of parameters is identical in the
\#call\index{\#call} instruction and the \#procedure\index{\#procedure}
instruction. A difference is a fatal error.
The parameter field consists of strings, separated by commas. If a string
contains a comma, this comma should be preceded by a
backslash\index{backslash} character (\verb:\:). If a string should contain
a linefeed\index{linefeed}, one should `escape' this linefeed by putting a
backslash and continue on the next line.
Before version 3 of \FORM\ the syntax was different. The parentheses
were curly brackets and the separators the symbol \verb:|:. This was made
to facilitate the use of strings that might contain commas. In practise
however, this turned out to be far from handy. In addition the new
preprocessor calculator is a bit more active and hence an instruction of
the type
\begin{verbatim}
#call test{1}
\end{verbatim}
will now be intercepted by the preprocessor calculator\index{calculator}
and changed into
\begin{verbatim}
#call test1
\end{verbatim}
Because there are many advantages to the preprocessor calculator treating
the parameters of the procedures before they are called (in the older
versions it did not do this), the notation has been changed. \FORM\ still
understands the old notation, provided that there is no conflict with the
preprocessor calculator. Hence
\begin{verbatim}
#call test{1|a}
#call test{1,a}
#call test(1|a)
#call test(1,a)
\end{verbatim}
are all legal and give the same result, but only the last notation will
work in future versions of \FORM.
Nowadays also the use of the argument field wildcard (see chapter
\ref{pattern} on pattern matching) is allowed as in the
regular functions:
% THIS EXAMPLE IS PART OF THE TESTSUITE. CHANGES HERE SHOULD BE APPLIED THERE AS
% WELL!
\begin{verbatim}
#define a "1"
#define bc2 "x"
#define bc3 "y"
#define b "c`~a'"
#procedure hop(c,?d);
#redefine a "3"
#message This is the call: `c',`?d'
#endprocedure
#redefine a "2"
#message This is b: `b'
~~~This is b: c2
#call hop(`b`!b''`!b'`b'`!b'`b',`~a',`b',`a')
~~~This is the call: xc2c3c2c3,3,c3,2
.end
\end{verbatim}
We also see here that the rules about delayed substitution (see also the
\#define\index{\#define} instruction in section \ref{predefine}) apply. The
use of `!b' cancels the delayed substitution that is asked for in the
definition of b.
The default extension for procedure files is .prc\index{.prc}, but it is
possible to change this. There are two different ways: One is with the
\#procedureExtension\index{\#procedureExtension} instruction in section
\ref{preprocedureextension}. The other is via the setup (see the chapter on
the setup file, chapter \ref{setup}).
%--#] call :
%--#[ case :
\section{\#case}
\label{precase}
\noindent Syntax:
\#case string
\noindent See also switch (\ref{preswitch}),
endswitch (\ref{preendswitch}),
break (\ref{prebreak}),
default (\ref{predefault})
\noindent The lines after the \#case\index{\#case} instruction will be used
if either this is the first \#case\index{\#case} instruction of which the
string matches the string in the \#switch\index{\#switch} instruction, or
the control flow was already using the lines before this \#case instruction
and there was no \#break\index{\#break} instruction (this is called
fall-through). The control flow will include lines either until the next
matching \#break instruction, or until the matching
\#endswitch\index{\#endswitch} instruction.
%--#] case :
%--#[ clearoptimize :
\section{\#clearoptimize}
\label{preclearoptimize}
\noindent Syntax:
\#clearoptimize
See the chapter about optimization \ref{optimization}
%--#] clearoptimize :
%--#[ close :
\section{\#close}
\label{preclose}
\noindent Syntax:
\#close $<$filename$>$
\noindent See also write (\ref{prewrite}), append (\ref{preappend}),
create (\ref{precreate}), remove (\ref{preremove})
\noindent This instruction closes\index{\#close} the file\index{file!close}
by the given name, if such a file had been opened by the previous
\#write\index{\#write} instruction. Normally \FORM\ closes all such files at
the end of execution. Hence the user would not have to worry about this.
The use of a subsequent \#write instruction with the same file name will
remove the old contents and hence start basically a new file. There are
times that this is useful.
%--#] close :
%--#[ closedictionary :
\section{\#closedictionary}
\label{preclosedictionary}
\noindent Syntax:
\#closedictionary
\noindent See chapter \ref{dictionaries} on dictionaries.
\noindent Either closes an open dictionary (\ref{preopendictionary}) or stops
using the dictionary (\ref{preusedictionary}) that is currently used for output
translation.
%--#] closedictionary :
%--#[ commentchar :
\section{\#commentchar}
\label{precommentchar}
\noindent Syntax:
\#commentchar character
\noindent The specified\index{\#commentchar} character should be a single
non-whitespace character. There may be white space (blanks and/or tabs)
before or after it. The character will take over the role of the comment
character. {\it i.e.} any line that starts with this character in column 1
will be considered commentary\index{commentary}. This feature was provided
because output of some other algebra programs could put the multiplication
sign in column 1 in longer expressions.
The default commentary character is $\ast$.
%--#] commentchar :
%--#[ create :
\section{\#create}
\label{precreate}
\noindent Syntax:
\#append $<$filename$>$
\noindent See also write (\ref{prewrite}),
close (\ref{preclose}), append (\ref{preappend}),
remove (\ref{preremove})
\noindent Opens the named\index{\#create} file for writing. If the file
existed already, its previous contents will be lost. The next
\#write\index{\#write} instruction will add to it. In principle this
instruction is not needed, because the \#write instruction would create the
file if it had not been opened yet at the moment of writing.
%--#] create :
%--#[ default :
\section{\#default}
\label{predefault}
\noindent Syntax:
\#default
\noindent See also switch (\ref{preswitch}),
endswitch (\ref{preendswitch}),
case (\ref{precase}),
break (\ref{prebreak})
\noindent Control\index{\#default} flow continues after this instruction if
there is no \#case\index{\#case} instruction of which the string matches
the string in the \#switch\index{\#switch} instruction. Control flow also
continues after this instruction, if the lines before were included and
there was no \#break\index{\#break} instruction to stop the control flow
(fall-through). Control flow will stop either when a matching \#break
instruction is reached, or when a matching \#endswitch\index{\#endswitch}
is encountered. In the last case of course control flow will continue after
the \#endswitch instruction.
%--#] default :
%--#[ define :
\section{\#define}
\label{predefine}
\noindent Syntax:
\#define name "string"
\noindent See also redefine (\ref{preredefine}), undefine
(\ref{preundefine})
\noindent in which name\index{\#define} refers to the name of the
preprocessor\index{preprocessor variable}
variable\index{variable!preprocessor} to be defined and the contents of the
string will form the value of the variable. The double quotes are mandatory
delimiters of the string.
The use of the \#define\index{\#define} instruction creates a new instance
of the preprocessor variable with the given name. This means that the old
instance\index{instance} remains. If for some reason the later instance
becomes undefined (see for instance \#undefine), the older instance will be
the one that is active. If the old definition is to be overwritten, one
should use the \#redefine\index{\#redefine} instruction.
As of version 3.2 preprocessor variables can also have arguments as in the
C\index{C} language. Hence
\#define var(a,b) "(`\verb:~:a'+`\verb:~:b'+`c')"
is allowed. The parameters should be referred to inside a pair of `' as
with all preprocessor variables. A special feature is the socalled
delayed\index{delayed substitution}
substitution\index{substitution!delayed}. With macro's like the above the
question is always {\sl when} a preprocessor variable will be substituted.
Take for instance
% THIS EXAMPLE IS PART OF THE TESTSUITE. CHANGES HERE SHOULD BE APPLIED THERE AS
% WELL!
\begin{verbatim}
#define c "3"
#define var1(a,b) "(`~a'+`~b'+`c')"
#define var2(a,b) "(`~a'+`~b'+`~c')"
#redefine c "4"
Local F1 = `var1(1,2)';
Local F2 = `var2(1,2)';
Print;
.end
F1 =
6;
F2 =
7;
\end{verbatim}
The parameter c will be substituted immediately when var1 is defined. In
var2 it will be only substituted when var2 is used. It should be clear that
a and b should also be used in the delayed fashion because they do not
exist yet at the moment of the definition of var1 and var2. Notice also
that the whole macro\index{macro}, with its arguments should be placed
between the backquote and the quote. Another example can be found with the
\#call\index{\#call} instruction. See section \ref{precall}
%--#] define :
%--#[ do :
\section{\#do}
\label{predo}
\noindent Syntax:
\#do lvar = i1,i2
\#do lvar = i1,i2,i3
\#do lvar = $\{$string1$|$...$|$stringn$\}$
\#do lvar = $\{$string1,...,stringn$\}$
\#do lvar = nameofexpression
\noindent See also enddo (\ref{preenddo})
\noindent The \#do\index{\#do} instruction\index{do loop} needs a matching
\#enddo\index{\#enddo} instruction. All code in-between these two
instructions will be read as many times as indicated in the parameter field
of the \#do instruction. The parameter lvar is a preprocessor variable of
which the value is determined by the other parameters. Inside the loop it
should be referred to by enclosing its name between a backquote/quote pair
as is usual for preprocessor variables. The various possible parameter
fields have the following meaning:
\begin{description}
\item[\#do lvar = i1,i2] The parameters i1 and i2 should be integers or
names of dollar expressions that evaluate into integers. The
first time in the loop lvar will get the value of i1 (as a string) and each
next time its value will be one greater (translated into a string again).
The last time in the loop the value of lvar will be the greatest integer
that is less or equal to i2. If i2 is less than i1, the loop is skipped
completely. If i2 is the name of a dollar variable, each time the control
reaches the end of the loop the dollar variable is evaluated and the
current value is used.
\item[\#do lvar = i1,i2,i3] The parameters i1,i2 and i3 should be integers
or names of dollar expressions that evaluate into integers.
The first time in the loop lvar will get the value of i1 (as a string) and
each next time its value will be incremented by adding i3 (translated into
a string again). If i3 is positive, the last value of lvar will be the one
for which lvar+i3 is greater than i2. If i2 is less than i1, the loop is
skipped completely. If i3 is negative the last value of lvar will be the
one for which lvar+i3 is less than i2. If i3 is zero there will be an
error. If i2 or i3 are the names of a dollar variable, each time the control
reaches the end of the loop the dollar variable(s) is/are evaluated and the
current value is used.
\item[\#do lvar = $\{$string1$|$...$|$stringn$\}$] The first time in the
loop the value of lvar is the string indicated by string1, the next time
will be string2 etc till the last time when it will be stringn. This is
called a listed\index{listed loop} loop\index{loop!listed}. The notation
with the $|$ is an old notation which is still accepted. The new notation
uses a comma instead.
\item[\#do lvar = $\{$string1,...,stringn$\}$] The first time in the loop
the value of lvar is the string indicated by string1, the next time will be
string2 etc till the last time when it will be stringn. This is called a
listed\index{listed loop} loop\index{loop!listed}.
\item[\#do lvar = expression] The loop variable will take one by one for
its value all the terms of the given expression. This is protected against
changing the expression inside the loop by making a copy of the expression
inside the memory. Hence one should be careful with very big expressions.
An expression that is zero gives a loop over zero terms, hence the loop is
never executed.
\end{description}
The first two types of \#do instructions are called
numerical\index{numerical loop} loops\index{loop!numerical}. In the
parameters of numerical loops the preprocessor calculator\index{calculator}
is invoked automatically. One should make sure not to use a leading $\{$
for the first numerical parameter in such a loop. This would be interpreted
as belonging to a listed loop.
After a loop has been finished, the corresponding preprocessor variable
will be undefined. This means that if there is a previous preprocessor
variable by the same name, the value of the \#do instruction will be used
inside the loop, and afterwards the old value will be active again.
It is allowed to overwrite the value of a preprocessor \#do instruction
variable. This can be very useful to create the equivalent of a repeat loop
that contains .sort instructions as in
\begin{verbatim}
#do i = 1,1
id,once,x = y+2;
if ( count(x,1) > 0 ) redefine i "0";
.sort
#enddo
\end{verbatim}
A few remarks are necessary here. The redefine\index{redefine} statement
(see section \ref{substaredefine}) should be before the last
.sort\index{.sort} inside the loop, because the \#do instruction is part of
the preprocessor. Hence the value of i is considered before the module is
executed. This means that if the redefine would be after the .sort, two
things would go wrong: First the loop would be terminated before the
redefine would ever make a chance of being executed. Second the statement
would be compiled in the expectation that there is a variable i, but then
the loop would be terminated. Afterwards, when the statement is being
executed it would refer to a variable that does not exist any longer.
If one wants to make a loop over the externals of the brackets of an
expression only, one needs to do some work. Assume we have the expression F
and we want to loop over the brackets in x and y:
\begin{verbatim}
L FF = F;
Bracket x,y;
.sort
CF acc,acc2;
Skip F;
Collect acc,acc2;
id acc(x?) = 1;
id acc2(x?)= 1;
B x,y;
.sort
Skip F;
Collect acc;
id acc(x?) = 1;
.sort
#do i = FF
L G = F[`i'];
.
.
#enddo
\end{verbatim}
Notice that we have to do the collect\index{collect} trick twice because
the first time the bracket could be too long for one term. The second time
that restriction doesn't exist because besides the x and the y there are
only integer coefficients.
%--#] do :
%--#[ else :
\section{\#else}
\label{preelse}
\noindent Syntax:
\#else
\noindent See also if (\ref{preif}),
endif (\ref{preendif}),
elseif (\ref{preelseif}),
ifdef (\ref{preifdef}),
ifndef (\ref{preifndef})
\noindent This instruction\index{\#else} is used inside a
\#if\index{\#if}/\#endif\index{\#endif} construction. The code that follows
it until the \#endif instruction will be read if the condition of the \#if
instruction (and of none of the corresponding \#elseif\index{\#elseif}
instructions) is not true. If any of these conditions is true, this code is
skipped. The reading is stopped after the matching \#endif is encountered
and continued after this matching \#endif instruction.
%--#] else :
%--#[ elseif :
\section{\#elseif}
\label{preelseif}
\noindent Syntax:
\#elseif ( condition )
\noindent See also if (\ref{preif}),
endif (\ref{preendif}),
else (\ref{preelse})
\noindent The syntax\index{\#elseif} of the condition is identical to the
syntax for the condition in the \#if\index{\#if} instruction. The \#elseif
instruction can occur between an \#if and an \#endif\index{\#endif}
instruction, before a possible matching \#else\index{\#else} instruction.
The code after this condition till the next \#elseif instruction, or till a
\#else instruction or till a \#endif instruction, whatever comes first,
will be read if the condition in the \#elseif instruction is true and none
of the conditions in matching previous \#if or \#elseif instructions were
true. The reading is stopped after the matching \#elseif/\#else/\#endif is
encountered and continued after the matching \#endif instruction.
Example
\begin{verbatim}
#if ( `i' == 2 )
some code
#elseif ( `i' == 3 )
more code
#elseif ( `j' >= "x2y" )
more code
#else
more code
#endif
\end{verbatim}
%--#] elseif :
%--#[ enddo :
\section{\#enddo}
\label{preenddo}
\noindent Syntax:
\#enddo
\noindent See also do (\ref{predo})
\noindent Used to\index{\#enddo} terminate\index{terminate} a preprocessor
do\index{do loop} loop. See the \#do\index{\#do} instruction.
%--#] enddo :
%--#[ endif :
\section{\#endif}
\label{preendif}
\noindent Syntax:
\#endif
\noindent See also if (\ref{preif}),
else (\ref{preelse}),
elseif (\ref{preelseif}),
ifdef (\ref{preifdef}),
ifndef (\ref{preifndef})
\noindent Used to terminate\index{\#endif} a \#if\index{\#if},
\#ifdef\index{\#ifdef} or \#ifndef\index{\#ifndef} construction.
Reading will continue after it.
%--#] endif :
%--#[ endinside :
\section{\#endinside}
\label{preendinside}
\noindent Syntax:
\#endinside
\noindent See also \#inside (\ref{preinside})
\noindent Used to\index{\#endinside} terminate a \#inside construction in
the preprocessor. For more details, see the \#inside\index{\#inside}
instruction.
%--#] endinside :
%--#[ endprocedure :
\section{\#endprocedure}
\label{preendprocedure}
\noindent Syntax:
\#endprocedure
\noindent See also procedure (\ref{preprocedure}), call
(\ref{precall})
\noindent Each procedure\index{procedure} must be terminated by an
\#endprocedure\index{\#endprocedure} instruction. If the procedure resides
in its own file, the \#endprocedure will cause the closing of the file.
Hence any text that is in the file after the \#endprocedure instruction
will be ignored.
When control reaches the \#endprocedure instruction, all (local)
preprocessor variables\index{variables!preprocessor} that were defined
inside the procedure and all parameters of the call of the procedure will
become undefined.
%--#] endprocedure :
%--#[ endswitch :
\section{\#endswitch}
\label{preendswitch}
\noindent Syntax:
\#endswitch
\noindent See also switch (\ref{preswitch}),
case (\ref{precase}),
break (\ref{prebreak}),
default (\ref{predefault})