tut.html (87833B)
1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" "http://www.w3.org/TR/1998/REC-html40-19980424/loose.dtd"> 2 <html lang="en"> 3 <head> 4 <meta http-equiv="Content-Type" content="text/html; charset=utf-8"> 5 <title>PicoLisp Tutorial</title> 6 <link rel="stylesheet" href="doc.css" type="text/css"> 7 </head> 8 <body> 9 <a href="mailto:abu@software-lab.de">abu@software-lab.de</a> 10 11 <h1>A PicoLisp Tutorial</h1> 12 13 <p align=right>(c) Software Lab. Alexander Burger 14 15 <h3>About this document</h3> 16 17 <p>This document demonstrates some aspects of the PicoLisp system in detail and 18 example. For a general description of the PicoLisp kernel please look at the <a 19 href="ref.html">PicoLisp Reference</a>. 20 21 <p>This is <i>not</i> a Lisp tutorial, as it assumes some basic knowledge of 22 programming, Lisp, and even PicoLisp. Please read these sections before coming 23 back here: <a href="ref.html#intro">Introduction</a> and <a 24 href="ref.html#vm">The PicoLisp Machine</a>. This tutorial concentrates on the 25 specificities of PicoLisp, and its differences with other Lisp dialects. 26 27 <h3>Now let's start</h3> 28 29 <p>If not stated otherwise, all examples assume that PicoLisp was started from a 30 global installation (see <a href="ref.html#inst">Installation</a>) from the 31 shell prompt as 32 33 <pre><code> 34 $ pil + 35 : 36 </code></pre> 37 38 <p>It loads the PicoLisp base system and the debugging environment, and waits 39 for you to enter input lines at the interpreter prompt (<code>:</code>). You can 40 terminate the interpreter and return to the shell at any time, by either hitting 41 the <code>Ctrl-D</code> key, or by executing the function <code><a 42 href="refB.html#bye">(bye)</a></code>. 43 44 <p>Please note that special handling is done during character input. This one 45 is incompatible with <code>rlwrap</code> for example but is more powerful. 46 <p><ul> 47 <li><code>vi</code>-like command-line editing (typos fixes and history with ESC, 48 <code>h</code>, <code>j</code>, <code>k</code> and <code>l</code> but not 49 arrows),</li> 50 <li>auto-formating (underlined) of double-quoted strings (don't try and struggle 51 to make <code>"</code> appear).</li> 52 </ul> 53 54 <p>If you prefer to use Emacs, please use the picolisp-mode bundled in the "el/" 55 directory (that is "@lib/el" for a local installation, or some system dependent 56 directory for a global installation). 57 58 <p>If you feel that you absolutely have to use an IDE, <code>rlwrap</code> or 59 another input front-end, please create an empty "~/.pil/editor" file. This 60 effectively disables the command line editor. Note that in this case, however, 61 you will not have the TAB symbol completion feature available during command 62 line editing. 63 64 <h3>Table of content</h3> 65 66 <p>If you are new to PicoLisp, you might want to read the following sections in 67 the given order, as some of them assume knowledge about previous ones. Otherwise 68 just jump anywhere you are interested in. 69 70 <p><ul> 71 <li><a href="#ledit">Command Line Editing</a> 72 <ul> 73 <li><a href="#vi-style">'vi'-style</a> 74 <li><a href="#em-style">'emacs'-style</a> 75 </ul> 76 <li><a href="#brw">Browsing</a> 77 <li><a href="#fun">Defining Functions</a> 78 <li><a href="#dbg">Debugging</a> 79 <li><a href="#funio">Functional I/O</a> 80 <li><a href="#script">Scripting</a> 81 <li><a href="#oop">Objects and Classes</a> 82 <li><a href="#ext">Persistence (External Symbols)</a> 83 <li><a href="#db">Database Programming</a> 84 <li><a href="#gui">User Interface (GUI) Programming</a> 85 <li><a href="#pilog">Pilog -- PicoLisp Prolog</a> 86 <li><a href="#sql">Poor Man's SQL</a> 87 <li><a href="#ref">References</a> 88 </ul> 89 90 91 <p><hr> 92 <h2><a name="ledit">Command Line Editing</a></h2> 93 94 <p>PicoLisp permanently reads input from the current input channel (i.e. the 95 console in interactive mode), evaluates it, and prints the result to the current 96 output channel. This is called a "read-eval-print-loop" (REPL). 97 98 <h3><a name="vi-style">'vi'-style</a></h3> 99 100 <p>This is the default line editor, as it needs less system resources and works 101 also on dumb terminals. It is similar to - though simpler than - the 'vi' edit 102 modes of the 'korn' and 'bash' shells. For an analog 'emacs' style editor, 103 please see <a href="#em-style">below</a>. 104 105 <p>It is very helpful - though not absolutely necessary - when you know how to 106 use the <code>vi</code> text editor. 107 108 <p>To alleviate the task of manual line input, a command line editor is provided 109 which is similar to (though much simpler than) the <code>readline</code> feature 110 of the <code>bash</code> shell. Only a subset of the <code>vi</code> mode is 111 supported, which is restricted to single-key commands (the "real" 112 <code>vi</code> supports multi-key commands and the modification of most 113 commands with count prefixes). It is loaded at startup in debug mode, you find 114 its source in "lib/led.l". 115 116 <p>You can enter lines in the normal way, correcting mistypes with the BACKSPACE 117 key, and terminating them with the ENTER key. This is the <i>Insert Mode</i>. 118 119 <p>If you hit ESC, you get into <i>Command Mode</i>. Now you can navigate 120 horizontally in the current input line, or vertically in the history of 121 previously entered lines, with key commands borrowed from the <code>vi</code> 122 editor (only <code>h</code>, <code>j</code>, <code>k</code> and <code>l</code> 123 and not arrows). Note, however, that there is always only a single line visible. 124 125 <p>Let's say you did some calculation 126 127 <pre><code> 128 : (* (+ 2 3) (- 7 2)) 129 -> 25 130 : 131 </code></pre> 132 133 <p>If you want to repeat a modified version of this command, using 134 <code>8</code> instead of <code>7</code>, you don't have to re-type the 135 whole command, but type 136 137 <p><ul> 138 <li>ESC to get into <i>Command Mode</i> 139 <li><code>k</code> to get one line "up" 140 <li><code>f</code> and <code>7</code> to "find" the character <code>7</code> 141 <li><code>r</code> and <code>8</code> to "replace" with <code>8</code> 142 </ul> 143 144 <p>Then you hit ENTER to execute the modified line. Instead of jumping to the 145 <code>7</code> with the "find" command, you may also type <code>l</code> (move 146 "right") repeatedly till you reach the correct position. 147 148 <p>The key commands in the <i>Command Mode</i> are listed below. Some commands 149 change the mode back to <i>Insert Mode</i> as indicated in parentheses. Deleting 150 or changing a "word" take either the current atom (number or symbol), or a whole 151 expression when the cursor is at a left parenthesis. 152 153 <p><ul> 154 <li><code>k</code> - Go up one line 155 <li><code>j</code> - Go down one line 156 <li><code>l</code> - Go right one character 157 <li><code>h</code> - Go left one character 158 <li><code>w</code> - Go right one word 159 <li><code>b</code> - Go back (left) one word 160 <li><code>0</code> - Go to the beginning of the line 161 <li><code>$</code> - Go to the end of the line 162 <li><code>i</code> - Enter <i>Insert Mode</i> at the cursor position 163 <li><code>a</code> - Append (<i>Insert Mode</i>) after the cursor position 164 <li><code>A</code> - Append (<i>Insert Mode</i>) at the end of the line 165 <li><code>I</code> - Insert (<i>Insert Mode</i>) at the beginning of the line 166 <li><code>x</code> - Delete the character at the cursor position 167 <li><code>X</code> - Delete the character left of the cursor position 168 <li><code>r</code> - Replace the character at the cursor position with the next key 169 <li><code>s</code> - Substitute the character at the cursor position (<i>Insert Mode</i>) 170 <li><code>S</code> - Substitute the whole line (<i>Insert Mode</i>) 171 <li><code>d</code> - Delete the word at the cursor position (<i>Insert Mode</i>) 172 <li><code>D</code> - Delete the rest of the line 173 <li><code>c</code> - Change the word at the cursor position (<i>Insert Mode</i>) 174 <li><code>C</code> - Change the rest of the line (<i>Insert Mode</i>) 175 <li><code>f</code> - Find next key in the rest of the current line 176 <li><code>p</code> - Paste data deleted with <code>x</code>, <code>X</code>, <code>d</code> or <code>D</code> after the cursor position 177 <li><code>P</code> - Paste data deleted with <code>x</code>, <code>X</code>, <code>d</code> or <code>D</code> before the cursor position 178 <li><code>/</code> - Accept an input pattern and search the history for it 179 <li><code>n</code> - Search for next occurrence of pattern (as entered with <code>/</code>) 180 <li><code>N</code> - Search for previous occurrence of pattern 181 <li><code>%</code> - Go to matching parenthesis 182 <li><code>~</code> - Convert character to opposite (lower or upper) case and move right 183 <li><code>u</code> - Undo the last change (one level only) 184 <li><code>U</code> - Undo all changes of the current line 185 <li><code>g</code> - Display current contents of cut buffer (not in <code>vi</code>) 186 </ul> 187 188 <p>Notes: 189 <ul> 190 191 <li>The <code>d</code> command corresponds to the <code>dw</code> command of the 192 <code>vi</code> editor, and <code>c</code> corresponds to <code>cw</code>. 193 194 <li>Search patterns may contain "<code>@</code>" characters as wildcards. 195 196 <li>Lines shorter than 3 characters, lines beginning with a space character, or 197 duplicate lines are not entered into the history. 198 199 <li>The history is stored in the file ".pil/history" in the user's home 200 directory. The length of the history is limited to 1000 lines. 201 202 </ul> 203 204 <p>The following two key-combinations work both in Insert and Command Mode: 205 206 <p><ul> 207 208 <li><code>Ctrl-D</code> will immediately terminate the current process. 209 210 <li><code>Ctrl-X</code> discards all input, abandons further processing, and 211 returns to the interpreter's top level (equivalent to invoking <code><a 212 href="refQ.html#quit">quit</a></code>). This is also useful when the program 213 stopped at a breakpoint (see single-stepping <a href="#dbg">Debugging</a>), or 214 after program execution was interrupted with <code>Ctrl-C</code>. 215 216 </ul> 217 218 <p>Besides these two keys, in <i>Insert Mode</i> only the following keys have a 219 special meaning: 220 221 <p><ul> 222 223 <li>BACKSPACE (<code>Ctrl-H</code>) and DEL erase the character to the left 224 225 <li><code>Ctrl-V</code> inserts the next key literally 226 227 <li><code>Ctrl-E</code> lets you <code><a href="refE.html#edit">edit</a></code> 228 the history 229 230 <li>TAB performs symbol and/or path completion: When a symbol (or path) name is 231 entered partially and TAB is pressed subsequently, all internal symbols (and/or 232 path names in the file system) matching the partial input are shown in sequence. 233 234 <li>ESC terminates <i>Input Mode</i> and enters <i>Command Mode</i> 235 236 </ul> 237 238 <h3><a name="em-style">'emacs'-style</a></h3> 239 240 <p>You can switch the command line editor to an 'emacs' style, if you call the 241 function <code>(em)</code> (i.e. without arguments). A single call is enough. 242 Alternatively, you could invoke PicoLisp at least once with the <code>-em</code> 243 command line option 244 245 <pre><code> 246 $ pil -em + 247 : 248 </code></pre> 249 250 <p>The style will be remembered in a file "~/.pil/editor", and used in all 251 subsequent PicoLisp sessions. 252 253 <p>To switch back to 'vi' style, call <code>(vi)</code>, use the 254 <code>-vi</code> command line option, or simply remove "~/.pil/editor". 255 256 257 <h3>Conclusion</h3> 258 259 <p>Please take some time to experiment and to get used to command line editing. 260 It will make life much easier in the future :-) 261 262 263 <p><hr> 264 <h2><a name="brw">Browsing</a></h2> 265 266 <p>PicoLisp provides some functionality for inspecting pieces of data and code 267 within the running system. 268 269 <h3>Basic tools</h3> 270 271 The really basic tools are of course available and their name alone is enough 272 to know: 273 <code><a href="refP.html#print">print</a></code>, 274 <code><a href="refS.html#size">size</a></code> 275 ... 276 277 <p>But you will appreciate some more powerful tools like: 278 <p><ul><li><code><a href="refM.html#match">match</a></code>, a predicate which 279 compares S-expressions with bindable wildcards when matching,</li> 280 </ul> 281 282 <h3>Inspect a symbol with <i>show</i></h3> 283 284 <p>The most commonly used tool is probably the <code><a 285 href="refS.html#show">show</a></code> function. It takes a symbolic argument, 286 and shows the symbol's name (if any), followed by its value, and then the 287 contents of the property list on the following lines (assignment of such things 288 to a symbol can be done with <code><a href="refS.html#set">set</a></code>, 289 <code><a href="refS.html#setq">setq</a></code>, and <code><a 290 href="refP.html#put">put</a></code>). 291 292 <pre><code> 293 : (setq A '(This is the value)) # Set the value of 'A' 294 -> (This is the value) 295 : (put 'A 'key1 'val1) # Store property 'key1' 296 -> val1 297 : (put 'A 'key2 'val2) # and 'key2' 298 -> val2 299 : (show 'A) # Now 'show' the symbol 'A' 300 A (This is the value) 301 key2 val2 302 key1 val1 303 -> A 304 </code></pre> 305 306 <p><code>show</code> accepts an arbitrary number of arguments which are 307 processed according to the rules of <code><a 308 href="refG.html#get">get</a></code>, resulting in a symbol which is showed then. 309 310 <pre><code> 311 : (put 'B 'a 'A) # Put 'A' under the 'a'-property of 'B' 312 -> A 313 : (setq Lst '(A B C)) # Create a list with 'B' as second argument 314 -> (A B C) 315 : (show Lst 2 'a) # Show the property 'a of the 2nd element of 'Lst' 316 A (This is the value) # (which is 'A' again) 317 key2 val2 318 key1 val1 319 -> A 320 </code></pre> 321 322 <h3>Inspect and edit with <i>edit</i></h3> 323 324 <p>Similar to <code>show</code> is <code><a 325 href="refE.html#edit">edit</a></code>. It takes an arbitrary number of symbolic 326 arguments, writes them to a temporary file in a format similar to 327 <code>show</code>, and starts the <code>vim</code> editor with that file. 328 329 <pre><code> 330 : (edit 'A 'B) 331 </code></pre> 332 333 <p>The <code>vim</code> window will look like 334 335 <pre><code> 336 A (This is the value) 337 key1 val1 338 key2 val2 339 340 (********) 341 342 B NIL 343 a A # (This is the value) 344 345 (********) 346 </code></pre> 347 348 <p>Now you can modify values or properties. You should not touch the 349 parenthesized asterisks, as they serve as delimiters. If you position the cursor 350 on the first character of a symbol name and type '<code>K</code>' ("Keyword 351 lookup"), the editor will be restarted with that symbol added to the editor 352 window. '<code>Q</code>' (for "Quit") will bring you back to the previous view. 353 354 <p><code>edit</code> is also very useful to browse in a database. You can follow 355 the links between objects with '<code>K</code>', and even - e.g. for low-level 356 repairs - modify the data (but only if you are really sure about what you are 357 doing, and don't forget to <code><a href="refC.html#commit">commit</a></code> 358 when you are done). 359 360 <h3>Built-in pretty print with <i>pp</i></h3> 361 362 <p>The <i>pretty-print</i> function <code><a href="refP.html#pp">pp</a></code> 363 takes a symbol that has a function defined (or two symbols that specify message 364 and class for a method definition), and displays that definition in a formatted 365 and indented way. 366 367 <pre><code> 368 : (pp 'pretty) 369 (de pretty (X N . @) 370 (setq N (abs (space (or N 0)))) 371 (while (args) (printsp (next))) 372 (if (or (atom X) (>= 12 (size X))) 373 (print X) 374 (while (== 'quote (car X)) 375 (prin "'") 376 (pop 'X) ) 377 (let Z X 378 (prin "(") 379 (cond 380 ((memq (print (pop 'X)) *PP) 381 (cond 382 ((memq (car Z) *PP1) 383 (if (and (pair (car X)) (pair (cdar X))) 384 (when (>= 12 (size (car X))) 385 (space) 386 (print (pop 'X)) ) 387 (space) 388 (print (pop 'X)) 389 (when 390 (or 391 (atom (car X)) 392 (>= 12 (size (car X))) ) 393 (space) 394 (print (pop 'X)) ) ) ) 395 ((memq (car Z) *PP2) 396 (inc 'N 3) 397 (loop 398 (prinl) 399 (pretty (cadr X) N (car X)) 400 (NIL (setq X (cddr X)) (space)) ) ) 401 ((or (atom (car X)) (>= 12 (size (car X)))) 402 (space) 403 (print (pop 'X)) ) ) ) 404 ((and (memq (car Z) *PP3) (>= 12 (size (head 2 X)))) 405 (space) 406 (print (pop 'X) (pop 'X)) ) ) 407 (when X 408 (loop 409 (T (== Z X) (prin " .")) 410 (T (atom X) (prin " . ") (print X)) 411 (prinl) 412 (pretty (pop 'X) (+ 3 N)) 413 (NIL X) ) 414 (space) ) 415 (prin ")") ) ) ) 416 -> pretty 417 </code></pre> 418 419 <p>The style is the same as we use in source files: 420 421 <ul> 422 423 <li>The indentation level is three spaces 424 425 <li>If a list is too long (to be precise: if its <code><a 426 href="refS.html#size">size</a></code> is greater than 12), pretty-print the CAR 427 on the current line, and each element of the CDR recursively on its own line. 428 429 <li>A closing parenthesis a preceded by a space if the corresponding open 430 parenthesis is not on the same line 431 432 </ul> 433 434 <h3>Inspect elements one by one with <i>more</i></h3> 435 436 <p><code><a href="refM.html#more">more</a></code> is a simple tool that displays 437 the elements of a list one by one. It stops after each element and waits for 438 input. If you just hit ENTER, <code>more</code> continues with the next element, 439 otherwise (usually I type a dot (<code>.</code>) followed by ENTER) it 440 terminates. 441 442 <pre><code> 443 : (more (1 2 3 4 5 6)) 444 1 # Hit ENTER 445 2. # Hit '.' and ENTER 446 -> T # stopped 447 </code></pre> 448 449 <p>Optionally <code>more</code> takes a function as a second argument and 450 applies that function to each element (instead of the default <code><a 451 href="refP.html#print">print</a></code>). Here, often <code>show</code> or 452 <code>pp</code> (see below) is used. 453 454 <pre><code> 455 : (more '(A B)) # Step through 'A' and 'B' 456 A 457 B 458 -> NIL 459 : (more '(A B) show) # Step through 'A' and 'B' with 'show' 460 A (This is the value) # showing 'A' 461 key2 val2 462 key1 val1 463 # Hit ENTER 464 B NIL # showing 'B' 465 a A 466 -> NIL 467 </code></pre> 468 469 <h3>Search through available symbols with <i>what</i></h3> 470 471 <p>The <code><a href="refW.html#what">what</a></code> function returns a list of 472 all internal symbols in the system which match a given pattern (with 473 '<code>@</code>' wildcard characters). 474 475 <pre><code> 476 : (what "prin@") 477 -> (prin print prinl print> printsp println) 478 </code></pre> 479 480 <h3>Search through values or properties of symbols with <i>who</i></h3> 481 482 <p>The function <code><a href="refW.html#who">who</a></code> returns <i>"who 483 contains that"</i>, i.e. a list of symbols that contain a given argument 484 somewhere in their value or property list. 485 486 <pre><code> 487 : (who 'print) 488 -> (query pretty pp msg more "edit" view show (print> . +Date) rules select 489 (print> . +relation))</code></pre> 490 491 <p>A dotted pair indicates either a method definition or a property entry. So 492 <code>(print> . +relation)</code> denotes the <code>print></code> method of 493 the <code><a href="refR.html#+relation">+relation</a></code> class. 494 495 <p><code>who</code> can be conveniently combined with <code>more</code> and 496 <code>pp</code>: 497 498 <pre><code> 499 : (more (who 'print) pp) 500 (de query ("Q" "Dbg") # Pretty-print these functions one by one 501 (use "R" 502 (loop 503 (NIL (prove "Q" "Dbg")) 504 (T (=T (setq "R" @)) T) 505 (for X "R" 506 (space) 507 (print (car X)) 508 (print '=) 509 (print (cdr X)) 510 (flush) ) 511 (T (line)) ) ) ) 512 513 (de pretty (X N . @) 514 ... 515 </code></pre> 516 517 <p>The argument to <code>who</code> may also be a pattern list (see <code><a 518 href="refM.html#match">match</a></code>): 519 520 <pre><code> 521 : (who '(print @ (val @))) 522 -> (show) 523 524 : (more (who '(% @ 7)) pp) 525 (de day (Dat Lst) 526 (get 527 (or Lst *DayFmt) 528 (inc (% (inc Dat) 7)) ) ) 529 530 (de _week (Dat) 531 (/ (- Dat (% (inc Dat) 7)) 7) ) 532 </code></pre> 533 534 <h3>Find what classes can accept a given message with <i>can</i></h3> 535 536 <p>The function <code><a href="refC.html#can">can</a></code> returns a list 537 which indicates which classes <i>can</i> accept a given message. Again, this 538 list is suitable for iteration with <code>pp</code>: 539 540 <pre><code> 541 : (can 'del>) # Which classes accept 'del>' ? 542 -> ((del> . +List) (del> . +Entity) (del> . +relation)) 543 544 : (more (can 'del>) pp) # Inspect the methods with 'pp' 545 (dm (del> . +List) (Obj Old Val) 546 (and ((<> Old Val) (delete Val Old)) ) 547 548 (dm (del> . +Entity) (Var Val) 549 (when 550 (and 551 Val 552 (has> (meta This Var) Val (get This Var)) ) 553 (let Old (get This Var) 554 (rel> 555 (meta This Var) 556 This 557 Old 558 (put This Var (del> (meta This Var) This Old @)) ) 559 (when (asoq Var (meta This 'Aux)) 560 (relAux This Var Old (cdr @)) ) 561 (upd> This Var Old) ) ) ) 562 563 (dm (del> . +relation) (Obj Old Val) 564 (and ((<> Old Val) Val) ) 565 </code></pre> 566 567 <h3>Inspect dependencies with <i>dep</i></h3> 568 569 <p><code><a href="refD.html#dep">dep</a></code> shows the dependencies in a 570 class hierarchy. That is, for a given class it displays the tree of its 571 (super)class(es) above it, and the tree of its subclasses below it. 572 573 <p>To view the complete hierarchy of input fields, we start with the root class 574 <code><a href="refR.html#+relation">+relation</a></code>: 575 576 <pre><code> 577 : (dep '+relation) 578 +relation 579 +Bag 580 +Any 581 +Blob 582 +Link 583 +Joint 584 +Bool 585 +Symbol 586 +String 587 +Number 588 +Time 589 +Date 590 -> +relation 591 </code></pre> 592 593 <p>If we are interested in <code>+Link</code>: 594 595 <pre><code> 596 : (dep '+Link) 597 +relation 598 +Link 599 +Joint 600 -> +Link 601 </code></pre> 602 603 <p>This says that <code>+Link</code> is a subclass of <code><a 604 href="refR.html#+relation">+relation</a></code>, and has a single subclass 605 (<code>+Joint</code>). 606 607 608 <p><hr> 609 <h2><a name="fun">Defining Functions</a></h2> 610 611 <p>Most of the time during programming is spent defining functions (or methods). 612 In the following we will concentrate on functions, but most will be true for 613 methods as well except for using <code><a href="refD.html#dm">dm</a></code> 614 instead of <code><a href="refD.html#de">de</a></code>. 615 616 <h3>Functions with no argument</h3> 617 618 <p>The notorious "Hello world" function must be defined: 619 620 <pre><code> 621 : (de hello () 622 (prinl "Hello world") ) 623 -> hello 624 </code></pre> 625 626 <p>The <code>()</code> in the first line indicates a function without arguments. 627 The body of the function is in the second line, consisting of a single 628 statement. The last line is the return value of <code>de</code>, which here is 629 the defined symbol. From now on we will omit the return values of examples when 630 they are unimportant. 631 632 <p>Now you can call this function this way: 633 634 <pre><code> 635 : (hello) 636 Hello world 637 </code></pre> 638 639 <h3>Functions with one argument</h3> 640 641 <p>A function with an argument might be defined this way: 642 643 <pre><code> 644 : (de hello (X) 645 (prinl "Hello " X) ) 646 # hello redefined 647 -> hello 648 </code></pre> 649 650 <p>PicoLisp informs you that you have just redefined the function. This might be 651 a useful warning in case you forgot that a bound symbol with that name already 652 existed. 653 654 <pre><code> 655 : (hello "world") 656 Hello world 657 </code></pre> 658 659 <pre><code> 660 : (hello "Alex") 661 Hello Alex 662 </code></pre> 663 664 <h3>Preventing arguments evaluation and variable number of arguments</h3> 665 666 <p>Normally, PicoLisp evaluates the arguments before it passes them to a 667 function: 668 669 <pre><code> 670 : (hello (+ 1 2 3)) 671 Hello 6 672 </code></pre> 673 674 <pre><code> 675 : (setq A 1 B 2) # Set 'A' to 1 and 'B' to 2 676 -> 2 677 : (de foo (X Y) # 'foo' returns the list of its arguments 678 (list X Y) ) 679 -> foo 680 : (foo A B) # Now call 'foo' with 'A' and 'B' 681 -> (1 2) # -> We get a list of 1 and 2, the values of 'A' and 'B' 682 </code></pre> 683 684 <p>In some cases you don't want that. For some functions (<code><a 685 href="refS.html#setq">setq</a></code> for example) it is better if the function 686 gets all arguments unevaluated, and can decide for itself what to do with them. 687 688 <p>For such cases you do not define the function with a <i>list</i> of 689 parameters, but give it a <i>single atomic</i> parameter instead. PicoLisp will 690 then bind all (unevaluated) arguments as a list to that parameter. 691 692 <pre><code> 693 : (de foo X 694 (list (car X) (cadr X)) ) # 'foo' lists the first two arguments 695 696 : (foo A B) # Now call it again 697 -> (A B) # -> We don't get '(1 2)', but '(A B)' 698 699 : (de foo X 700 (list (car X) (eval (cadr X))) ) # Now evaluate only the second argument 701 702 : (foo A B) 703 -> (A 2) # -> We get '(A 2)' 704 </code></pre> 705 706 <h3>Mixing evaluated arguments and variable number of unevaluated arguments</h3> 707 708 <p>As a logical consequence, you can combine these principles. To define a 709 function with 2 evaluated and an arbitrary number of unevaluated arguments: 710 711 <pre><code> 712 : (de foo (X Y . Z) # Evaluate only the first two args 713 (list X Y Z) ) 714 715 : (foo A B C D E) 716 -> (1 2 (C D E)) # -> Get the value of 'A' and 'B' and the remaining list 717 </code></pre> 718 719 <h3>Variable number of evaluated arguments</h3> 720 721 <p>More common, in fact, is the case where you want to pass an arbitrary number 722 of <i>evaluated</i> arguments to a function. For that, PicoLisp recognizes the 723 symbol <code>@</code> as a single atomic parameter and remembers all evaluated 724 arguments in an internal frame. This frame can then be accessed sequentially 725 with the <code><a href="refA.html#args">args</a></code>, <code><a 726 href="refN.html#next">next</a></code>, <code><a 727 href="refA.html#arg">arg</a></code> and <code><a 728 href="refR.html#rest">rest</a></code> functions. 729 730 <pre><code> 731 : (de foo @ 732 (list (next) (next)) ) # Get the first two arguments 733 734 : (foo A B) 735 -> (1 2) 736 </code></pre> 737 738 <p>Again, this can be combined: 739 740 <pre><code> 741 : (de foo (X Y . @) 742 (list X Y (next) (next)) ) # 'X' and 'Y' are fixed arguments 743 744 : (foo A B (+ 3 4) (* 3 4)) 745 -> (1 2 7 12) # All arguments are evaluated 746 </code></pre> 747 748 <p>These examples are not very useful, because the advantage of a variable 749 number of arguments is not used. A function that prints all its evaluated 750 numeric arguments, each on a line followed by its squared value: 751 752 <pre><code> 753 : (de foo @ 754 (while (args) # Check if there are some args left 755 (println (next) (* (arg) (arg))) ) ) # Call the last arg (next) returned 756 757 : (foo (+ 2 3) (- 7 1) 1234 (* 9 9)) 758 5 25 759 6 36 760 1234 1522756 761 81 6561 762 -> 6561 763 </code></pre> 764 765 <p>This next example shows the behaviour of <code>args</code> and 766 <code>rest</code>: 767 768 <pre><code> 769 : (de foo @ 770 (while (args) 771 (next) 772 (println (arg) (args) (rest)) ) ) 773 : (foo 1 2 3) 774 1 T (2 3) 775 2 T (3) 776 3 NIL NIL 777 </code></pre> 778 779 <p>Finally, it is possible to pass all these evaluated arguments to another 780 function, using <code><a href="refP.html#pass">pass</a></code>: 781 782 <pre><code> 783 : (de foo @ 784 (pass println 9 8 7) # First print all arguments preceded by 9, 8, 7 785 (pass + 9 8 7) ) # Then add all these values 786 787 : (foo (+ 2 3) (- 7 1) 1234 (* 9 9)) 788 9 8 7 5 6 1234 81 # Printing ... 789 -> 1350 # Return the result 790 </code></pre> 791 792 <h3>Anonymous functions without the <i>lambda</i> keyword</h3> 793 794 There's no distinction between code and data in PicoLisp, 795 <code><a href="refQ.html#quote">quote</a></code> will do what you want (see 796 also <a href="faq.html#lambda">this FAQ entry</a>). 797 798 <pre><code> 799 : ((quote (X) (* X X)) 9) 800 -> 81 801 </code></pre> 802 803 <pre><code> 804 : (setq f '((X) (* X X))) # This is equivalent to (de f (X) (* X X)) 805 -> ((X) (* X X)) 806 : f 807 -> ((X) (* X X)) 808 : (f 3) 809 -> 9 810 </code></pre> 811 812 813 <p><hr> 814 <h2><a name="dbg">Debugging</a></h2> 815 816 <p>There are two major ways to debug functions (and methods) at runtime: 817 <i>Tracing</i> and <i>single-stepping</i>. 818 819 <p>In this section we will use the REPL to explore the debugging facilities, but 820 in the <a href="#script">Scripting</a> section, you will learn how to launch 821 PicoLisp scripts with some selected functions debugged: 822 823 <pre><code> 824 $ pil app/file1.l -"trace 'foo" -main -"debug 'bar" app/file2.l + 825 </code></pre> 826 827 <h3>Tracing</h3> 828 829 <p><i>Tracing</i> means letting functions of interest print their name and arguments 830 when they are entered, and their name again and the return value when they are 831 exited. 832 833 <p>For demonstration, let's define the unavoidable factorial function (or just 834 <code><a href="refL.html#load">load</a></code> the file "<code><a 835 href="fun.l">@doc/fun.l</a></code>"): 836 837 <pre><code> 838 (de fact (N) 839 (if (=0 N) 840 1 841 (* N (fact (dec N))) ) ) 842 </code></pre> 843 844 <p>With <code><a href="refT.html#trace">trace</a></code> we can put it in trace 845 mode: 846 847 <pre><code> 848 : (trace 'fact) 849 -> fact 850 </code></pre> 851 852 <p>Calling <code>fact</code> now will display its execution trace. 853 854 <pre><code> 855 : (fact 3) 856 fact : 3 857 fact : 2 858 fact : 1 859 fact : 0 860 fact = 1 861 fact = 1 862 fact = 2 863 fact = 6 864 -> 6 865 </code></pre> 866 867 <p>As can be seen here, each level of function call will indent by an additional 868 space. Upon function entry, the name is separated from the arguments with a 869 colon (<code>:</code>), and upon function exit with an equals sign 870 (<code>=</code>) from the return value. 871 872 <p><code>trace</code> works by modifying the function body, so generally it 873 works only for functions defined as lists (lambda expressions, see <a 874 href="ref.html#ev">Evaluation</a>). Tracing a C-function is possible, however, 875 when it is a function that evaluates all its arguments. 876 877 <p>So let's trace the functions <code><a href="ref_.html#=0">=0</a></code> and 878 <code><a href="ref_.html#*">*</a></code>: 879 880 <pre><code> 881 : (trace '=0) 882 -> =0 883 : (trace '*) 884 -> * 885 </code></pre> 886 887 <p>If we call <code>fact</code> again, we see the additional output: 888 889 <pre><code> 890 : (fact 3) 891 fact : 3 892 =0 : 3 893 =0 = NIL 894 fact : 2 895 =0 : 2 896 =0 = NIL 897 fact : 1 898 =0 : 1 899 =0 = NIL 900 fact : 0 901 =0 : 0 902 =0 = 0 903 fact = 1 904 * : 1 1 905 * = 1 906 fact = 1 907 * : 2 1 908 * = 2 909 fact = 2 910 * : 3 2 911 * = 6 912 fact = 6 913 -> 6 914 </code></pre> 915 916 <p>To reset a function to its untraced state, call <code><a 917 href="refU.html#untrace">untrace</a></code>: 918 919 <pre><code> 920 : (untrace 'fact) 921 -> fact 922 : (untrace '=0) 923 -> =0 924 : (untrace '*) 925 -> * 926 </code></pre> 927 928 <p>or simply use <code><a href="refM.html#mapc">mapc</a></code>: 929 930 <pre><code> 931 : (mapc untrace '(fact =0 *)) 932 -> * 933 </code></pre> 934 935 <h3>Single-stepping</h3> 936 937 <p><i>Single-stepping</i> means to execute a function step by step, giving the 938 programmer an opportunity to look more closely at what is happening. The 939 function <code><a href="refD.html#debug">debug</a></code> inserts a breakpoint 940 into each top-level expression of a function. When the function is called, it 941 stops at each breakpoint, displays the expression it is about to execute next 942 (this expression is also stored into the global variable <code><a 943 href="ref_.html#^">^</a></code>) and enters a read-eval-loop. The programmer can 944 then 945 946 <ul> 947 948 <li>inspect the current environment by typing variable names or calling 949 functions 950 951 <li>execute <code>(<a href="refD.html#d">d</a>)</code> to recursively debug the 952 next expression (looping through subexpressions of this expression) 953 954 <li>execute <code>(<a href="refE.html#e">e</a>)</code> to evaluate the next 955 expression, to see what will happen without actually advancing on 956 957 <li>type ENTER (that is, enter an empty line) to leave the read-eval loop and 958 continue with the next expression 959 960 </ul> 961 962 <p>Thus, in the simplest case, single-stepping consists of just hitting ENTER 963 repeatedly to step through the function. 964 965 <p>To try it out, let's look at the <code><a 966 href="refS.html#stamp">stamp</a></code> system function. You may need to have a 967 look at 968 969 <ul> 970 <li><code><a href="ref_.html#=T">=T</a></code> (T test),</li> 971 972 <li><code><a href="refD.html#date">date</a></code> and <code><a 973 href="refT.html#time">time</a></code> (grab system date and time) 974 975 <li><code><a href="refD.html#default">default</a></code> (conditional 976 assignments) 977 978 <li><code><a href="refP.html#pack">pack</a></code> (kind of concatenation), and 979 980 <li><code><a href="refD.html#dat$">dat$</a></code> and <code><a 981 href="refT.html#tim$">tim$</a></code> (date and time formats)</li> 982 983 </ul> 984 985 to understand this definition. 986 987 <pre><code> 988 : (pp 'stamp) 989 (de stamp (Dat Tim) 990 (and (=T Dat) (setq Dat (date T))) 991 (default Dat (date) Tim (time T)) 992 (pack (dat$ Dat "-") " " (tim$ Tim T)) ) 993 -> stamp 994 </code></pre> 995 996 <pre><code> 997 : (debug 'stamp) # Debug it 998 -> T 999 : (stamp) # Call it again 1000 (and (=T Dat) (setq Dat (date T))) # stopped at first expression 1001 ! # ENTER 1002 (default Dat (date) Tim (time T)) # second expression 1003 ! # ENTER 1004 (pack (dat$ Dat "-") " " (tim$ ... # third expression 1005 ! Tim # inspect 'Tim' variable 1006 -> 41908 1007 ! (time Tim) # convert it 1008 -> (11 38 28) 1009 ! # ENTER 1010 -> "2004-10-29 11:38:28" # done, as there are only 3 expressions 1011 </code></pre> 1012 1013 <p>Now we execute it again, but this time we want to look at what's happening 1014 inside the second expression. 1015 1016 <pre><code> 1017 : (stamp) # Call it again 1018 (and (=T Dat) (setq Dat (date T))) 1019 ! # ENTER 1020 (default Dat (date) Tim (time T)) 1021 ! # ENTER 1022 (pack (dat$ Dat "-") " " (tim$ ... # here we want to look closer 1023 ! (d) # debug this expression 1024 -> T 1025 ! # ENTER 1026 (dat$ Dat "-") # stopped at first subexpression 1027 ! (e) # evaluate it 1028 -> "2004-10-29" 1029 ! # ENTER 1030 (tim$ Tim T) # stopped at second subexpression 1031 ! (e) # evaluate it 1032 -> "11:40:44" 1033 ! # ENTER 1034 -> "2004-10-29 11:40:44" # done 1035 </code></pre> 1036 1037 <p>The breakpoints still remain in the function body. We can see them when we 1038 pretty-print it: 1039 1040 <pre><code> 1041 : (pp 'stamp) 1042 (de stamp (Dat Tim) 1043 (! and (=T Dat) (setq Dat (date T))) 1044 (! default Dat (date) Tim (time T)) 1045 (! pack 1046 (! dat$ Dat "-") 1047 " " 1048 (! tim$ Tim T) ) ) 1049 -> stamp 1050 </code></pre> 1051 1052 <p>To reset the function to its normal state, call <code><a 1053 href="refU.html#unbug">unbug</a></code>: 1054 1055 <pre><code> 1056 : (unbug 'stamp) 1057 </code></pre> 1058 1059 <p>Often, you will not want to single-step a whole function. Just use 1060 <code>edit</code> (see above) to insert a single breakpoint (the exclamation 1061 mark followed by a space) as CAR of an expression, and run your program. 1062 Execution will then stop there as described above; you can inspect the 1063 environment and continue execution with ENTER when you are done. 1064 1065 1066 <p><hr> 1067 <h2><a name="funio">Functional I/O</a></h2> 1068 1069 <p>Input and output in PicoLisp is functional, in the sense that there are not 1070 variables assigned to file descriptors, which need then to be passed to I/O 1071 functions for reading, writing and closing. Instead, these functions operate on 1072 implicit input and output channels, which are created and maintained as dynamic 1073 environments. 1074 1075 <p>Standard input and standard output are the default channels. Try reading a 1076 single expression: 1077 1078 <pre><code> 1079 : (read) 1080 (a b c) # Console input 1081 -> (a b c) 1082 </code></pre> 1083 1084 <p>To read from a file, we redirect the input with <code><a 1085 href="refI.html#in">in</a></code>. Note that comments and whitespace are 1086 automatically skipped by <code>read</code>: 1087 1088 <pre><code> 1089 : (in "@doc/fun.l" (read)) 1090 -> (de fact (N) (if (=0 N) 1 (* N (fact (dec N))))) 1091 </code></pre> 1092 1093 <p>The <code><a href="refS.html#skip">skip</a></code> function can also be used 1094 directly. To get the first non-white character in the file with <code><a 1095 href="refC.html#char">char</a></code>: 1096 1097 <pre><code> 1098 : (in "@doc/fun.l" (skip "#") (char)) 1099 -> "(" 1100 </code></pre> 1101 1102 <p><code><a href="refF.html#from">from</a></code> searches through the input 1103 stream for given patterns. Typically, this is not done with Lisp source files 1104 (there are better ways), but for a simple example let's extract all items 1105 immediately following <code>fact</code> in the file, 1106 1107 <pre><code> 1108 : (in "@doc/fun.l" (while (from "fact ") (println (read)))) 1109 (N) 1110 (dec N) 1111 </code></pre> 1112 1113 <p>or the word following "(de " with <code><a 1114 href="refT.html#till">till</a></code>: 1115 1116 <pre><code> 1117 : (in "@doc/fun.l" (from "(de ") (till " " T))) 1118 -> "fact" 1119 </code></pre> 1120 1121 1122 <p>With <code><a href="refL.html#line">line</a></code>, a line of characters is 1123 read, either into a single <a href="ref.html#transient-io">transient</a> symbol 1124 (the type used by PicoLisp for strings), 1125 1126 <pre><code> 1127 : (in "@doc/tut.html" (line T)) 1128 -> "<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" "http://..." 1129 </code></pre> 1130 1131 <p>or into a list of symbols (characters): 1132 1133 <pre><code> 1134 : (in "@doc/tut.html" (line)) 1135 -> ("<" "!" "D" "O" "C" "T" "Y" "P" "E" " " "H" "T" "M" "L" ... 1136 </code></pre> 1137 1138 <p><code>line</code> is typically used to read tabular data from a file. 1139 Additional arguments can split the line into fixed-width fields, as described in 1140 the <code><a href="refL.html#line">reference manual</a></code>. If, however, the 1141 data are of variable width, delimited by some special character, the <code><a 1142 href="refS.html#split">split</a></code> function can be used to extract the 1143 fields. A typical way to import the contents of such a file is: 1144 1145 <pre><code> 1146 (load "@lib/import.l") 1147 1148 (in '("bin/utf2" "importFile.txt") # Pipe: Convert to UTF-8 1149 (until (eof) # Process whole file 1150 (let L (split (line) "^I") # TAB-delimited data 1151 ... use 'getStr', 'getNum' etc ... # process them 1152 </code></pre> 1153 1154 <p>Some more examples with <code><a href="refE.html#echo">echo</a></code>: 1155 1156 <pre><code> 1157 (in "a" # Copy the first 40 Bytes 1158 (out "b" # from file "a" to file "b" 1159 (echo 40) ) ) 1160 1161 (in "@doc/tut.html" # Show the HTTP-header 1162 (line) 1163 (echo "<body>") ) 1164 1165 (out "file.mac" # Convert to Macintosh 1166 (in "file.txt" # from Unix or DOS format: 1167 (while (char) 1168 (prin 1169 (case @ 1170 ("^M" NIL) # ignore CR 1171 ("^J" "^M") # convert CR to LF 1172 (T @) ) ) ) ) ) # otherwise no change 1173 1174 (out "c" # Merge the contents of "a" 1175 (in "b" # and "b" into "c" 1176 (in "a" 1177 (while (read) # Read an item from "a", 1178 (println @ (in -1 (read))) ) ) ) ) # print it with an item from "b" 1179 </code></pre> 1180 1181 1182 <p><hr> 1183 <h2><a name="script">Scripting</a></h2> 1184 1185 <p>There are two possibilities to get the PicoLisp interpreter into doing useful 1186 work: via command line arguments, or as a stand-alone script. 1187 1188 <h3>Command line arguments for the PicoLisp interpreter</h3> 1189 1190 <p>The command line can specify either files for execution, or arbitrary Lisp 1191 expressions for direct evaluation (see <a href="ref.html#invoc">Invocation</a>): 1192 if an argument starts with a hyphen, it is evaluated, otherwise it is <code><a 1193 href="refL.html#load">load</a></code>ed as a file. A typical invocation might 1194 look like: 1195 1196 <pre><code> 1197 $ pil app/file1.l -main app/file2.l + 1198 </code></pre> 1199 1200 <p>It loads the debugging environment, an application source file, calls the 1201 main function, and then loads another application source. In a typical 1202 development and debugging session, this line is often modified using the shell's 1203 history mechanisms, e.g. by inserting debugging statements: 1204 1205 <pre><code> 1206 $ pil app/file1.l -"trace 'foo" -main -"debug 'bar" app/file2.l + 1207 </code></pre> 1208 1209 <p>Another convenience during debugging and testing is to put things into the 1210 command line (shell history) which would otherwise have to be done each time in 1211 the application's user interface: 1212 1213 <pre><code> 1214 $ pil app/file1.l -main app/file2.l -go -'login "name" "password"' + 1215 </code></pre> 1216 1217 <p>The final production release of an application usually includes a shell 1218 script, which initializes the environment, does some bookkeeping and cleanup, 1219 and calls the application with a proper command line. It is no problem if the 1220 command line is long and complicated. 1221 1222 <p>For small utility programs, however, this is overkill. Enter full PicoLisp 1223 scripts. 1224 1225 <h3>PicoLisp scripts</h3> 1226 1227 It is better to write 1228 a single executable file using the mechanisms of "interpreter files". If the 1229 first two characters in an executable file are "<code>#!</code>", the operating 1230 system kernel will pass this file to an interpreter program whose pathname is 1231 given in the first line (optionally followed by a single argument). This is fast 1232 and efficient, because the overhead of a subshell is avoided. 1233 1234 <p>Let's assume you installed PicoLisp in the directory "/home/foo/picolisp/", 1235 and put links to the executable and the installation directory as: 1236 1237 <pre><code> 1238 $ ln -s /home/foo/picolisp /usr/lib/picolisp 1239 $ ln -s /usr/lib/picolisp/bin/picolisp /usr/bin/picolisp 1240 </code></pre> 1241 1242 Then a simple hello-world script might look like: 1243 1244 <pre><code> 1245 #!/usr/bin/picolisp /usr/lib/picolisp/lib.l 1246 (prinl "Hello world!") 1247 (bye) 1248 </code></pre> 1249 1250 <p>If you write this into a text file, and use <code>chmod</code> to set it to 1251 "executable", it can be executed like any other command. Note that (because 1252 <code>#</code> is the comment character in PicoLisp) the first line will not be 1253 interpreted, and you can still use that file as a normal command line argument 1254 to PicoLisp (useful during debugging). 1255 1256 <h3>Grab command line arguments from PicoLisp scripts</h3> 1257 1258 <p>The fact that a hyphen causes evaluation of command line arguments can be 1259 used to simulate something like command line options. The following script 1260 defines two functions <code>a</code> and <code>f</code>, and then calls 1261 <code>(<a href="refL.html#load">load</a> T)</code> to process the rest of the 1262 command line (which otherwise would be ignored because of the <code>(<a 1263 href="refB.html#bye">bye</a>)</code> statement): 1264 1265 <pre><code> 1266 #!/usr/bin/picolisp /usr/lib/picolisp/lib.l 1267 1268 (de a () 1269 (println '-a '-> (opt)) ) 1270 1271 (de f () 1272 (println '-f '-> (opt)) ) 1273 1274 (load T) 1275 (bye) 1276 </code></pre> 1277 1278 (<code><a href="refO.html#opt">opt</a></code> retrieves the next command line 1279 option) 1280 1281 <p>Calling this script (let's say we named it "testOpts") gives: 1282 1283 <pre><code> 1284 $ ./testOpts -f abc 1285 -f -> "abc" 1286 $ ./testOpts -a xxx -f yyy 1287 -a -> "xxx" 1288 -f -> "yyy" 1289 </code></pre> 1290 1291 <p>We have to be aware of the fact, however, that the aggregation of arguments 1292 like 1293 1294 <pre><code> 1295 $ ./testOpts -axxx -fyyy 1296 </code></pre> 1297 1298 <p>or 1299 1300 <pre><code> 1301 $ ./testOpts -af yyy 1302 </code></pre> 1303 1304 <p>cannot be achieved with this simple and general mechanism of command line 1305 processing. 1306 1307 <h3>Run scripts from arbitrary places on the host file system</h3> 1308 1309 <p>Utilities are typically used outside the context of the PicoLisp environment. 1310 All examples above assumed that the current working directory is the PicoLisp 1311 installation directory, which is usually all right for applications developed in 1312 that environment. Command line file arguments like "app/file1.l" will be 1313 properly found. 1314 1315 <p>To allow utilities to run in arbitrary places on the host file system, the 1316 concept of <i>home directory substitution</i> was introduced. The interpreter 1317 remembers internally at start-up the pathname of its first argument (usually 1318 "lib.l"), and substitutes any leading "<code>@</code>" character in subsequent 1319 file names with that pathname. Thus, to run the above example in some other 1320 place, simply write: 1321 1322 <pre><code> 1323 $ /home/foo/picolisp/pil @app/file1.l -main @app/file2.l + 1324 </code></pre> 1325 1326 <p>that is, supply a full path name to the initial command (here 'p'), or put it 1327 into your <code>PATH</code> variable, and prefix each file which has to be 1328 loaded from the PicoLisp home directory with a <code>@</code> character. 1329 "Normal" files (not prefixed by <code>@</code>) will be opened or created 1330 relative to the current working directory as usual. 1331 1332 <p>Stand-alone scripts will often want to load additional modules from the 1333 PicoLisp environment, beyond the "lib.l" we provided in the first line of the 1334 hello-world script. Typically, at least a call to 1335 1336 <pre><code> 1337 (load "@lib/misc.l") 1338 </code></pre> 1339 1340 <p>(note the home directory substitution) will be included near the beginning of 1341 the script. 1342 1343 <p>As a more complete example, here is a script which extracts the date, name 1344 and size of the latest official PicoLisp release version from the download web 1345 site, and prints it to standard output: 1346 1347 <pre><code> 1348 #!/usr/bin/picolisp /usr/lib/picolisp/lib.l 1349 1350 (load "@lib/misc.l" "@lib/http.l") 1351 1352 (use (@Date @Name @Size) 1353 (when 1354 (match 1355 '(@Date ~(chop " - <a href=\"") @Name "\"" ">" 1356 @Name ~(chop "</a> (") @Size ) 1357 (client "software-lab.de" 80 "down.html" 1358 (from "Release Archive") 1359 (from "<li>") 1360 (till ",") ) ) 1361 (prinl @Name) 1362 (prinl @Date " -- " @Size) ) ) 1363 1364 (bye) 1365 </code></pre> 1366 1367 <h3>Editing scripts</h3> 1368 1369 <p>We recommend that you have a terminal window open, and try the examples by 1370 yourself. You may either type them in, directly to the PicoLisp interpreter, or 1371 edit a separate source file (e.g. <code>"@doc/fun.l"</code>) in a second 1372 terminal window and load it into PicoLisp with 1373 1374 <pre><code> 1375 : (load "@doc/fun.l") 1376 </code></pre> 1377 1378 <p>each time you have modified and saved it. 1379 1380 <h3>Editing scripts with vi</h3> 1381 1382 <p>Once a function is loaded from a source file, you can call 'vim' directly on 1383 that function with 1384 1385 <pre><code> 1386 : (vi 'fact) 1387 </code></pre> 1388 1389 <p>The function 'vi' opens the appropriate source file, and jumps to the right 1390 line where 'fact' is defined. When you modify it, you can simply call 'ld' to 1391 (re)load that source file 1392 1393 <pre><code> 1394 : (ld) 1395 </code></pre> 1396 1397 <p><hr> 1398 <h2><a name="oop">Objects and Classes</a></h2> 1399 1400 <p>The PicoLisp object model is very simple, yet flexible and powerful. Objects 1401 as well as classes are both implemented as symbols. In fact, there is no formal 1402 difference between objects and classes; classes are more a conceptual design 1403 consideration in the head of the programmer than a physical reality. 1404 1405 <p>Having said this, we declare that normally: 1406 1407 <ol> 1408 <li>A Class 1409 <ul> 1410 <li>Has a name (interned symbol) 1411 <li>Has method definitions and superclass(es) in the value 1412 <li>May have class variables (attributes) in the property list 1413 </ul> 1414 <li>An Object 1415 <ul> 1416 <li>Has no name (anonymous symbol) or is an external symbol 1417 <li>Has class(es) (and optionally method definitions) in the value 1418 <li>Has instance variables (attributes) in the property list 1419 </ul> 1420 </ol> 1421 1422 <p>So the main difference between classes and objects is that the former ones 1423 usually are internal symbols. By convention, their names start with a 1424 '<code>+</code>'. Sometimes it makes sense, however, to create named objects (as 1425 global singletons, for example), or even anonymous classes. 1426 1427 <p>Both classes and objects have a list in their value, consisting of method 1428 definitions (often empty for objects) and (super)class(es). And both classes and 1429 objects have local data in their property lists (often empty for classes). This 1430 implies, that any given object (as an instance of a class) may have private 1431 (object-local) methods defined. 1432 1433 <p>It is rather difficult to contrive a simple OOP example. We constructed a 1434 hierarchy of geometric shapes, with a base class <code>+Shape</code> and two 1435 subclasses <code>+Rectangle</code> and <code>+Circle</code>. 1436 1437 <p>The source code is included as "<code><a 1438 href="shape.l">@doc/shape.l</a></code>" in the PicoLisp distribution, so you 1439 don't have to type it in. Just <code><a href="refL.html#load">load</a></code> 1440 the file, or start it from the shell as: 1441 1442 <pre><code> 1443 $ pil @doc/shape.l + 1444 </code></pre> 1445 1446 <p>Let's look at it piece by piece. Here's the base class: 1447 1448 <pre><code> 1449 (class +Shape) 1450 # x y 1451 1452 (dm T (X Y) 1453 (=: x X) 1454 (=: y Y) ) 1455 1456 (dm move> (DX DY) 1457 (inc (:: x) DX) 1458 (inc (:: y) DY) ) 1459 </code></pre> 1460 1461 <p>The first line '<code>(class +Shape)</code>' defines the symbol 1462 <code>+Shape</code> as a class without superclasses. The following method 1463 definitions will go to that class. 1464 1465 <p>The comment '<code># x y</code>' in the second line is just a convention, to 1466 indicate what instance variables (properties) that class uses. As PicoLisp is a 1467 dynamic language, a class can be extended at runtime with any number of 1468 properties, and there is nothing like a fixed object size or structure. This 1469 comment is a hint of what the programmer thinks to be essential and typical for 1470 that class. In the case of <code>+Shape</code>, <code>x</code> and 1471 <code>y</code> are the coordinates of the shape's origin. 1472 1473 <p>Then we have two method definitions, using the keyword <code><a 1474 href="refD.html#dm">dm</a></code> for "define method". The first method is 1475 special, in that its name is <code>T</code>. Each time a new object is created, 1476 and a method with that name is found in its class hierarchy, that method will be 1477 executed. Though this looks like a "constructor" in other programming languages, 1478 it should probably better be called "initializer". The <code>T</code> method of 1479 <code>+Shape</code> takes two arguments <code>X</code> and <code>Y</code>, and 1480 stores them in the object's property list. 1481 1482 <p>The second method <code>move></code> changes the object's origin by adding 1483 the offset values <code>DX</code> and <code>DY</code> to the object's origin. 1484 1485 <p>Now to the first derived class: 1486 1487 <pre><code> 1488 (class +Rectangle +Shape) 1489 # dx dy 1490 1491 (dm T (X Y DX DY) 1492 (super X Y) 1493 (=: dx DX) 1494 (=: dy DY) ) 1495 1496 (dm area> () 1497 (* (: dx) (: dy)) ) 1498 1499 (dm perimeter> () 1500 (* 2 (+ (: dx) (: dy))) ) 1501 1502 (dm draw> () 1503 (drawRect (: x) (: y) (: dx) (: dy)) ) 1504 </code></pre> 1505 1506 <p><code>+Rectangle</code> is defined as a subclass of <code>+Shape</code>. 1507 The comment '<code># dx dy</code>' indicates that <code>+Rectangle</code> has a 1508 width and a height in addition to the origin coordinates inherited from 1509 <code>+Shape</code>. 1510 1511 <p>The <code>T</code> method passes the origin coordinates <code>X</code> and 1512 <code>Y</code> to the <code>T</code> method of the superclass 1513 (<code>+Shape</code>), then stores the width and height parameters into 1514 <code>dx</code> and <code>dy</code>. 1515 1516 <p>Next we define the methods <code>area></code> and 1517 <code>perimeter></code> which do some obvious calculations, and a method 1518 <code>draw></code> which is supposed to draw the shape on the screen by 1519 calling some hypothetical function <code>drawRect</code>. 1520 1521 <p>Finally, we define a <code>+Circle</code> class in an analog way, postulating 1522 the hypothetical function <code>drawCircle</code>: 1523 1524 <pre><code> 1525 (class +Circle +Shape) 1526 # r 1527 1528 (dm T (X Y R) 1529 (super X Y) 1530 (=: r R) ) 1531 1532 (dm area> () 1533 (*/ (: r) (: r) 31415927 10000000) ) 1534 1535 (dm perimeter> () 1536 (*/ 2 (: r) 31415927 10000000) ) 1537 1538 (dm draw> () 1539 (drawCircle (: x) (: y) (: r)) ) 1540 </code></pre> 1541 1542 <p>Now we can experiment with geometrical shapes. We create a rectangle at point 1543 (0,0) with a width of 30 and a height of 20, and keep it in the variable 1544 <code>R</code>: 1545 1546 <pre><code> 1547 : (setq R (new '(+Rectangle) 0 0 30 20)) # New rectangle 1548 -> $134432824 # returned anonymous symbol 1549 : (show R) 1550 $134432824 (+Rectangle) # Show the rectangle 1551 dy 20 1552 dx 30 1553 y 0 1554 x 0 1555 </code></pre> 1556 1557 <p>We see that the symbol <code>$134432824</code> has a list of classes 1558 '<code>(+Rectangle)</code>' in its value, and the coordinates, width and height 1559 in its property list. 1560 1561 <p>Sending messages to that object 1562 1563 <pre><code> 1564 : (area> R) # Calculate area 1565 -> 600 1566 : (perimeter> R) # and perimeter 1567 -> 100 1568 </code></pre> 1569 1570 <p>will return the values for area and perimeter, respectively. 1571 1572 <p>Then we move the object's origin: 1573 1574 <pre><code> 1575 : (move> R 10 5) # Move 10 right and 5 down 1576 -> 5 1577 : (show R) 1578 $134432824 (+Rectangle) 1579 y 5 # Origin changed (0,0) -> (10,5) 1580 x 10 1581 dy 20 1582 dx 30 1583 </code></pre> 1584 1585 <p>Though a method <code>move></code> wasn't defined for the 1586 <code>+Rectangle</code> class, it is inherited from the <code>+Shape</code> 1587 superclass. 1588 1589 <p>Similarly, we create and use a circle object: 1590 1591 <pre><code> 1592 : (setq C (new '(+Circle) 10 10 30)) # New circle 1593 -> $134432607 # returned anonymous symbol 1594 : (show C) 1595 $134432607 (+Circle) # Show the circle 1596 r 30 1597 y 10 1598 x 10 1599 -> $134432607 1600 : (area> C) # Calculate area 1601 -> 2827 1602 : (perimeter> C) # and perimeter 1603 -> 188 1604 : (move> C 10 5) # Move 10 right and 5 down 1605 -> 15 1606 : (show C) 1607 $134432607 (+Circle) # Origin changed (10,10) -> (20,15) 1608 y 15 1609 x 20 1610 r 30 1611 </code></pre> 1612 1613 <p>It is also easy to send messages to objects in a list: 1614 1615 <pre><code> 1616 : (mapcar 'area> (list R C)) # Get list of areas 1617 -> (600 2827) 1618 : (mapc 1619 '((Shape) (move> Shape 10 10)) # Move all 10 right and down 1620 (list R C) ) 1621 -> 25 1622 : (show R) 1623 $134431493 (+Rectangle) 1624 y 15 1625 x 20 1626 dy 20 1627 dx 30 1628 -> $134431493 1629 : (show C) 1630 $134431523 (+Circle) 1631 y 25 1632 x 30 1633 r 30 1634 </code></pre> 1635 1636 <p>Assume that we want to extend our shape system. From time to time, we need 1637 shapes that behave exactly like the ones above, but are tied to a fixed 1638 position. That is, they do not change their position even if they receive a 1639 <code>move></code> message. 1640 1641 <p>One solution would be to modify the <code>move></code> method in the 1642 <code>+Shape</code> class to a no-operation. But this would require to duplicate 1643 the whole shape hierarchy (e.g. by defining <code>+FixedShape</code>, 1644 <code>+FixedRectangle</code> and <code>+FixedCircle</code> classes). 1645 1646 <p>The PicoLisp Way is the use of <u>Prefix Classes</u> through multiple 1647 inheritance. It uses the fact that searching for method definitions is a 1648 depth-first, left-to-right search of the class tree. We define a prefix class: 1649 1650 <pre><code> 1651 : (class +Fixed) 1652 1653 (dm move> (DX DY)) # A do-nothing method 1654 </code></pre> 1655 1656 <p>We can now create a fixed rectangle, and try to move it: 1657 1658 <pre><code> 1659 : (setq R (new '(+Fixed +Rectangle) 0 0 30 20)) # '+Fixed' prefix class 1660 -> $134432881 1661 : (move> R 10 5) # Send 'move>' message 1662 -> NIL 1663 : (show R) 1664 $134432881 (+Fixed +Rectangle) 1665 dy 20 1666 dx 30 1667 y 0 # Did not move! 1668 x 0 1669 </code></pre> 1670 1671 <p>We see, prefix classes can surgically change the inheritance tree for 1672 selected objects or classes. 1673 1674 <p>Alternatively, if fixed rectangles are needed often, it might make sense to 1675 define a new class <code>+FixRect</code>: 1676 1677 <pre><code> 1678 : (class +FixRect +Fixed +Rectangle) 1679 -> +FixRect 1680 </code></pre> 1681 1682 <p>and then use it directly: 1683 1684 <pre><code> 1685 : (setq R (new '(+FixRect) 0 0 30 20)) 1686 -> $13455710 1687 </code></pre> 1688 1689 1690 <p><hr> 1691 <h2><a name="ext">Persistence (External Symbols)</a></h2> 1692 1693 <p>PicoLisp has persistent objects built-in as a first class data type. With 1694 "first class" we mean not just the ability of being passed around, or returned 1695 from functions (that's a matter of course), but that they are a primary data 1696 type with their own interpreter tag bits. They are, in fact, a special type of 1697 symbolic atoms (called "<a href="ref.html#external">External Symbols</a>"), that 1698 happen to be read from pool file(s) when accessed, and written back 1699 automatically when modified. 1700 1701 <p>In all other aspects they are normal symbols. They have a value, a property 1702 list and a name. 1703 1704 <p>The name cannot be directly controlled by the programmer, as it is assigned 1705 when the symbol is created. It is an encoded index of the symbol's location in 1706 its database file. In its visual representation (output by the <code><a 1707 href="refP.html#print">print</a></code> functions and input by the <code><a 1708 href="refR.html#read">read</a></code> functions) it is surrounded by braces. 1709 1710 <p>To make use of external symbols, you need to open a database first: 1711 1712 <pre><code> 1713 : (pool "test.db") 1714 </code></pre> 1715 1716 <p>If a file with that name did not exist, it got created now. Also created at 1717 the same moment was <code>{1}</code>, the very first symbol in the file. This 1718 symbol is of great importance, and is handled especially by PicoLisp. Therefore 1719 a global constant <code><a href="refD.html#*DB">*DB</a></code> exists, which 1720 points to that symbol <code>{1}</code>, which should be used exclusively to 1721 access the symbol <code>{1}</code>, and which should never be modified by the 1722 programmer. 1723 1724 <pre><code> 1725 : *DB # The value of '*DB' 1726 -> {1} # is '{1}' 1727 : (show *DB) 1728 {1} NIL # Value of '{1}' is NIL, property list empty 1729 </code></pre> 1730 1731 <p>Now let's put something into the value and property list of <code>{1}</code>. 1732 1733 <pre><code> 1734 : (set *DB "Hello world") # Set value of '{1}' to a transient symbol (string) 1735 -> "Hello world" 1736 : (put *DB 'a 1) # Property 'a' to 1 1737 -> 1 1738 : (put *DB 'b 2) # Property 'b' to 2 1739 -> 2 1740 : (show *DB) # Now show the symbol '{1}' 1741 {1} "Hello world" 1742 b 2 1743 a 1 1744 </code></pre> 1745 1746 <p>Note that instead of '<code>(set *DB "Hello world")</code>', we might 1747 also have written '<code>(setq {1} "Hello world")</code>', and instead of 1748 '<code>(put *DB 'a 1)</code>' we might have written '<code>(put '{1} 'a 1749 1)</code>'. This would have the same effect, but as a rule external symbols 1750 should never be be accessed literally in application programs, because the 1751 garbage collector might not be able to free these symbols and all symbols 1752 connected to them (and that might well be the whole database). It is all right, 1753 however, to access external symbols literally during interactive debugging. 1754 1755 <p>Now we can create our first own external symbol. This can be done with 1756 <code><a href="refN.html#new">new</a></code> when a <code>T</code> argument is 1757 supplied: 1758 1759 <pre><code> 1760 : (new T) 1761 -> {2} # Got a new symbol 1762 </code></pre> 1763 1764 <p>We store it in the database root <code>{1}</code>: 1765 1766 <pre><code> 1767 : (put *DB 'newSym '{2}) # Literal '{2}' (ok during debugging) 1768 -> {2} 1769 : (show *DB) 1770 {1} "Hello world" 1771 newSym {2} # '{2}' is now stored in '{1}' 1772 b 2 1773 a 1 1774 </code></pre> 1775 1776 <p>Put some property value into '{2}' 1777 1778 <pre><code> 1779 : (put *DB 'newSym 'x 777) # Put 777 as 'x'-property of '{2}' 1780 -> 777 1781 : (show *DB 'newSym) # Show '{2}' (indirectly) 1782 {2} NIL 1783 x 777 1784 -> {2} 1785 : (show '{2}) # Show '{2}' (directly) 1786 {2} NIL 1787 x 777 1788 </code></pre> 1789 1790 <p>All modifications to - and creations of - external symbols done so far are 1791 not written to the database yet. We could call <code><a 1792 href="refR.html#rollback">rollback</a></code> (or simply exit PicoLisp) to undo 1793 all the changes. But as we want to keep them: 1794 1795 <pre><code> 1796 : (commit) # Commit all changes 1797 -> T 1798 : (bye) # Exit picolisp 1799 $ # back to the shell 1800 </code></pre> 1801 1802 <p>So, the next time when .. 1803 1804 <pre><code> 1805 $ pil + # .. we start PicoLisp 1806 : (pool "test.db") # and open the database file, 1807 -> T 1808 : (show *DB) # our two symbols are there again 1809 {1} "Hello world" 1810 newSym {2} 1811 b 2 1812 a 1 1813 -> {1} 1814 : (show *DB 'newSym) 1815 {2} NIL 1816 x 777 1817 -> {2} 1818 </code></pre> 1819 1820 1821 <p><hr> 1822 <h2><a name="db">Database Programming</a></h2> 1823 1824 <p>To a database, there is more than just persistence. PicoLisp includes an 1825 entity/relation class framework (see also <a href="ref.html#dbase">Database</a>) 1826 which allows a close mapping of the application data structure to the database. 1827 1828 <p>We provided a simple yet complete database and GUI demo application in 1829 <code><a href="family.tgz">@doc/family.tgz</a></code> and <code><a 1830 href="family64.tgz">@doc/family64.tgz</a></code>. Please unpack the first one if 1831 you use a 32-bit system, and the second one on a 64-bit system. Both contain the 1832 sources in <code><a href="family.l">@doc/family.l</a></code>, and an initial 1833 database in the "family/" subdirectory. 1834 1835 <p>To use it, please unpack it first in your current working directory, then 1836 start it up in the following way: 1837 1838 <pre><code> 1839 $ pil family.l -main + 1840 : 1841 </code></pre> 1842 1843 <p>This loads the source file, initializes the database by calling the 1844 <code>main</code> function, and prompts for user input. 1845 1846 <p>The data model is small and simple. We define a class <code>+Person</code> 1847 and two subclasses <code>+Man</code> and <code>+Woman</code>. 1848 1849 <pre><code> 1850 (class +Person +Entity) 1851 </code></pre> 1852 1853 <p><code>+Person</code> is a subclass of the <code><a 1854 href="refE.html#+Entity">+Entity</a></code> system class. Usually all objects in 1855 a database are of a direct or indirect subclass of <code><a 1856 href="refE.html#+Entity">+Entity</a></code>. We can then define the relations to 1857 other data with the <code><a href="refR.html#rel">rel</a></code> function. 1858 1859 <pre><code> 1860 (rel nm (+Need +Sn +Idx +String)) # Name 1861 </code></pre> 1862 1863 <p>This defines the name property (<code>nm</code>) of a person. The first 1864 argument to <code>rel</code> is always a list of relation classes (subclasses of 1865 <code><a href="refR.html#+relation">+relation</a></code>), optionally followed 1866 by further arguments, causing relation daemon objects be created and stored in 1867 the class definition. These daemon objects control the entity's behavior later 1868 at runtime. 1869 1870 <p>Relation daemons are a kind of <i>metadata</i>, controlling the interactions 1871 between entities, and maintaining database integrity. Like other classes, 1872 relation classes can be extended and refined, and in combination with proper 1873 prefix classes a fine-grained description of the application's structure can be 1874 produced. 1875 1876 <p>Besides primitive relation classes, like <code>+Number</code>, 1877 <code>+String</code> or <code>+Date</code>, there are 1878 1879 <ul> 1880 1881 <li>relations between entities, like <code>+Link</code> (unidirectional link), 1882 <code>+Joint</code> (bidirectional link) or <code>+Hook</code> (object-local 1883 index trees) 1884 1885 <li>relations that bundle other relations into a single unit (<code>+Bag</code>) 1886 1887 <li>a <code>+List</code> prefix class 1888 1889 <li>a <code>+Blob</code> class for "binary large objects" 1890 1891 <li>prefix classes that maintain index trees, like <code>+Key</code> (unique 1892 index), <code>+Ref</code> (non-unique index) or <code>+Idx</code> (full text 1893 index) 1894 1895 <li>prefix classes which in turn modify index class behavior, like 1896 <code>+Sn</code> (modified soundex algorithm [<a href="#knuth73">knuth73</a>] 1897 for tolerant searches) 1898 1899 <li>a <code>+Need</code> prefix class, for existence checks 1900 1901 <li>a <code>+Dep</code> prefix class controlling dependencies between other 1902 relations 1903 1904 </ul> 1905 1906 <p>In the case of the person's name (<code>nm</code>) above, the relation object 1907 is of type <code>(+Need +Sn +Idx +String)</code>. Thus, the name of each person 1908 in this demo database is a mandatory attribute (<code>+Need</code>), searchable 1909 with the soundex algorithm (<code>+Sn</code>) and a full index 1910 (<code>+Idx</code>) of type <code>+String</code>. 1911 1912 <pre><code> 1913 (rel pa (+Joint) kids (+Man)) # Father 1914 (rel ma (+Joint) kids (+Woman)) # Mother 1915 (rel mate (+Joint) mate (+Person)) # Partner 1916 </code></pre> 1917 1918 <p>The attributes for <i>father</i> (<code>pa</code>), <i>Mother</i> 1919 (<code>ma</code>) and <i>partner</i> (<code>mate</code>) are all defined as 1920 <code>+Joint</code>s. A <code>+Joint</code> is probably the most powerful 1921 relation mechanism in PicoLisp; it establishes a bidirectional link between two 1922 objects. 1923 1924 <p>The above declarations say that the <i>father</i> (<code>pa</code>) attribute 1925 points to an object of type <code>+Man</code>, and is joined with that object's 1926 <code>kids</code> attribute (which is a list of joints back to all his 1927 children). 1928 1929 <p>The consistency of <code>+Joint</code>s is maintained automatically by the 1930 relation daemons. These become active whenever a value is stored to a person's 1931 <code>pa</code>, <code>ma</code>, <code>mate</code> or <code>kids</code> 1932 property. 1933 1934 <p>For example, interesting things happen when a person's <code>mate</code> is 1935 changed to a new value. Then the <code>mate</code> property of the old mate's 1936 object is cleared (she has no mate after that). Now when the person pointed to 1937 by the new value already has a mate, then that mate's <code>mate</code> property 1938 gets cleared, and the happy new two mates now get their joints both set 1939 correctly. 1940 1941 <p>The programmer doesn't have to care about all that. He just declares these 1942 relations as <code>+Joint</code>s. 1943 1944 <p>The last four attributes of person objects are just static data: 1945 1946 <pre><code> 1947 (rel job (+Ref +String)) # Occupation 1948 (rel dat (+Ref +Date)) # Date of birth 1949 (rel fin (+Ref +Date)) # Date of death 1950 (rel txt (+String)) # Info 1951 </code></pre> 1952 1953 <p>They are all searchable via a non-unique index (<code>+Ref</code>). Date 1954 values in PicoLisp are just numbers, representing the day number (starting first 1955 of March of the year zero). 1956 1957 <p>A method <code>url></code> is defined: 1958 1959 <pre><code> 1960 (dm url> () 1961 (list "!person" '*ID This) ) 1962 </code></pre> 1963 1964 <p>It is needed later in the GUI, to cause a click on a link to switch to that 1965 object. 1966 1967 <p>The classes <code>+Man</code> and <code>+Woman</code> are subclasses of 1968 <code>+Person</code>: 1969 1970 <pre><code> 1971 (class +Man +Person) 1972 (rel kids (+List +Joint) pa (+Person)) # Children 1973 1974 (class +Woman +Person) 1975 (rel kids (+List +Joint) ma (+Person)) # Children 1976 </code></pre> 1977 1978 <p>They inherit everything from <code>+Person</code>, except for the 1979 <code>kids</code> attribute. This attribute joins with the <code>pa</code> or 1980 <code>ma</code> attribute of the child, depending on the parent's gender. 1981 1982 <p>That's the whole data model for our demo database application. 1983 1984 <p>It is followed by a call to <code><a href="refD.html#dbs">dbs</a></code> 1985 ("database sizes"). This call is optional. If it is not present, the whole 1986 database will reside in a single file, with a block size of 256 bytes. If it is 1987 given, it should specify a list of items, each having a number in its CAR, and a 1988 list in its CDR. The CARs taken together will be passed later to <a 1989 href="refP.html#pool">pool</a>, causing an individual database file with that 1990 size to be created. The CDRs tell what entity classes (if an item is a symbol) 1991 or index trees (if an item is a list with a class in its CAR and a list of 1992 relations in its CDR) should be placed into that file. 1993 1994 1995 <p>A handful of access functions is provided, that know about database 1996 relationships and thus allows higher-level access modes to the external symbols 1997 in a database. 1998 1999 <p>For one thing, the B-Trees created and maintained by the index daemons can be 2000 used directly. Though this is rarely done in a typical application, they form 2001 the base mechanisms of other access modes and should be understood first. 2002 2003 <p>The function <code><a href="refT.html#tree">tree</a></code> returns the tree 2004 structure for a given relation. To iterate over the whole tree, the functions 2005 <code><a href="refI.html#iter">iter</a></code> and <code><a 2006 href="refS.html#scan">scan</a></code> can be used: 2007 2008 <pre><code> 2009 (iter (tree 'dat '+Person) '((P) (println (datStr (get P 'dat)) (get P 'nm)))) 2010 "1770-08-03" "Friedrich Wilhelm III" 2011 "1776-03-10" "Luise Augusta of Mecklenburg-Strelitz" 2012 "1797-03-22" "Wilhelm I" 2013 ... 2014 </code></pre> 2015 2016 <p>They take a function as the first argument. It will be applied to all objects 2017 found in the tree (to show only a part of the tree, an optional begin- and 2018 end-value can be supplied), producing a simple kind of report. 2019 2020 <p>More useful is <code><a href="refC.html#collect">collect</a></code>; it 2021 returns a list of all objects that fall into a range of index values: 2022 2023 <pre><code> 2024 : (collect 'dat '+Person (date 1982 1 1) (date 1988 12 31)) 2025 -> ({2-M} {2-L} {2-E}) 2026 </code></pre> 2027 2028 <p>This returns all persons born between 1982 and 1988. Let's look at them with 2029 <code><a href="refS.html#show">show</a></code>: 2030 2031 <pre><code> 2032 : (more (collect 'dat '+Person (date 1982 1 1) (date 1988 12 31)) show) 2033 {2-M} (+Man) 2034 nm "William" 2035 dat 724023 2036 ma {2-K} 2037 pa {2-J} 2038 job "Heir to the throne" 2039 2040 {2-L} (+Man) 2041 nm "Henry" 2042 dat 724840 2043 ma {2-K} 2044 pa {2-J} 2045 job "Prince" 2046 2047 {2-E} (+Woman) 2048 nm "Beatrice" 2049 dat 726263 2050 ma {2-D} 2051 job "Princess" 2052 pa {2-B} 2053 </code></pre> 2054 2055 <p>If you are only interested in a certain attribute, e.g. the name, you can 2056 return it directly: 2057 2058 <pre><code> 2059 : (collect 'dat '+Person (date 1982 1 1) (date 1988 12 31) 'nm) 2060 -> ("William" "Henry" "Beatrice") 2061 </code></pre> 2062 2063 <p>To find a single object in the database, the function <code><a 2064 href="refD.html#db">db</a></code> is used: 2065 2066 <pre><code> 2067 : (db 'nm '+Person "Edward") 2068 -> {2-;} 2069 </code></pre> 2070 2071 <p>If the key is not unique, additional arguments may be supplied: 2072 2073 <pre><code> 2074 : (db 'nm '+Person "Edward" 'job "Prince" 'dat (date 1964 3 10)) 2075 -> {2-;} 2076 </code></pre> 2077 2078 <p>The programmer must know which combination of keys will suffice to specify 2079 the object uniquely. The tree search is performed using the first value 2080 ("Edward"), while all other attributes are used for filtering. Later, in 2081 the <a href="#pilog">Pilog</a> section, we will show how more general (and 2082 possibly more efficient) searches can be performed. 2083 2084 2085 <p><hr> 2086 <h2><a name="gui">User Interface (GUI) Programming</a></h2> 2087 2088 <p>The only types of GUI supported by the PicoLisp application server framework 2089 is either dynamically generated (but static by nature) HTML, or an interactive 2090 XHTML/CSS framework with the optional use of JavaScript. 2091 2092 <p>Before we explain the GUI of our demo database application, we present a 2093 minimal example for a plain HTML-GUI in <code><a 2094 href="hello.l">@doc/hello.l</a></code>. Start the application server as: 2095 2096 <pre><code> 2097 $ pil @lib/http.l --server 8080 @doc/hello.l -wait 2098 </code></pre> 2099 2100 <p>Now point your browser to the address '<code><a 2101 href="http://localhost:8080">http://localhost:8080</a></code>'. You should see a 2102 very simple HTML page. You can come back here with the browser's BACK button. 2103 2104 <p>You can call the page repeatedly, or concurrently with many clients if you 2105 like. To terminate the server, you have to send it a TERM signal (e.g. 2106 '<code>killall pil</code>'), or type the <code>Ctrl-C</code> key in the console 2107 window. 2108 2109 <p>In our demo database application, a single function <code>person</code> is 2110 responsible for the whole GUI. Again, please look at <code><a 2111 href="family.l">@doc/family.l</a></code>. 2112 2113 <p>To start the database <i>and</i> the application server, call: 2114 2115 <pre><code> 2116 $ pil family.l -main -go + 2117 </code></pre> 2118 2119 <p>As before, the database is opened with <code>main</code>. The function 2120 <code>go</code> is also defined in <code>@doc/family.l</code>: 2121 2122 <pre><code> 2123 (de go () 2124 (server 8080 "!person") ) 2125 </code></pre> 2126 2127 <p>It starts the HTTP server listening on TCP port 8080 (we did a similar thing 2128 in our minimal GUI example above directly on the command line). Each connect to 2129 that port will cause the function <code>person</code> to be invoked. 2130 2131 <p>Again, point your browser to the address '<code><a 2132 href="http://localhost:8080" target="GUI">http://localhost:8080</a></code>'. 2133 2134 <p>You should see a new browser window with an input form created by the 2135 function <code>person</code>. We provided an initial database in "family/[1-4]". 2136 You can navigate through it by clicking on the pencil icons besides the input 2137 fields. 2138 2139 <p>The chart with the children data can be scrolled using the down 2140 (<code>v</code>) and up (<code>^</code>) buttons. 2141 2142 <p>A click on the button "Select" below opens a search dialog. You can scroll 2143 through the chart as before. Again, a click on a pencil will jump to that 2144 person. You can abort the dialog with a click on the "Cancel"-button. 2145 2146 <p>The search fields in the upper part of the dialog allow a conjunctive search. 2147 If you enter "Edward" in the "Name" field and click "Search", you'll see all 2148 persons having the string "Edward" in their name. If you also enter "Duke" in 2149 the "Occupation" field, the result list will reduce to only two entries. 2150 2151 <p>To create a new person, press the "New Man" or "New Woman" button. A new 2152 empty form will be displayed. Please type a name into the first field, and 2153 perhaps also an occupation and birth date. Any change of contents should be 2154 followed by a press on the "Done" button, though any other button (also Scroll 2155 or Select-buttons) will also do. 2156 2157 <p>To assign a <i>father</i> attribute, you can either type a name directly into 2158 the field (if that person already exists in the database and you know the exact 2159 spelling), or use the "Set"-button (<code>-></code>) to the left of that 2160 field to open the search dialog. If you type in the name directly, your input 2161 must exactly match upper and lower case. 2162 2163 <p>Alternatively, you may create a new person and assign a child in the 2164 "Children" chart. 2165 2166 <p>On the console where you started PicoLisp, there should a prompt have 2167 appeared just when the browser connected. You can debug the application 2168 interactively while it is running. For example, the global variable 2169 <code>*Top</code> always contains the top level GUI object: 2170 2171 <pre><code> 2172 : (show *Top) 2173 </code></pre> 2174 2175 <p>To take a look at the first field on the form: 2176 2177 <pre><code> 2178 : (show *Top 'gui 1) 2179 </code></pre> 2180 2181 <p>A production application would be started in a slightly different way: 2182 2183 <pre><code> 2184 $ pil family.l -main -go -wait 2185 </code></pre> 2186 2187 <p>In that case, no debug prompt will appear. In both cases, however, two 2188 <code>pil</code> processes will be running now. One is the initial server 2189 process which will continue to run until it is killed. The other is a child 2190 process holding the state of the GUI in the browser. It will terminate some time 2191 after the browser is closed, or when <code>(<a 2192 href="refB.html#bye">bye</a>)</code> or a <code>Ctrl-D</code> is entered at the 2193 PicoLisp prompt. 2194 2195 <p>Now back to the explanation of the GUI function <code>person</code>: 2196 2197 <pre><code> 2198 (de person () 2199 (app) 2200 (action 2201 (html 0 (get (default *ID (val *DB)) 'nm) "@lib.css" NIL 2202 (form NIL 2203 (<h2> (<id> (: nm))) 2204 </code></pre> 2205 2206 <p>For an in-depth explanation of that startup code, please refer to the guide 2207 to <a href="app.html">PicoLisp Application Development</a>. 2208 2209 <p>All components like fields and buttons are controlled by <code>form</code>. 2210 The function <code>gui</code> creates a single GUI component and takes the type 2211 (a list of classes) and a variable number of arguments depending on the needs of 2212 these classes. 2213 2214 <pre><code> 2215 (gui '(+E/R +TextField) '(nm : home obj) 40 "Name") 2216 </code></pre> 2217 2218 <p>This creates a <code>+TextField</code> with the label "Name" and a length of 2219 40 characters. The <code>+E/R</code> (: Entity/Relation) prefix class connects 2220 that field to a database object, the <code>nm</code> attribute of a person in 2221 this case, so that the person's name is displayed in that text field, and any 2222 changes entered into that field are propagated to the database automatically. 2223 2224 <pre><code> 2225 (gui '(+ClassField) '(: home obj) '(("Male" +Man) ("Female" +Woman))) 2226 </code></pre> 2227 2228 <p>A <code>+ClassField</code> displays and changes the class of an object, in 2229 this case the person's sex from <code>+Man</code> to <code>+Woman</code> and 2230 vice versa. 2231 2232 <p>As you see, there is no place where explicit accesses to the database have to 2233 be programmed, no <code>select</code> or <code>update</code>. This is all 2234 encapsulated in the GUI components, mainly in the <code>+E/R</code> prefix 2235 class. The above function <code>person</code> is fully functional as we present 2236 it and allows creation, modification and deletion of person objects in the 2237 database. 2238 2239 <p>The two buttons on the bottom right generate simple reports: 2240 2241 <p>The first one shows all contemporaries of the person that is currently 2242 displayed, i.e. all persons who did not die before, or were not born after that 2243 person. This is a typical PicoLisp report, in that in addition to the report's 2244 HTML page, a temporary file may be generated, suitable for download (and import 2245 into a spread sheet), and from which a PDF can be produced for print-out. 2246 2247 <p>In PicoLisp, there is not a real difference between a plain HTML-GUI and a 2248 report. Again, the function <code>html</code> is used to generate the page. 2249 2250 <p>The second report is much simpler. It produces a recursive structure of the 2251 family. 2252 2253 <p>In both reports, links to the person objects are created which allow easy 2254 navigation through the database. 2255 2256 2257 <p><hr> 2258 <h2><a name="pilog">Pilog -- PicoLisp Prolog</a></h2> 2259 2260 <p>This sections explains some cases of using Pilog in typical application 2261 programming, in combination with persistent objects and databases. Please refer 2262 to the <a href="ref.html#pilog">Pilog</a> section of the PicoLisp Reference for 2263 the basic usage of Pilog. 2264 2265 <p>Again, we use our demo application <code><a 2266 href="family.l">@doc/family.l</a></code> that was introduced in the <a 2267 href="#db">Database Programming</a> section. 2268 2269 <p>Normally, Pilog is used either interactively to query the database during 2270 debugging, or in applications to generate export data and reports. In the 2271 following examples we use the interactive query front-end functions <code><a 2272 href="ref_.html#?">?</a></code> and <code><a 2273 href="refS.html#select">select</a></code>. An application will use <code><a 2274 href="refG.html#goal">goal</a></code> and <code><a 2275 href="refP.html#prove">prove</a></code> directly, or use convenience functions 2276 like <code><a href="refP.html#pilog">pilog</a></code> or <code><a 2277 href="refS.html#solve">solve</a></code>. 2278 2279 <p>All Pilog access to external symbols is done via the two predicates <code><a 2280 href="refD.html#db/3">db/3</a></code> and <code><a 2281 href="refS.html#select/3">select/3</a></code>. 2282 2283 <ul> 2284 2285 <li><code><a href="refD.html#db/3">db/3</a></code> corresponds to the Lisp-level 2286 functions <code><a href="refD.html#db">db</a></code> and <code><a 2287 href="refC.html#collect">collect</a></code>, as it derives its data from a 2288 single relation. It can be used for simple database queries. 2289 2290 <li><code><a href="refS.html#select/3">select/3</a></code> provides for 2291 self-optimizing parallel access to an arbitrary number of relations. There is 2292 also a Lisp front-end function <code><a 2293 href="refS.html#select">select</a></code>, for convenient calls to the Pilog 2294 <code>select</code> predicate. 2295 2296 </ul> 2297 2298 <p>A predicate <code><a href="refS.html#show/1">show/1</a></code> is pre-defined 2299 for debugging purposes (a simple glue to the Lisp-level function 2300 <code>show</code>, see <a href="#brw">Browsing</a>). Searching with <code><a 2301 href="refD.html#db/3">db/3</a></code> for all persons having the string "Edward" 2302 in their name: 2303 2304 <pre><code> 2305 : (? (db nm +Person "Edward" @P) (show @P)) 2306 {2-;} (+Man) 2307 nm "Edward" 2308 ma {2-:} 2309 pa {2-A} 2310 dat 717346 2311 job "Prince" 2312 @P={2-;} 2313 {2-1B} (+Man) 2314 nm "Albert Edward" 2315 kids ({2-1C} {2-1D} {2-1E} {2-1F} {2-1G} {2-1H} {2-1I} {2-g} {2-a}) 2316 job "Prince" 2317 mate {2-f} 2318 fin 680370 2319 dat 664554 2320 @P={2-1B} 2321 ... # more results 2322 </code></pre> 2323 2324 <p>To search for all persons with "Edward" in their name who are married to 2325 somebody with occupation "Queen": 2326 2327 <pre><code> 2328 : (? (db nm +Person "Edward" @P) (val "Queen" @P mate job) (show @P)) 2329 {2-1B} (+Man) 2330 mate {2-f} 2331 nm "Albert Edward" 2332 kids ({2-1C} {2-1D} {2-1E} {2-1F} {2-1G} {2-1H} {2-1I} {2-g} {2-a}) 2333 job "Prince" 2334 fin 680370 2335 dat 664554 2336 @P={2-1B} 2337 -> NIL # only one result 2338 </code></pre> 2339 2340 <p>If you are interested in the names of "Albert Edward"'s children: 2341 2342 <pre><code> 2343 : (? (db nm +Person "Albert Edward" @P) (lst @K @P kids) (val @Kid @K nm)) 2344 @P={2-1B} @K={2-1C} @Kid="Beatrice Mary Victoria" 2345 @P={2-1B} @K={2-1D} @Kid="Leopold George Duncan" 2346 @P={2-1B} @K={2-1E} @Kid="Arthur William Patrick" 2347 @P={2-1B} @K={2-1F} @Kid="Louise Caroline Alberta" 2348 @P={2-1B} @K={2-1G} @Kid="Helena Augusta Victoria" 2349 @P={2-1B} @K={2-1H} @Kid="Alfred Ernest Albert" 2350 @P={2-1B} @K={2-1I} @Kid="Alice Maud Mary" 2351 @P={2-1B} @K={2-g} @Kid="Victoria Adelaide Mary" 2352 @P={2-1B} @K={2-a} @Kid="Edward VII" 2353 -> NIL 2354 </code></pre> 2355 2356 <p><code><a href="refD.html#db/3">db/3</a></code> can do a direct index access 2357 only for a single attribute (<code>nm</code> of <code>+Person</code> above). To 2358 search for several criteria at the same time, <code><a 2359 href="refS.html#select/3">select/3</a></code> has to be used: 2360 2361 <pre><code> 2362 : (? 2363 (select (@P) 2364 ((nm +Person "Edward") (nm +Person "Augusta" pa)) # Generator clauses 2365 (tolr "Edward" @P nm) # Filter clauses 2366 (tolr "Augusta" @P kids nm) ) 2367 (show @P) ) 2368 {2-1B} (+Man) 2369 kids ({2-1C} {2-1D} {2-1E} {2-1F} {2-1G} {2-1H} {2-1I} {2-g} {2-a}) 2370 mate {2-f} 2371 nm "Albert Edward" 2372 job "Prince" 2373 fin 680370 2374 dat 664554 2375 @P={2-1B} 2376 -> NIL 2377 </code></pre> 2378 2379 <p><code><a href="refS.html#select/3">select/3</a></code> takes a list of 2380 generator clauses which are used to retrieve objects from the database, and a 2381 number of normal Pilog filter clauses. In the example above the generators are 2382 2383 <ul> 2384 2385 <li><code>(nm +Person "Edward")</code> to generate persons with "Edward" in 2386 their names, and 2387 2388 <li><code>(nm +Person "Augusta" pa)</code> to find persons with "Augusta" 2389 in their names and generate persons using the <code>pa</code> ("father") 2390 attribute. 2391 2392 </ul> 2393 2394 <p>All persons generated are possible candidates for our selection. The 2395 <code>nm</code> index tree of <code>+Person</code> is traversed twice in 2396 parallel, optimizing the search in such a way that successful hits get higher 2397 priority in the search, depending on the filter clauses. The process will stop 2398 as soon as any one of the generators is exhausted. Note that this is different 2399 from the standard Prolog search algorithm. 2400 2401 <p>The filter clauses in this example both use the pre-defined predicate 2402 <code><a href="refT.html#tolr/3">tolr/3</a></code> for <i>tolerant</i> string 2403 matches (according either to the soundex algorithm (see the section <a 2404 href="#db">Database Programming</a>) or to substring matches), and filter 2405 objects that 2406 2407 <ul> 2408 2409 <li>match "Edward" in their name: <code>(tolr "Edward" @P nm)</code>, and 2410 2411 <li>match "Augusta" in one of their kids' names: <code>(tolr "Augusta" @P 2412 kids nm)</code> 2413 2414 </ul> 2415 2416 <p>A more typical and extensive example for the usage of <code>select</code> can 2417 be found in the <code>qPerson</code> function in <code><a 2418 href="family.l">@doc/family.l</a></code>. It is used in the search dialog of the 2419 demo application, and searches for a person with the name, the parents' and 2420 partner's names, the occupation and a time range for the birth date. The 2421 relevant index trees in the database are searched (actually only those trees 2422 where the user entered a search key in the corresponding dialog field), and a 2423 logical AND of the search attributes is applied to the result. 2424 2425 <p>For example, press the "Select" button, enter "Elizabeth" into the "Mother" 2426 search field and "Phil" in the "Partner" search field, meaning to look for all 2427 persons whose mother's name is like "Elizabeth" and whose partner's name is like 2428 "Phil". As a result, two persons ("Elizabeth II" and "Anne") will show up. 2429 2430 <p>In principle, <code><a href="refD.html#db/3">db/3</a></code> can be seen as a 2431 special case of <code><a href="refS.html#select/3">select/3</a></code>. The 2432 following two queries are equivalent: 2433 2434 <pre><code> 2435 : (? (db nm +Person "Edward" @P)) 2436 @P={2-;} 2437 @P={2-1B} 2438 @P={2-R} 2439 @P={2-1K} 2440 @P={2-a} 2441 @P={2-T} 2442 -> NIL 2443 : (? (select (@P) ((nm +Person "Edward")))) 2444 @P={2-;} 2445 @P={2-1B} 2446 @P={2-R} 2447 @P={2-1K} 2448 @P={2-a} 2449 @P={2-T} 2450 -> NIL 2451 </code></pre> 2452 2453 2454 <p><hr> 2455 <h2><a name="sql">Poor Man's SQL</a></h2> 2456 2457 <h3>select</h3> 2458 2459 <p>For convenience, a <code><a href="refS.html#select">select</a></code> Lisp 2460 glue function is provided as a front-end to the <code>select</code> predicate. 2461 Note that this function does not evaluate its arguments (it is intended for 2462 interactive use), and that it supports only a subset of the predicate's 2463 functionality. The syntax resembles SELECT in the SQL language, for example: 2464 2465 <pre><code> 2466 # SELECT * FROM Person 2467 : (select +Person) # Step through the whole database 2468 {2-o} (+Man) 2469 nm "Adalbert Ferdinand Berengar Viktor of Prussia" 2470 dat 688253 2471 ma {2-j} 2472 pa {2-h} 2473 fin 711698 2474 2475 {2-1B} (+Man) 2476 nm "Albert Edward" 2477 dat 664554 2478 job "Prince" 2479 mate {2-f} 2480 kids ({2-1C} {2-1D} {2-1E} {2-1F} {2-1G} {2-1H} {2-1I} {2-g} {2-a}) 2481 fin 680370 2482 ... 2483 </code></pre> 2484 2485 <pre><code> 2486 # SELECT * FROM Person WHERE nm LIKE "%Edward%" 2487 : (select +Person nm "Edward") # Show all Edwards 2488 {2-;} (+Man) 2489 nm "Edward" 2490 dat 717346 2491 job "Prince" 2492 ma {2-:} 2493 pa {2-A} 2494 2495 {2-1B} (+Man) 2496 nm "Albert Edward" 2497 dat 664554 2498 job "Prince" 2499 kids ({2-1C} {2-1D} {2-1E} {2-1F} {2-1G} {2-1H} {2-1I} {2-g} {2-a}) 2500 mate {2-f} 2501 fin 680370 2502 ... 2503 </code></pre> 2504 2505 <pre><code> 2506 # SELECT nm, dat FROM Person WHERE nm LIKE "%Edward%" 2507 : (select nm dat +Person nm "Edward") 2508 "Edward" "1964-03-10" {2-;} 2509 "Albert Edward" "1819-08-26" {2-1B} 2510 "George Edward" NIL {2-R} 2511 "Edward Augustus Hanover" NIL {2-1K} 2512 ... 2513 </code></pre> 2514 2515 <pre><code> 2516 # SELECT dat, fin, p1.nm, p2.nm 2517 # FROM Person p1, Person p2 2518 # WHERE p1.nm LIKE "%Edward%" 2519 # AND p1.job LIKE "King%" 2520 # AND p1.mate = p2.mate -- Actually, in a SQL model we'd need 2521 # -- another table here for the join 2522 : (select dat fin nm (mate nm) +Person nm "Edward" job "King") 2523 "1894-06-23" "1972-05-28" "Edward VIII" "Wallace Simpson" {2-T} 2524 "1841-11-09" NIL "Edward VII" "Alexandra of Denmark" {2-a} 2525 -> NIL 2526 </code></pre> 2527 2528 2529 <h3>update</h3> 2530 2531 <p>In addition (just to stay with the SQL terminology ;-), there is also an 2532 <code><a href="refU.html#update">update</a></code> function. It is a front-end 2533 to the <code><a href="refE.html#entityMesssages">set!></a></code> and <code><a 2534 href="refE.html#entityMesssages">put!></a></code> transaction methods, and 2535 should be used when single objects in the database have to be modified by hand. 2536 2537 <p>In principle, it would also be possible to use the <code><a 2538 href="refE.html#edit">edit</a></code> function to modify a database object. This 2539 is not recommended, however, because <code>edit</code> does not know about 2540 relations to other objects (like Links, Joints and index trees) and may easily 2541 cause database corruption. 2542 2543 <p>In the most general case, the value of a property in a database object is 2544 changed with the <code>put!></code> method. Let's look at "Edward" from the 2545 previous examples: 2546 2547 <pre><code> 2548 : (show '{2-;}) 2549 {2R} (+Man) 2550 job "Prince" 2551 nm "Edward" 2552 dat 717346 2553 ma {2-:} 2554 pa {20A} 2555 -> {2-;} 2556 </code></pre> 2557 2558 <p>We might change the name to "Johnny" with <code>put!></code>: 2559 2560 <pre><code> 2561 : (put!> '{2-;} 'nm "Johnny") 2562 -> "Johnny" 2563 </code></pre> 2564 2565 <p>However, an easier and less error-prone prone way - especially when more than 2566 one property has to be changed - is using <code><a 2567 href="refU.html#update">update</a></code>. It presents the value (the list of 2568 classes) and then each property on its own line, allowing the user to change it 2569 with the <a href="#ledit">command line editor</a>. 2570 2571 <p>Just hitting ENTER will leave that property unchanged. To modify it, you'll 2572 typically hit ESC to get into command mode, and move the cursor to the point of 2573 change. 2574 2575 <p>For properties with nested list structures (<code>+List +Bag</code>), 2576 <code>update</code> will recurse into the data structure. 2577 2578 <pre><code> 2579 : (update '{2-;}) 2580 {2-;} (+Man) # ENTER 2581 nm "Johnny" # Modified the name to "Johnny" 2582 ma {2-:} # ENTER 2583 pa {2-A} # ENTER 2584 dat 1960-03-10 # Modified the year from "1964" to "1960" 2585 job "Prince" # ENTER 2586 -> {2-;} 2587 </code></pre> 2588 2589 <p>All changes are committed immediately, observing the rules of database 2590 synchronization so that any another user looking at the same object will have 2591 his GUI updated correctly. 2592 2593 <p>To abort <code>update</code>, hit <code>Ctrl-X</code>. 2594 2595 <p>If only a single property has to be changed, <code>update</code> can be 2596 called directly for that property: 2597 2598 <pre><code> 2599 : (update '{2-;} 'nm) 2600 {2-;} nm "Edward" 2601 ... 2602 </code></pre> 2603 2604 2605 <p><hr> 2606 <h2><a name="ref">References</a></h2> 2607 2608 <p><a name="knuth73">[knuth73]</a> Donald E. Knuth: ``The Art of Computer 2609 Programming'', Vol.3, Addison-Wesley, 1973, p. 392 2610 2611 </body> 2612 </html>