1 2\chapter{The preprocessor} 3\label{preprocessor} 4 5%--#[ General : 6 7The preprocessor\index{preprocessor} is a program segment that reads and 8edits\index{edit} the input, after which the processed input is offered to 9the compiler\index{compiler} part of \FORM. When a module\index{module} 10instruction is encountered by the preprocessor, the compilation is halted 11and the module is executed. The compiler buffers are cleared and \FORM\ 12will continue with the next module. The preprocessor acts almost purely on 13character strings. As such it does not know about the algebraic properties 14of the objects it processes. Additionally the preprocessor also filters out 15the commentary\index{commentary}. 16 17The commands for the preprocessor are called instructions. Preprocessor 18instructions start with the character \# as the first non-blank character 19in a line. After this there are several possibilities. 20\begin{description} 21\item[\#:]\index{\#:} Special syntax for setup parameters at the beginning 22of the program. See the chapter on the setup parameters. 23\item[\#$-$, \#$+$]\index{\#$-$}\index{\#$+$} Turns the listing of the input off or 24on. 25\item[\#name]\index{\#name} Preprocessor command. The syntax of the various 26commands will be discussed below. 27\item[\#\$name]\index{\#\$name} Giving a value to a dollar variable in the 28preprocessor. See chapter \ref{dollars} on dollar variables. 29\end{description} 30 31%--#] General : 32%--#[ The preprocessor variables : 33 34\section{The preprocessor variables} 35\label{preprovariables} 36 37In order to help in the edit\index{edit} function the preprocessor is 38equipped with variables\index{preprocessor variables} that can be defined 39or redefined by the user or by other preprocessor actions. Preprocessor 40variables have regular names that are composed of strings of alphanumeric 41characters of which the first one must be alphabetic. When they are defined 42one just uses this name. When they are used the name should be enclosed 43between a backquote\index{backquote} and a quote\index{quote} as if these 44were some type of brackets. Hence `a2r' is the reference to a regular 45preprocessor variable. Preprocessor variables contain strings of 46characters. No interpretation is given to these strings. The 47backquote/quote pairs can be nested. Hence `a`i'r' will result in the 48preprocessor variable `i' to be substituted first. If this happens to be 49the string "2", the result after the first substitution would be `a2r' and 50then \FORM\ would look for its string value. 51 52The use of the backquotes is different from the earlier versions of \FORM. 53There the preprocessor variables would be enclosed in a pair of quotes and 54no nesting\index{nesting} was possible. \FORM\ still understands this old 55notation because it does not lead to ambiguities. The user is however 56strongly advised to use the new notation with the backquotes, because in 57future versions the old\index{old notation} notation may not be recognized 58any longer. 59 60\noindent \FORM\ has a number of built in preprocessor variables. They are: 61 62\begin{description} 63\item[VERSION\_] The current version\index{VERSION\_} as the \formmajorversion{} in 64 \formmajorversion.\formminorversion. 65\item[SUBVERSION\_] The sub-version\index{SUBVERSION\_} as the \formminorversion{} in 66 \formmajorversion.\formminorversion. 67\item[NAME\_] The name\index{NAME\_} of the program file. 68\item[DATE\_] The date\index{DATE\_} of the current run. 69\item[CMODULE\_] The number\index{CMODULE\_} of the current module. 70\item[SHOWINPUT\_] If input listing\index{SHOWINPUT\_} is on: 1, if off: 0. 71\item[EXTRASYMBOLS\_] The current number of extra symbols\index{EXTRASYMBOLS\_} 72 (see \ref{substaextrasymbols}). 73\item[OLDNUMEXTRASYMBOLS\_] The number of extra symbols\index{OLDNUMEXTRASYMBOLS\_} 74 before the current optimization started (see chapter \ref{optimization}). 75\item[OPTIMMINVAR\_] The number of the first extra symbol\index{OPTIMMINVAR\_} needed 76 for the current optimization (see chapter \ref{optimization}). 77\item[OPTIMMAXVAR\_] The number of the last extra symbol\index{OPTIMMAXVAR\_} needed 78 for the current optimization (see chapter \ref{optimization}). 79\item[OPTIMSCHEME\_] The best Horner scheme\index{OPTIMSCHEME\_} found 80 for the current optimization (see chapter~\ref{optimization}). 81\item[OPTIMVALUE\_] The number of arithmetic operations\index{OPTIMVALUE\_} 82 in the resulting expression for the current optimization 83 (see chapter~\ref{optimization}). 84\item[PID\_] The process identifier (PID) \index{PID} \index{PID\_} of 85 the running process. In \ParFORM{} (\ref{parform}), it represents 86 the PID of the master process in order to ensure that all the 87 processes in a job use the same number. A recovered session from 88 a checkpoint (\ref{checkpoints}) keeps using the PID of the 89 crushed session. 90\item[STOPWATCH\_] Same as `TIMER\_'. 91\item[TIME\_] The running time\index{time\_} till the moment of call in the string format 92 with a decimal point and two digits after the decimal point. 93 This is the same format as in the statistics. 94\item[TIMER\_] The running time\index{timer\_} since the last reset in milliseconds. Hence, 95 unlike `time\_' this value can be used in the preprocessor 96 calculator and in numerical compares in \#if instructions. 97 See also the \#reset (see \ref{prereset}) instruction. 98\item[NUMACTIVEEXPRS\_] The number of the current active expressions. 99\item[ACTIVEEXPRNAMES\_] The list of the current active expression names 100 separated by commas. This can be passed to \#do lvar=\{...\} 101 instruction~(\ref{predo}) like: 102\begin{verbatim} 103 #do e = {`activeexprnames_'} 104 #ifdef `e' 105 Local `e' = `e' + something; 106 #endif 107 #enddo 108\end{verbatim} 109\end{description} 110 111\noindent If \FORM\ cannot find a preprocessor variable, because it has 112neither been defined by the user, nor is it one of the built in variables, 113it will look in the systems environment\index{environment} to see whether 114there is an environment variable by that name. If this is the case its 115string value will be substituted. 116 117\noindent Preprocessor variables can have arguments and thereby become 118macro's. One should consult the description of the \#define~\ref{predefine} 119instruction about the delayed substitution feature to avoid the value of 120the preprocessor variables in the macro would be substituted immediately 121during the definition. Hence proper use is 122\begin{verbatim} 123 #define EXCHANGE(x,y) "Multiply replace_(`~x',`~y',`~y',`~x');" 124\end{verbatim} 125 126\noindent \FORM{} has the following built in macro's: 127\begin{description} 128\item[TOLOWER\_(string)] in which the character string in the argument is 129converted to lower case. After this it will become input. 130\item[TOUPPER\_(string)] in which the character string in the argument is 131converted to upper case. After this it will become input. 132\end{description} 133It is anticipated that some more macro's will become available to allow for 134the editing of names of variables. 135 136%--#] The preprocessor variables : 137%--#[ Calculator : 138\section{The preprocessor calculator} 139\label{calculator} 140 141Sometimes a preprocessor\index{preprocessor variable!numeric} variable 142should be interpreted as a number and some arithmetic\index{arithmetic} 143should be done with it. For this \FORM\ is equipped with what is called the 144preprocessor calculator\index{calculator}. When the input reading device 145encounters a left curly\index{curly bracket} bracket\index{bracket!curly} 146\verb:{:, it will read till the matching right curly bracket \verb:}: and 147then test whether the characters (after substitution of preprocessor 148variables) can be interpreted as a numerical expression. If it is not a 149valid numerical expression the whole string, including the curly brackets, 150will be passed on to the later stages of the program. If it is a numerical 151expression, it will be evaluated, and the whole string, including the curly 152brackets, will be replaced by a textual representation of the result. 153Example: 154\begin{verbatim} 155 Local F`i' = F{`i'-1}+F{`i'-2}; 156\end{verbatim} 157If the preprocessor variable i has the value 11, the calculator makes this 158into 159\begin{verbatim} 160 Local F11 = F10+F9; 161\end{verbatim} 162Valid numerical expressions can contain the characters 163\begin{verbatim} 164 0 1 2 3 4 5 6 7 8 9 + - * / % ( ) { } & | ^ ! 165\end{verbatim} 166The use of parentheses is as in regular arithmetic. The curly 167brackets fulfil the same role, as one can nest these brackets of course. 168Operators are: 169\begin{description} 170\item[$+$] Regular addition\index{addition}. 171\item[$-$] Regular subtraction\index{subtraction}. 172\item[$\ast$] Regular multiplication\index{multiplication}. 173\item[$/$] Regular (integer) division\index{division}. 174\item[$\%$] The remainder\index{remainder} after (integer) division as in 175the language C\index{C}. 176\item[$\&$] And\index{and} operator. This is a bitwise operator. 177\item[$|$] Or\index{or} operator. This is a bitwise or. 178\item[$\wedge$] Exponent\index{exponent} operator. 179\item[$!$] Factorial\index{factorial}. This is a postfix operator. 180\item[$\wedge\%$] A postfix ${}^2\!\log$. This means that it 181takes\index{twolog} the ${}^2\!\log$ of the object to the left of it. 182\item[$\wedge/$] A postfix square\index{square root} root. This means that 183it takes the square root of the object to the left of it. 184\end{description} 185Note that all arithmetic\index{arithmetic} is done over the integers and 186that there is a finite range. On 32\index{32 bits} bit systems this range 187will be $2^{31}-1$ to $-2^{31}$, while on 64\index{64 bits} bit systems 188this will be $2^{63}-1$ to $-2^{63}$. In particular this means that 189\verb:{13^/}: becomes \verb:3:. The preprocessor calculator is only meant 190for some simple counting and organization of the program flow. Hence there 191is no large degree of sophistication. Very important is that the 192comma\index{comma} character is not a legal character for the preprocessor 193calculator. This can be used to avoid some problems. Suppose one needs to 194make a substitution of the type: 195\begin{verbatim} 196 id f(x?!{0}) = 1/x; 197\end{verbatim} 198in which the value zero should be excluded from the pattern matching (see 199dynamical\index{set!dynamical} sets in chapter \ref{pattern} on pattern 200matching). This would not work, because the preprocessor would make this 201into 202\begin{verbatim} 203 id f(x?!0) = 1/x; 204\end{verbatim} 205which is illegal syntax. Hence the proper trick is to write 206\begin{verbatim} 207 id f(x?!{,0}) = 1/x; 208\end{verbatim} 209With the comma the preprocessor will leave this untouched, and hence now 210the set is passed properly. 211 212Good use of the preprocessor calculator can make life much easier for 213\FORM. For example the following statements 214\begin{verbatim} 215 id f(`i') = 1/(`i'+1); 216 id f(`i') = 1/{`i'+1}; 217\end{verbatim} 218are quite different in nature. In the first statement the compiler gets an 219expression with a composite denominator. The compiler never tries to 220simplify expressions by doing algebra on them. Sometimes this may not be 221optimal, but there are cases in which it would cause wrong results (in 222particular when noncommuting and commuting functions are mixed and 223wildcards are used). Hence the composite denominator has to be worked out 224during run time for each term separately. The second statement has the 225preprocessor work out the sum and hence the compiler gets a simple fraction 226and less time will be needed during running. Note that 227\begin{verbatim} 228 id f(`i') = {1/(`i'+1)}; 229\end{verbatim} 230would most likely not produce the desired result, because the preprocessor 231calculator works only over the integers. Hence, unless i is equal to zero 232or -2, the result would be zero (excluding of course the fatal error when i 233is equal to -1). 234 235%--#] Calculator : 236%--#[ ... : 237\section{The triple dot operator} 238\label{tripledot} 239 240The last\index{...} stage of the actions of the preprocessor involves the 241triple dot operator. It indicates a repeated pattern as in \verb:a1+...+a4: 242which would expand into \verb:a1+a2+a3+a4:. This operator is used in two 243different ways. First the most general way: 244\begin{verbatim} 245 <pattern1>operator1...operator2<pattern2> 246\end{verbatim} 247in which the less\index{less than} than and greater\index{greater than} 248than signs serve as boundaries for the patterns. The operators can be any 249pair of the following: 250\begin{description} 251\item[+\ +]\index{+...+} Repetitions will be separated by plus signs. 252\item[--\ --]\index{-...-} Repetitions will be separated by minus signs. 253\item[+\ --]\index{+...-} Repetitions will be separated by alternating signs. 254First will be plus. 255\item[--\ +]\index{-...+} Repetitions will be separated by alternating signs. 256First will be minus. 257\item[$\ast\ \ast$]\index{*...*} Repetitions will be separated by $\ast$. 258\item[/\ /]\index{/.../} Repetitions will be separated by /. 259\item[,\ ,]\index{,...,} Repetitions will be separated by comma's. 260\item[:\ :]\index{:...:} Repetitions will be separated by {\it single} dots. 261%\item[+\ +]\index{.@$+\cdots+$} Repetitions will be separated by plus signs. 262%\item[--\ --]\index{.@$-\cdots-$} Repetitions will be separated by minus signs. 263%\item[+\ --]\index{.@$+\cdots-$} Repetitions will be separated by alternating signs. 264%First will be plus. 265%\item[--\ +]\index{.@$-\cdots+$} Repetitions will be separated by alternating signs. 266%First will be minus. 267%\item[$\ast\ \ast$]\index{.@$\ast\cdots\ast$} Repetitions will be separated by $\ast$. 268%\item[/\ /]\index{.@$/\cdots/$} Repetitions will be separated by /. 269%\item[,\ ,]\index{.@$,\cdots,$} Repetitions will be separated by comma's. 270%\item[:\ :]\index{.@$:\cdots:$} Repetitions will be separated by {\it single} dots. 271\end{description} 272For such a pair of operators \FORM\ will inspect the patterns\index{pattern} 273and see whether the differences between the two patterns are just numbers. 274If the differences are numbers and the absolute value of the difference of 275each matching pair is always the same (a difference of zero is allowed too; 276it leads to no action for the pair), then \FORM\ will expand the pattern, 277running from the first to the last in increments of one. For each pair the 278counter can either run up or run down, depending on whether the number in 279the first pattern is greater or less than the number in the second pattern. 280Example: 281\begin{verbatim} 282 Local F = <a1b6(c3)>-...+<a4b3(c6)>; 283\end{verbatim} 284leads to 285\begin{verbatim} 286 Local F = a1b6(c3)-a2b5(c4)+a3b4(c5)-a4b3(c6); 287\end{verbatim} 288The second form is a bit simpler. It recognizes that there are special 289cases that can be written in a more intuitive way. If there is only a 290single number to be varied, and it is the end of the pattern, and the rest 291of the patterns consists only of alphanumeric characters of which the first 292is an alphabetic character, we do not need the less than/greater than 293combination. This is shown in 294\begin{verbatim} 295 Symbol a1,...,a12; 296\end{verbatim} 297There is one extra exception. The variables used this way may have a 298question mark after them to indicate that they are wildcards: 299\begin{verbatim} 300 id f(a1?,...,a4?) = g(a1,...,a4,a1+...+a4); 301\end{verbatim} 302This construction did not exist in earlier versions of \FORM\ (version 1 and 303version 2). There one needed the \#do\index{\#do} instruction for many of 304the above constructions, creating code that was very hard to read. The 305\verb:...: operator should improve the readability of the programs very 306much. 307 308%--#] ... : 309%--#[ add : 310 311\section{\#add} 312\label{preadd} 313 314\noindent Syntax: 315 316\#add object: "string" 317 318\noindent See chapter \ref{dictionaries} on dictionaries. 319 320\noindent Adds words to an open dictionary. 321 322%--#] add : 323%--#[ addseparator : 324 325\section{\#addseparator} 326\label{preaddseparator} 327 328\noindent Syntax: 329 330\#addseparator character 331 332\noindent See also \#rmseparator (\ref{prermseparator}), 333 \#call (\ref{precall}), \#do (\ref{predo}) 334 335\noindent Adds a character\index{\#addseparator} to the list of permissible 336separator characters for arguments of \#call or \#do instructions. By 337default the two characters that are permitted are the comma and the 338character \verb:|:. Blanks, tabs and double quotes are ignored. Note that 339the comma must be specified between double quotes as in 340\begin{verbatim} 341 #addseparator "," 342\end{verbatim} 343 344 345%--#] addseparator : 346%--#[ append : 347 348\section{\#append} 349\label{preappend} 350 351\noindent Syntax: 352 353\#append $<$filename$>$ 354 355\noindent See also write (\ref{prewrite}), 356 close (\ref{preclose}), create (\ref{precreate}), 357 remove (\ref{preremove}) 358 359\noindent Opens\index{\#append} the named file for writing. The file will 360be positioned at the end. The next \#write\index{\#write} instruction will 361add to it. 362 363%--#] append : 364%--#[ appendpath : 365 366\section{\#appendpath} 367\label{preappendpath} 368 369\noindent Syntax: 370 371\#appendpath pathname 372 373\noindent See also prependpath~(\ref{preprependpath}) 374 375\noindent Appends the given path relative to the current file to the end of 376the FORM path\index{path}. 377 378%--#] appendpath : 379%--#[ break : 380 381\section{\#break} 382\label{prebreak} 383 384\noindent Syntax: 385 386\#break 387 388\noindent See also switch (\ref{preswitch}), 389 endswitch (\ref{preendswitch}), 390 case (\ref{precase}), 391 default (\ref{predefault}) 392 393\noindent If the\index{\#break} lines before were not part of the control 394flow ({\it i.e.} these lines are used for the later stages of the program), 395this instruction is ignored. If they are part of the control flow, the flow 396will continue after the matching \#endswitch\index{\#endswitch} 397instruction. The \#break instruction must of course be inside the range of 398a \#switch\index{\#switch}/\#endswitch construction. 399 400%--#] break : 401%--#[ breakdo : 402 403\section{\#breakdo} 404\label{prebreakdo} 405 406\noindent Syntax: 407 408\#breakdo [{\tt<}number{\tt>}] 409 410\noindent See also \#do (\ref{predo}) and \#enddo (\ref{preenddo}) 411 412\noindent The \#breakdo\index{\#breakdo} instruction allows one to jump out 413of a \#do loop. If a (nonzero integer) number is specified it indicates the 414number of loops the program should terminate. Control will continue after 415the \#enddo instruction of the number of loops indicated by `number'. 416The default value is one. If the value is zero the statement has no effect. 417 418%--#] breakdo : 419%--#[ call : 420 421\section{\#call} 422\label{precall} 423 424\noindent Syntax: 425 426\#call procname(var1,...,varn) 427 428\noindent See also procedure (\ref{preprocedure}), endprocedure 429(\ref{preendprocedure}) 430 431\noindent This instruction\index{\#call} calls the 432procedure\index{procedure} with the name procname. The result is that \FORM\ 433looks for this procedure, first in its procedure 434buffers\index{buffer!procedure} (for procedures that were defined in the 435regular text stream as explained under the \#procedure\index{\#procedure} 436instruction), then it looks for a file by the name procname.prc in the 437current directory, and if it still has not found the procedure, it looks in 438the directories indicated by the path\index{path} variable in either the setup 439file or at the start of the program (see chapter \ref{setup} on the setup 440file). Next it looks for the -p option in the command that started \FORM\ 441(see the chapter on running \FORM). If this -p option has not been used \FORM\ 442will see whether there is an environment variable by the name 443FORMPATH\index{FORMPATH}. The directories indicated there will be searched 444for the file procname.prc. If \FORM\ cannot find the file, there will be an 445error message and execution will be stopped immediately. 446 447Once the procedure has been located, \FORM\ reads the whole file and then 448determines whether the number of parameters is identical in the 449\#call\index{\#call} instruction and the \#procedure\index{\#procedure} 450instruction. A difference is a fatal error. 451 452The parameter field consists of strings, separated by commas. If a string 453contains a comma, this comma should be preceded by a 454backslash\index{backslash} character (\verb:\:). If a string should contain 455a linefeed\index{linefeed}, one should `escape' this linefeed by putting a 456backslash and continue on the next line. 457 458Before version 3 of \FORM\ the syntax was different. The parentheses 459were curly brackets and the separators the symbol \verb:|:. This was made 460to facilitate the use of strings that might contain commas. In practise 461however, this turned out to be far from handy. In addition the new 462preprocessor calculator is a bit more active and hence an instruction of 463the type 464\begin{verbatim} 465 #call test{1} 466\end{verbatim} 467will now be intercepted by the preprocessor calculator\index{calculator} 468and changed into 469\begin{verbatim} 470 #call test1 471\end{verbatim} 472Because there are many advantages to the preprocessor calculator treating 473the parameters of the procedures before they are called (in the older 474versions it did not do this), the notation has been changed. \FORM\ still 475understands the old notation, provided that there is no conflict with the 476preprocessor calculator. Hence 477\begin{verbatim} 478 #call test{1|a} 479 #call test{1,a} 480 #call test(1|a) 481 #call test(1,a) 482\end{verbatim} 483are all legal and give the same result, but only the last notation will 484work in future versions of \FORM. 485 486Nowadays also the use of the argument field wildcard (see chapter 487\ref{pattern} on pattern matching) is allowed as in the 488regular functions: 489% THIS EXAMPLE IS PART OF THE TESTSUITE. CHANGES HERE SHOULD BE APPLIED THERE AS 490% WELL! 491\begin{verbatim} 492 #define a "1" 493 #define bc2 "x" 494 #define bc3 "y" 495 #define b "c`~a'" 496 #procedure hop(c,?d); 497 #redefine a "3" 498 #message This is the call: `c',`?d' 499 #endprocedure 500 501 #redefine a "2" 502 #message This is b: `b' 503~~~This is b: c2 504 505 #call hop(`b`!b''`!b'`b'`!b'`b',`~a',`b',`a') 506~~~This is the call: xc2c3c2c3,3,c3,2 507 508 .end 509\end{verbatim} 510We also see here that the rules about delayed substitution (see also the 511\#define\index{\#define} instruction in section \ref{predefine}) apply. The 512use of `!b' cancels the delayed substitution that is asked for in the 513definition of b. 514 515The default extension for procedure files is .prc\index{.prc}, but it is 516possible to change this. There are two different ways: One is with the 517\#procedureExtension\index{\#procedureExtension} instruction in section 518\ref{preprocedureextension}. The other is via the setup (see the chapter on 519the setup file, chapter \ref{setup}). 520 521%--#] call : 522%--#[ case : 523 524\section{\#case} 525\label{precase} 526 527\noindent Syntax: 528 529\#case string 530 531\noindent See also switch (\ref{preswitch}), 532 endswitch (\ref{preendswitch}), 533 break (\ref{prebreak}), 534 default (\ref{predefault}) 535 536\noindent The lines after the \#case\index{\#case} instruction will be used 537if either this is the first \#case\index{\#case} instruction of which the 538string matches the string in the \#switch\index{\#switch} instruction, or 539the control flow was already using the lines before this \#case instruction 540and there was no \#break\index{\#break} instruction (this is called 541fall-through). The control flow will include lines either until the next 542matching \#break instruction, or until the matching 543\#endswitch\index{\#endswitch} instruction. 544 545%--#] case : 546%--#[ clearoptimize : 547 548\section{\#clearoptimize} 549\label{preclearoptimize} 550 551\noindent Syntax: 552 553\#clearoptimize 554 555See the chapter about optimization \ref{optimization} 556 557%--#] clearoptimize : 558%--#[ close : 559 560\section{\#close} 561\label{preclose} 562 563\noindent Syntax: 564 565\#close $<$filename$>$ 566 567\noindent See also write (\ref{prewrite}), append (\ref{preappend}), 568 create (\ref{precreate}), remove (\ref{preremove}) 569 570\noindent This instruction closes\index{\#close} the file\index{file!close} 571by the given name, if such a file had been opened by the previous 572\#write\index{\#write} instruction. Normally \FORM\ closes all such files at 573the end of execution. Hence the user would not have to worry about this. 574The use of a subsequent \#write instruction with the same file name will 575remove the old contents and hence start basically a new file. There are 576times that this is useful. 577 578%--#] close : 579%--#[ closedictionary : 580 581\section{\#closedictionary} 582\label{preclosedictionary} 583 584\noindent Syntax: 585 586\#closedictionary 587 588\noindent See chapter \ref{dictionaries} on dictionaries. 589 590\noindent Either closes an open dictionary (\ref{preopendictionary}) or stops 591using the dictionary (\ref{preusedictionary}) that is currently used for output 592translation. 593 594%--#] closedictionary : 595%--#[ commentchar : 596 597\section{\#commentchar} 598\label{precommentchar} 599 600\noindent Syntax: 601 602\#commentchar character 603 604\noindent The specified\index{\#commentchar} character should be a single 605non-whitespace character. There may be white space (blanks and/or tabs) 606before or after it. The character will take over the role of the comment 607character. {\it i.e.} any line that starts with this character in column 1 608will be considered commentary\index{commentary}. This feature was provided 609because output of some other algebra programs could put the multiplication 610sign in column 1 in longer expressions. 611 612The default commentary character is $\ast$. 613 614%--#] commentchar : 615%--#[ create : 616 617\section{\#create} 618\label{precreate} 619 620\noindent Syntax: 621 622\#append $<$filename$>$ 623 624\noindent See also write (\ref{prewrite}), 625 close (\ref{preclose}), append (\ref{preappend}), 626 remove (\ref{preremove}) 627 628\noindent Opens the named\index{\#create} file for writing. If the file 629existed already, its previous contents will be lost. The next 630\#write\index{\#write} instruction will add to it. In principle this 631instruction is not needed, because the \#write instruction would create the 632file if it had not been opened yet at the moment of writing. 633 634%--#] create : 635%--#[ default : 636 637\section{\#default} 638\label{predefault} 639 640\noindent Syntax: 641 642\#default 643 644\noindent See also switch (\ref{preswitch}), 645 endswitch (\ref{preendswitch}), 646 case (\ref{precase}), 647 break (\ref{prebreak}) 648 649\noindent Control\index{\#default} flow continues after this instruction if 650there is no \#case\index{\#case} instruction of which the string matches 651the string in the \#switch\index{\#switch} instruction. Control flow also 652continues after this instruction, if the lines before were included and 653there was no \#break\index{\#break} instruction to stop the control flow 654(fall-through). Control flow will stop either when a matching \#break 655instruction is reached, or when a matching \#endswitch\index{\#endswitch} 656is encountered. In the last case of course control flow will continue after 657the \#endswitch instruction. 658 659%--#] default : 660%--#[ define : 661 662\section{\#define} 663\label{predefine} 664 665\noindent Syntax: 666 667\#define name "string" 668 669\noindent See also redefine (\ref{preredefine}), undefine 670(\ref{preundefine}) 671 672\noindent in which name\index{\#define} refers to the name of the 673preprocessor\index{preprocessor variable} 674variable\index{variable!preprocessor} to be defined and the contents of the 675string will form the value of the variable. The double quotes are mandatory 676delimiters of the string. 677 678The use of the \#define\index{\#define} instruction creates a new instance 679of the preprocessor variable with the given name. This means that the old 680instance\index{instance} remains. If for some reason the later instance 681becomes undefined (see for instance \#undefine), the older instance will be 682the one that is active. If the old definition is to be overwritten, one 683should use the \#redefine\index{\#redefine} instruction. 684 685As of version 3.2 preprocessor variables can also have arguments as in the 686C\index{C} language. Hence 687 688\#define var(a,b) "(`\verb:~:a'+`\verb:~:b'+`c')" 689 690is allowed. The parameters should be referred to inside a pair of `' as 691with all preprocessor variables. A special feature is the socalled 692delayed\index{delayed substitution} 693substitution\index{substitution!delayed}. With macro's like the above the 694question is always {\sl when} a preprocessor variable will be substituted. 695Take for instance 696% THIS EXAMPLE IS PART OF THE TESTSUITE. CHANGES HERE SHOULD BE APPLIED THERE AS 697% WELL! 698\begin{verbatim} 699 #define c "3" 700 #define var1(a,b) "(`~a'+`~b'+`c')" 701 #define var2(a,b) "(`~a'+`~b'+`~c')" 702 #redefine c "4" 703 Local F1 = `var1(1,2)'; 704 Local F2 = `var2(1,2)'; 705 Print; 706 .end 707 708 F1 = 709 6; 710 711 F2 = 712 7; 713\end{verbatim} 714The parameter c will be substituted immediately when var1 is defined. In 715var2 it will be only substituted when var2 is used. It should be clear that 716a and b should also be used in the delayed fashion because they do not 717exist yet at the moment of the definition of var1 and var2. Notice also 718that the whole macro\index{macro}, with its arguments should be placed 719between the backquote and the quote. Another example can be found with the 720\#call\index{\#call} instruction. See section \ref{precall} 721 722%--#] define : 723%--#[ do : 724 725\section{\#do} 726\label{predo} 727 728\noindent Syntax: 729 730\#do lvar = i1,i2 731 732\#do lvar = i1,i2,i3 733 734\#do lvar = $\{$string1$|$...$|$stringn$\}$ 735 736\#do lvar = $\{$string1,...,stringn$\}$ 737 738\#do lvar = nameofexpression 739 740\noindent See also enddo (\ref{preenddo}) 741 742\noindent The \#do\index{\#do} instruction\index{do loop} needs a matching 743\#enddo\index{\#enddo} instruction. All code in-between these two 744instructions will be read as many times as indicated in the parameter field 745of the \#do instruction. The parameter lvar is a preprocessor variable of 746which the value is determined by the other parameters. Inside the loop it 747should be referred to by enclosing its name between a backquote/quote pair 748as is usual for preprocessor variables. The various possible parameter 749fields have the following meaning: 750\begin{description} 751\item[\#do lvar = i1,i2] The parameters i1 and i2 should be integers or 752names of dollar expressions that evaluate into integers. The 753first time in the loop lvar will get the value of i1 (as a string) and each 754next time its value will be one greater (translated into a string again). 755The last time in the loop the value of lvar will be the greatest integer 756that is less or equal to i2. If i2 is less than i1, the loop is skipped 757completely. If i2 is the name of a dollar variable, each time the control 758reaches the end of the loop the dollar variable is evaluated and the 759current value is used. 760\item[\#do lvar = i1,i2,i3] The parameters i1,i2 and i3 should be integers 761or names of dollar expressions that evaluate into integers. 762The first time in the loop lvar will get the value of i1 (as a string) and 763each next time its value will be incremented by adding i3 (translated into 764a string again). If i3 is positive, the last value of lvar will be the one 765for which lvar+i3 is greater than i2. If i2 is less than i1, the loop is 766skipped completely. If i3 is negative the last value of lvar will be the 767one for which lvar+i3 is less than i2. If i3 is zero there will be an 768error. If i2 or i3 are the names of a dollar variable, each time the control 769reaches the end of the loop the dollar variable(s) is/are evaluated and the 770current value is used. 771\item[\#do lvar = $\{$string1$|$...$|$stringn$\}$] The first time in the 772loop the value of lvar is the string indicated by string1, the next time 773will be string2 etc till the last time when it will be stringn. This is 774called a listed\index{listed loop} loop\index{loop!listed}. The notation 775with the $|$ is an old notation which is still accepted. The new notation 776uses a comma instead. 777\item[\#do lvar = $\{$string1,...,stringn$\}$] The first time in the loop 778the value of lvar is the string indicated by string1, the next time will be 779string2 etc till the last time when it will be stringn. This is called a 780listed\index{listed loop} loop\index{loop!listed}. 781\item[\#do lvar = expression] The loop variable will take one by one for 782its value all the terms of the given expression. This is protected against 783changing the expression inside the loop by making a copy of the expression 784inside the memory. Hence one should be careful with very big expressions. 785An expression that is zero gives a loop over zero terms, hence the loop is 786never executed. 787\end{description} 788The first two types of \#do instructions are called 789numerical\index{numerical loop} loops\index{loop!numerical}. In the 790parameters of numerical loops the preprocessor calculator\index{calculator} 791is invoked automatically. One should make sure not to use a leading $\{$ 792for the first numerical parameter in such a loop. This would be interpreted 793as belonging to a listed loop. 794 795After a loop has been finished, the corresponding preprocessor variable 796will be undefined. This means that if there is a previous preprocessor 797variable by the same name, the value of the \#do instruction will be used 798inside the loop, and afterwards the old value will be active again. 799 800It is allowed to overwrite the value of a preprocessor \#do instruction 801variable. This can be very useful to create the equivalent of a repeat loop 802that contains .sort instructions as in 803\begin{verbatim} 804 #do i = 1,1 805 id,once,x = y+2; 806 if ( count(x,1) > 0 ) redefine i "0"; 807 .sort 808 #enddo 809\end{verbatim} 810A few remarks are necessary here. The redefine\index{redefine} statement 811(see section \ref{substaredefine}) should be before the last 812.sort\index{.sort} inside the loop, because the \#do instruction is part of 813the preprocessor. Hence the value of i is considered before the module is 814executed. This means that if the redefine would be after the .sort, two 815things would go wrong: First the loop would be terminated before the 816redefine would ever make a chance of being executed. Second the statement 817would be compiled in the expectation that there is a variable i, but then 818the loop would be terminated. Afterwards, when the statement is being 819executed it would refer to a variable that does not exist any longer. 820 821If one wants to make a loop over the externals of the brackets of an 822expression only, one needs to do some work. Assume we have the expression F 823and we want to loop over the brackets in x and y: 824\begin{verbatim} 825 L FF = F; 826 Bracket x,y; 827 .sort 828 CF acc,acc2; 829 Skip F; 830 Collect acc,acc2; 831 id acc(x?) = 1; 832 id acc2(x?)= 1; 833 B x,y; 834 .sort 835 Skip F; 836 Collect acc; 837 id acc(x?) = 1; 838 .sort 839 #do i = FF 840 L G = F[`i']; 841 . 842 . 843 #enddo 844\end{verbatim} 845Notice that we have to do the collect\index{collect} trick twice because 846the first time the bracket could be too long for one term. The second time 847that restriction doesn't exist because besides the x and the y there are 848only integer coefficients. 849 850%--#] do : 851%--#[ else : 852 853\section{\#else} 854\label{preelse} 855 856\noindent Syntax: 857 858\#else 859 860\noindent See also if (\ref{preif}), 861 endif (\ref{preendif}), 862 elseif (\ref{preelseif}), 863 ifdef (\ref{preifdef}), 864 ifndef (\ref{preifndef}) 865 866\noindent This instruction\index{\#else} is used inside a 867\#if\index{\#if}/\#endif\index{\#endif} construction. The code that follows 868it until the \#endif instruction will be read if the condition of the \#if 869instruction (and of none of the corresponding \#elseif\index{\#elseif} 870instructions) is not true. If any of these conditions is true, this code is 871skipped. The reading is stopped after the matching \#endif is encountered 872and continued after this matching \#endif instruction. 873 874%--#] else : 875%--#[ elseif : 876 877\section{\#elseif} 878\label{preelseif} 879 880\noindent Syntax: 881 882\#elseif ( condition ) 883 884\noindent See also if (\ref{preif}), 885 endif (\ref{preendif}), 886 else (\ref{preelse}) 887 888\noindent The syntax\index{\#elseif} of the condition is identical to the 889syntax for the condition in the \#if\index{\#if} instruction. The \#elseif 890instruction can occur between an \#if and an \#endif\index{\#endif} 891instruction, before a possible matching \#else\index{\#else} instruction. 892The code after this condition till the next \#elseif instruction, or till a 893\#else instruction or till a \#endif instruction, whatever comes first, 894will be read if the condition in the \#elseif instruction is true and none 895of the conditions in matching previous \#if or \#elseif instructions were 896true. The reading is stopped after the matching \#elseif/\#else/\#endif is 897encountered and continued after the matching \#endif instruction. 898 899Example 900\begin{verbatim} 901 #if ( `i' == 2 ) 902 some code 903 #elseif ( `i' == 3 ) 904 more code 905 #elseif ( `j' >= "x2y" ) 906 more code 907 #else 908 more code 909 #endif 910\end{verbatim} 911 912%--#] elseif : 913%--#[ enddo : 914 915\section{\#enddo} 916\label{preenddo} 917 918\noindent Syntax: 919 920\#enddo 921 922\noindent See also do (\ref{predo}) 923 924\noindent Used to\index{\#enddo} terminate\index{terminate} a preprocessor 925do\index{do loop} loop. See the \#do\index{\#do} instruction. 926 927%--#] enddo : 928%--#[ endif : 929 930\section{\#endif} 931\label{preendif} 932 933\noindent Syntax: 934 935\#endif 936 937\noindent See also if (\ref{preif}), 938 else (\ref{preelse}), 939 elseif (\ref{preelseif}), 940 ifdef (\ref{preifdef}), 941 ifndef (\ref{preifndef}) 942 943\noindent Used to terminate\index{\#endif} a \#if\index{\#if}, 944\#ifdef\index{\#ifdef} or \#ifndef\index{\#ifndef} construction. 945Reading will continue after it. 946 947%--#] endif : 948%--#[ endinside : 949 950\section{\#endinside} 951\label{preendinside} 952 953\noindent Syntax: 954 955\#endinside 956 957\noindent See also \#inside (\ref{preinside}) 958 959\noindent Used to\index{\#endinside} terminate a \#inside construction in 960the preprocessor. For more details, see the \#inside\index{\#inside} 961instruction. 962 963%--#] endinside : 964%--#[ endprocedure : 965 966\section{\#endprocedure} 967\label{preendprocedure} 968 969\noindent Syntax: 970 971\#endprocedure 972 973\noindent See also procedure (\ref{preprocedure}), call 974(\ref{precall}) 975 976\noindent Each procedure\index{procedure} must be terminated by an 977\#endprocedure\index{\#endprocedure} instruction. If the procedure resides 978in its own file, the \#endprocedure will cause the closing of the file. 979Hence any text that is in the file after the \#endprocedure instruction 980will be ignored. 981 982When control reaches the \#endprocedure instruction, all (local) 983preprocessor variables\index{variables!preprocessor} that were defined 984inside the procedure and all parameters of the call of the procedure will 985become undefined. 986 987%--#] endprocedure : 988%--#[ endswitch : 989 990\section{\#endswitch} 991\label{preendswitch} 992 993\noindent Syntax: 994 995\#endswitch 996 997\noindent See also switch (\ref{preswitch}), 998 case (\ref{precase}), 999 break (\ref{prebreak}), 1000 default (\ref{predefault}) 1001 1002\noindent This instruction marks the end\index{\#endswitch} of a 1003\#switch\index{\#switch} construction. After none or one of the cases of 1004the \#switch construction has been included in the control flow, reading 1005will continue after the matching \#endswitch instruction. Each \#switch 1006needs a \#endswitch, unless a .end instruction is encountered first. 1007 1008%--#] endswitch : 1009%--#[ exchange : 1010 1011\section{\#exchange} 1012\label{preexchange} 1013 1014\noindent Syntax: 1015 1016\#exchange expr1,expr2 1017 1018\#exchange \$var1,\$var2 1019 1020\noindent Exchanges\index{\#exchange} the names of two 1021expressions\index{expression}. This means that the contents of the 1022expressions remain where they are. Hence the order in which the expressions 1023are processed remains the same, but the name under which one has to refer 1024to them has been changed. 1025 1026In the variety with the dollar variables\index{\$-variable} the contents of 1027the variables are exchanged. This is not much work, because dollar 1028variables reside in memory and hence only two pointers to the contents have 1029to be exchanged (and some extra information about the contents). 1030 1031This instruction can be very useful when sorting expressions or dollar 1032variables by their contents. 1033 1034%--#] exchange : 1035%--#[ external : 1036 1037\section{\#external} 1038\label{preexternal} 1039 1040\noindent Syntax: 1041 1042\#external ["prevar"] systemcommand 1043 1044\noindent Starts the command\index{\#external} in the background, 1045connecting to its standard\index{standard output}\index{standard input} 1046input\index{input!standard} and output\index{output!standard}. By default, 1047the \#external command has no controlling terminal, the standard error stream 1048is redirected to \verb|/dev/null| and the command is run in a subshell in a 1049new session and in a new process group (see the preprocessor instruction 1050\verb|#setexternalattr|). 1051 1052The optional parameter ``prevar'' is the name of a preprocessor variable 1053placed between double quotes. If it is present, the ``descriptor'' (small 1054positive integer number) of the external command is stored into this 1055variable and can be used for references to this external command (if there 1056is more than one external command running simultaneously). 1057 1058The external command that is started last becomes the ``current'' (active) 1059external command. All further instructions 1060\#fromexternal\index{\#fromexternal} and \#toexternal\index{\#toexternal} 1061deal with the current external command. 1062 1063%--#] external : 1064%--#[ factdollar : 1065 1066\section{\#factdollar} 1067\label{prefactdollar} 1068 1069\noindent Syntax: 1070 1071\#factdollar \$-variable 1072 1073\noindent See also the chapters on polynomials \ref{polynomials} and 1074\$-variables \ref{dollars} 1075 1076\noindent The \#factdollar\index{\#factdollar} instruction causes the 1077factorization of the indicated \$-variable. After this instruction and 1078until the \$-variable is redefined there will be two versions of the 1079variable: one is the original unfactorized version and the other is a list 1080of factors. If the name of the variable is \$a the factors can be accessed 1081as $\$a[1],\cdots,\$a[n]$. The total number of factors is given by 1082$\$a[0]$. These factors can also be treated as preprocessor variables by 1083putting them between quotes as in `$\$a[2]$'. 1084 1085%--#] factdollar : 1086%--#[ fromexternal : 1087 1088\section{\#fromexternal} 1089\label{prefromexternal} 1090 1091\noindent Syntax: 1092 1093\#fromexternal[$+-$] ["[\$]varname" [maxlength]] 1094 1095\noindent Appends\index{\#fromexternal} the output of the current external 1096command to the \FORM\ program. The semantics differ depending on the optional 1097arguments. After the external command sends the prompt\index{prompt}, \FORM\ 1098will continue with a next line after the line containing the \#fromexternal 1099instruction. The prompt string is not appended. The optional $+$ or $-$ sign 1100after the name has influence on the listing of the content. The varieties 1101are: 1102 1103\#fromexternal[$+-$] 1104 1105\noindent The semantics is similar to the \#include\index{\#include} 1106instruction but folders are not supported. 1107 1108\#fromexternal[$+-$] "[\$]varname" 1109 1110\noindent is used to read the text from the running external command into 1111the preprocessor variable varname, or into the dollar variable \$varname if 1112the name of the variable starts with the dollar sign ``\$''. 1113 1114\#fromexternal[$+-$] "[\$]varname" maxlength 1115 1116\noindent is used to read the text from the running external command into 1117the preprocessor (or dollar) variable varname. Only the first maxlength 1118characters are stored. 1119 1120%--#] fromexternal : 1121%--#[ if : 1122 1123\section{\#if} 1124\label{preif} 1125 1126\noindent Syntax: 1127 1128\#if ( condition ) 1129 1130\noindent See also endif (\ref{preendif}), 1131 else (\ref{preelse}), 1132 elseif (\ref{preelseif}), 1133 ifdef (\ref{preifdef}), 1134 ifndef (\ref{preifndef}) 1135 1136\noindent The \#if\index{\#if} instruction should be accompanied by a 1137matching \#endif\index{\#endif} instruction. In addition there can be 1138between the \#if and the \#endif some \#elseif\index{\#elseif} instructions 1139and/or a single \#else\index{\#else} instruction. The condition is a 1140logical variable that is true if its value is not equal to zero, and false 1141if its value is zero. Hence it is allowed to use 1142\begin{verbatim} 1143 #if `i' 1144 statements 1145 #endif 1146\end{verbatim} 1147provided that i has a value which can be interpreted as a number. If there 1148is just a string that cannot be seen as a logical\index{logical} condition 1149or a number it will be interpreted as false. The regular syntax of the 1150simple condition is 1151\begin{verbatim} 1152 #if `i' == st2x 1153 statements 1154 #endif 1155\end{verbatim} 1156or 1157\begin{verbatim} 1158 #if ( `i' == st2x ) 1159 statements 1160 #endif 1161\end{verbatim} 1162in which the compare is a numerical compare if both strings can be seen as 1163numbers, while it will be a string compare if at least one of the two 1164cannot be seen as a numerical object. One can also use more complicated 1165conditions as in 1166\begin{verbatim} 1167 #if ( ( `i' > 5 ) && ( `j' > `i' ) ) 1168\end{verbatim} 1169These are referred to as composite conditions. The possible operators are 1170\begin{description} 1171\item[$>$] Greater than, either in numerical or in lexicographical sense. 1172\item[$<$] Less than, either in numerical or in lexicographical sense. 1173\item[$>=$] Greater than or equal to, either in numerical or in 1174lexicographical sense. 1175\item[$<=$] Less than or equal to, either in numerical or in 1176lexicographical sense. 1177\item[$==$ or $=$] Equal to. 1178\item[$!=$] Not equal to. 1179\item[$\&\&$] Logical and operator to combine conditions. 1180\item[$||$] Logical or operator to combine conditions. 1181\end{description} 1182 1183If the condition evaluates to true, the lines after the \#if instruction 1184will be read until the first matching \#elseif instruction, or a \#else 1185instruction or a \#endif instruction, whatever comes first. After such an 1186instruction is encountered input reading stops and continues after the 1187matching \#endif instruction. 1188 1189Like with the regular if-statement (see \ref{substaif}), there are some special 1190functions that allow the asking of questions about objects. These are 1191 1192\leftvitem{3cm}{exists()} 1193\rightvitem{13cm}{The argument of exists\index{exists} is the name of an 1194expression or a \$-variable. This function then returns one if this object 1195exists, cq. has been defined. Otherwise it returns zero. } 1196 1197\leftvitem{3cm}{isdefined()} 1198\rightvitem{13cm}{The argument of isdefined\index{isdefined} is the name of a 1199preprocessor variable. This function then returns one if this object 1200has been defined. Otherwise it returns zero. Technically \texttt{\#ifdef `VAR'} 1201and 1202\texttt{\#if ( isdefined(VAR) )} are the same. The isdefined function 1203allows for greater flexibility in composite conditions.} 1204 1205\leftvitem{3cm}{isfactorized()} 1206\rightvitem{13cm}{The argument of isfactorized\index{isfactorized} is the 1207name of an expression or a \$-variable. This function then returns one if 1208the object has been factorized. Otherwise it returns zero. } 1209 1210\leftvitem{3cm}{isnumerical()} 1211\rightvitem{13cm}{The argument of isnumerical\index{isnumerical} is the 1212name of an expression or a \$-variable. This function then returns one if 1213the object contains a single term that is purely numerical in nature. 1214Otherwise it returns zero. } 1215 1216\leftvitem{3cm}{maxpowerof()} 1217\rightvitem{13cm}{The argument of maxpowerof\index{maxpowerof} is the name 1218of a symbol. This function then evaluates into the maximum power of that 1219symbol as it has been declared. If no maximum power has been set in the 1220declaration of the symbol, the general maximum power for symbols is 1221returned (see \ref{substasymbols}).} 1222 1223\leftvitem{3cm}{minpowerof()} 1224\rightvitem{13cm}{The argument of minpowerof\index{minpowerof} is the name 1225of a symbol. This function then evaluates into the minimum power of that 1226symbol as it has been declared. If no minimum power has been set in the 1227declaration of the symbol, the general minimum power for symbols is 1228returned (see \ref{substasymbols}).} 1229 1230\leftvitem{3cm}{sizeof()} 1231\rightvitem{13cm}{The argument of termsin\index{termsin} is the name of an 1232expression or a \$-variable. This function then evaluates into the number 1233of \FORM words in that expression or variable.} 1234 1235\leftvitem{3cm}{termsin()} 1236\rightvitem{13cm}{The argument of termsin\index{termsin} is the name of an 1237expression or a \$-variable. This function then evaluates into the number 1238of terms in that expression.} 1239 1240%--#] if : 1241%--#[ ifdef : 1242 1243\section{\#ifdef} 1244\label{preifdef} 1245 1246\noindent Syntax: 1247 1248\#ifdef `prevar' 1249 1250\noindent See also if (\ref{preif}), 1251 endif (\ref{preendif}), 1252 else (\ref{preelse}), 1253 ifndef (\ref{preifndef}) 1254 1255\noindent If the named\index{\#ifdef} preprocessor variable has been 1256defined the condition is true, else it is false. For the rest the 1257instruction behaves like the \#if\index{\#if} instruction. 1258 1259An alternative is to use the isdefined object inside the \#if instruction. 1260 1261%--#] ifdef : 1262%--#[ ifndef : 1263 1264\section{\#ifndef} 1265\label{preifndef} 1266 1267\noindent Syntax: 1268 1269\#ifndef `prevar' 1270 1271\noindent See also if (\ref{preif}), 1272 endif (\ref{preendif}), 1273 else (\ref{preelse}), 1274 ifdef (\ref{preifdef}) 1275 1276\noindent If the named\index{\#ifndef} preprocessor variable has been 1277defined the condition is false, else it is true. For the rest the 1278instruction behaves like the \#if\index{\#if} instruction. 1279 1280%--#] ifndef : 1281%--#[ include : 1282 1283\section{\#include} 1284\label{preinclude} 1285 1286\noindent Syntax: 1287 1288\#include[$-+$] filename 1289 1290\#include[$-+$] filename \# foldname 1291 1292\noindent The named\index{\#include} file is searched for and opened. 1293Reading\index{reading} continues from this file until its end. Then the 1294file will be closed and reading continues after the \#include instruction. 1295If a foldname\index{foldname} is specified, \FORM\ will only read the 1296contents of the first fold\index{fold} it encounters in the given file that 1297has the specified name. 1298 1299The file is searched for in the current directory, then in the path 1300specified in the path\index{path} variable in the setup file or at the 1301beginning of the program (see chapter \ref{setup} on the setup file). Next 1302it will look in the path specified in the -p option when \FORM\ is started 1303(see the chapter on running \FORM). If this option has not been used, \FORM\ 1304will look for the environment variable FORMPATH\index{FORMPATH}. If this 1305variable exists it will be interpreted as a path and \FORM\ will search the 1306indicated directories for the given file. If none is found there will be an 1307error message and execution will be halted. 1308 1309The optional $+$ or $-$ sign after the name has influence on the listing of the 1310contents of the file. A $-$ sign will have the effect of a \#$-$ instruction 1311during the reading of the file. A plus sign will have the effect of a \#$+$ 1312instruction during the reading of the file. 1313 1314A fold is defined by a starting line of the format: 1315\begin{verbatim} 1316 *--#[ name : 1317\end{verbatim} 1318and a closing line of the format 1319\begin{verbatim} 1320 *--#] name : 1321\end{verbatim} 1322in which the first character is actually the current 1323commentary\index{commentary} character (see the \#commentchar instruction). 1324All lines between two such lines are considered to be the contents of the 1325fold. If \FORM\ decides that it needs this fold, it will read these contents 1326and put them in its input stream. More about folds is explained in the 1327manual of the STedi editor which is also provided in the \FORM\ 1328distribution. 1329 1330%--#] include : 1331%--#[ inside : 1332 1333\section{\#inside} 1334\label{preinside} 1335 1336\noindent Syntax: 1337 1338\#inside \$var1 [more \$variables] 1339 1340\noindent See also \#endinside (\ref{preendinside}) 1341 1342\noindent Used to\index{\#inside} execute a few statements on the contents 1343of one or more dollar variables (see \ref{dollars}) during compilation time. 1344Although this is a preprocessor instruction one can use the 1345triple dot operator provided one uses the generic version with the $<>$. 1346 1347\noindent The statements in the scope of the \#inside / \#endinside 1348construction must be regular executable statements. They may not contain 1349end-of-module instructions like the .sort instruction. It is allowed to use 1350dollar variables, procedures and preprocessor do loops and if's, but it is 1351not allowed to nest the \#inside / \#endinside constructions. 1352 1353%--#] inside : 1354%--#[ message : 1355 1356\section{\#message} 1357\label{premessage} 1358 1359\noindent Syntax: 1360 1361\#message themessagestring 1362 1363\noindent This instruction places a message\index{\#message} in the output 1364that is clearly marked as such. It is printed with an initial three 1365characters in front as in 1366\begin{verbatim} 1367 Symbols a,b,c; 1368 #message Simple example; 1369~~~Simple example; 1370 Local F = (a+b+c)^10; 1371 .end 1372 1373Time = 0.00 sec Generated terms = 66 1374 F Terms in output = 66 1375 Bytes used = 1138 1376\end{verbatim} 1377Note that the semicolon\index{semicolon} is not needed and if present is 1378printed as well. If one needs messages without this clear marking, one 1379should use the \#write\index{\#write} instruction. 1380 1381%--#] message : 1382%--#[ opendictionary : 1383 1384\section{\#opendictionary} 1385\label{preopendictionary} 1386 1387\noindent Syntax: 1388 1389\#opendictionary name 1390 1391\noindent See chapter \ref{dictionaries} on dictionaries. 1392 1393\noindent Opens a dictionary and makes it ready for adding words to it. If 1394the dictionary does not exist yet, it will be created. 1395 1396%--#] opendictionary : 1397%--#[ optimize : 1398 1399\section{\#optimize} 1400\label{preoptimize} 1401 1402\noindent Syntax: 1403 1404\#optimize nameofoneexpression 1405 1406See the chapter about optimization \ref{optimization} 1407 1408%--#] optimize : 1409%--#[ pipe : 1410 1411\section{\#pipe} 1412\label{prepipe} 1413 1414\noindent Syntax: 1415 1416\#pipe systemcommand 1417 1418\noindent See also system (\ref{presystem}) 1419 1420\noindent This\index{\#pipe} forces a system command to be executed by the 1421operating system. The complete string (excluding initial blanks or tabs) is 1422passed to the operating system. Next \FORM\ will intercept the output of 1423whatever is produced and read that as input. Hence, whenever output is 1424produced \FORM\ will take action, and it will wait when no output is ready. 1425After the command has been finished, \FORM\ will continue with the next line. 1426This instruction has only been implemented on systems that support 1427pipes\index{pipe}. This is mainly UNIX\index{UNIX} and derived systems. 1428Note that this instruction also introduces operating system dependent code. 1429Hence it should be used with great care. 1430 1431%--#] pipe : 1432%--#[ preout : 1433 1434\section{\#preout} 1435\label{prepreout} 1436 1437\noindent Syntax: 1438 1439\#preout ON 1440 1441\#preout OFF 1442 1443\noindent Turns\index{\#preout} listing of the output of the preprocessor 1444to the compiler on or off. Example: 1445% THIS EXAMPLE IS PART OF THE TESTSUITE. CHANGES HERE SHOULD BE APPLIED THERE AS 1446% WELL! 1447\begin{verbatim} 1448 #PreOut ON 1449 S a1,...,a4; 1450 S,a1,a2,a3,a4 1451 L F = (a1+...+a4)^2; 1452 L,F=(a1+a2+a3+a4)^2 1453 id a4 = -a1; 1454 id,a4=-a1 1455 .end 1456 1457Time = 0.00 sec Generated terms = 10 1458 F Terms in output = 3 1459 Bytes used = 52 1460\end{verbatim} 1461 1462%--#] preout : 1463%--#[ prependpath : 1464 1465\section{\#prependpath} 1466\label{preprependpath} 1467 1468\noindent Syntax: 1469 1470\#prependpath pathname 1471 1472\noindent See also appendpath~(\ref{preappendpath}) 1473 1474\noindent Prepends the given path relative to the current file to the beginning 1475of the FORM path\index{path}. 1476 1477%--#] prependpath : 1478%--#[ printtimes : 1479 1480\section{\#printtimes} 1481\label{preprinttimes} 1482 1483\noindent Syntax: 1484 1485\#printtimes 1486 1487\noindent Prints\index{\#printtimes} the current execution time and real 1488time in the same way as done at the end of the program. Helps in monitoring 1489the real time passed in TFORM jobs. 1490Example: 1491\begin{verbatim} 1492 #Printtimes 1493 423.59 sec + 5815.88 sec: 6239.47 sec out of 1215.29 sec 1494\end{verbatim} 1495 1496%--#] printtimes : 1497%--#[ procedure : 1498 1499\section{\#procedure} 1500\label{preprocedure} 1501 1502\noindent Syntax: 1503 1504\#procedure name(var1,...,varn) 1505 1506\noindent See also endprocedure (\ref{preendprocedure}), call 1507(\ref{precall}) 1508 1509\noindent Name\index{\#procedure} is the name of the 1510procedure\index{procedure}. It will be referred to by this name. If the 1511procedure resides in a separate file the name of the file should be 1512name.prc and the \#procedure instruction should form the first line of the 1513file. The \# should be the first character of the file. The parameter field 1514is optional. If there are no parameters, the procedure should also be 1515called without parameters (see the \#call instruction). The parameters 1516(here called var1 to varn) are preprocessor variables and hence they should 1517be referred to between a backquote\index{backquote}/quote\index{quote} pair 1518as in `var1' to `varn'. If there exist already variables with such names 1519when the procedure is called, the new definition comes on top of the old 1520one. Hence in the procedure (and procedures called from it, unless the same 1521problems occurs there too, as would be the case with recursions) the new 1522definition is used, and it is released again when control returns from the 1523procedure. After that the old definition will be in effect again. 1524 1525If the procedure is included in the regular input stream, \FORM\ will read 1526the text of the procedure until the \#endprocedure\index{\#endprocedure} 1527instruction and store it in a special buffer. When the procedure is called, 1528\FORM\ will read the procedure from this buffer, rather than from a file. In 1529systems where file transfer is slow (very busy server with a slow network) 1530this may be faster, especially when many small procedures are called. 1531 1532One way to make libraries\index{library!making a}\index{library} that 1533contain many procedures and maybe more code is to put all procedures into 1534one header (.h) file and include this file at the beginning of the program 1535with a \#include\index{\#include} instruction. This way one has all 1536procedures load and one knows for sure that it are the proper procedures as 1537it guards against the inadvertently picking up of procedures from other 1538directories. It also makes for fewer files and hence makes for better 1539housekeeping. 1540 1541%--#] procedure : 1542%--#[ procedureextension : 1543 1544% NEW@@@ 1545 1546\section{\#procedureextension} 1547\label{preprocedureextension} 1548 1549\noindent Syntax: 1550 1551\#procedureextension string 1552 1553\noindent See also \#call (\ref{precall}) 1554 1555\noindent The default\index{\#procedureextension} extension of procedures 1556is .prc\index{.prc} in \FORM. It is however possible that this clashes with 1557the extensions used by other programs like the Grace\index{Grace} system 1558(Yuasa et al, Prog. Theor. Phys. Suppl. 138(2000)18 ). In that case it is 1559possible to change the extension of the procedures in the current program. 1560This is either done via the setup (page \ref{setup}) or by the 1561\#procedureextension instruction of the preprocessor. The new string 1562replaces the string prc, used by default. For the new string the following 1563restrictions hold: 1564\begin{enumerate} 1565\item The first character must be alphabetic 1566\item No whitespace characters (blanks and/or tabs) are allowed 1567\end{enumerate} 1568For the rest any characters can be used. 1569 1570\noindent The new extension will remain valid either till the next 1571\#procedureextension instruction or to the next .clear\index{.clear} 1572instruction (page \ref{instrclear}), whatever comes first. 1573 1574%--#] procedureextension : 1575%--#[ prompt : 1576 1577\section{\#prompt} 1578\label{preprompt} 1579 1580\noindent Syntax: 1581 1582\#prompt [newprompt] 1583 1584\noindent Sets a new prompt\index{\#prompt} for the current external 1585command (if present) and all further (newly started) external commands. 1586 1587If newprompt is an empty string, the default prompt (an empty line) will be 1588used. 1589 1590The prompt\index{prompt} is a line consisting of a single prompt string. By 1591default, this is an empty string. 1592 1593%--#] prompt : 1594%--#[ redefine : 1595 1596\section{\#redefine} 1597\label{preredefine} 1598 1599\noindent Syntax: 1600 1601\#redefine name "string" 1602 1603\noindent See also define (\ref{predefine}), undefine 1604(\ref{preundefine}) 1605 1606\noindent in which\index{\#redefine} name refers to the name of the 1607preprocessor\index{preprocessor variable} 1608variable\index{variable!preprocessor} to be redefined. The contents of the 1609string will be its new value. If no variable of the given name exists yet, 1610the instruction will be equivalent to the \#define\index{\#define} 1611instruction. 1612 1613%--#] redefine : 1614%--#[ remove : 1615 1616\section{\#remove} 1617\label{preremove} 1618 1619\noindent Syntax: 1620 1621\#remove $<$filename$>$ 1622 1623\noindent See also write (\ref{prewrite}), append (\ref{preappend}), 1624 create (\ref{precreate}), close (\ref{preclose}) 1625 1626\noindent Deletes\index{\#remove} the named file from the system. Under 1627UNIX\index{UNIX} this would be equivalent to the instruction 1628\begin{verbatim} 1629 #system rm filename 1630\end{verbatim} 1631and under MS-DOS\index{MS-DOS} oriented systems like Windows\index{Windows} 1632it would be equivalent to 1633\begin{verbatim} 1634 #system del filename 1635\end{verbatim} 1636The difference with the \#system\index{\#system} instruction is that the 1637\#remove\index{\#remove} instruction does not depend on the particular 1638syntax of the operating system. Hence the \#remove instruction can always 1639be used. 1640 1641%--#] remove : 1642%--#[ reset : 1643 1644\section{\#reset} 1645\label{prereset} 1646 1647\noindent Syntax: 1648 1649\#reset [{\tt<}keyword{\tt>}] 1650 1651\noindent See also `TIMER\_' preprocessor variable. 1652 1653\noindent Currently the only keywords that are allowed are timer and 1654stopwatch. They have the same effect, which is to reset the timer for the 1655`timer\_' (or `stopwatch\_) preprocessor variable (see \ref{preprovariables}). 1656 1657%--#] reset : 1658%--#[ reverseinclude : 1659 1660\section{\#reverseinclude} 1661\label{prereverseinclude} 1662 1663\noindent Syntax: 1664 1665\#reverseinclude[$-+$] filename 1666 1667\#reverseinclude[$-+$] filename \# foldname 1668 1669\noindent This instruction is identical to the \#include \ref{preinclude} 1670instruction, with the exception that the statements and instructions in the 1671file are read in reverse order. This can be useful at times when code is 1672generated in a particular order in a file and one would like to 'undo' this 1673code. It is somewhat related to the effects of the debugflag option 1674(\ref{optimdebugflag}) in the optimization options of the format statement 1675\ref{optimization}. 1676 1677There are a few limitations. If, for instance, linefeeds or semicolons 1678occur inside preprocessor variables, the reading routines cannot see this. 1679Additionally unfinished strings (unmatched double quotes) will result in 1680a fatal error. On the other hand the fold structure remains preserved. 1681 1682%--#] reverseinclude : 1683%--#[ rmexternal : 1684 1685\section{\#rmexternal} 1686\label{prermexternal} 1687 1688\noindent Syntax: 1689 1690\#rmexternal [n] 1691 1692\noindent Terminates\index{\#rmexternal} an external command. The integer 1693number n must be either the descriptor of a running external command, or 0. 1694 1695If n is 0, then all external programs will be terminated. 1696 1697If n is not specified, the current external command will be terminated. 1698 1699The action of this instruction depends on the attributes of the external 1700channel (see the \#setexternalattr\index{\#setexternalattr} (section 1701\ref{setexternalcommunication}) instruction). By default, the instruction 1702closes the commands' IO channels, sends a KILL\index{KILL signal} signal to 1703every process in its process group and waits for the external command to be 1704finished. 1705 1706%--#] rmexternal : 1707%--#[ rmseparator : 1708 1709\section{\#rmseparator} 1710\label{prermseparator} 1711 1712\noindent Syntax: 1713 1714\#rmseparator character 1715 1716\noindent See also \#addseparator (\ref{preaddseparator}), 1717 \#call (\ref{precall}), \#do (\ref{predo}) 1718 1719\noindent Removes a character\index{\#rmseparator} from the list of permissible 1720separator characters for arguments of \#call or \#do instructions. By 1721default the two characters that are permitted are the comma and the 1722character \verb:|:. Blanks, tabs and double quotes are ignored. Note that 1723the comma must be specified between double quotes as in 1724\begin{verbatim} 1725 #rmseparator "," 1726\end{verbatim} 1727 1728%--#] rmseparator : 1729%--#[ setexternal : 1730 1731\section{\#setexternal} 1732\label{presetexternal} 1733 1734\noindent Syntax: 1735 1736\#setexternal n 1737 1738\noindent Sets\index{\#setexternal} the ``current'' external command. The 1739instructions \#toexternal\index{\#toexternal} and 1740\#fromexternal\index{\#fromexternal} deal with the current external 1741command. The integer number n must be the descriptor of a running external 1742command. 1743 1744%--#] setexternal : 1745%--#[ setexternalattr : 1746 1747\section{\#setexternalattr} 1748\label{presetexternalattr} 1749 1750\noindent Syntax: 1751 1752\#setexternalattr list\_of\_attributes 1753 1754\noindent sets\index{\#setexternalattr} attributes for {\em newly started} 1755external commands. Already running external commands are not affected. The 1756list of attributes is a comma separated list of pairs attribute=value, 1757e.g.: 1758\begin{verbatim} 1759 #setexternalattr shell=noshell,kill=9,killall=false 1760\end{verbatim} 1761Possible attributes are: 1762\begin{description} 1763\item[kill\index{kill}] 1764specifies the signal to be sent to the external command 1765either before the termination of the \FORM\ program or by the preprocessor 1766instruction \verb|#rmexternal|. By default this is 9 ( 1767SIGKILL\index{SIGKILL signal}). Number 0 means that no signal will be sent. 1768\item[killall\index{killall}] Indicates whether the kill signal will be sent to the whole 1769group or only to the initial process. Possible values are ``\verb|true|'' 1770and ``\verb|false|''. By default, the kill signal will be sent to the 1771whole group. 1772\item[daemon\index{daemon}] 1773Indicates whether the command should be ``daemonized'', i.e. 1774the initial process will be passed to the init process and will belong 1775to the new process group in the new session. 1776Possible values are ``\verb|true|'' and ``\verb|false|''. By default, 1777``\verb|true|''. 1778\item[shell\index{shell}] 1779specifies which shell\index{shell} is used to run a 1780command. (Starting an external command in a subshell permits to 1781start not only executable files but also scripts\index{script} and 1782pipelined\index{pipelined job} jobs. The disadvantage is that there is no 1783way to detect failure upon startup since usually the shell is started 1784successfully.) By default this is ``\verb|/bin/sh -c|''. If set 1785\verb|shell=noshell|, the command will be stared by the instruction 1786\#external\index{\#external} directly but not in a subshell, so the command 1787should be a name of the executable file rather than a system command. The 1788instruction \#external will duplicate the actions of the shell in searching 1789for an executable file if the specified file name does not contain a slash 1790(/) character. The search path is the path specified in the environment by 1791the PATH\index{PATH} variable. If this variable isn't specified, the 1792default path ``\verb|:/bin:/usr/bin|'' 1793is used. 1794\item[stderr\index{stderr}] 1795specifies a file to redirect the standard\index{standard error} error 1796stream to. By default it is ``\verb|/dev/null|''. If set 1797\verb|stderr=terminal|, no redirection occurs. 1798\end{description} 1799Only attributes that are explicitly mentioned are changed, all others remain 1800unchanged. Note, changing attributes should be done with care. For example, 1801\begin{verbatim} 1802 #setexternalattr daemon=false 1803\end{verbatim} 1804starts a command in the subshell within the current process group with 1805default attributes kill=9 and killall=true. 1806The instruction \#rmexternal\index{\#rmexternal} sends the 1807KILL\index{KILL signal} signal to the wholegroup, which means that also 1808\FORM\ itself will be killed. 1809 1810%--#] setexternalattr : 1811%--#[ setrandom : 1812 1813\section{\#setrandom} 1814\label{presetrandom} 1815 1816\noindent Syntax: 1817 1818\#setrandom number 1819 1820\noindent See also random\_ (\ref{funrandom}) and ranperm\_ (\ref{funranperm}) 1821 1822\noindent The \#setrandom\index{\#setrandom} instruction initializes the 1823random number generator 1824random\_~\ref{funrandom}\index{random\_}\index{function!random\_}. The 1825number that is used as a seed can have the length of two words in FORM. 1826This means that on a 32-bits computer it can be an (unsigned) 32-bits 1827integer and on a 64-bits computer it can be an (unsigned) 64 bits integer. 1828If there is no \#setrandom instruction the random number generator is 1829initialized in a built in standard way. The \#setrandom instruction also 1830initializes the random number generators of the workers when one uses TFORM 1831or ParFORM. They are initialized with different seeds that are derived in a 1832non-trivial way from the seed given by the user and the number of the 1833worker. 1834 1835%--#] setrandom : 1836%--#[ show : 1837 1838\section{\#show} 1839\label{preshow} 1840 1841\noindent Syntax: 1842 1843\#show [preprocessorvariablename[s]] 1844 1845\noindent If no names\index{\#show} are present, the contents of all 1846preprocessor variables\index{variable!preprocessor} will be printed to the 1847regular output. If one or more preprocessor variables are specified 1848(separated by comma's), only their contents will be printed. The 1849preprocessor variables should be represented by their name only. No 1850enclosing backquote/quote should be used, because that would force a 1851substitution of the preprocessor variable before the instruction gets to 1852see the name. Example: 1853\begin{verbatim} 1854 #define MAX "3" 1855 Symbols a1,...,a`MAX'; 1856 L F = (a1+...+a`MAX')^2; 1857 #show 1858#The preprocessor variables: 18590: VERSION_ = "3" 18601: SUBVERSION_ = "2" 18612: NAMEVERSION_ = "" 18623: DATE_ = "Wed Feb 28 08:43:20 2007" 18634: NAME_ = "testpre.frm" 18645: CMODULE_ = "1" 18656: MAX = "3" 1866 .end 1867 1868Time = 0.00 sec Generated terms = 6 1869 F Terms in output = 6 1870 Bytes used = 102 1871\end{verbatim} 1872We see that the variable MAX has indeed the value 3. There are six 1873additional variables which have been defined by \FORM\ itself. Hence the 1874trailing underscore which cannot be used in user defined names. The current 1875version of \FORM\ is shown in the variable VERSION\_\index{VERSION\_} and the 1876name of the current program is given in the variable NAME\_\index{NAME\_}. 1877For more about the system defined preprocessor variables see 1878\ref{preprovariables}. 1879 1880There is another preprocessor variable that does not show in the listings. 1881Its name is SHOWINPUT\_\index{SHOWINPUT\_}. This variable has the value one 1882if the listing of the input is on and the value zero if the listing of the 1883input is off. 1884 1885%--#] show : 1886%--#[ skipextrasymbols : 1887 1888\section{\#skipextrasymbols} 1889\label{preskipextrasymbols} 1890 1891\noindent Syntax: 1892 1893\#skipextrasymbols positivenumber 1894 1895\noindent See also ExtraSymbols~(\ref{substaextrasymbols}) and the chapter 1896on optimization~(\ref{optimization}). 1897 1898\noindent This instructions adds a number of dummy extra 1899symbols\index{extra symbols} to the list of extra 1900symbols~(\ref{substaextrasymbols}). This can be used when several 1901optimizations are done on an expression in such a way that the extra 1902symbols of previous optimizations are still present. Normally the number 1903space for them is erased in a \#clearoptimize instruction. This can be 1904avoided with a sequence like 1905\begin{verbatim} 1906 #skipextrasymbols,{`optimmaxvar_'-`optimminvar_'+1} 1907\end{verbatim} 1908In this case the numbering of the next optimization will start after the 1909last extra symbol of the previous optimization. 1910One should realize however that the definitions of the extra symbols are 1911not kept once the new optimization is started or once a \#clearoptimize 1912instruction is issued. Example: 1913\begin{verbatim} 1914 #- 1915 S a,b,c,d,e; 1916 L F = (a+b+c+d+3*e)^3; 1917 B b; 1918 .sort 1919 ExtraSymbols,array,w; 1920 Format O3,stats=ON; 1921 #optimize F 1922 #write <> " %4O" 1923 .sort 1924 #SkipExtraSymbols,{`optimmaxvar_'-`optimminvar_'+1} 1925 id b = b+1; 1926 Print +f; 1927 B b; 1928 .end 1929\end{verbatim} 1930Because the O3 format is still active, the final printing uses the 1931optimization as well. If the \#SkipExtraSymbols instruction would have been 1932omitted, the numbering would start again from one, while the rhs. of their 1933definitions would contain the old extra symbols. The result would be 1934incorrect. 1935 1936%--#] skipextrasymbols : 1937%--#[ switch : 1938 1939\section{\#switch} 1940\label{preswitch} 1941 1942\noindent Syntax: 1943 1944\#switch string 1945 1946\noindent See also endswitch (\ref{preendswitch}), 1947 case (\ref{precase}), 1948 break (\ref{prebreak}), 1949 default (\ref{predefault}) 1950 1951\noindent the\index{\#switch} string could for instance be a preprocessor 1952variable as in 1953\begin{verbatim} 1954 #switch `i' 1955\end{verbatim} 1956The \#switch\index{\#switch} instruction, together with 1957\#case\index{\#case}, \#break\index{\#break}, \#default\index{\#default} 1958and \#endswitch\index{\#endswitch}, allows the user to conveniently make 1959code for a number of cases that are distinguished by the value of a 1960preprocessor variable. In the past this was only possible with the use of 1961folds\index{folds} in the \#include\index{\#include} instruction and the 1962corresponding include file\index{file!include} (see \ref{preinclude}). 1963Because few people have an editor like STedi (see the \FORM\ distribution 1964site) that can handle the folds in a proper way, it was judged that the 1965more common switch mechanism might be friendlier. The proper syntax of a 1966complete construction would be 1967\begin{verbatim} 1968 #switch `par' 1969 #case 1 1970 some statements 1971 #break 1972 #case ax2 1973 other statements 1974 #break 1975 #default 1976 more statements 1977 #break 1978 #endswitch 1979\end{verbatim} 1980The number of cases is not limited. The compare between the strings in the 1981\#switch instruction and in the \#case instructions is as a text string. 1982Hence numerical strings have no special meaning. If a \#break instruction 1983is omitted, control may go into another case. This is called 1984fall-through\index{fall-through}. 1985This is a way in which one can have the same statements for several cases. 1986The \#default instruction is not mandatory. 1987 1988\FORM\ will look for the first case of which the string matches the string 1989in the \#switch instruction. Input reading (control flow) starts after this 1990\#case instruction, and continues till either a \#break instruction is 1991encountered, or the \#endswitch is met. After that input reading continues 1992after the \#endswitch instruction. If no case has a matching string, input 1993reading starts after the \#default instruction. If no \#default instruction 1994is found, input reading continues after the matching \#endswitch 1995instruction. 1996 1997\#switch constructions can be nested\index{nested}. They can be combined 1998with \#if\index{\#if} constructions, \#do\index{\#do} instructions, etc. 1999but they should obey normal nesting rules (as with nesting of 2000brackets\index{bracket} of different types). 2001 2002%--#] switch : 2003%--#[ system : 2004 2005\section{\#system} 2006\label{presystem} 2007 2008\noindent Syntax: 2009 2010\#system systemcommand 2011 2012\noindent See also pipe (\ref{prepipe}) 2013 2014\noindent This forces a system\index{\#system} command to be executed by 2015the operating system. The complete string (excluding initial blanks or 2016tabs) is passed to the operating system. \FORM\ will then wait until control 2017is returned. Note that this instruction introduces operating system 2018dependent code. Hence it should be used with great care. 2019 2020%--#] system : 2021%--#[ terminate : 2022 2023\section{\#terminate} 2024\label{preterminate} 2025 2026\noindent Syntax: 2027 2028\#terminate [exitcode] 2029 2030\noindent This forces \FORM\ to terminate\index{\#terminate} execution 2031immediately. If an exit code is given (an integer number), this will be the 2032return value that \FORM\ gives to the shell program from which it was run. If 2033no return value is specified, the value -1 will be returned. 2034 2035%--#] terminate : 2036%--#[ timeoutafter : 2037 2038\section{\#timeoutafter} 2039\label{pretimeoutafter} 2040 2041\noindent Syntax: 2042 2043\#timeoutafter $<$Number of seconds$>$ 2044 2045\noindent This instruction starts a timer. When the given time expires the 2046current program will be terminated, unless the timer is reset before this 2047time. Resetting the timer is dome with the "\#timeoutafter 0" instruction. 2048 2049The purpose of this instruction is to prevent runaway programs, because a 2050given subpart takes much more time than it should. Example: 2051\begin{verbatim} 2052 .sort 2053 #timeoutafter 1000 2054 #call problematicprocedure 2055 .sort 2056 #timeoutafter 0 2057\end{verbatim} 2058If one runs many diagrams with a make-like facility like minos, diagrams 2059that behave in an unexpected way can be killed this way and minos can 2060continue with the next diagram. Later one can see which diagrams caused 2061problems and one may study what the problem was. 2062 2063%--#] timeoutafter : 2064%--#[ toexternal : 2065 2066\section{\#toexternal} 2067\label{pretoexternal} 2068 2069\noindent Syntax: 2070 2071\#toexternal "formatstring" $<$,variables$>$ 2072 2073\noindent Sends\index{\#toexternal} the output to the current external 2074command. The semantics of the \verb|"formatstring"| and the 2075\verb|[,variables]| is the same as for the \#write\index{\#write} 2076instruction, except for the trailing end-of-line symbol. In contrast to the 2077\#write instruction, the \#toexternal instruction does not append any new 2078line symbol to the end of its output. 2079 2080%--#] toexternal : 2081%--#[ undefine : 2082 2083\section{\#undefine} 2084\label{preundefine} 2085 2086\noindent Syntax: 2087 2088\#undefine name 2089 2090\noindent See also define (\ref{predefine}), redefine 2091(\ref{preredefine}) 2092 2093\noindent \index{\#undefine} Name refers to the name of the 2094preprocessor variable\index{variable!preprocessor} to be undefined. This 2095statement causes the given preprocessor variable to be removed from the 2096stack of preprocessor variables. If an earlier instance of this variable 2097existed (other variable with the same name), it will become active again. 2098There are various other ways by which preprocessor variables can become 2099undefined. All variables belonging to a procedure are undefined at the end 2100of a procedure, and so are all other preprocessor variables that were 2101defined inside this procedure. The same holds for the preprocessor variable 2102that is used as a loop parameter in the \#do\index{\#do} instruction. 2103 2104%--#] undefine : 2105%--#[ usedictionary : 2106 2107\section{\#usedictionary} 2108\label{preusedictionary} 2109 2110\noindent Syntax: 2111 2112\#usedictionary name 2113\#usedictionary name (options) 2114 2115\noindent See chapter \ref{dictionaries} on dictionaries. 2116 2117\noindent Starts using a dictionary for output translation. 2118 2119%--#] usedictionary : 2120%--#[ write : 2121 2122\section{\#write} 2123\label{prewrite} 2124 2125\noindent Syntax: 2126 2127\#write [$<$filename$>$] "formatstring" [,variables] 2128 2129\noindent See also append (\ref{preappend}), 2130 create (\ref{precreate}), remove (\ref{preremove}), 2131 close (\ref{preclose}) 2132 2133\noindent If there\index{\#write} is no file specified, the output will be 2134to the regular output\index{output channel} channel. If a file is 2135specified, \FORM\ will look whether this file is open already. If it is open 2136already, the specified output will be added to the file. If it is not open 2137yet it will be opened. Any previous contents will be lost. This would be 2138equivalent to using the \#create\index{\#create} instruction first. If 2139output has to be added to an existing file, the \#append\index{\#append} 2140instruction should be used first. 2141 2142The format\index{format string} string is like a format string in the 2143language C\index{C}. This means 2144that it is placed between double quotes. It will contain text that will be 2145printed, and it will contain special character sequences for special 2146actions. These sequences and the corresponding actions are: 2147\begin{description} 2148\item[$\backslash$n] A newline\index{newline} character. 2149\item[$\backslash$t] A tab\index{tab} character. 2150\item[$\backslash$"] A double\index{double quote} quote character. 2151\item[$\backslash$b] A backslash\index{backslash} character. 2152\item[\%\%] The character \%\index{\%}. 2153\item[\%] If the last character in the string, it causes the omission of a 2154linefeed\index{linefeed} at the end of the printing. Note that if this 2155happens in the regular output (as opposed to a file) there may be 2156interference with the listing of the input. 2157\item[\%\$] A dollar variable\index{\$-variable}. The variable should be 2158indicated in the list of variables. Each occurrence of \%\$ will look for 2159the next variable. 2160\item[\%e] An active expression\index{expression}. The expression should be 2161indicated in the list of variables. Each occurrence of \%e will look for 2162the next variable. Unlike the output caused by the print statement the 2163expression will be printed without its name and there will also be no 2164\verb:=: sign unless there is one in the format string of course. If the 2165current output format is fortran\index{fortran} output there is an extra option. After the 2166name of the expression one should put between parentheses the name to be 2167used when there are too many continuation cards. 2168\item[\%+e] Like \%e, but like the +s option in the Print 2169statement\ref{substaprint} where each term starts on a new line. 2170\item[\%E] Like \%e, but whereas the \%e terminates the expression with a 2171;, the \%E does not give this trailing semicolon\index{semicolon}. 2172\item[\%+E] Like \%E, but like the +s option in the Print 2173statement\ref{substaprint} where each term starts on a new line. 2174\item[\%s] A string\index{string}. The string should be 2175given in the list of variables and be enclosed between double quotes. Each 2176occurrence of \%s will look for the next variable in the list. 2177\item[\%f] A file\index{file}. The name of the file will be expected in the 2178list of variables. The file is searched for in the current directory, then 2179in path indicated by the path variable in the setup file or at the 2180beginning of the file (see chapter \ref{setup} on the setup file), then in 2181the path specified in the -p option when \FORM\ is started (see the chapter 2182on running \FORM). If this option has not been used, \FORM\ will look for the 2183environment variable FORMPATH\index{FORMPATH}. If this variable exists it 2184will be interpreted as a path and \FORM\ will search the indicated 2185directories for the given file. If none is found there will be an error 2186message and execution will be halted. 2187\item[\%X] Forces the printing of the list of extra symbols 2188(\ref{sect-extrasymbols}) and their definitions\index{extrasymbols}. 2189\item[\%O] Forces the printing of the definitions of the extra symbols in 2190the buffer with the temporary variables from the previous optimization (see 2191the chapter on optimizations \ref{optimization}). 2192\end{description} 2193If no special variables are asked for (by means of \%\$, \%e, \%E or \%s) 2194the list of variables will be ignored (if present). Example: 2195% THIS EXAMPLE IS PART OF THE TESTSUITE. CHANGES HERE SHOULD BE APPLIED THERE AS 2196% WELL! 2197\begin{verbatim} 2198 Symbols a,b; 2199 L F = a+b; 2200 #$a1 = a+b; 2201 #$a2 = (a+b)^2; 2202 #$a3 = $a1^3; 2203 #write " One power: %$\n Two powers: %$\n Three powers: %$\n%s"\ 2204 ,$a1,$a2,$a3," The end" 2205 One power: b+a 2206 Two powers: b^2+2*a*b+a^2 2207 Three powers: b^3+3*a*b^2+3*a^2*b+a^3 2208 The end 2209 .end 2210 2211Time = 0.00 sec Generated terms = 2 2212 F Terms in output = 2 2213 Bytes used = 32 2214\end{verbatim} 2215We see that the writing occurs immediately after the \#write\index{\#write} 2216instruction, because it is done by the preprocessor. Hence the output comes 2217before the execution of the expression F. 2218% THIS EXAMPLE IS PART OF THE TESTSUITE. CHANGES HERE SHOULD BE APPLIED THERE AS 2219% WELL! 2220\begin{verbatim} 2221 S x1,...,x10; 2222 L MyExpression = (x1+...+x10)^4; 2223 .sort 2224 Format Fortran; 2225 #write <fun.f> " FUNCTION fun(x1,x2,x3,x4,x5,x6,x7,x8,x9,x10)" 2226 #write <fun.f> " REAL x1,x2,x3,x4,x5,x6,x7,x8,x9,x10" 2227 #write <fun.f> " fun = %e",MyExpression(fun) 2228 #write <fun.f> " RETURN" 2229 #write <fun.f> " END" 2230 .end 2231\end{verbatim} 2232Some remarks are necessary here. Because the \#write is a preprocessor 2233instruction, the .sort\index{.sort} is essential. Without it, the 2234expression has not been worked out at the moment we want to write. The name 2235of the expression is too long for fortran\index{fortran}, and hence the 2236output file will use a different name (in this case the name `fun' was 2237selected). The output file looks like 2238% THIS EXAMPLE IS PART OF THE TESTSUITE. CHANGES HERE SHOULD BE APPLIED THERE AS 2239% WELL! 2240\begin{verbatim} 2241 FUNCTION fun(x1,x2,x3,x4,x5,x6,x7,x8,x9,x10) 2242 REAL x1,x2,x3,x4,x5,x6,x7,x8,x9,x10 2243 fun = 24*x1*x2*x3*x4 + 24*x1*x2*x3*x5 + 24*x1*x2*x3*x6 + 24*x1*x2 2244 & *x3*x7 + 24*x1*x2*x3*x8 + 24*x1*x2*x3*x9 + 24*x1*x2*x3*x10 + 12* 2245 ..... 2246 & x8 + 4*x6**3*x9 + 4*x6**3*x10 + x6**4 + 24*x7*x8*x9*x10 + 12*x7* 2247 & x8*x9**2 2248 fun = fun + 12*x7*x8*x10**2 + 12*x7*x8**2*x9 + 12*x7*x8**2*x10 + 2249 & 4*x7*x8**3 + 12*x7*x9*x10**2 + 12*x7*x9**2*x10 + 4*x7*x9**3 + 4* 2250 & x7*x10**3 + 12*x7**2*x8*x9 + 12*x7**2*x8*x10 + 6*x7**2*x8**2 + 2251 & 12*x7**2*x9*x10 + 6*x7**2*x9**2 + 6*x7**2*x10**2 + 4*x7**3*x8 + 2252 & 4*x7**3*x9 + 4*x7**3*x10 + x7**4 + 12*x8*x9*x10**2 + 12*x8*x9**2 2253 & *x10 + 4*x8*x9**3 + 4*x8*x10**3 + 12*x8**2*x9*x10 + 6*x8**2* 2254 & x9**2 + 6*x8**2*x10**2 + 4*x8**3*x9 + 4*x8**3*x10 + x8**4 + 4*x9 2255 & *x10**3 + 6*x9**2*x10**2 + 4*x9**3*x10 + x9**4 + x10**4 2256 2257 RETURN 2258 END 2259\end{verbatim} 2260and each time after 19 continuation lines we have to break the expression 2261and use the \verb:fun = fun +: trick to continue. 2262 2263%--#] write : 2264%--#[ Some remarks : 2265 2266\section{Some remarks} 2267It should be noted that the various constructions like 2268\#do\index{\#do}/\#enddo\index{\#enddo}, 2269\#procedure\index{\#procedure}/\#endprocedure\index{\#endprocedure}, 2270\#switch\index{\#switch}/\#endswitch\index{\#endswitch} and 2271\#if\index{\#if}/\#endif\index{\#endif} all 2272create a certain environment. These environments cannot be interweaved. This 2273means that one cannot make code of the type 2274\begin{verbatim} 2275 #do i = 1,5 2276 #if ( `MAX' > `i' ) 2277 id f(`i') = g`i'(x); 2278 #enddo 2279 some statements 2280 #do i = 1,5 2281 #endif 2282 #enddo 2283\end{verbatim} 2284whether this could be considered useful or not. Similarly one cannot make a 2285construction that might be very useful: 2286\begin{verbatim} 2287 #do i = 1,5 2288 #do j`i' = 1,3 2289 #enddo 2290 some statements 2291 #do i = 1,5 2292 #enddo 2293 #enddo 2294\end{verbatim} 2295Currently the syntax does not allow this. This may change in the future. 2296 2297%--#] Some remarks : 2298 2299 2300