1This is Info file chpp.info, produced by Makeinfo version 1.68 from the 2input file chpp.texi. 3 4 This file documents the `chpp' Preprocessor. 5 6 Copyright (C) 1997-1999, Mark Probst, Heinz Deinhart 7 8 Permission is granted to make and distribute verbatim copies of this 9manual provided the copyright notice and this permission notice are 10preserved on all copies. 11 12START-INFO-DIR-ENTRY 13* chpp:: A very powerful macro preprocessor. 14END-INFO-DIR-ENTRY 15 16 17File: chpp.info, Node: Special Forms, Next: Macro Reference, Prev: Extending chpp, Up: Top 18 19Special Forms 20************* 21 22 Special forms, although syntactically equivalent to macros, differ 23from macros in that their arguments are not automatically evaluated 24before they are called. The evaluation of their arguments usually 25depend on some condition of some other argument. 26 27 - Special Form: if (CONDITION,CONSEQUENT[,ALTERNATIVE]) 28 Evaluates CONDITION and, if its boolean value is TRUE, evaluates 29 CONSEQUENT. Otherwise, ALTERNATIVE is evaluated, if specified. 30 31 - Special Form: cond ([CONDITION,CONSEQUENT[,...]]) 32 Evaluates the CONDITIONs one at a time and checks for their 33 boolean value. If a CONDITION with a value of TRUE is encountered, 34 its corresponding CONSEQUENT is evaluated and its result returned. 35 If no CONDITION evaluates to TRUE, nothing is done. Example: 36 37 %<number=23>\ 38 %cond(%[number < 10],less than 10, 39 %[number < 50],less than 50 but greater than 9, 40 else,greater than 49) 41 => less than 50 but greater than 9 42 43 - Special Form: case 44 (STRING,LIST,CONSEQUENT[,...[,`else',ALTERNATIVE]]) 45 Evaluates STRING to a scalar. Then, one at a time evaluates each 46 LIST and checks whether STRING is contained in the resulting list. 47 If it is, the corresponding CONSEQUENT is evaluated and its result 48 returned. If the `else' clause is specified and the string is 49 contained in no list, its ALTERNATIVE is evaluated. Otherwise, 50 nothing is done. Example: 51 52 %<number=7>\ 53 %case(%number, 54 %list(0,2,4,6,8),even, 55 %list(1,3,5,7,9),odd) 56 => odd 57 58 - Special Form: for (COUNTER,START,STOP,[INCREMENT,]BODY) 59 Evaluates COUNTER, START, STOP and, if specified, INCREMENT. The 60 values of START, STOP and INCREMENT must be integer numbers. If 61 INCREMENT is not specified, an increment of 1 is used if START is 62 greater than STOP, otherwise -1. Then counts, beginning with 63 START, while the value of the counter is before or equal to STOP 64 in the counting direction. For each step, evaluates BODY in a new 65 environment where COUNTER is bound to the value of the counter. 66 67 A few examples: 68 69 %for(i,1,10,%i%' ') 70 => 1 2 3 4 5 6 7 8 9 10 71 %for(i,10,1,%i%' ') 72 => 10 9 8 7 6 5 4 3 2 1 73 %for(i,1,10,2,%i%' ') 74 => 1 3 5 7 9 75 %for(i,10,1,-2,%i%' ') 76 => 10 8 6 4 2 77 %for(i,1,10,0,%i%' ') 78 error--> increment in for-loop cannot be zero 79 %for(i,10,1,1,%i%' ') 80 => 81 82 - Special Form: foreach (COUNTER,LIST,BODY) 83 Evaluates COUNTER and LIST, which must yield a list. Then iterates 84 over this list evaluating BODY in a new environment in which 85 COUNTER is bound to the current list element. 86 87 - Special Form: foreachkey (COUNTER,HASH,BODY) 88 Evaluates COUNTER and HASH, which must yield a hash. Then iterates 89 over all keys in the hash evaluating BODY in a new environment in 90 which COUNTER is bound to the current hash key. 91 92 - Special Form: while (CONDITION,EXPR) 93 Evaluates CONDITION. If this yields a boolean value of TRUE, EXPR 94 is evaluated, otherwise the loop is finished. Then repeats the 95 cycle. 96 97 - Special Form: until (CONDITION,EXPR) 98 Evaluates CONDITION. If this yields a boolean value of TRUE, the 99 loop is finished, otherwise EXPR is evaluated. Then repeats the 100 cycle. 101 102 - Special Form: dowhile (EXPR,CONDITION) 103 Evaluates EXPR, then evaluates CONDITION. If this yields a boolean 104 value of TRUE, the cycle is repeated. 105 106 - Special Form: dountil (EXPR,CONDITION) 107 Evaluates EXPR, then evaluates CONDITION. If this yields a boolean 108 value of TRUE, the loop is finished, otherwise the cycle is 109 repeated. 110 111 - Special Form: and ([EXPR[,...]]) 112 Evaluates the EXPRs from left to right. For the first EXPR 113 evaluating to boolean FALSE, returns `0'. If all EXPRs evaluate to 114 boolean TRUE, returns `1'. This means that if one EXPR evaluates 115 to FALSE, all EXPRs to its right do not get evaluated. If `and' is 116 called without parameters, it returns `1'. 117 118 - Special Form: or ([EXPR[,...]]) 119 Evaluates the EXPRs from left to right. For the first EXPR 120 evaluating to boolean TRUE, returns `1'. If all EXPRs evaluate to 121 boolean FALSE, returns `0'. This means that if one EXPR evaluates 122 to TRUE, all EXPRs to its right do not get evaluated. If `or' is 123 called without parameters, it returns `0'. 124 125 - Special Form: define (NAME,ARGNAME[,ARGNAME...],BODY) 126 Defines a macro with the name NAME and the specified argument 127 names. The body BODY is not evaluated. 128 129 If the last ARGNAME matches the pattern 130 LSTNAME`:'[LOWER]`:'[UPPER] then the macro takes a variable number 131 of arguments. All ARGNAMEs but the last are treated as single 132 arguments. The last ARGNAME corresponds to a number of arguments 133 not less than LOWER and not greater than UPPER. When the macro is 134 called, these arguments are bound to the LSTNAME in the form of a 135 list. If LOWER is not given, zero arguments for LSTNAME are 136 allowed. If UPPER is not given, there is no upper limit on the 137 number of arguments. 138 139 Examples: 140 141 %define(mac,a,b,a=%a b=%b) 142 143 defines a macro `mac' taking exactly two arguments. 144 145 %define(mac,a,b,c:2:3,a=%a b=%b c=%encode(%c)) 146 %mac(1,2,3,4) 147 => a=1 b=2 c=%list(%'3',%'4') 148 149 defines a macro `mac' taking four or five arguments. 150 151 %define(mac,a,b,c::3,a=%a b=%b c=%encode(%c)) 152 153 defines a macro `mac' taking at most five arguments. 154 155 %define(mac,a,b,c:2:,a=%a b=%b c=%encode(%c)) 156 157 defines a macro `mac' taking at least four arguments. 158 159 - Special Form: defspecial (NAME,ARGNAME[,ARGNAME...],BODY) 160 Defines a special form with the name NAME and the specified 161 argument names. The body BODY is not evaluated. 162 163 When a special form is called, its arguments are not evaluated. 164 This is left to the special form. Instead, intermediate code of 165 the arguments is bound to the ARGNAMEs and BODY is evaluated. The 166 special form can evaluate any of the arguments any time it wishes 167 to by using the `eval' macro. 168 169 The special form body is evaluated in an environment whose parent 170 is the environment from which the special form was invoked. 171 172 As an example, we give an implementation of a special form `unless' 173 which evalutes its second argument only if its first argument 174 evaluates to a boolean value of FALSE: 175 176 %defspecial(unless,cond,body, 177 %if(%not(%eval(%cond)), 178 %eval(%body) 179 ) 180 ) 181 182 Note that any side-effects that result from evalutating the second 183 argument do not occur if the first argument evaluates to TRUE: 184 185 %<a=123> 186 %unless(1,%<a=xyz>) 187 %%a is %a 188 => %a is 123 189 190 - Special Form: lambda (ARGNAME[,ARGNAME...],BODY) 191 Creates an anonymous macro (closure) with the specified argument 192 names and the body BODY, which is not evaluated. 193 194 If the last ARGNAME matches the pattern 195 LSTNAME`:'[LOWER]`:'[UPPER] then the closure takes a variable 196 number of arguments. The semantics of this feature are equal to 197 that of `define'. 198 199 The definition 200 201 %define(mac,a,b,a=%a b=%b) 202 203 is semantically equivalent to 204 205 %<mac=%lambda(a,b,a=%a b=%b)> 206 207 - Special Form: let (NAME,VALUE[,NAME,VALUE...],BODY) 208 Evaluates BODY in a new environment with the local variables NAMEs 209 bound to their corresponding VALUEs. The variables are bound 210 beginning with the first NAME from left to right and the bindings 211 are immediately visible to the following VALUE expressions, i.e. 212 the second VALUE is evaluated in an environment where the first 213 NAME is already bound. This is a behaviour similar to Lisp's 214 `let*'. 215 216 %let(a,1,b,%[a+1],%%a=%a %%b=%b) 217 => %a=1 %b=2 218 219 - Special Form: locals (SYMBOL[,SYMBOL...],BODY) 220 Evaluates BODY in a new environment with the specified local 221 variables. 222 223 224File: chpp.info, Node: Macro Reference, Next: Internal Variables, Prev: Special Forms, Up: Top 225 226Macros 227****** 228 229* Menu: 230 231* List Operations:: 232* Hash Operations:: 233* Environment Operations:: 234* File Operations:: 235* String Operations:: 236* Time Operations:: 237* Miscellaneous:: 238 239 240File: chpp.info, Node: List Operations, Next: Hash Operations, Prev: Macro Reference, Up: Macro Reference 241 242List Operations 243=============== 244 245 - Macro: list ([ELEMENT,...]) 246 Returns a list containing all specified ELEMENTs in the specified 247 order, beginning with index 0. Note that `%list()' returns an empty 248 list while `%list(%'')' returns a list with one element, which is 249 the empty string. 250 251 - Macro: llength (LIST) 252 Returns the number of elements in the list LIST. 253 254 - Macro: linsert (LIST,INDEX,ELEMENT) 255 Inserts the element ELEMENT into the list LIST at index INDEX. If 256 INDEX is greater or equal the length of LIST, the list is enlarged 257 by appending empty strings. Examples: 258 259 %<lst=%list(a,b,c)> 260 261 %linsert(%&lst,1,x)%encode(%lst) 262 => %list(%'a',%'x',%'b',%'c') 263 %linsert(%&lst,5,y)%encode(%lst) 264 => %list(%'a',%'x',%'b',%'c',%'',%'y') 265 266 - Macro: ldelete (LIST,INDEX) 267 Deletes from the list LIST the element at index INDEX. Example: 268 269 %<lst=%list(a,b,c)>%ldelete(%&lst,1)%encode(%lst) 270 => %list(%'a',%'c') 271 272 - Macro: lsort (LIST[,COMPARATOR]) 273 Sorts the elements of the list LIST, which should be strings, 274 according to the order specified by COMPARATOR, which must be a 275 closure taking two arguments and returning an integer. A return 276 value of `0' denotes that the two arguments are equal, less than 277 `0' means that the first argument should come before the second, 278 greater than `0' means that the first argument should come after 279 the second. If COMPARATOR is omitted, the macro `scmp' is used. 280 Returns the resulting list. Examples: 281 282 %encode(%lsort(%list(b,c,a))) 283 => %list(%'a',%'b',%'c') 284 %encode(%lsort(%list(b,c,a),%lambda(a,b,%scmp(%b,%a)))) 285 => %list(%'c',%'b',%'a') 286 287 - Macro: lappend (LIST,VALUE[,VALUE...]) 288 Appends all VALUEs to the list LIST. Returns nothing, i.e. is 289 called for its side effects, which means that the first parameter 290 should be a list to be modified, not a copy of a list. 291 292 - Macro: luniq (LIST[,COMPARATOR]) 293 Removes all but the first occurrences of all sequential 294 occurrences of the same element in LIST, where the sameness is 295 determined by the closure COMPARATOR, which must accept two 296 arguments and return a boolean value of TRUE if they are equal, 297 FALSE otherwise. If COMPARATOR is omitted, `seq' is used. Returns 298 the modified LIST. 299 300 %encode(%luniq(%list(a,b,b,c,d,e,e,e,f))) 301 => %list(%'a',%'b',%'c',%'d',%'e',%'f') 302 303 304File: chpp.info, Node: Hash Operations, Next: Environment Operations, Prev: List Operations, Up: Macro Reference 305 306Hash Operations 307=============== 308 309 - Macro: hash ([KEY,VALUE,...]) 310 Returns a hash containing all the specified key/value pairs. 311 312 - Macro: hcount (HASH) 313 Returns the number of key/value pairs in the hash HASH. 314 315 - Macro: hcontains (HASH,KEY) 316 Returns `1', if the key KEY is contained in the hash HASH. 317 Otherwise, returns `0'. 318 319 - Macro: hkeys (HASH) 320 Returns a list of all keys in the hash HASH in no particular order. 321 322 - Macro: hdelete (HASH,KEY) 323 Removes the key KEY from the hash HASH. Does nothing if KEY is not 324 contained in HASH. 325 326 %<h=%hash(a,1,b,2,c,3)> 327 %hdelete(%&h,b) 328 %encode(%h) 329 => %hash(%'a',%'1',%'c',%'3') 330 331 332File: chpp.info, Node: Environment Operations, Next: File Operations, Prev: Hash Operations, Up: Macro Reference 333 334Environment Operations 335====================== 336 337 - Macro: envThis () 338 Returns the environment which the macro is executed in. 339 340 - Macro: envNew ([PARENT]) 341 Returns a new environment. If PARENT is specified, it is used as 342 the parent to the newly created environment. Otherwise, the new 343 environment is a top-level environment, i.e. has no parent. 344 345 - Macro: envAdd (ENV,NAME,VALUE) 346 Adds a binding for the name NAME to the value VALUE to the 347 environment ENV. 348 349 350File: chpp.info, Node: File Operations, Next: String Operations, Prev: Environment Operations, Up: Macro Reference 351 352File Operations 353=============== 354 355 - Macro: fopen (FILENAME[,MODE]) 356 Opens the file named FILENAME and returns a handle to it. If the 357 file could not be opened, for example because it does not exists, 358 for lack of permission or if MODE is illegal, returns `-1'. MODE 359 describes for what purposes the file is opened and must be one of 360 the following: 361 362 `r' 363 Reading. 364 365 `w' 366 Writing. 367 368 `a' 369 Appending. 370 371 If MODE is omitted, the file is opened for reading. 372 373 - Macro: fpipe (MODE,EXECUTABLE[,ARG...]) 374 Forks off a child process, starts the specified executable with the 375 specified parameters. If MODE is `r', returns a handle for reading 376 the processes standard output. If MODE is `w', returns a handle 377 for writing to the processes standard input. Returns `-1' if 378 something goes wrong. Note that the arguments are not subject to 379 shell expansion, since the process does not start a subshell. If 380 you want shell expansion, you have to start a subshell explicitly. 381 For example, to list all files beginning with an `a': 382 383 %fpipe(r,/bin/sh,-c,ls a*) 384 385 386 - Macro: fclose (FILE) 387 Closes the file associated with the handle FILE. 388 389 - Macro: fgets (FILE) 390 Reads one line from the file associated with the handle FILE and 391 returns it. The newline character is included. 392 393 - Macro: fputs (FILE,STRING) 394 Writes STRING to the file associated with the handle FILE, which 395 must have been opened for writing. 396 397 - Macro: feof (FILE) 398 Returns boolean TRUE if the end of the file associated with the 399 handle FILE is reached, FALSE otherwise. 400 401 - Macro: fstat (FILENAME) 402 Returns a hash containing information on the file with name 403 FILENAME. Returns an empty hash if the file does not exist. 404 Otherwise, the hash contains values for the following keys: 405 406 `uid' 407 User ID of owner. 408 409 `gid' 410 Group ID of owner. 411 412 `size' 413 Size in bytes. 414 415 `blksize' 416 Blocksize for filesystem I/O. 417 418 `blocks' 419 Number of blocks allocated. 420 421 `atime' 422 Time of last access. 423 424 `mtime' 425 Time of last modification. 426 427 `ctime' 428 Time of last change. 429 430 All times are given in seconds since January 1, 1970, 00:00:00 431 GMT. For detailed description of these values see `stat(2)'. 432 433 - Macro: fgetwd () 434 Returns the current working directory. 435 436 - Macro: fchdir (PATH) 437 Changes the current working directory to PATH. 438 439 - Macro: fglob (PATTERN) 440 Matches the pattern string PATTERN using shell pattern matching 441 rules. Returns a list of all filenames matched or boolean FALSE if 442 no filenames could be matched or in case of an error. 443 444 %encode(%fglob(/b*)) 445 => %list(%'/bin',%'/boot') 446 447 448File: chpp.info, Node: String Operations, Next: Time Operations, Prev: File Operations, Up: Macro Reference 449 450String Operations 451================= 452 453 - Macro: smatch (REGEXP,STRING[,REGISTERS]) 454 Searches the string STRING for the first occurrence of the regular 455 expression REGEXP and returns the index of the first character of 456 this substring. If no match was found, returns `-1'. If REGISTERS 457 is specified, which must be a list, clears it and sets its 458 elements (beginning with 1) to the contents of the corresponding 459 submatches (parts of the regular expression enclosed by 460 parentheses). The element `0' is set to the whole match. For 461 example: 462 463 %<regs=%list()>\ 464 %smatch(%'\.([^.]*)$',alittlepicture.jpg,%®s) %regs[1] 465 => 14 jpg 466 467 - Macro: ssplit (REGEXP,STRING[,CONNECTOR]) 468 Splits the string STRING into parts separated by the regular 469 expression REGEXP. Returns a list containing these parts. If 470 CONNECTOR is specified, the parts that are inserted into the list 471 are generated by invocations of CONNECTOR. CONNECTOR is always 472 called with three parameters, the first being the registers of 473 REGEXP for the match right before the string and the third being 474 the registers of the match right after the string. The second 475 parameter is the string itself. For the very first string, the 476 first parameter is an empty list, whereas for the last string, the 477 third parameter is an empty list. Thus 478 479 %ssplit(%regex,%string) 480 481 is equivalent to 482 483 %ssplit(%regex,%string,%lambda(a,b,c,%b)) 484 485 Example: 486 487 %encode(%ssplit(:+,foo::bar:rules)) 488 => %list(%'foo',%'bar',%'rules') 489 490 - Macro: stokenize (REGEXP,STRING[,TOKENER]) 491 Returns a list containing all substrings of STRING matching 492 REGEXP. If TOKENER is specified, not the whole matches are 493 inserted into the result list, but the results of calling TOKENER 494 with the respective lists of registers of the matches. This means, 495 that these two calls have the same result: 496 497 %stokenize(%regexp,%string) 498 %stokenize(%regexp,%string,%lambda(r,%r[0])) 499 500 Examples: 501 502 %encode(%stokenize([a-zA-Z0-9]+,%' a bc d04 d fsfd, rwe')) 503 => %list(%'a',%'bc',%'d04',%'d',%'fsfd',%'rwe') 504 %encode(%stokenize(%'-([0-9]+)-',%' -32- -- 543 -12--43--', 505 %lambda(r,%r[1]))) 506 => %list(%'32',%'12',%'43') 507 508 - Macro: sgsub (REGEXP,STRING,REPLACEMENT[,OPTIONS]) 509 Replaces all occurrences of the regular expression REGEXP in 510 STRING. If REPLACEMENT is a string, the occurrences are replaced 511 with this string. Otherwise, REPLACEMENT must be a closure taking 512 one argument and returning a string. In this case, the occurrences 513 are replaced by the result of the closure when called with a list 514 containing the regular expression registers in elements beginning 515 with `1' and the whole match in element `0'. OPTIONS, if 516 specified, should be a string composed of one or more of the 517 following characters: 518 519 `i' 520 Match case insensitively. The default is case-sensitive 521 matching. 522 523 Examples: 524 525 %sgsub(ei,HEINZI Deinzi,!,i) 526 => H!NZI D!nzi 527 %sgsub(a+,abaacaaadaaaa,%lambda(r,%slength(%r[0]))) 528 => 1b2c3d4 529 530 - Macro: sremovews (STRING) 531 Returns a string which results from removing all leading and 532 trailing whitespace from the string STRING. 533 534 - Macro: slength (STRING) 535 Returns the length of the string STRING. 536 537 - Macro: ssub (STRING,START[,LENGTH]) 538 Returns a substring of the string STRING. If it is called with two 539 arguments and START is positive, then the substring beginning with 540 index START is returned. If START is negative, the last -START 541 characters are returned. If called with two arguments, START 542 specifies the index of the first character in the substring. If 543 LENGTH is positive, it specifies the length of substring. If it is 544 negative, then -LENGTH specifies the index of the character 545 following the last character of the substring. Examples: 546 547 %substring(0123456789,3) 548 => 3456789 549 %substring(0123456789,-3) 550 => 789 551 %substring(0123456789,2,3) 552 => 234 553 %substring(0123456789,2,-5) 554 => 234 555 556 - Macro: scmp (STRING1,STRING2) 557 Returns the result of the `strcmp()' C function with STRING1 and 558 STRING2. 559 560 - Macro: schr (CODE) 561 Returns a string with the character with character code CODE. 562 563 - Macro: snumber (NUMBER,BASE) 564 Formats the decimal integer NUMBER according to the given base 565 BASE, which must be between 2 and 36 inclusive. Example: 566 567 %snumber(34,2) 568 => 100010 569 %snumber(-255,16) 570 => -ff 571 572 - Macro: srange (CHAR1,CHAR2) 573 Generates a string by concatenating all characters between and 574 including CHAR1 and CHAR2. Example: 575 576 %srange(a,f) 577 => abcdef 578 579 - Macro: smap (SRC,DEST,STR) 580 Returns a string where all characters of the string STR included 581 in SRC are translated to characters at the same position in DEST. 582 SRC and DEST must be strings of the same length. Example: 583 584 %smap(%srange(a,z),%srange(A,Z),Heinzi Deinzi) 585 => HEINZI DEINZI 586 587 588File: chpp.info, Node: Time Operations, Next: Miscellaneous, Prev: String Operations, Up: Macro Reference 589 590Time Operations 591=============== 592 593 Time values are represented in `chpp' by hashes containing values 594for some of the following keys: 595 596`year' 597 598`month' 599 600`day' 601 602`hour' 603 604`minute' 605 606`second' 607 - Macro: timeUNIX () 608 Returns the current time in UNIX `time_t' format. 609 610 %timeUNIX() 611 => 917465546 612 613 - Macro: timeUNIX2Hash (UTIME) 614 Returns a time hash that corresponds to the UNIX time UTIME. 615 616 %<(%timeUNIX2Hash(917465546)){year}> 617 => 1999 618 619 - Macro: timeHash2UNIX (HTIME) 620 Returns the UNIX time corresponding to the time hash HTIME. The 621 hash must contain sane values for at least the keys `second', 622 `minute', `hour', `day', `month' and `year'. 623 624 625File: chpp.info, Node: Miscellaneous, Prev: Time Operations, Up: Macro Reference 626 627Miscellaneous 628============= 629 630 - Macro: void (EXPR) 631 Executes EXPR but discard the result. Example: 632 633 %<regs=%list()>\ 634 %void(%smatch(%'\.([^.]*)$',alittlepicture.jpg,%®s))%regs[1] 635 => jpg 636 637 - Macro: outputenable (FLAG) 638 If the boolean value of FLAG is TRUE, enables output, otherwise 639 disables it. If output is disabled, everything is evaluated as 640 usual, but `chpp' does not output anything. 641 642 - Macro: depend (DEPENDENCY[,TARGET]) 643 Adds the filename DEPENDENCY to the list of dependencies for the 644 file TARGET. If TARGET is not specified, the name of the output 645 file is used. 646 647 - Macro: warning (MESSAGE) 648 Causes `chpp' to give a warning with the message MESSAGE. 649 650 - Macro: error (MESSAGE) 651 Causes `chpp' to signal an error with the message MESSAGE. 652 653 - Macro: encode (VALUE) 654 Returns a string which, upon evaluation, yields a value equal to 655 VALUE. 656 657 - Macro: random (LIMIT) 658 Returns a random number in the interval 0 to LIMIT-1. The random 659 number are uniformly distributed. 660 661 - Macro: same (VAL1,VAL2) 662 Returns `1' if VAL1 and VAL2 refer to the same value, otherwise 663 `0'. Two values are the same if a change in one entails the same 664 change in the other, i.e. if they occupy the same memory location. 665 Examples: 666 667 %<val=abc>%same(%val,%val) 668 => 0 669 %<val=abc>%same(%&val,%&val) 670 => 1 671 %<val=abc>%<val2=%&val>%same(%&val,%&val2) 672 => 1 673 674 - Macro: equal (VAL1,VAL2) 675 Returns `1' if VAL1 is equal to VAL2, otherwise `0'. Two scalars 676 are equal if the strings they contain are equal. Two lists are 677 equal if they have the same length and contain equal elements. Two 678 hashes are equal if they have the same count and the same keys map 679 to equal values. 680 681 %equal(%list(a,b,c),%list(a,b,c)) 682 => 1 683 %equal(%hash(a,1,b,2,c,3),%hash(c,3,b,2,a,1)) 684 => 1 685 %equal(%list(a,b,c),%list(1,2,3)) 686 => 0 687 688 - Macro: typeof (VALUE) 689 Returns the type of VALUE. The result can be one of `scalar', 690 `list', `hash', `lambda', `built-in'. 691 692 %typeof(abc) 693 => scalar 694 %typeof(%list(a,b,c)) 695 => list 696 %typeof(%hash(a,1,b,2,c,3)) 697 => hash 698 %typeof(%lambda(a,%a%a)) 699 => lambda 700 %typeof(%typeof) 701 => built-in 702 703 - Macro: bound (NAME) 704 Returns `1' if the name NAME is bound in the current environment. 705 If not, returns `0'. 706 707 - Macro: apply (LAMBDA,ARGLIST) 708 Calls LAMBDA with the elements of ARGLIST as arguments. 709 710 %apply(%lambda(a,b,c,my args are %a %b %c),%list(1,2,3)) 711 => my args are 1 2 3 712 713 - Macro: eval (CODE[,ENV]) 714 Evaluates the code CODE in the the environment ENV or in the local 715 environment if ENV is not specified. 716 717 %let(a,xyz,%eval(%%a)) 718 => xyz 719 %let(e,%envNew(),%envAdd(%&e,a,xyz)%eval(%%a,%&e)) 720 => xyz 721 722 - Macro: not (EXPR) 723 Returns the negation of the boolean value of EXPR, i.e. returns 724 `1' if EXPR is FALSE and `0' if EXPR is TRUE. 725 726 - Macro: shexencode (STRING) 727 Translates the bytes of STRING to a sequence of hexadecimal digits. 728 729 %shexencode(hello world!) 730 => 68656C6C6F20776F726C6421 731 732 - Macro: shexdecode (STRING) 733 Translates a sequence of hexadecimal digits as produced by 734 `shexencode' to a string. 735 736 %shexdecode(68656C6C6F20776F726C6421) 737 => hello world! 738 739 740File: chpp.info, Node: Internal Variables, Next: Package Reference, Prev: Macro Reference, Up: Top 741 742Internal Variables 743****************** 744 745 - Variable: outputenabled 746 Is `1' if output is enabled, `0' otherwise. Output can be enabled 747 and disabled with the macro `outputenable'. 748 749 - Variable: dependencing 750 Is `1' if `chpp' was started to generate dependencies (option 751 `--generate-dependencies'), `0' otherwise. 752 753 - Variable: mainfilename 754 Is set to the filename of the currently executed top-level source 755 file. 756 757 - Variable: env 758 Is a hash containing all environment variables of the process. 759 760 %env{TERM} 761 => xterm 762 763 764File: chpp.info, Node: Package Reference, Next: Macro Index, Prev: Internal Variables, Up: Top 765 766Packages 767******** 768 769* Menu: 770 771* files.chh:: 772* strings.chh:: 773* list.chh:: 774* time.chh:: 775* sql.chh:: 776* cgi.chh:: 777* w3lib.chh:: 778 779 780File: chpp.info, Node: files.chh, Next: strings.chh, Prev: Package Reference, Up: Package Reference 781 782`files.chh' 783=========== 784 785 - Macro: frest (FILE) 786 Returns the not yet read contents of the file associated with the 787 handle FILE. 788 789 - Macro: fwholefile (FILENAME) 790 Returns the whole contents of the file with the name FILENAME. 791 792 - Macro: fneweras (FILENAME1,FILENAME2) 793 Returns `1' if the modification time of the file with name 794 FILENAME1 is more recent than that of the file with name FILENAME2 795 or if the file with name FILENAME2 does not exist. Returns 0 796 otherwise. 797 798 799File: chpp.info, Node: strings.chh, Next: list.chh, Prev: files.chh, Up: Package Reference 800 801`strings.chh' 802============= 803 804 - Macro: replacesubstring (STRING,START,LENGTH,REPLACEMENT) 805 Returns a string resulting from replacing the substring starting at 806 index START with length LENGTH of STRING by the string REPLACEMENT. 807 808 - Macro: strneq (STRING1,STRING2) 809 Returns a boolean value of TRUE if STRING1 and STRING2 are not 810 equal, otherwise TRUE. 811 812 813File: chpp.info, Node: list.chh, Next: time.chh, Prev: strings.chh, Up: Package Reference 814 815`list.chh' 816========== 817 818 - Macro: listSearch (LIST,CRITERION) 819 Returns the index of the first element of LIST for which the 820 closure CRITERION, when called with that element as parameter, 821 evaluates to boolean TRUE. Example 822 823 %listSearch(%list(a,bb,ccc,dddd),%lambda(e,%[%slength(%e)>=3])) 824 => 2 825 826 - Macro: listIndexOf (LIST,VALUE) 827 Returns the index of the first element of LIST which is `equal' to 828 VALUE. Example: 829 830 %listIndexOf(%list(a,b,c,d),b) 831 => 1 832 833 - Macro: listMap (MAPPING,LIST[,LIST...]) 834 All LISTs must have the same length, and MAPPING must be a closure 835 taking as many arguments as there are LISTs. `listMap' creates a 836 new list by applying MAPPING element-wise to the elements of the 837 LISTs and storing the results in the corresponding elements of the 838 resulting list. Example: 839 840 %listMap(%lambda(a,b,%[a+b]),%list(2,5,7),%list(4,2,9)) 841 => %list(%'6',%'7',%'16') 842 843 - Macro: listLeftAccumulate (ACCUMULATOR,LIST,ZERO) 844 If the length of LIST is `0', returns ZERO. Otherwise, accumulates 845 all elements of LIST through ACCUMULATOR, which must be a closure 846 taking two arguments, in a left-associative way. Examples: 847 848 %listLeftAccumulate(%lambda(a,b,%[a+b]),%list(1,2,3),0) 849 => 6 850 %listLeftAccumulate(%lambda(a,b,acc%'('%a%','%b%')'), 851 %list(a,b,c),zero) 852 => acc(acc(a,b),c) 853 854 - Macro: listRightAccumulate (ACCUMULATOR,LIST,ZERO) 855 If the length of LIST is `0', returns ZERO. Otherwise, accumulates 856 all elements of LIST through ACCUMULATOR, which must be a closure 857 taking two arguments, in a right-associative way. Examples: 858 859 %listRightAccumulate(%lambda(a,b,acc%'('%a%','%b%')'), 860 %list(a,b,c),zero) 861 => acc(a,acc(b,c)) 862 863 - Macro: listJoin (STRING,LIST) 864 Joins the elements of the list LIST by inserting between two 865 sequential elements the string STRING. Example: 866 867 %listJoin(:,%list(the,quick,brown,fox)) 868 => the:quick:brown:fox 869 870 871File: chpp.info, Node: time.chh, Next: sql.chh, Prev: list.chh, Up: Package Reference 872 873`time.chh' 874========== 875 876 - Macro: timeNow () 877 Returns a time hash for the current time. 878 879 - Macro: timeToString (FORMAT,TIME) 880 Converts a time value to a string according to the format string 881 FORMAT. Ordinary characters in FORMAT are copied verbatim, while 882 the dollar character (`$'), followed by any of the following 883 characters is treated specially: 884 885 `$' 886 The character `$'. 887 888 `d' 889 The day of the month as a decimal number, beginning with `1' 890 for the first day of the month. 891 892 `m' 893 The month as a decimal number, beginning with `1' for January. 894 895 `b' 896 The abbreviated month name. 897 898 `B' 899 The full month name. 900 901 `Y' 902 The year as a decimal number. 903 904 `H' 905 The hour as a decimal number (range `0' to `23'). 906 907 `M' 908 The minute as a decimal number (range `0' to `59'). 909 910 `S' 911 The second as a decimal number (range `0' to `59'). 912 913 Example: 914 915 %timeToString($d $B $Y,%hash(day,29,month,12,year,1975)) 916 => 29 December 1975 917 918 - Macro: timeFromString (FORMAT,STRING) 919 Converts the string STRING, which must obey the time format 920 FORMAT, as described above, to a time value. Example: 921 922 %encode(%timeFromString($d $B $Y,29 December 1975)) 923 => %hash(%'year',%'1975',%'day',%'29',%'month',%'12') 924 925 926File: chpp.info, Node: sql.chh, Next: cgi.chh, Prev: time.chh, Up: Package Reference 927 928`sql.chh' 929========= 930 931 This section describes `chpp''s interface to relational databases, 932called `chdbc' (`chpp' Database Connectivity). The interface is a layer 933above the client libraries for the various database servers, making it 934thus transparent to the user which database she is using. 935 936 Connections and results are represented by abstract datatypes. When 937passing a connection or result to a `chdbc' macro, do always pass the 938value which was returned by the creating macro, not a copy (i.e. use 939the reference form of variable access (*note Accessing Variables::.) to 940pass connection and result parameters). 941 942 Drivers are currently implemented for mSQL and MySQL. The latter 943takes a connection hash with keys `user' and `password'. 944 945 - Macro: sqlConnect (URL,HASH) 946 Opens a connection to the SQL Server with the given URL, which 947 needs to be of the form 948 `chdbc:'DRIVERNAME`://'HOSTNAME[`:'PORT]`/'DBNAME`/'. A valid 949 example would be `chdbc:mysql://localhost/test/'. HASH must be 950 hash containing information required by the driver to connect to 951 the server, e.g. username and password. `sqlConnect' returns a 952 value representing the connection to the server or a boolean value 953 of FALSE if the connection could not be made. 954 955 - Macro: sqlClose (CONNECTION) 956 Closes the database connection CONNECTION. 957 958 - Macro: sqlDatabaseInfo (CONNECTION) 959 Returns a hash containing information about the database. The hash 960 contains values for the following keys, if appropriate for the 961 database: 962 963 `timeformat' 964 Format for time values which can be used in inserts and 965 updates, like `$H:$M:$S'. 966 967 `dateformat' 968 Format for date values which can be used in inserts and 969 updates, like `$Y-$m-$d'. 970 971 `datetimeformat' 972 Format for time plus date values which can be used in inserts 973 and updates, like `$Y-$m-$d $H:$M:$S'. 974 975 - Macro: sqlQuery (CONNECTION,QUERYSTRING) 976 Performs a query on the database connected to by CONNECTION. 977 Returns a value representing the result of the query or a boolean 978 value of FALSE if the query could not be executed. 979 980 - Macro: sqlResultData (RESULT) 981 Returns the result rows of the query result RESULT, as obtained by 982 `sqlQuery', in the form of a list. Each row in this list is 983 represented as a hash whose keys are the column names of the 984 result. Values for columns representing time (`time', `date' and 985 `datetime') are automatically converted to `chpp''s time format 986 (*note time.chh::.). 987 988 - Macro: sqlResultColumnInfo (RESULT) 989 Returns a hash indexed by the column names of the query result 990 RESULT containing information about the columns. Each value 991 contained in the hash is a hash containing values for the following 992 keys: 993 994 `type' 995 Type of the column. 996 997 - Macro: sqlResultColumnNames (RESULT) 998 Returns a list containing the names of the column of the query 999 result RESULT. 1000 1001 - Macro: sqlUpdate (CONNECTION,UPDATESTRING) 1002 Performs an SQL statement contained in the string UPDATESTRING 1003 changing the data of the database connected to by CONNECTION, like 1004 an insert or an update. 1005 1006 1007File: chpp.info, Node: cgi.chh, Next: w3lib.chh, Prev: sql.chh, Up: Package Reference 1008 1009`cgi.chh' 1010========= 1011 1012 The package `cgi.chh' provides rudimentary support for CGI scripting. 1013 1014 - Macro: cgiGetParameters () 1015 Returns a hash containing all parameters passed to the CGI script. 1016 Supported encodings are `application/x-www-form-urlencoded' (both 1017 `GET' and `POST') and `multipart/form-data'. 1018 1019 1020File: chpp.info, Node: w3lib.chh, Prev: cgi.chh, Up: Package Reference 1021 1022`w3lib.chh' 1023=========== 1024 1025 This package provides rudimentary support for web page building. It 1026requires the program `xli' to parse picture files. 1027 1028 There is some experimental JavaScript code in `w3lib.chh', but 1029nothing is used by now. If you are a JavaScript guru you might want to 1030code a bit? 1031 1032 - Variable: w3xliExecutable 1033 If set before `w3lib.chh' is included, it will use this as full 1034 path to the `xli' program. 1035 1036 - Macro: w3img (IMAGENAME,[ARG...]) 1037 - Macro: w3image (IMAGENAME,[ARG...]) 1038 Generates an `img' tag for IMAGENAME. If ARGs are supplied the 1039 will be added at the end of the `img' tag. `w3img' takes care of 1040 dependencies. 1041 1042 - Macro: w3imgX (IMAGENAME) 1043 - Macro: w3imgWidth (IMAGENAME) 1044 Returns the width of the image IMAGENAME. Takes care of 1045 dependencies. 1046 1047 - Macro: w3imgY (IMAGENAME) 1048 - Macro: w3imgHeight (IMAGENAME) 1049 Returns the height of the image IMAGENAME. Takes care of 1050 dependencies. 1051 1052 - Macro: w3rgbcolor (RED,GREEN,BLUE) 1053 Returns an HTML conforming color value string. 1054 1055 `w3lib.chh' is intended to be used together with `make'. A simple 1056`Makefile' may look like this: 1057 1058 # chpp Makefile for web pages 1059 1060 HTML = Main.html News.html Authors.html Manual.html Wizard.html \ 1061 Download.html Links.html 1062 1063 # --- general 1064 ---------------------------------------------------------------- 1065 1066 all : $(HTML) 1067 1068 clean : 1069 rm -f *.d *.jpgd *.gifd *.pngd *.html core *~ 1070 1071 # --- chpp dependencies 1072 ------------------------------------------------------ 1073 1074 %.html : %.csml 1075 chpp $< > $ 1076 %.d : %.csml 1077 chpp -M -o $(<:.csml=.html) $< > $ 1078 # --- includes 1079 --------------------------------------------------------------- 1080 1081 -include $(HTML:.html=.d) 1082 1083 1084File: chpp.info, Node: Macro Index, Prev: Package Reference, Up: Top 1085 1086Macro Index 1087*********** 1088 1089* Menu: 1090 1091* and: Special Forms. 1092* apply: Miscellaneous. 1093* bound: Miscellaneous. 1094* case: Special Forms. 1095* cgiGetParameters: cgi.chh. 1096* cond: Special Forms. 1097* define <1>: Special Forms. 1098* define: Command Reference. 1099* defspecial: Special Forms. 1100* depend: Miscellaneous. 1101* disc: Command Reference. 1102* discard: Command Reference. 1103* dountil: Special Forms. 1104* dowhile: Special Forms. 1105* encode: Miscellaneous. 1106* envAdd: Environment Operations. 1107* envNew: Environment Operations. 1108* envThis: Environment Operations. 1109* equal: Miscellaneous. 1110* error <1>: Miscellaneous. 1111* error: Command Reference. 1112* eval: Miscellaneous. 1113* fchdir: File Operations. 1114* fclose: File Operations. 1115* feof: File Operations. 1116* fgets: File Operations. 1117* fgetwd: File Operations. 1118* fglob: File Operations. 1119* fneweras: files.chh. 1120* fopen: File Operations. 1121* for: Special Forms. 1122* foreach: Special Forms. 1123* foreachkey: Special Forms. 1124* fpipe: File Operations. 1125* fputs: File Operations. 1126* frest: files.chh. 1127* fstat: File Operations. 1128* fwholefile: files.chh. 1129* hash: Hash Operations. 1130* hcontains: Hash Operations. 1131* hcount: Hash Operations. 1132* hdelete: Hash Operations. 1133* hkeys: Hash Operations. 1134* if <1>: Special Forms. 1135* if: Command Reference. 1136* ifdef: Command Reference. 1137* ifdefined: Command Reference. 1138* ifndef: Command Reference. 1139* ifnotdefined: Command Reference. 1140* include: Command Reference. 1141* lambda: Special Forms. 1142* lappend: List Operations. 1143* ldelete: List Operations. 1144* let: Special Forms. 1145* linsert: List Operations. 1146* list: List Operations. 1147* listIndexOf: list.chh. 1148* listJoin: list.chh. 1149* listLeftAccumulate: list.chh. 1150* listMap: list.chh. 1151* listRightAccumulate: list.chh. 1152* listSearch: list.chh. 1153* llength: List Operations. 1154* locals: Special Forms. 1155* lsort: List Operations. 1156* luniq: List Operations. 1157* not: Miscellaneous. 1158* or: Special Forms. 1159* outputenable: Miscellaneous. 1160* random: Miscellaneous. 1161* replacesubstring: strings.chh. 1162* same: Miscellaneous. 1163* schr: String Operations. 1164* scmp: String Operations. 1165* sgsub: String Operations. 1166* shexdecode: Miscellaneous. 1167* shexencode: Miscellaneous. 1168* slength: String Operations. 1169* smap: String Operations. 1170* smatch: String Operations. 1171* snumber: String Operations. 1172* sqlClose: sql.chh. 1173* sqlConnect: sql.chh. 1174* sqlDatabaseInfo: sql.chh. 1175* sqlQuery: sql.chh. 1176* sqlResultColumnInfo: sql.chh. 1177* sqlResultColumnNames: sql.chh. 1178* sqlResultData: sql.chh. 1179* sqlUpdate: sql.chh. 1180* srange: String Operations. 1181* sremovews: String Operations. 1182* ssplit: String Operations. 1183* ssub: String Operations. 1184* stokenize: String Operations. 1185* strneq: strings.chh. 1186* timeFromString: time.chh. 1187* timeHash2UNIX: Time Operations. 1188* timeNow: time.chh. 1189* timeToString: time.chh. 1190* timeUNIX: Time Operations. 1191* timeUNIX2Hash: Time Operations. 1192* typeof: Miscellaneous. 1193* until: Special Forms. 1194* void: Miscellaneous. 1195* w3image: w3lib.chh. 1196* w3img: w3lib.chh. 1197* w3imgHeight: w3lib.chh. 1198* w3imgWidth: w3lib.chh. 1199* w3imgX: w3lib.chh. 1200* w3imgY: w3lib.chh. 1201* w3rgbcolor: w3lib.chh. 1202* warning: Miscellaneous. 1203* while: Special Forms. 1204 1205 1206
