API tools faq
paste
Guest User

Single-page Picolisp Reference #2

a guest
Oct 15th, 2015
28
0
Never
Add comment
Not a member of Pastebin yet? Sign Up, it unlocks many cool features!
text 475.39 KB | None | 0 0
raw download clone embed print report
  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 Reference</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. <p align=right>
  12. <i>Perfection is attained</i><br>
  13. <i>not when there is nothing left to add</i><br>
  14. <i>but when there is nothing left to take away</i><br>
  15. <i>(Antoine de Saint-Exupéry)</i><br>
  16.  
  17.  
  18. <h1>The PicoLisp Reference</h1>
  19.  
  20. <p align=right>(c) Software Lab. Alexander Burger
  21.  
  22. <p>This document describes the concepts, data types, and kernel functions of the
  23. <a href="http://software-lab.de/down.html">PicoLisp</a> system.
  24.  
  25. <p>This is <i>not</i> a Lisp tutorial. For an introduction to Lisp, a
  26. traditional Lisp book like "Lisp" by Winston/Horn (Addison-Wesley 1981) is
  27. recommended. Note, however, that there are significant differences between
  28. PicoLisp and Maclisp (and even greater differences to Common Lisp).
  29.  
  30. <p>Please take a look at the <a href="tut.html">PicoLisp Tutorial</a> for an
  31. explanation of some aspects of PicoLisp, and scan through the list of <a
  32. href="faq.html">Frequently Asked Questions (FAQ)</a>.
  33.  
  34. <p><ul>
  35. <li><a href="#intro">Introduction</a>
  36. <li><a href="#vm">The PicoLisp Machine</a>
  37. <ul>
  38. <li><a href="#cell">The Cell</a>
  39. <li><a href="#data">Data Types</a>
  40. <ul>
  41. <li><a href="#number">Numbers</a>
  42. <li><a href="#symbol">Symbols</a>
  43. <ul>
  44. <li><a href="#nilSym">NIL</a>
  45. <li><a href="#internal">Internal Symbols</a>
  46. <li><a href="#transient">Transient Symbols</a>
  47. <li><a href="#external">External Symbols</a>
  48. </ul>
  49. <li><a href="#lst">Lists</a>
  50. </ul>
  51. <li><a href="#mem">Memory Management</a>
  52. </ul>
  53. <li><a href="#penv">Programming Environment</a>
  54. <ul>
  55. <li><a href="#inst">Installation</a>
  56. <li><a href="#invoc">Invocation</a>
  57. <li><a href="#io">Input/Output</a>
  58. <ul>
  59. <li><a href="#num-io">Numbers</a>
  60. <li><a href="#sym-io">Symbols</a>
  61. <ul>
  62. <li><a href="#nilSym-io">NIL</a>
  63. <li><a href="#internal-io">Internal Symbols</a>
  64. <li><a href="#transient-io">Transient Symbols</a>
  65. <li><a href="#external-io">External Symbols</a>
  66. </ul>
  67. <li><a href="#lst-io">Lists</a>
  68. <li><a href="#macro-io">Read-Macros</a>
  69. </ul>
  70. <li><a href="#ev">Evaluation</a>
  71. <li><a href="#libs">Shared Libraries</a>
  72. <li><a href="#coroutines">Coroutines</a>
  73. <li><a href="#int">Interrupt</a>
  74. <li><a href="#errors">Error Handling</a>
  75. <li><a href="#atres">@ Result</a>
  76. <li><a href="#cmp">Comparing</a>
  77. <li><a href="#oop">OO Concepts</a>
  78. <li><a href="#dbase">Database</a>
  79. <ul>
  80. <li><a href="#trans">Transactions</a>
  81. <li><a href="#er">Entities / Relations</a>
  82. </ul>
  83. <li><a href="#pilog">Pilog (PicoLisp Prolog)</a>
  84. <li><a href="#conv">Naming Conventions</a>
  85. <li><a href="#trad">Breaking Traditions</a>
  86. <li><a href="#bugs">Bugs</a>
  87. </ul>
  88. <li><a href="#fun">Function Reference</a>
  89. <li><a href="#down">Download</a>
  90. </ul>
  91.  
  92.  
  93. <p><hr>
  94. <h2><a name="intro">Introduction</a></h2>
  95.  
  96. <p>PicoLisp is the result of a language design study, trying to answer the
  97. question "What is a minimal but useful architecture for a virtual machine?".
  98. Because opinions differ about what is meant by "minimal" and "useful", there are
  99. many answers to that question, and people might consider other solutions more
  100. "minimal" or more "useful". But from a practical point of view, PicoLisp has
  101. proven to be a valuable answer to that question.
  102.  
  103. <p>First of all, PicoLisp is a virtual machine architecture, and then a
  104. programming language. It was designed in a "bottom up" way, and "bottom up" is
  105. also the most natural way to understand and to use it: <i>Form Follows
  106. Function</i>.
  107.  
  108. <p>PicoLisp has been used in several commercial and research programming
  109. projects since 1988. Its internal structures are simple enough, allowing an
  110. experienced programmer always to fully understand what's going on under the
  111. hood, and its language features, efficiency and extensibility make it suitable
  112. for almost any practical programming task.
  113.  
  114. <p>In a nutshell, emphasis was put on four design objectives. The PicoLisp
  115. system should be
  116.  
  117. <p><dl>
  118.  
  119. <dt>Simple
  120. <dd>The internal data structure should be as simple as possible. Only one single
  121. data structure is used to build all higher level constructs.
  122.  
  123. <dt>Unlimited
  124. <dd>There are no limits imposed upon the language due to limitations of the
  125. virtual machine architecture. That is, there is no upper bound in symbol name
  126. length, number digit counts, stack depth, or data structure and buffer sizes,
  127. except for the total memory size of the host machine.
  128.  
  129. <dt>Dynamic
  130. <dd>Behavior should be as dynamic as possible ("run"-time vs. "compile"-time).
  131. All decisions are delayed until runtime where possible. This involves matters
  132. like memory management, dynamic symbol binding, and late method binding.
  133.  
  134. <dt>Practical
  135. <dd>PicoLisp is not just a toy of theoretical value. It is in use since 1988 in
  136. actual application development, research and production.
  137.  
  138. </dl>
  139.  
  140.  
  141. <p><hr>
  142. <h2><a name="vm">The PicoLisp Machine</a></h2>
  143.  
  144. <p>An important point in the PicoLisp philosophy is the knowledge about the
  145. architecture and data structures of the internal machinery. The high-level
  146. constructs of the programming language directly map to that machinery, making
  147. the whole system both understandable and predictable.
  148.  
  149. <p>This is similar to assembly language programming, where the programmer has
  150. complete control over the machine.
  151.  
  152.  
  153. <p><hr>
  154. <h3><a name="cell">The Cell</a></h3>
  155.  
  156. <p>The PicoLisp virtual machine is both simpler and more powerful than most
  157. current (hardware) processors. At the lowest level, it is constructed from a
  158. single data structure called "cell":
  159.  
  160. <pre><code>
  161. +-----+-----+
  162. | CAR | CDR |
  163. +-----+-----+
  164. </code></pre>
  165.  
  166. <p>A cell is a pair of machine words, which traditionally are called CAR and CDR
  167. in the Lisp terminology. These words can represent either a numeric value
  168. (scalar) or the address of another cell (pointer). All higher level data
  169. structures are built out of cells.
  170.  
  171. <p>The type information of higher level data is contained in the pointers to
  172. these data. Assuming the implementation on a byte-addressed physical machine,
  173. and a pointer size of typically 4 bytes, each cell has a size of 8 bytes.
  174. Therefore, the pointer to a cell must point to an 8-byte boundary, and its
  175. bit-representation will look like:
  176.  
  177. <pre><code>
  178. xxxxxxxxxxxxxxxxxxxxxxxxxxxxx000
  179. </code></pre>
  180.  
  181. <p>(the '<code>x</code>' means "don't care"). For the individual data types, the
  182. pointer is adjusted to point to other parts of a cell, in effect setting some of
  183. the lower three bits to non-zero values. These bits are then used by the
  184. interpreter to determine the data type.
  185.  
  186. <p>In any case, bit(0) - the least significant of these bits - is reserved as a
  187. mark bit for garbage collection.
  188.  
  189. <p>Initially, all cells in the memory are unused (free), and linked together to
  190. form a "free list". To create higher level data types at runtime, cells are
  191. taken from that free list, and returned by the garbage collector when they are
  192. no longer needed. All memory management is done via that free list; there are no
  193. additional buffers, string spaces or special memory areas, with two exceptions:
  194.  
  195. <p><ul>
  196. <li>A certain fixed area of memory is set aside to contain the executable code
  197. and global variables of the interpreter itself, and
  198.  
  199. <li>a standard push down stack for return addresses and temporary storage. Both
  200. are not directly accessible by the programmer).
  201.  
  202. </ul>
  203.  
  204. <p><hr>
  205. <h3><a name="data">Data Types</a></h3>
  206.  
  207. <p>On the virtual machine level, PicoLisp supports
  208.  
  209. <p><ul>
  210. <li>three base data types: Numbers, Symbols and Cons Pairs (Lists),
  211. <li>the three scope variations of symbols: Internal, Transient and External, and
  212. <li>the special symbol <code>NIL</code>.
  213. </ul>
  214.  
  215. <p>They are all built from the single cell data structure, and all runtime data
  216. cannot consist of any other types than these three.
  217.  
  218. <p>The following diagram shows the complete data type hierarchy, consisting of
  219. the three base types and the symbol variations:
  220.  
  221. <pre><code>
  222. cell
  223. |
  224. +--------+--------+
  225. | | |
  226. Number Symbol Pair
  227. |
  228. |
  229. +--------+--------+--------+
  230. | | | |
  231. NIL Internal Transient External
  232. </code></pre>
  233.  
  234.  
  235. <p><hr>
  236. <h4><a name="number">Numbers</a></h4>
  237.  
  238. <p>A number can represent a signed integral value of arbitrary size. The CARs of
  239. one or more cells hold the number's "digits" (each in the machine's word size),
  240. to store the number's binary representation.
  241.  
  242. <pre><code>
  243. Number
  244. |
  245. V
  246. +-----+-----+
  247. | DIG | | |
  248. +-----+--+--+
  249. |
  250. V
  251. +-----+-----+
  252. | DIG | | |
  253. +-----+--+--+
  254. |
  255. V
  256. ...
  257. </code></pre>
  258.  
  259. <p>The first cell holds the least significant digit. The least significant bit
  260. of that digit represents the sign.
  261.  
  262. <p>The pointer to a number points into the middle of the CAR, with an offset of
  263. 2 from the cell's start address. Therefore, the bit pattern of a number will be:
  264.  
  265. <pre><code>
  266. xxxxxxxxxxxxxxxxxxxxxxxxxxxxx010
  267. </code></pre>
  268.  
  269. <p>Thus, a number is recognized by the interpreter when bit(1) is non-zero.
  270.  
  271.  
  272. <p><hr>
  273. <h4><a name="symbol">Symbols</a></h4>
  274.  
  275. <p>A symbol is more complex than a number. Each symbol has a value, and
  276. optionally a name and an arbitrary number of properties. The CDR of a symbol
  277. cell is also called VAL, and the CAR points to the symbol's tail. As a minimum,
  278. a symbol consists of a single cell, and has no name or properties:
  279.  
  280. <pre><code>
  281. Symbol
  282. |
  283. V
  284. +-----+-----+
  285. | / | VAL |
  286. +-----+-----+
  287. </code></pre>
  288.  
  289. <p>That is, the symbol's tail is empty (points to <code>NIL</code>, as indicated
  290. by the '<code>/</code>' character).
  291.  
  292. <p>The pointer to a symbol points to the CDR of the cell, with an offset of 4
  293. from the cell's start address. Therefore, the bit pattern of a symbol will be:
  294.  
  295. <pre><code>
  296. xxxxxxxxxxxxxxxxxxxxxxxxxxxxx100
  297. </code></pre>
  298.  
  299. <p>Thus, a symbol is recognized by the interpreter when bit(2) is non-zero.
  300.  
  301. <p>A property is a key-value pair, represented by a cons pair in the symbol's
  302. tail. This is called a "property list". The property list may be terminated by a
  303. number representing the symbol's name. In the following example, a symbol with
  304. the name <code>"abc"</code> has three properties: A KEY/VAL pair, a cell with
  305. only a KEY, and another KEY/VAL pair.
  306.  
  307. <pre><code>
  308. Symbol
  309. |
  310. V
  311. +-----+-----+
  312. | | | VAL |
  313. +--+--+-----+
  314. | tail
  315. |
  316. V name
  317. +-----+-----+ +-----+-----+ +-----+-----+ +-----+-----+
  318. | | | ---+---> | KEY | ---+---> | | | ---+---> |'cba'| / |
  319. +--+--+-----+ +-----+-----+ +--+--+-----+ +-----+-----+
  320. | |
  321. V V
  322. +-----+-----+ +-----+-----+
  323. | VAL | KEY | | VAL | KEY |
  324. +-----+-----+ +-----+-----+
  325. </code></pre>
  326.  
  327. <p>Each property in a symbol's tail is either a symbol (like the single KEY
  328. above, then it represents the boolean value <code>T</code>), or a cons pair with
  329. the property key in its CDR and the property value in its CAR. In both cases,
  330. the key should be a symbol, because searches in the property list are performed
  331. using pointer comparisons.
  332.  
  333. <p>The name of a symbol is stored as a number at the end of the tail. It
  334. contains the characters of the name in UTF-8 encoding, using between one and
  335. three 8-bit-bytes per character. The first byte of the first character is stored
  336. in the lowest 8 bits of the number.
  337.  
  338. <p>All symbols have the above structure, but depending on scope and
  339. accessibility there are actually four types of symbols: <code><a
  340. href="#nilSym">NIL</a></code>, <a href="#internal">internal</a>, <a
  341. href="#transient">transient</a> and <a href="#external">external</a> symbols.
  342.  
  343.  
  344. <p><hr>
  345. <h5><a name="nilSym">NIL</a></h5>
  346.  
  347. <p><code>NIL</code> is a special symbol which exists exactly once in the whole
  348. system. It is used
  349.  
  350. <p><ul>
  351. <li>as an end-of-list marker
  352. <li>to represent the empty list
  353. <li>to represent the boolean value "false"
  354. <li>to represent the absolute minimum
  355. <li>to represent a string of length zero
  356. <li>to represent the value "Not a Number"
  357. <li>as the root of all class hierarchies
  358. </ul>
  359.  
  360. <p>For that, <code>NIL</code> has a special structure:
  361.  
  362. <pre><code>
  363. NIL: /
  364. |
  365. V
  366. +-----+-----+-----+-----+
  367. | / | / | / | / |
  368. +-----+--+--+-----+-----+
  369. </code></pre>
  370.  
  371. <p>The reason for that structure is <code>NIL</code>'s dual nature both as a
  372. symbol and as a list:
  373.  
  374. <p><ul>
  375. <li>As a symbol, it should give <code>NIL</code> for its VAL, and be without
  376. properties
  377.  
  378. <li>For the empty list, <code>NIL</code> should give <code>NIL</code> both for
  379. its CAR and for its CDR
  380.  
  381. </ul>
  382.  
  383. <p>These requirements are fulfilled by the above structure.
  384.  
  385.  
  386. <p><hr>
  387. <h5><a name="internal">Internal Symbols</a></h5>
  388.  
  389. <p>Internal Symbols are all those "normal" symbols, as they are used for
  390. function definitions and variable names. They are "interned" into an index
  391. structure, so that it is possible to find an internal symbol by searching for
  392. its name.
  393.  
  394. <p>There cannot be two different internal symbols with the same name.
  395.  
  396. <p>Initially, a new internal symbol's VAL is <code>NIL</code>.
  397.  
  398.  
  399. <p><hr>
  400. <h5><a name="transient">Transient Symbols</a></h5>
  401.  
  402. <p>Transient symbols are only interned into a index structure for a certain time
  403. (e.g. while reading the current source file), and are released after that. That
  404. means, a transient symbol cannot be accessed then by its name, and there may be
  405. several transient symbols in the system having the same name.
  406.  
  407. <p>Transient symbols are used
  408.  
  409. <p><ul>
  410. <li>as text strings
  411.  
  412. <li>as identifiers with a limited access scope (like, for example,
  413. <code>static</code> identifiers in the C language family)
  414.  
  415. <li>as anonymous, dynamically created objects (without a name)
  416.  
  417. </ul>
  418.  
  419. <p>Initially, a new transient symbol's VAL is that symbol itself.
  420.  
  421. <p>A transient symbol without a name can be created with the <code><a
  422. href="#box">box</a></code> or <code><a
  423. href="#new">new</a></code> functions.
  424.  
  425.  
  426. <p><hr>
  427. <h5><a name="external">External Symbols</a></h5>
  428.  
  429. <p>External symbols reside in a database file (or a similar resources, see
  430. <code><a href="#*Ext">*Ext</a></code>), and are loaded into memory -
  431. and written back to the file - dynamically as needed, and transparently to the
  432. programmer. They are kept in memory ("cached") as long as they are accessible
  433. ("referred to") from other parts of the program, or when they were modified but
  434. not yet written to the database file (by <code><a
  435. href="#commit">commit</a></code>).
  436.  
  437. <p>The interpreter recognizes external symbols internally by an additional tag
  438. bit in the tail structure.
  439.  
  440. <p>There cannot be two different external symbols with the same name. External
  441. symbols are maintained in index structures while they are loaded into memory,
  442. and have their external location (disk file and block offset) directly coded
  443. into their names (more details <a href="#external-io">here</a>).
  444.  
  445. <p>Initially, a new external symbol's VAL is <code>NIL</code>, unless otherwise
  446. specified at creation time.
  447.  
  448.  
  449. <p><hr>
  450. <h4><a name="lst">Lists</a></h4>
  451.  
  452. <p>A list is a sequence of one or more cells (cons pairs), holding numbers,
  453. symbols, or cons pairs.
  454.  
  455. <pre><code>
  456. |
  457. V
  458. +-----+-----+
  459. | any | | |
  460. +-----+--+--+
  461. |
  462. V
  463. +-----+-----+
  464. | any | | |
  465. +-----+--+--+
  466. |
  467. V
  468. ...
  469. </code></pre>
  470.  
  471. <p>Lists are used in PicoLisp to emulate composite data structures like arrays,
  472. trees, stacks or queues.
  473.  
  474. <p>In contrast to lists, numbers and symbols are collectively called "Atoms".
  475.  
  476. <p>Typically, the CDR of each cell in a list points to the following cell,
  477. except for the last cell which points to <code>NIL</code>. If, however, the CDR of
  478. the last cell points to an atom, that cell is called a "dotted pair" (because of
  479. its I/O syntax with a dot '<code>.</code>' between the two values).
  480.  
  481.  
  482. <p><hr>
  483. <h3><a name="mem">Memory Management</a></h3>
  484.  
  485. <p>The PicoLisp interpreter has complete knowledge of all data in the system,
  486. due to the type information associated with every pointer. Therefore, an
  487. efficient garbage collector mechanism can easily be implemented. PicoLisp
  488. employs a simple but fast mark-and-sweep garbage collector.
  489.  
  490. <p>As the collection process is very fast (in the order of milliseconds per
  491. megabyte), it was not necessary to develop more complicated, time-consuming and
  492. error-prone garbage collection algorithms (e.g. incremental collection). A
  493. compacting garbage collector is also not necessary, because the single cell data
  494. type cannot cause heap fragmentation.
  495.  
  496.  
  497. <p><hr>
  498. <h2><a name="penv">Programming Environment</a></h2>
  499.  
  500. <p>Lisp was chosen as the programming language, because of its clear and simple
  501. structure.
  502.  
  503. <p>In some previous versions, a Forth-like syntax was also implemented on top of
  504. a similar virtual machine (Lifo). Though that language was more flexible and
  505. expressive, the traditional Lisp syntax proved easier to handle, and the virtual
  506. machine can be kept considerably simpler.
  507.  
  508. PicoLisp inherits the major advantages of classical Lisp systems like
  509.  
  510. <p><ul>
  511. <li>Dynamic data types and structures
  512. <li>Formal equivalence of code and data
  513. <li>Functional programming style
  514. <li>An interactive environment
  515. </ul>
  516.  
  517. <p>In the following, some concepts and peculiarities of the PicoLisp language
  518. and environment are described.
  519.  
  520.  
  521. <p><hr>
  522. <h3><a name="inst">Installation</a></h3>
  523.  
  524. <p>PicoLisp supports two installation strategies: Local and Global.
  525.  
  526. <p>Normally, if you didn't build PicoLisp yourself but installed it with your
  527. operating system's package manager, you will have a global installation. This
  528. allows system-wide access to the executable and library/documentation files.
  529.  
  530. <p>To get a local installation, you can directly download the PicoLisp tarball,
  531. and follow the instructions in the INSTALL file.
  532.  
  533. <p>A local installation will not interfere in any way with the world outside its
  534. directory. There is no need to touch any system locations, and you don't have to
  535. be root to install it. Many different versions - or local modifications - of
  536. PicoLisp can co-exist on a single machine.
  537.  
  538. <p>Note that you are still free to have local installations along with a global
  539. installation, and invoke them explicitly as desired.
  540.  
  541. <p>Most examples in the following apply to a global installation.
  542.  
  543.  
  544. <p><hr>
  545. <h3><a name="invoc">Invocation</a></h3>
  546.  
  547. <p>When PicoLisp is invoked from the command line, an arbitrary number of
  548. arguments may follow the command name.
  549.  
  550. <p>By default, each argument is the name of a file to be executed by the
  551. interpreter. If, however, the argument's first character is a hyphen
  552. '<code>-</code>', then the rest of that argument is taken as a Lisp function
  553. call (without the surrounding parentheses), and a hyphen by itself as an
  554. argument stops evaluation of the rest of the command line (it may be processed
  555. later using the <code><a href="#argv">argv</a></code> and <code><a
  556. href="#opt">opt</a></code> functions). This whole mechanism corresponds
  557. to calling <code>(<a href="#load">load</a> T)</code>.
  558.  
  559. <p>A special case is if the last argument is a single '<code>+</code>'. This
  560. will switch on debug mode (the <code><a href="#*Dbg">*Dbg</a></code>
  561. global variable) and discard the '<code>+</code>'.
  562.  
  563. <p>As a convention, PicoLisp source files have the extension "<code>.l</code>".
  564.  
  565. <p>Note that the PicoLisp executable itself does not expect or accept any
  566. command line flags or options (except the '<code>+</code>', see above). They are
  567. reserved for application programs.
  568.  
  569. <p>The simplest and shortest invocation of PicoLisp does nothing, and exits
  570. immediately by calling <code><a href="#bye">bye</a></code>:
  571.  
  572. <pre><code>
  573. $ picolisp -bye
  574. $
  575. </code></pre>
  576.  
  577. <p>In interactive mode, the PicoLisp interpreter (see <code><a
  578. href="#load">load</a></code>) will also exit when <code>Ctrl-D</code>
  579. is entered:
  580.  
  581. <pre><code>
  582. $ picolisp
  583. : $ # Typed Ctrl-D
  584. </code></pre>
  585.  
  586. <p>To start up the standard PicoLisp environment, several files should be
  587. loaded. The most commonly used things are in "lib.l" and in a bunch of other
  588. files, which are in turn loaded by "ext.l". Thus, a typical call would be:
  589.  
  590. <pre><code>
  591. $ picolisp lib.l ext.l
  592. </code></pre>
  593.  
  594. <p>The recommended way, however, is to call the "pil" shell script, which
  595. includes "lib.l" and "ext.l". Given that your current project is loaded by some
  596. file "myProject.l" and your startup function is <code>main</code>, your
  597. invocation would look like:
  598.  
  599. <pre><code>
  600. $ pil myProject.l -main
  601. </code></pre>
  602.  
  603. <p>For interactive development it is recommended to enable debugging mode, to
  604. get the vi-style line editor, single-stepping, tracing and other debugging
  605. utilities.
  606.  
  607. <pre><code>
  608. $ pil myProject.l -main +
  609. </code></pre>
  610.  
  611. <p>This is - in a local installation - equivalent to
  612.  
  613. <pre><code>
  614. $ ./pil myProject.l -main +
  615. </code></pre>
  616.  
  617. <p>In any case, the directory part of the first file name supplied (normally,
  618. the path to "lib.l" as called by 'pil') is remembered internally as the
  619. <i>PicoLisp Home Directory</i>. This path is later automatically substituted for
  620. any leading "<code>@</code>" character in file name arguments to I/O functions
  621. (see <code><a href="#path">path</a></code>).
  622.  
  623. <p>Instead of the default vi-style line editor, an emacs-style editor can be
  624. used. It can be switched on permanently by calling the function
  625. <code>(em)</code> (i.e. without arguments), or by passing <code>-em</code> on
  626. the command line:
  627.  
  628. <pre><code>
  629. $ pil -em +
  630. :
  631. </code></pre>
  632.  
  633. <p>A single call is enough, because the style will be remembered in a file
  634. "~/.pil/editor", and used in all subsequent PicoLisp sessions.
  635.  
  636. <p>To switch back to 'vi' style, call <code>(vi)</code>, use the
  637. <code>-vi</code> command line option, or simply remove "~/.pil/editor".
  638.  
  639.  
  640. <p><hr>
  641. <h3><a name="io">Input/Output</a></h3>
  642.  
  643. <p>In Lisp, each internal data structure has a well-defined external
  644. representation in human-readable format. All kinds of data can be written to a
  645. file, and restored later to their original form by reading that file.
  646.  
  647. <p>In normal operation, the PicoLisp interpreter continuously executes an
  648. infinite "read-eval-print loop". It reads one expression at a time, evaluates
  649. it, and prints the result to the console. Any input into the system, like data
  650. structures and function definitions, is done in a consistent way no matter
  651. whether it is entered at the console or read from a file.
  652.  
  653. <p>Comments can be embedded in the input stream with the hash <code>#</code>
  654. character. Everything up to the end of that line will be ignored by the reader.
  655.  
  656. <pre><code>
  657. : (* 1 2 3) # This is a comment
  658. -> 6
  659. </code></pre>
  660.  
  661. <p>A comment spanning several lines may be enclosed between <code>#{</code> and
  662. <code>}#</code>.
  663.  
  664.  
  665. <p>Here is the I/O syntax for the individual PicoLisp data types (numbers,
  666. symbols and lists) and for read-macros:
  667.  
  668.  
  669. <p><hr>
  670. <h4><a name="num-io">Numbers</a></h4>
  671.  
  672. <p>A number consists of an arbitrary number of digits ('<code>0</code>' through
  673. '<code>9</code>'), optionally preceded by a sign character ('<code>+</code>' or
  674. '<code>-</code>'). Legal number input is:
  675.  
  676. <pre><code>
  677. : 7
  678. -> 7
  679. : -12345678901245678901234567890
  680. -> -12345678901245678901234567890
  681. </code></pre>
  682.  
  683. <p>Fixpoint numbers can be input by embedding a decimal point '<code>.</code>',
  684. and setting the global variable <code><a href="#*Scl">*Scl</a></code>
  685. appropriately:
  686.  
  687. <pre><code>
  688. : *Scl
  689. -> 0
  690.  
  691. : 123.45
  692. -> 123
  693. : 456.78
  694. -> 457
  695.  
  696. : (setq *Scl 3)
  697. -> 3
  698. : 123.45
  699. -> 123450
  700. : 456.78
  701. -> 456780
  702. </code></pre>
  703.  
  704. <p>Thus, fixpoint input simply scales the number to an integer value
  705. corresponding to the number of digits in <code><a
  706. href="#*Scl">*Scl</a></code>.
  707.  
  708. <p>Formatted output of scaled fixpoint values can be done with the <code><a
  709. href="#format">format</a></code> and <code><a
  710. href="#round">round</a></code> functions:
  711.  
  712. <pre><code>
  713. : (format 1234567890 2)
  714. -> "12345678.90"
  715. : (format 1234567890 2 "." ",")
  716. -> "12,345,678.90"
  717. </code></pre>
  718.  
  719.  
  720. <p><hr>
  721. <h4><a name="sym-io">Symbols</a></h4>
  722.  
  723. <p>The reader is able to recognize the individual symbol types from their
  724. syntactic form. A symbol name should - of course - not look like a legal number
  725. (see above).
  726.  
  727. <p>In general, symbol names are case-sensitive. <code>car</code> is not the same
  728. as CAR.
  729.  
  730.  
  731. <p><hr>
  732. <h5><a name="nilSym-io">NIL</a></h5>
  733.  
  734. <p>Besides for standard normal form, <code>NIL</code> is also recognized as
  735. <code>()</code>, <code>[]</code> or <code>""</code>.
  736.  
  737. <pre><code>
  738. : NIL
  739. -> NIL
  740. : ()
  741. -> NIL
  742. : ""
  743. -> NIL
  744. </code></pre>
  745.  
  746. <p>Output will always appear as <code>NIL</code>.
  747.  
  748.  
  749. <p><hr>
  750. <h5><a name="internal-io">Internal Symbols</a></h5>
  751.  
  752. <p>Internal symbol names can consist of any printable (non-whitespace)
  753. character, except for the following meta characters:
  754.  
  755. <pre><code>
  756. " ' ( ) , [ ] ` ~ { }
  757. </code></pre>
  758.  
  759. <p>It is possible, though, to include these special characters into symbol names
  760. by escaping them with a backslash '<code>\</code>'.
  761.  
  762. <p>The dot '<code>.</code>' has a dual nature. It is a meta character when
  763. standing alone, denoting a <a href="#dotted">dotted pair</a>, but can otherwise
  764. be used in symbol names.
  765.  
  766. <p>As a rule, anything not recognized by the reader as another data type will be
  767. returned as an internal symbol.
  768.  
  769.  
  770. <p><hr>
  771. <h5><a name="transient-io">Transient Symbols</a></h5>
  772.  
  773. <p>A transient symbol is anything surrounded by double quotes '<code>"</code>'.
  774. With that, it looks - and can be used - like a string constant in other
  775. languages. However, it is a real symbol, and may be assigned a value or a
  776. function definition, and properties.
  777.  
  778. <p>Initially, a transient symbol's value is that symbol itself, so that it does
  779. not need to be quoted for evaluation:
  780.  
  781. <p><pre><code>
  782. : "This is a string"
  783. -> "This is a string"
  784. </code></pre>
  785.  
  786. <p>However, care must be taken when assigning a value to a transient symbol.
  787. This may cause unexpected behavior:
  788.  
  789. <p><pre><code>
  790. : (setq "This is a string" 12345)
  791. -> 12345
  792. : "This is a string"
  793. -> 12345
  794. </code></pre>
  795.  
  796. <p>The name of a transient symbol can contain any character except the
  797. null-byte. A double quote character can be escaped with a backslash
  798. '<code>\</code>', and a backslash itself has to be escaped with another
  799. backslash. Control characters can be written with a preceding hat
  800. '<code>^</code>' character.
  801.  
  802. <p><pre><code>
  803. : "We^Ird\\Str\"ing"
  804. -> "We^Ird\\Str\"ing"
  805. : (chop @)
  806. -> ("W" "e" "^I" "r" "d" "\\" "S" "t" "r" "\"" "i" "n" "g")
  807. </code></pre>
  808.  
  809. <p>A backslash '<code>\</code>' in a transient symbol name at the end of a line
  810. discards the newline, and continues the name in the next line. In that case, all
  811. leading spaces and tabs in that line are discarded, to allow proper source code
  812. indentation.
  813.  
  814. <p><pre><code>
  815. : "abc\
  816. def"
  817. -> "abcdef"
  818. </code></pre>
  819.  
  820. <p>The index for transient symbols is cleared automatically before and after
  821. <code><a href="#load">load</a></code>ing a source file, or it can be
  822. reset explicitly with the <code><a href="#====">====</a></code>
  823. function. With that mechanism, it is possible to create symbols with a local
  824. access scope, not accessible from other parts of the program.
  825.  
  826. <p>A special case of transient symbols are <i>anonymous symbols</i>. These are
  827. symbols without name (see <code><a href="#box">box</a></code>, <code><a
  828. href="#box?">box?</a></code> or <code><a
  829. href="#new">new</a></code>). They print as a dollar sign
  830. (<code>$</code>) followed by a decimal digit string (actually their machine
  831. address).
  832.  
  833.  
  834. <p><hr>
  835. <h5><a name="external-io">External Symbols</a></h5>
  836.  
  837. <p>External symbol names are surrounded by braces ('<code>{</code>' and
  838. '<code>}</code>'). The characters of the symbol's name itself identify the
  839. physical location of the external object. This is
  840.  
  841. <ul>
  842. <li>in the 32-bit version: The number of the database file, and - separated by a
  843. hyphen - the starting block in the database file. Both numbers are encoded in
  844. base-64 notation (characters '<code>0</code>' through '<code>9</code>',
  845. '<code>:</code>', '<code>;</code>', '<code>A</code>' through '<code>Z</code>'
  846. and '<code>a</code>' through '<code>z</code>').
  847.  
  848. <li>in the 64-bit version: The number of the database file minus 1 in "hax"
  849. notation (i.e. hexadecimal/alpha notation, where '<code>@</code>' is zero,
  850. '<code>A</code>' is 1 and '<code>O</code>' is 15 (from "alpha" to "omega")),
  851. immediately followed (without a hyphen) the starting block in octal
  852. ('<code>0</code>' through '<code>7</code>').
  853.  
  854. </ul>
  855.  
  856. <p>In both cases, the database file (and possibly the hypen) are omitted for the
  857. first (default) file.
  858.  
  859. <p><hr>
  860. <h4><a name="lst-io">Lists</a></h4>
  861.  
  862. <p>Lists are surrounded by parentheses ('<code>(</code>' and '<code>)</code>').
  863.  
  864. <p><code>(A)</code> is a list consisting of a single cell, with the symbol
  865. <code>A</code> in its CAR, and <code>NIL</code> in its CDR.
  866.  
  867. <p><code>(A B C)</code> is a list consisting of three cells, with the symbols
  868. <code>A</code>, <code>B</code> and <code>C</code> respectively in their CAR, and
  869. <code>NIL</code> in the last cell's CDR.
  870.  
  871. <p><a name="dotted"><code>(A . B)</code></a> is a "dotted pair", a list
  872. consisting of a single cell, with the symbol <code>A</code> in its CAR, and
  873. <code>B</code> in its CDR.
  874.  
  875. <p>PicoLisp has built-in support for reading and printing simple circular lists.
  876. If the dot in a dotted-pair notation is immediately followed by a closing
  877. parenthesis, it indicates that the CDR of the last cell points back to the
  878. beginning of that list.
  879.  
  880. <pre><code>
  881. : (let L '(a b c) (conc L L))
  882. -> (a b c .)
  883. : (cdr '(a b c .))
  884. -> (b c a .)
  885. : (cddddr '(a b c .))
  886. -> (b c a .)
  887. </code></pre>
  888.  
  889. <p>A similar result can be achieved with the function <code><a
  890. href="#circ">circ</a></code>. Such lists must be used with care,
  891. because many functions won't terminate or will crash when given such a list.
  892.  
  893.  
  894. <p><hr>
  895. <h4><a name="macro-io">Read-Macros</a></h4>
  896.  
  897. <p>Read-macros in PicoLisp are special forms that are recognized by the reader,
  898. and modify its behavior. Note that they take effect immediately while <code><a
  899. href="#read">read</a></code>ing an expression, and are not seen by the
  900. <code>eval</code> in the main loop.
  901.  
  902. <p>The most prominent read-macro in Lisp is the single quote character
  903. "<code>'</code>", which expands to a call of the <code><a
  904. href="#quote">quote</a></code> function. Note that the single quote
  905. character is also printed instead of the full function name.
  906.  
  907. <pre><code>
  908. : '(a b c)
  909. -> (a b c)
  910. : '(quote . a)
  911. -> 'a
  912. : (cons 'quote 'a) # (quote . a)
  913. -> 'a
  914. : (list 'quote 'a) # (quote a)
  915. -> '(a)
  916. </code></pre>
  917.  
  918. <p>A comma (<code>,</code>) will cause the reader to collect the following data
  919. item into an <code><a href="#idx">idx</a></code> tree in the global
  920. variable <code><a href="#*Uni">*Uni</a></code>, and to return a
  921. previously inserted equal item if present. This makes it possible to create a
  922. unique list of references to data which do normally not follow the rules of
  923. pointer equality. If the value of <code>*Uni</code> is <code>T</code>, the
  924. comma read macro mechanism is disabled.
  925.  
  926. <p>A single backquote character "<code>`</code>" will cause the reader to
  927. evaluate the following expression, and return the result.
  928.  
  929. <pre><code>
  930. : '(a `(+ 1 2 3) z)
  931. -> (a 6 z)
  932. </code></pre>
  933.  
  934. <p>A tilde character <code>~</code> inside a list will cause the reader to
  935. evaluate the following expression, and (destructively) splice the result into
  936. the list.
  937.  
  938. <pre><code>
  939. : '(a b c ~(list 'd 'e 'f) g h i)
  940. -> (a b c d e f g h i)
  941. </code></pre>
  942.  
  943. <p>When a tilde character is used to separate two symbol names (without
  944. surrounding whitespace), the first is taken as a namespace to look up the second
  945. (64-bit version only).
  946.  
  947. <pre><code>
  948. : 'libA~foo # Look up 'foo' in namespace 'libA'
  949. -> "foo" # "foo" is not interned in the current namespace
  950. </code></pre>
  951.  
  952. <p>Reading <code>libA~foo</code> is equivalent to switching the current
  953. namespace to <code>libA</code> (with <code><a
  954. href="#symbols">symbols</a></code>), reading the symbol
  955. <code>foo</code>, and then switching back to the original namespace.
  956.  
  957. <p>Brackets ('<code>[</code>' and '<code>]</code>') can be used as super
  958. parentheses. A closing bracket will match the innermost opening bracket, or all
  959. currently open parentheses.
  960.  
  961. <pre><code>
  962. : '(a (b (c (d]
  963. -> (a (b (c (d))))
  964. : '(a (b [c (d]))
  965. -> (a (b (c (d))))
  966. </code></pre>
  967.  
  968. <p>Finally, reading the sequence '<code>{}</code>' will result in a new
  969. anonymous symbol with value <code>NIL</code>, equivalent to a call to <code><a
  970. href="#box">box</a></code> without arguments.
  971.  
  972. <pre><code>
  973. : '({} {} {})
  974. -> ($134599965 $134599967 $134599969)
  975. : (mapcar val @)
  976. -> (NIL NIL NIL)
  977. </code></pre>
  978.  
  979.  
  980. <p><hr>
  981. <h3><a name="ev">Evaluation</a></h3>
  982.  
  983. <p>PicoLisp tries to evaluate any expression encountered in the read-eval-print
  984. loop. Basically, it does so by applying the following three rules:
  985.  
  986. <p><ul>
  987. <li>A number evaluates to itself.
  988.  
  989. <li>A symbol evaluates to its value (VAL).
  990.  
  991. <li>A list is evaluated as a function call, with the CAR as the function and the
  992. CDR the arguments to that function. These arguments are in turn evaluated
  993. according to these three rules.
  994.  
  995. </ul>
  996.  
  997. <pre><code>
  998. : 1234
  999. -> 1234 # Number evaluates to itself
  1000. : *Pid
  1001. -> 22972 # Symbol evaluates to its VAL
  1002. : (+ 1 2 3)
  1003. -> 6 # List is evaluated as a function call
  1004. </code></pre>
  1005.  
  1006. <p>For the third rule, however, things get a bit more involved. First - as a
  1007. special case - if the CAR of the list is a number, the whole list is returned as
  1008. it is:
  1009.  
  1010. <pre><code>
  1011. : (1 2 3 4 5 6)
  1012. -> (1 2 3 4 5 6)
  1013. </code></pre>
  1014.  
  1015. <p>This is not really a function call but just a convenience to avoid having to
  1016. quote simple data lists.
  1017.  
  1018. <p>Otherwise, if the CAR is a symbol or a list, PicoLisp tries to obtain an
  1019. executable function from that, by either using the symbol's value, or by
  1020. evaluating the list.
  1021.  
  1022. <p>What is an executable function? Or, said in another way, what can be applied
  1023. to a list of arguments, to result in a function call? A legal function in
  1024. PicoLisp is
  1025.  
  1026. <p><dl>
  1027. <dt>either
  1028. <dd>a <i>number</i>. When a number is used as a function, it is simply taken as
  1029. a pointer to executable code that will be called with the list of (unevaluated)
  1030. arguments as its single parameter. It is up to that code to evaluate the
  1031. arguments, or not. Some functions do not evaluate their arguments (e.g.
  1032. <code>quote</code>) or evaluate only some of their arguments (e.g.
  1033. <code>setq</code>).
  1034.  
  1035. <dt>or
  1036. <dd>a <i>lambda expression</i>. A lambda expression is a list, whose CAR is
  1037. either a symbol or a list of symbols, and whose CDR is a list of expressions.
  1038. Note: In contrast to other Lisp implementations, the symbol LAMBDA itself does
  1039. not exist in PicoLisp but is implied from context.
  1040.  
  1041. </dl>
  1042.  
  1043. <p>A few examples should help to understand the practical consequences of these
  1044. rules. In the most common case, the CAR will be a symbol defined as a function,
  1045. like the <code>*</code> in:
  1046.  
  1047. <pre><code>
  1048. : (* 1 2 3) # Call the function '*'
  1049. -> 6
  1050. </code></pre>
  1051.  
  1052. <p>Inspecting the VAL of <code>*</code> gives
  1053.  
  1054. <pre><code>
  1055. : * # Get the VAL of the symbol '*'
  1056. -> 67318096
  1057. </code></pre>
  1058.  
  1059. <p>The VAL of <code>*</code> is a number. In fact, it is the numeric
  1060. representation of a C-function pointer, i.e. a pointer to executable code. This
  1061. is the case for all built-in functions of PicoLisp.
  1062.  
  1063. <p>Other functions in turn are written as Lisp expressions:
  1064.  
  1065. <pre><code>
  1066. : (de foo (X Y) # Define the function 'foo'
  1067. (* (+ X Y) (+ X Y)) )
  1068. -> foo
  1069. : (foo 2 3) # Call the function 'foo'
  1070. -> 25
  1071. : foo # Get the VAL of the symbol 'foo'
  1072. -> ((X Y) (* (+ X Y) (+ X Y)))
  1073. </code></pre>
  1074.  
  1075. <p>The VAL of <code>foo</code> is a list. It is the list that was assigned to
  1076. <code>foo</code> with the <code>de</code> function. It would be perfectly legal
  1077. to use <code>setq</code> instead of <code>de</code>:
  1078.  
  1079. <pre><code>
  1080. : (setq foo '((X Y) (* (+ X Y) (+ X Y))))
  1081. -> ((X Y) (* (+ X Y) (+ X Y)))
  1082. : (foo 2 3)
  1083. -> 25
  1084. </code></pre>
  1085.  
  1086. <p>If the VAL of <code>foo</code> were another symbol, that symbol's VAL would
  1087. be used instead to search for an executable function.
  1088.  
  1089. <p>As we said above, if the CAR of the evaluated expression is not a symbol but
  1090. a list, that list is evaluated to obtain an executable function.
  1091.  
  1092. <pre><code>
  1093. : ((intern (pack "c" "a" "r")) (1 2 3))
  1094. -> 1
  1095. </code></pre>
  1096.  
  1097. <p>Here, the <code>intern</code> function returns the symbol <code>car</code>
  1098. whose VAL is used then. It is also legal, though quite dangerous, to use the <a
  1099. name="codePointer">code-pointer</a> directly:
  1100.  
  1101. <pre><code>
  1102. : *
  1103. -> 67318096
  1104. : ((* 2 33659048) 1 2 3)
  1105. -> 6
  1106. : ((quote . 67318096) 1 2 3)
  1107. -> 6
  1108. : ((quote . 1234) (1 2 3))
  1109. Segmentation fault
  1110. </code></pre>
  1111.  
  1112. <p>When an executable function is defined in Lisp itself, we call it a <a
  1113. name="lambda"><i>lambda expression</i></a>. A lambda expression always has a
  1114. list of executable expressions as its CDR. The CAR, however, must be a either a
  1115. list of symbols, or a single symbol, and it controls the evaluation of the
  1116. arguments to the executable function according to the following rules:
  1117.  
  1118. <p><dl>
  1119.  
  1120. <dt>When the CAR is a list of symbols
  1121. <dd>For each of these symbols an argument is evaluated, then the symbols are
  1122. bound simultaneously to the results. The body of the lambda expression is
  1123. executed, then the VAL's of the symbols are restored to their original values.
  1124. This is the most common case, a fixed number of arguments is passed to the
  1125. function.
  1126.  
  1127. <dt>Otherwise, when the CAR is the symbol <code>@</code>
  1128. <dd>All arguments are evaluated and the results kept internally in a list. The
  1129. body of the lambda expression is executed, and the evaluated arguments can be
  1130. accessed sequentially with the <code><a href="#args">args</a></code>,
  1131. <code><a href="#next">next</a></code>, <code><a
  1132. href="#arg">arg</a></code> and <code><a
  1133. href="#rest">rest</a></code> functions. This allows to define functions
  1134. with a variable number of evaluated arguments.
  1135.  
  1136. <dt>Otherwise, when the CAR is a single symbol
  1137. <dd>The symbol is bound to the whole unevaluated argument list. The body of the
  1138. lambda expression is executed, then the symbol is restored to its original
  1139. value. This allows to define functions with unevaluated arguments. Any kind of
  1140. interpretation and evaluation of the argument list can be done inside the
  1141. expression body.
  1142.  
  1143. </dl>
  1144.  
  1145. <p>In all cases, the return value is the result of the last expression in the
  1146. body.
  1147.  
  1148. <pre><code>
  1149. : (de foo (X Y Z) # CAR is a list of symbols
  1150. (list X Y Z) ) # Return a list of all arguments
  1151. -> foo
  1152. : (foo (+ 1 2) (+ 3 4) (+ 5 6))
  1153. -> (3 7 11) # all arguments are evaluated
  1154. </code></pre>
  1155.  
  1156. <pre><code>
  1157. : (de foo @ # CAR is the symbol '@'
  1158. (list (next) (next) (next)) ) # Return the first three arguments
  1159. -> foo
  1160. : (foo (+ 1 2) (+ 3 4) (+ 5 6))
  1161. -> (3 7 11) # all arguments are evaluated
  1162. </code></pre>
  1163.  
  1164. <pre><code>
  1165. : (de foo X # CAR is a single symbol
  1166. X ) # Return the argument
  1167. -> foo
  1168. : (foo (+ 1 2) (+ 3 4) (+ 5 6))
  1169. -> ((+ 1 2) (+ 3 4) (+ 5 6)) # the whole unevaluated list is returned
  1170. </code></pre>
  1171.  
  1172. <p>Note that these forms can also be combined. For example, to evaluate only the
  1173. first two arguments, bind the results to <code>X</code> and <code>Y</code>, and
  1174. bind all other arguments (unevaluated) to <code>Z</code>:
  1175.  
  1176. <pre><code>
  1177. : (de foo (X Y . Z) # CAR is a list with a dotted-pair tail
  1178. (list X Y Z) ) # Return a list of all arguments
  1179. -> foo
  1180. : (foo (+ 1 2) (+ 3 4) (+ 5 6))
  1181. -> (3 7 ((+ 5 6))) # Only the first two arguments are evaluated
  1182. </code></pre>
  1183.  
  1184. <p>Or, a single argument followed by a variable number of arguments:
  1185.  
  1186. <pre><code>
  1187. : (de foo (X . @) # CAR is a dotted-pair with '@'
  1188. (println X) # print the first evaluated argument
  1189. (while (args) # while there are more arguments
  1190. (println (next)) ) ) # print the next one
  1191. -> foo
  1192. : (foo (+ 1 2) (+ 3 4) (+ 5 6))
  1193. 3 # X
  1194. 7 # next argument
  1195. 11 # and the last argument
  1196. -> 11
  1197. </code></pre>
  1198.  
  1199. <p>In general, if more than the expected number of arguments is supplied to a
  1200. function, these extra arguments will be ignored. Missing arguments default to
  1201. <code>NIL</code>.
  1202.  
  1203.  
  1204. <p><hr>
  1205. <h3><a name="libs">Shared Libraries</a></h3>
  1206.  
  1207. <p>Analogous to built-in functions (which are written in assembly (64-bit
  1208. version) or C (32-bit version) in the interpreter kernel), PicoLisp functions
  1209. may also be defined in shared object files (called "DLLs" on some systems). The
  1210. coding style, register usage, argument passing etc. follow the same rules as for
  1211. normal built-in functions.
  1212.  
  1213. <p>Note that this has nothing to do with external (e.g. third-party) library
  1214. functions called with <a href="#native">native</a>.
  1215.  
  1216. <p>When the interpreter encounters a symbol supposed to be called as a function,
  1217. without a function definition, but with a name of the form
  1218. "<code>lib:sym</code>", then - instead of throwing an "undefined"-error - it
  1219. tries to locate a shared object file with the name <code>lib</code> and a
  1220. function <code>sym</code>, and stores a pointer to this code in the symbol's
  1221. value. From that point, this symbol <code>lib:sym</code> keeps that function
  1222. definition, and is undistinguishable from built-in functions. Future calls to
  1223. this function do not require another library search.
  1224.  
  1225. <p>A consequence of this lookup mechanism, however, is the fact that such
  1226. symbols cannot be used directly in a function-passing context (i.e.
  1227. "<code>apply</code>" them) like
  1228.  
  1229. <pre><code>
  1230. (apply + (1 2 3))
  1231. (mapcar inc (1 2 3))
  1232. </code></pre>
  1233.  
  1234. <p>These calls work because <code>+</code> and <code>inc</code> already have a
  1235. (function) value at this point. Applying a shared library function like
  1236.  
  1237. <pre><code>
  1238. (mapcar ext:Base64 (1 2 3))
  1239. </code></pre>
  1240.  
  1241. <p>works <i>only</i> if <code>ext:Base64</code> was either called before (and
  1242. thus automatically received a function definition), or was fetched explicitly
  1243. with <code>(getd 'ext:Base64)</code>.
  1244.  
  1245. <p>Therefore, it is recommended to always apply such functions by passing the
  1246. symbol itself and not just the value:
  1247.  
  1248. <pre><code>
  1249. (mapcar 'ext:Base64 (1 2 3))
  1250. </code></pre>
  1251.  
  1252.  
  1253. <p><hr>
  1254. <h3><a name="coroutines">Coroutines</a></h3>
  1255.  
  1256. <p>Coroutines are independent execution contexts. They may have multiple entry
  1257. and exit points, and preserve their environment between invocations.
  1258.  
  1259. <p>They are available only in the 64-bit version.
  1260.  
  1261. <p>A coroutine is identified by a tag. This tag can be passed to other
  1262. functions, and (re)invoked as needed. In this regard coroutines are similar to
  1263. "continuations" in other languages.
  1264.  
  1265. <p>When the tag goes out of scope while it is not actively running, the
  1266. coroutine will be garbage collected. In cases where this is desired, using a <a
  1267. href="#transient">transient</a> symbol for the tag is recommended.
  1268.  
  1269. <p>A coroutine is created by calling <code><a href="#co">co</a></code>.
  1270. Its <code>prg</code> body will be executed, and unless <code><a
  1271. href="#yield">yield</a></code> is called at some point, the coroutine
  1272. will "fall off" at the end and disappear.
  1273.  
  1274. <p>When <code><a href="#yield">yield</a></code> is called, control is
  1275. either transferred back to the caller, or to some other - explicitly specified,
  1276. and already running - coroutine.
  1277.  
  1278. <p>A coroutine is stopped and disposed when
  1279.  
  1280. <p><ul>
  1281. <li>execution falls off the end
  1282.  
  1283. <li>some other (co)routine calls <code><a href="#co">co</a></code> with
  1284. that tag but without a <code>prg</code> body
  1285.  
  1286. <li>a <code><a href="#throw">throw</a></code> into another (co)routine
  1287. environment is executed
  1288.  
  1289. <li>an error occurred, and <a href="#errors">error handling</a> was entered
  1290.  
  1291. </ul>
  1292.  
  1293. <p>Reentrant coroutines are not supported: A coroutine cannot resume itself
  1294. directly or indirectly.
  1295.  
  1296. <p>Before using many coroutines, make sure you have sufficient stack space, e.g.
  1297. by calling
  1298.  
  1299. <pre><code>
  1300. $ ulimit -s unlimited
  1301. </code></pre>
  1302.  
  1303. <p>Without that, the stack limit in Linux is typically 8 MB.
  1304.  
  1305.  
  1306. <p><hr>
  1307. <h3><a name="int">Interrupt</a></h3>
  1308.  
  1309. <p>During the evaluation of an expression, the PicoLisp interpreter can be
  1310. interrupted at any time by hitting <code>Ctrl-C</code>. It will then enter the
  1311. breakpoint routine, as if <code><a href="#!">!</a></code> were called.
  1312.  
  1313. <p>Hitting ENTER at that point will continue evaluation, while <code>(<a
  1314. href="#quit">quit</a>)</code> will abort evaluation and return the
  1315. interpreter to the top level. See also <code><a
  1316. href="#debug">debug</a></code>, <code><a
  1317. href="#e">e</a></code>, <code><a href="ref_.html#^">^</a></code> and
  1318. <code><a href="#*Dbg">*Dbg</a></code>
  1319.  
  1320. <p>Other interrupts may be handled by <code><a
  1321. href="#alarm">alarm</a></code>, <code><a
  1322. href="#sigio">sigio</a></code>, <code><a
  1323. href="#*Hup">*Hup</a></code> and <code><a
  1324. href="#*Sig1">*Sig[12]</a></code>.
  1325.  
  1326.  
  1327. <p><hr>
  1328. <h3><a name="errors">Error Handling</a></h3>
  1329.  
  1330. <p>When a runtime error occurs, execution is stopped and an error handler is
  1331. entered.
  1332.  
  1333. <p>The error handler resets the I/O channels to the console, and displays the
  1334. location (if possible) and the reason of the error, followed by an error
  1335. message. That message is also stored in the global <code><a
  1336. href="#*Msg">*Msg</a></code>, and the location of the error in <code><a
  1337. href="#^">^</a></code>. If the VAL of the global <code><a
  1338. href="#*Err">*Err</a></code> is non-<code>NIL</code> it is executed as
  1339. a <code>prg</code> body. If the standard input is from a terminal, a
  1340. read-eval-print loop (with a question mark "<code>?</code>" as prompt) is
  1341. entered (the loop is exited when an empty line is input). Then all pending
  1342. <code><a href="#finally">finally</a></code> expressions are executed,
  1343. all variable bindings restored, and all files closed. If the standard input is
  1344. not from a terminal, the interpreter terminates. Otherwise it is reset to its
  1345. top-level state.
  1346.  
  1347. <pre><code>
  1348. : (de foo (A B) (badFoo A B)) # 'foo' calls an undefined symbol
  1349. -> foo
  1350. : (foo 3 4) # Call 'foo'
  1351. !? (badFoo A B) # Error handler entered
  1352. badFoo -- Undefined
  1353. ? A # Inspect 'A'
  1354. -> 3
  1355. ? B # Inspect 'B'
  1356. -> 4
  1357. ? # Empty line: Exit
  1358. :
  1359. </code></pre>
  1360.  
  1361. <p>Errors can be caught with <code><a href="#catch">catch</a></code>,
  1362. if a list of substrings of possible error messages is supplied for the first
  1363. argument. In such a case, the matching substring (or the whole error message if
  1364. the substring is <code>NIL</code>) is returned.
  1365.  
  1366. <p>An arbitrary error can be thrown explicitly with <code><a
  1367. href="#quit">quit</a></code>.
  1368.  
  1369.  
  1370. <p><hr>
  1371. <h3><a name="atres">@ Result</a></h3>
  1372.  
  1373. <p>In certain situations, the result of the last evaluation is stored in the VAL
  1374. of the symbol <code>@</code>. This can be very convenient, because it often
  1375. makes the assignment to temporary variables unnecessary.
  1376.  
  1377. <p>This happens in two - only superficially similar - situations:
  1378.  
  1379. <p><dl>
  1380.  
  1381. <dt><code><a href="#load">load</a></code>
  1382. <dd>In read-eval loops, the last three results which were printed at the console
  1383. are available in <code>@@@</code>, <code>@@</code> and <code>@</code>, in that
  1384. order (i.e the latest result is in <code>@</code>).
  1385.  
  1386. <pre><code>
  1387. : (+ 1 2 3)
  1388. -> 6
  1389. : (/ 128 4)
  1390. -> 32
  1391. : (- @ @@) # Subtract the last two results
  1392. -> 26
  1393. </code></pre>
  1394.  
  1395. <p><dt>Flow functions
  1396. <dd>Flow- and logic-functions store the result of their controlling expression -
  1397. respectively non-<code>NIL</code> results of their conditional expression - in
  1398. <code>@</code>.
  1399.  
  1400. <pre><code>
  1401. : (while (read) (println 'got: @))
  1402. abc # User input
  1403. got: abc # print result
  1404. 123 # User input
  1405. got: 123 # print result
  1406. NIL
  1407. -> 123
  1408.  
  1409. : (setq L (1 2 3 4 5 1 2 3 4 5))
  1410. -> (1 2 3 4 5 1 2 3 4 5)
  1411. : (and (member 3 L) (member 3 (cdr @)) (set @ 999))
  1412. -> 999
  1413. : L
  1414. -> (1 2 3 4 5 1 2 999 4 5)
  1415. </code></pre>
  1416.  
  1417. <p>Functions with controlling expressions are
  1418. <a href="#case">case</a>,
  1419. <a href="#casq">casq</a>,
  1420. <a href="#prog1">prog1</a>,
  1421. <a href="#prog2">prog2</a>,
  1422. and the bodies of <code><a href="#*Run">*Run</a></code> tasks.
  1423.  
  1424. <p>Functions with conditional expressions are
  1425. <a href="#and">and</a>,
  1426. <a href="#cond">cond</a>,
  1427. <a href="#do">do</a>,
  1428. <a href="#for">for</a>,
  1429. <a href="#if">if</a>,
  1430. <a href="#if2">if2</a>,
  1431. <a href="#ifn">ifn</a>,
  1432. <a href="#loop">loop</a>,
  1433. <a href="#nand">nand</a>,
  1434. <a href="#nond">nond</a>,
  1435. <a href="#nor">nor</a>,
  1436. <a href="#not">not</a>,
  1437. <a href="#or">or</a>,
  1438. <a href="#state">state</a>,
  1439. <a href="#unless">unless</a>,
  1440. <a href="#until">until</a>,
  1441. <a href="#when">when</a> and
  1442. <a href="#while">while</a>.
  1443.  
  1444. </dl>
  1445.  
  1446. <p><code>@</code> is generally local to functions and methods, its value is
  1447. automatically saved upon function entry and restored at exit.
  1448.  
  1449.  
  1450. <p><hr>
  1451. <h3><a name="cmp">Comparing</a></h3>
  1452.  
  1453. <p>In PicoLisp, it is legal to compare data items of arbitrary type. Any two
  1454. items are either
  1455.  
  1456. <p><dl>
  1457.  
  1458. <dt>Identical
  1459. <dd>They are the same memory object (pointer equality). For example, two
  1460. internal symbols with the same name are identical. In the 64-bit version, also
  1461. short numbers (up to 60 bits plus sign) are pointer-equal.
  1462.  
  1463. <dt>Equal
  1464. <dd>They are equal in every respect (structure equality), but need not to be
  1465. identical. Examples are numbers with the same value, transient symbols with the
  1466. same name or lists with equal elements.
  1467.  
  1468. <dt>Or they have a well-defined ordinal relationship
  1469. <dd>Numbers are comparable by their numeric value, strings by their name, and
  1470. lists recursively by their elements (if the CAR's are equal, their CDR's are
  1471. compared). For differing types, the following rule applies: Numbers are less
  1472. than symbols, and symbols are less than lists. As special cases,
  1473. <code>NIL</code> is always less than anything else, and <code>T</code> is always
  1474. greater than anything else.
  1475.  
  1476. </dl>
  1477.  
  1478. <p>To demonstrate this, <code><a href="#sort">sort</a></code> a list of
  1479. mixed data types:
  1480.  
  1481. <pre><code>
  1482. : (sort '("abc" T (d e f) NIL 123 DEF))
  1483. -> (NIL 123 DEF "abc" (d e f) T)
  1484. </code></pre>
  1485.  
  1486. <p>See also <code><a href="#max">max</a></code>, <code><a
  1487. href="#min">min</a></code>, <code><a
  1488. href="#rank">rank</a></code>, <code><a href="ref_.html#<"><</a></code>,
  1489. <code><a href="#=">=</a></code>, <code><a
  1490. href="#>">></a></code> etc.
  1491.  
  1492.  
  1493. <p><hr>
  1494. <h3><a name="oop">OO Concepts</a></h3>
  1495.  
  1496. <p>PicoLisp comes with built-in object oriented extensions. There seems to be a
  1497. common agreement upon three criteria for object orientation:
  1498.  
  1499. <p><dl>
  1500. <dt>Encapsulation
  1501. <dd>Code and data are encapsulated into <u>objects</u>, giving them both a
  1502. <u>behavior</u> and a <u>state</u>. Objects communicate by sending and receiving
  1503. <u>messages</u>.
  1504.  
  1505. <dt>Inheritance
  1506. <dd>Objects are organized into <u>classes</u>. The behavior of an object is
  1507. inherited from its class(es) and superclass(es).
  1508.  
  1509. <dt>Polymorphism
  1510. <dd>Objects of different classes may behave differently in response to the same
  1511. message. For that, classes may define different methods for each message.
  1512.  
  1513. </dl>
  1514.  
  1515. <p>PicoLisp implements both objects and classes with symbols. Object-local data
  1516. are stored in the symbol's property list, while the code (methods) and links to
  1517. the superclasses are stored in the symbol's VAL (encapsulation).
  1518.  
  1519. <p>In fact, there is no formal difference between objects and classes (except
  1520. that objects usually are anonymous symbols containing mostly local data, while
  1521. classes are named internal symbols with an emphasis on method definitions). At
  1522. any time, a class may be assigned its own local data (class variables), and any
  1523. object can receive individual method definitions in addition to (or overriding)
  1524. those inherited from its (super)classes.
  1525.  
  1526. <p>PicoLisp supports multiple inheritance. The VAL of each object is a (possibly
  1527. empty) association list of message symbols and method bodies, concatenated with
  1528. a list of classes. When a message is sent to an object, it is searched in the
  1529. object's own method list, and then (with a left-to-right depth-first search) in
  1530. the tree of its classes and superclasses. The first method found is executed and
  1531. the search stops. The search may be explicitly continued with the <code><a
  1532. href="#extra">extra</a></code> and <code><a
  1533. href="#super">super</a></code> functions.
  1534.  
  1535. <p>Thus, which method is actually executed when a message is sent to an object
  1536. depends on the classes that the object is currently linked to (polymorphism). As
  1537. the method search is fully dynamic (late binding), an object's type (i.e. its
  1538. classes and method definitions) can be changed even at runtime!
  1539.  
  1540. <p>While a method body is being executed, the global variable <code><a
  1541. href="#This">This</a></code> is set to the current object, allowing
  1542. the use of the short-cut property functions <code><a
  1543. href="#=:">=:</a></code>, <code><a href="ref_.html#:">:</a></code>
  1544. and <code><a href="#::">::</a></code>.
  1545.  
  1546.  
  1547. <p><hr>
  1548. <h3><a name="dbase">Database</a></h3>
  1549.  
  1550. <p>On the lowest level, a PicoLisp database is just a collection of <a
  1551. href="#external">external symbols</a>. They reside in a database file, and are
  1552. dynamically swapped in and out of memory. Only one database can be open at a
  1553. time (<code><a href="#pool">pool</a></code>).
  1554.  
  1555. <p>In addition, further external symbols can be specified to originate from
  1556. arbitrary sources via the <code><a href="#*Ext">*Ext</a></code>
  1557. mechanism.
  1558.  
  1559. <p>Whenever an external symbol's value or property list is accessed, it will be
  1560. automatically fetched into memory, and can then be used like any other symbol.
  1561. Modifications will be written to disk only when <code><a
  1562. href="#commit">commit</a></code> is called. Alternatively, all
  1563. modifications since the last call to <code>commit</code> can be discarded by
  1564. calling <code><a href="#rollback">rollback</a></code>.
  1565.  
  1566. <p><hr>
  1567. <h4><a name="trans">Transactions</a></h4>
  1568.  
  1569. <p>In the typical case there will be multiple processes operating on the same
  1570. database. These processes should be all children of the same parent process,
  1571. which takes care of synchronizing read/write operations and heap contents. Then
  1572. a database transaction is normally initiated by calling <code>(<a
  1573. href="#dbSync">dbSync</a>)</code>, and closed by calling <code>(<a
  1574. href="#commit">commit</a> 'upd)</code>. Short transactions, involving
  1575. only a single DB operation, are available in functions like <code><a
  1576. href="#new!">new!</a></code> and methods like <code><a
  1577. href="#entityMesssages">put!></a></code> (by convention with an
  1578. exclamation mark), which implicitly call <code>(dbSync)</code> and <code>(commit
  1579. 'upd)</code> themselves.
  1580.  
  1581. <p>A transaction proceeds through five phases:
  1582.  
  1583. <p><ol>
  1584. <li><code><a href="#dbSync">dbSync</a></code> waits to get a <code><a
  1585. href="#lock">lock</a></code> on the root object <code><a
  1586. href="#*DB">*DB</a></code>. Other processes continue reading and
  1587. writing meanwhile.
  1588.  
  1589. <li><code><a href="#dbSync">dbSync</a></code> calls <code><a
  1590. href="#sync">sync</a></code> to synchronize with changes from other
  1591. processes. We hold the shared lock, but other processes may continue reading.
  1592.  
  1593. <li>We make modifications to the internal state of external symbols with
  1594. <code><a href="#entityMesssages">put>, set>, lose></a></code> etc. We -
  1595. and also other processes - can still read the DB.
  1596.  
  1597. <li>We call <code>(<a href="#commit">commit</a> 'upd)</code>.
  1598. <code>commit</code> obtains an exclusive lock (no more read operations by other
  1599. processes), writes an optional transaction log, and then all modified symbols.
  1600. As <code><a href="#upd">upd</a></code> is passed to 'commit', other
  1601. processes synchronize with these changes.
  1602.  
  1603. <li>Finally, all locks are released by 'commit'
  1604.  
  1605. </ol>
  1606.  
  1607. <p><hr>
  1608. <h4><a name="er">Entities / Relations</a></h4>
  1609.  
  1610. <p>The symbols in a database can be used to store arbitrary information
  1611. structures. In typical use, some symbols represent nodes of search trees, by
  1612. holding keys, values, and links to subtrees in their VAL's. Such a search tree
  1613. in the database is called <u>index</u>.
  1614.  
  1615. <p>For the most part, other symbols in the database are objects derived from the
  1616. <code><a href="#+Entity">+Entity</a></code> class.
  1617.  
  1618. <p>Entities depend on objects of the <code><a
  1619. href="#+relation">+relation</a></code> class hierarchy.
  1620. Relation-objects manage the property values of entities, they define the
  1621. application database model and are responsible for the integrity of mutual
  1622. object references and index trees.
  1623.  
  1624. <p>Relations are stored as properties in the entity classes, their methods are
  1625. invoked as daemons whenever property values in an entity are changed. When
  1626. defining an <code><a href="#+Entity">+Entity</a></code> class, relations are defined - in addition to
  1627. the method definitions of a normal class - with the <code><a
  1628. href="#rel">rel</a></code> function. Predefined relation classes
  1629. include
  1630.  
  1631. <p><ul>
  1632. <li>Scalar relations like
  1633. <dl>
  1634. <dt><code><a href="#+Symbol">+Symbol</a></code>
  1635. <dd>Symbolic data
  1636. <dt><code><a href="#+String">+String</a></code>
  1637. <dd>Strings (just a general case of symbols)
  1638. <dt><code><a href="#+Number">+Number</a></code>
  1639. <dd>Integers and fixpoint numbers
  1640. <dt><code><a href="#+Date">+Date</a></code>
  1641. <dd>Calendar date values, represented by a number
  1642. <dt><code><a href="#+Time">+Time</a></code>
  1643. <dd>Time-of-the-day values, represented by a number
  1644. <dt><code><a href="#+Blob">+Blob</a></code>
  1645. <dd>"Binary large objects" stored in separate files
  1646. <dt><code><a href="#+Bool">+Bool</a></code>
  1647. <dd><code>T</code> or <code>NIL</code>
  1648. </dl>
  1649. <li>Object-to-object relations
  1650. <dl>
  1651. <dt><code><a href="#+Link">+Link</a></code>
  1652. <dd>A reference to some other entity
  1653. <dt><code><a href="#+Hook">+Hook</a></code>
  1654. <dd>A reference to an entity holding object-local index trees
  1655. <dt><code><a href="#+Joint">+Joint</a></code>
  1656. <dd>A bidirectional reference to some other entity
  1657. </dl>
  1658. <li>Container prefix classes like
  1659. <dl>
  1660. <dt><code><a href="#+List">+List</a></code>
  1661. <dd>A list of any of the other primitive or object relation types
  1662. <dt><code><a href="#+Bag">+Bag</a></code>
  1663. <dd>A list containing a mixture of any of the other types
  1664. </dl>
  1665. <li>Index prefix classes
  1666. <dl>
  1667. <dt><code><a href="#+Ref">+Ref</a></code>
  1668. <dd>An index with other primitives or entities as key
  1669. <dt><code><a href="#+Key">+Key</a></code>
  1670. <dd>A unique index with other primitives or entities as key
  1671. <dt><code><a href="#+Idx">+Idx</a></code>
  1672. <dd>A full-text index, typically for strings
  1673. <dt><code><a href="#+Fold">+Fold</a></code>
  1674. <dd>A folded text index
  1675. <dt><code><a href="#+IdxFold">+IdxFold</a></code>
  1676. <dd>Folded substring index
  1677. <dt><code><a href="#+Sn">+Sn</a></code>
  1678. <dd>Tolerant index, using a modified Soundex-Algorithm
  1679. </dl>
  1680. <li>And a catch-all class
  1681. <dl>
  1682. <dt><code><a href="#+Any">+Any</a></code>
  1683. <dd>Not specified, may be any of the above relations
  1684. </dl>
  1685. </ul>
  1686.  
  1687.  
  1688. <p><hr>
  1689. <h3><a name="pilog">Pilog (PicoLisp Prolog)</a></h3>
  1690.  
  1691. <p>A declarative language is built on top of PicoLisp, that has the semantics of
  1692. Prolog, but uses the syntax of Lisp.
  1693.  
  1694. <p>For an explanation of Prolog's declarative programming style, an introduction
  1695. like "Programming in Prolog" by Clocksin/Mellish (Springer-Verlag 1981) is
  1696. recommended.
  1697.  
  1698. <p>Facts and rules can be declared with the <code><a
  1699. href="#be">be</a></code> function. For example, a Prolog fact
  1700. '<code>likes(john,mary).</code>' is written in Pilog as:
  1701.  
  1702. <pre><code>
  1703. (be likes (John Mary))
  1704. </code></pre>
  1705.  
  1706. <p>and a rule '<code>likes(john,X) :- likes(X,wine), likes(X,food).</code>' is
  1707. in Pilog:
  1708.  
  1709. <pre><code>
  1710. (be likes (John @X) (likes @X wine) (likes @X food))
  1711. </code></pre>
  1712.  
  1713. <p>As in Prolog, the difference between facts and rules is that the latter ones
  1714. have conditions, and usually contain variables.
  1715.  
  1716. <p>A variable in Pilog is any symbol starting with an at-mark character
  1717. ("<code>@</code>"). The symbol <code>@</code> itself can be used as an anonymous
  1718. variable: It will match during unification, but will not be bound to the matched
  1719. values.
  1720.  
  1721. <p>The <i>cut</i> operator of Prolog (usually written as an exclamation mark
  1722. (<code>!</code>)) is the symbol <code>T</code> in Pilog.
  1723.  
  1724. <p>An interactive query can be done with the <code><a
  1725. href="#?">?</a></code> function:
  1726.  
  1727. <pre><code>
  1728. (? (likes John @X))
  1729. </code></pre>
  1730.  
  1731. <p>This will print all solutions, waiting for user input after each line. If a
  1732. non-empty line (not just a ENTER key, but for example a dot (<code>.</code>)
  1733. followed by ENTER) is typed, it will terminate.
  1734.  
  1735. <p>Pilog can be called from Lisp and vice versa:
  1736.  
  1737. <ul>
  1738.  
  1739. <li>The interface from Lisp is via the functions <code><a
  1740. href="#goal">goal</a></code> (prepare a query from Lisp data) and
  1741. <code><a href="#prove">prove</a></code> (return an association list of
  1742. successful bindings), and the application level functions <code><a
  1743. href="#pilog">pilog</a></code> and <code><a
  1744. href="#solve">solve</a></code>.
  1745.  
  1746. <li>When the CAR of a Pilog clause is the symbol <code>^</code>, then the CDDR
  1747. is executed as a Lisp <code>prg</code> body and the result unified with the
  1748. CADR.
  1749.  
  1750. <li>Within such a Lisp expression in a Pilog clause, the current bindings of
  1751. Pilog variables can be accessed with the <code><a
  1752. href="#->">-&gt</a></code> function.
  1753.  
  1754. </ul>
  1755.  
  1756. <p><hr>
  1757. <h3><a name="conv">Naming Conventions</a></h3>
  1758.  
  1759. <p>It was necessary to introduce - and adhere to - a set of conventions for
  1760. PicoLisp symbol names. Because all (internal) symbols have a global scope (there
  1761. are no packages or name spaces), and each symbol can only have either a value or
  1762. function definition, it would otherwise be very easy to introduce name
  1763. conflicts. Besides this, source code readability is increased when the scope of
  1764. a symbol is indicated by its name.
  1765.  
  1766. <p>These conventions are not hard-coded into the language, but should be so into
  1767. the head of the programmer. Here are the most commonly used ones:
  1768.  
  1769. <p><ul>
  1770. <li>Global variables start with an asterisk "<code>*</code>"
  1771. <li>Functions and other global symbols start with a lower case letter
  1772. <li>Locally bound symbols start with an upper case letter
  1773. <li>Local functions start with an underscore "<code>_</code>"
  1774. <li>Classes start with a plus-sign "<code>+</code>", where the first letter
  1775. <ul>
  1776. <li>is in lower case for abstract classes
  1777. <li>and in upper case for normal classes
  1778. </ul>
  1779. <li>Methods end with a right arrow "<code>></code>"
  1780. <li>Class variables may be indicated by an upper case letter
  1781. </ul>
  1782.  
  1783. <p>For historical reasons, the global constant symbols <code>T</code> and
  1784. <code>NIL</code> do not obey these rules, and are written in upper case.
  1785.  
  1786. <p>For example, a local variable could easily overshadow a function definition:
  1787.  
  1788. <pre><code>
  1789. : (de max-speed (car)
  1790. (.. (get car 'speeds) ..) )
  1791. -> max-speed
  1792. </code></pre>
  1793.  
  1794. <p>Inside the body of <code>max-speed</code> (and all other functions called
  1795. during that execution) the kernel function <code>car</code> is redefined to some
  1796. other value, and will surely crash if something like <code>(car Lst)</code> is
  1797. executed. Instead, it is safe to write:
  1798.  
  1799. <pre><code>
  1800. : (de max-speed (Car) # 'Car' with upper case first letter
  1801. (.. (get Car 'speeds) ..) )
  1802. -> max-speed
  1803. </code></pre>
  1804.  
  1805. <p>Note that there are also some strict naming rules (as opposed to the
  1806. voluntary conventions) that are required by the corresponding kernel
  1807. functionalities, like:
  1808.  
  1809. <p><ul>
  1810. <li>Transient symbols are enclosed in double quotes (see <a
  1811. href="#transient-io">Transient Symbols</a>)
  1812. <li>External symbols are enclosed in braces (see <a href="#external-io">External
  1813. Symbols</a>)
  1814. <li>Pattern-Wildcards start with an at-mark "<code>@</code>" (see <a
  1815. href="#match">match</a> and <a href="refF.html#fill">fill</a>)
  1816. <li>Symbols referring to a shared library contain a colon "<code>lib:sym</code>"
  1817. </ul>
  1818.  
  1819. <p>With that, the last of the above conventions (local functions start with an
  1820. underscore) is not really necessary, because true local scope can be enforced
  1821. with transient symbols.
  1822.  
  1823.  
  1824. <p><hr>
  1825. <h3><a name="trad">Breaking Traditions</a></h3>
  1826.  
  1827. <p>PicoLisp does not try very hard to be compatible with traditional Lisp
  1828. systems. If you are used to some other Lisp dialects, you may notice the
  1829. following differences:
  1830.  
  1831. <p><dl>
  1832.  
  1833. <dt>Case Sensitivity
  1834. <dd>PicoLisp distinguishes between upper case and lower case characters in
  1835. symbol names. Thus, <code>CAR</code> and <code>car</code> are different symbols,
  1836. which was not the case in traditional Lisp systems.
  1837.  
  1838. <dt><code>QUOTE</code>
  1839. <dd>In traditional Lisp, the <code>QUOTE</code> function returns its
  1840. <i>first</i> unevaluated argument. In PicoLisp, on the other hand,
  1841. <code>quote</code> returns <i>all</i> (unevaluated) argument(s).
  1842.  
  1843. <dt><code>LAMBDA</code>
  1844. <dd>The <code>LAMBDA</code> function, in some way at the heart of traditional
  1845. Lisp, is completely missing (and <code>quote</code> is used instead).
  1846.  
  1847. <dt><code>PROG</code>
  1848. <dd>The <code>PROG</code> function of traditional Lisp, with its GOTO and ENTER
  1849. functionality, is also missing. PicoLisp's <code>prog</code> function is just a
  1850. simple sequencer (as <code>PROGN</code> in some Lisps).
  1851.  
  1852. <dt>Function/Value
  1853. <dd>In PicoLisp, a symbol cannot have a value <i>and</i> a function definition
  1854. at the same time. Though this is a disadvantage at first sight, it allows a
  1855. completely uniform handling of functional data.
  1856.  
  1857. </dl>
  1858.  
  1859.  
  1860. <p><hr>
  1861. <h3><a name="bugs">Bugs</a></h3>
  1862.  
  1863. <p>The names of the symbols <code>T</code> and <code>NIL</code> violate the <a
  1864. href="#conv">naming conventions</a>. They are global symbols, and should
  1865. therefore start with an asterisk "<code>*</code>". It is too easy to bind them
  1866. to some other value by mistake:
  1867.  
  1868. <pre><code>
  1869. (de foo (R S T)
  1870. ...
  1871. </code></pre>
  1872.  
  1873. <p>However, <code><a href="#lint">lint</a></code> will issue a warning
  1874. in such a case.
  1875.  
  1876.  
  1877. <p><hr>
  1878. <h2><a name="fun">Function Reference</a></h2>
  1879.  
  1880. <p>This section provides a reference manual for the kernel functions, and some
  1881. extensions. See the thematically grouped list of indexes below.
  1882.  
  1883. <p>Though PicoLisp is a dynamically typed language (resolved at runtime, as
  1884. opposed to statically (compile-time) typed languages), many functions can only
  1885. accept and/or return a certain set of data types. For each function, the
  1886. expected argument types and return values are described with the following
  1887. abbreviations:
  1888.  
  1889. <p>The primary data types:
  1890.  
  1891. <p><ul>
  1892. <li><code>num</code> - Number
  1893. <li><code>sym</code> - Symbol
  1894. <li><code>lst</code> - List
  1895. </ul>
  1896.  
  1897. <p>Other (derived) data types
  1898.  
  1899. <p><ul>
  1900. <li><code>any</code> - Anything: Any data type
  1901. <li><code>flg</code> - Flag: Boolean value (<code>NIL</code> or non-<code>NIL</code>)
  1902. <li><code>cnt</code> - A count or a small number
  1903. <li><code>dat</code> - Date: Days, starting first of March of the year 0 A.D.
  1904. <li><code>tim</code> - Time: Seconds since midnight
  1905. <li><code>obj</code> - Object/Class: A symbol with methods and/or classes
  1906. <li><code>var</code> - Variable: Either a symbol or a cons pair
  1907. <li><code>exe</code> - Executable: An executable expression (<code>eval</code>)
  1908. <li><code>prg</code> - Prog-Body: A list of executable expressions (<code>run</code>)
  1909. <li><code>fun</code> - Function: Either a number (code-pointer), a symbol (message) or a list (lambda)
  1910. <li><code>msg</code> - Message: A symbol sent to an object (to invoke a method)
  1911. <li><code>cls</code> - Class: A symbol defined as an object's class
  1912. <li><code>typ</code> - Type: A list of <code>cls</code> symbols
  1913. <li><code>pat</code> - Pattern: A symbol whose name starts with an at-mark "<code>@</code>"
  1914. <li><code>pid</code> - Process ID: A number, the ID of a Unix process
  1915. <li><code>tree</code> - Database index tree specification
  1916. <li><code>hook</code> - Database hook object
  1917. </ul>
  1918.  
  1919. <p>Arguments evaluated by the function (depending on the context) are quoted
  1920. (prefixed with the single quote character "<code>'</code>").
  1921.  
  1922. <p>
  1923. <a href="#A">A</a>
  1924. <a href="#B">B</a>
  1925. <a href="#C">C</a>
  1926. <a href="#D">D</a>
  1927. <a href="#E">E</a>
  1928. <a href="#F">F</a>
  1929. <a href="#G">G</a>
  1930. <a href="#H">H</a>
  1931. <a href="#I">I</a>
  1932. <a href="#J">J</a>
  1933. <a href="#K">K</a>
  1934. <a href="#L">L</a>
  1935. <a href="#M">M</a>
  1936. <a href="#N">N</a>
  1937. <a href="#O">O</a>
  1938. <a href="#P">P</a>
  1939. <a href="#Q">Q</a>
  1940. <a href="#R">R</a>
  1941. <a href="#S">S</a>
  1942. <a href="#T">T</a>
  1943. <a href="#U">U</a>
  1944. <a href="#V">V</a>
  1945. <a href="#W">W</a>
  1946. <a href="#X">X</a>
  1947. <a href="#Y">Y</a>
  1948. <a href="#Z">Z</a>
  1949. <a href="#_">Other</a>
  1950.  
  1951. <p><span id="sortBtnHome"></span><dl>
  1952.  
  1953. <dt>Symbol Functions
  1954. <dd><code>
  1955. <a href="#new">new</a>
  1956. <a href="#sym">sym</a>
  1957. <a href="#str">str</a>
  1958. <a href="#char">char</a>
  1959. <a href="#name">name</a>
  1960. <a href="#sp?">sp?</a>
  1961. <a href="#pat?">pat?</a>
  1962. <a href="#fun?">fun?</a>
  1963. <a href="#all">all</a>
  1964. <a href="#symbols">symbols</a>
  1965. <a href="#local">local</a>
  1966. <a href="#import">import</a>
  1967. <a href="#intern">intern</a>
  1968. <a href="#extern">extern</a>
  1969. <a href="#====">====</a>
  1970. <a href="#qsym">qsym</a>
  1971. <a href="#loc">loc</a>
  1972. <a href="#box?">box?</a>
  1973. <a href="#str?">str?</a>
  1974. <a href="#ext?">ext?</a>
  1975. <a href="#touch">touch</a>
  1976. <a href="#zap">zap</a>
  1977. <a href="#length">length</a>
  1978. <a href="#size">size</a>
  1979. <a href="#format">format</a>
  1980. <a href="#chop">chop</a>
  1981. <a href="#pack">pack</a>
  1982. <a href="#glue">glue</a>
  1983. <a href="#pad">pad</a>
  1984. <a href="#align">align</a>
  1985. <a href="#center">center</a>
  1986. <a href="#text">text</a>
  1987. <a href="#wrap">wrap</a>
  1988. <a href="#pre?">pre?</a>
  1989. <a href="#sub?">sub?</a>
  1990. <a href="#low?">low?</a>
  1991. <a href="#upp?">upp?</a>
  1992. <a href="#lowc">lowc</a>
  1993. <a href="#uppc">uppc</a>
  1994. <a href="#fold">fold</a>
  1995. <a href="#val">val</a>
  1996. <a href="#getd">getd</a>
  1997. <a href="#set">set</a>
  1998. <a href="#setq">setq</a>
  1999. <a href="#def">def</a>
  2000. <a href="#de">de</a>
  2001. <a href="#dm">dm</a>
  2002. <a href="#recur">recur</a>
  2003. <a href="#undef">undef</a>
  2004. <a href="#redef">redef</a>
  2005. <a href="#daemon">daemon</a>
  2006. <a href="#patch">patch</a>
  2007. <a href="#swap">swap</a>
  2008. <a href="#xchg">xchg</a>
  2009. <a href="#on">on</a>
  2010. <a href="#off">off</a>
  2011. <a href="#onOff">onOff</a>
  2012. <a href="#zero">zero</a>
  2013. <a href="#one">one</a>
  2014. <a href="#default">default</a>
  2015. <a href="#expr">expr</a>
  2016. <a href="#subr">subr</a>
  2017. <a href="#let">let</a>
  2018. <a href="#let?">let?</a>
  2019. <a href="#use">use</a>
  2020. <a href="#accu">accu</a>
  2021. <a href="#push">push</a>
  2022. <a href="#push1">push1</a>
  2023. <a href="#push1q">push1q</a>
  2024. <a href="#pop">pop</a>
  2025. <a href="#cut">cut</a>
  2026. <a href="#del">del</a>
  2027. <a href="#queue">queue</a>
  2028. <a href="#fifo">fifo</a>
  2029. <a href="#idx">idx</a>
  2030. <a href="#lup">lup</a>
  2031. <a href="#cache">cache</a>
  2032. <a href="#locale">locale</a>
  2033. <a href="#dirname">dirname</a>
  2034. </code>
  2035.  
  2036. <dt>Property Access
  2037. <dd><code>
  2038. <a href="#put">put</a>
  2039. <a href="#get">get</a>
  2040. <a href="#prop">prop</a>
  2041. <a href="#;">;</a>
  2042. <a href="#=:">=:</a>
  2043. <a href="#:">:</a>
  2044. <a href="#::">::</a>
  2045. <a href="#putl">putl</a>
  2046. <a href="#getl">getl</a>
  2047. <a href="#wipe">wipe</a>
  2048. <a href="#meta">meta</a>
  2049. </code>
  2050.  
  2051. <dt>Predicates
  2052. <dd><code>
  2053. <a href="#atom">atom</a>
  2054. <a href="#pair">pair</a>
  2055. <a href="#circ?">circ?</a>
  2056. <a href="#lst?">lst?</a>
  2057. <a href="#num?">num?</a>
  2058. <a href="#sym?">sym?</a>
  2059. <a href="#flg?">flg?</a>
  2060. <a href="#sp?">sp?</a>
  2061. <a href="#pat?">pat?</a>
  2062. <a href="#fun?">fun?</a>
  2063. <a href="#box?">box?</a>
  2064. <a href="#str?">str?</a>
  2065. <a href="#ext?">ext?</a>
  2066. <a href="#bool">bool</a>
  2067. <a href="#not">not</a>
  2068. <a href="#==">==</a>
  2069. <a href="#n==">n==</a>
  2070. <a href="#=">=</a>
  2071. <a href="#<>"><&gt</a>
  2072. <a href="#=0">=0</a>
  2073. <a href="#=T">=T</a>
  2074. <a href="#n0">n0</a>
  2075. <a href="#nT">nT</a>
  2076. <a href="#<">&lt;</a>
  2077. <a href="#<=">&lt;=</a>
  2078. <a href="#>">&gt;</a>
  2079. <a href="#>=">&gt;=</a>
  2080. <a href="#match">match</a>
  2081. </code>
  2082.  
  2083. <dt>Arithmetics
  2084. <dd><code>
  2085. <a href="#+">+</a>
  2086. <a href="#-">-</a>
  2087. <a href="#*">*</a>
  2088. <a href="#/">/</a>
  2089. <a href="#%">%</a>
  2090. <a href="#*/">*/</a>
  2091. <a href="#**">**</a>
  2092. <a href="#inc">inc</a>
  2093. <a href="#dec">dec</a>
  2094. <a href="#>>">>></a>
  2095. <a href="#lt0">lt0</a>
  2096. <a href="#le0">le0</a>
  2097. <a href="#ge0">ge0</a>
  2098. <a href="#gt0">gt0</a>
  2099. <a href="#abs">abs</a>
  2100. <a href="#bit?">bit?</a>
  2101. <a href="#&">&</a>
  2102. <a href="#|">|</a>
  2103. <a href="#x|">x|</a>
  2104. <a href="#sqrt">sqrt</a>
  2105. <a href="#seed">seed</a>
  2106. <a href="#hash">hash</a>
  2107. <a href="#rand">rand</a>
  2108. <a href="#max">max</a>
  2109. <a href="#min">min</a>
  2110. <a href="#length">length</a>
  2111. <a href="#size">size</a>
  2112. <a href="#accu">accu</a>
  2113. <a href="#format">format</a>
  2114. <a href="#pad">pad</a>
  2115. <a href="#money">money</a>
  2116. <a href="#round">round</a>
  2117. <a href="#bin">bin</a>
  2118. <a href="#oct">oct</a>
  2119. <a href="#hex">hex</a>
  2120. <a href="#hax">hax</a>
  2121. <a href="#fmt64">fmt64</a>
  2122. </code>
  2123.  
  2124. <dt>List Processing
  2125. <dd><code>
  2126. <a href="#car">car</a>
  2127. <a href="#cdr">cdr</a>
  2128. <a href="#caar">caar</a>
  2129. <a href="#cadr">cadr</a>
  2130. <a href="#cdar">cdar</a>
  2131. <a href="#cddr">cddr</a>
  2132. <a href="#caaar">caaar</a>
  2133. <a href="#caadr">caadr</a>
  2134. <a href="#cadar">cadar</a>
  2135. <a href="#caddr">caddr</a>
  2136. <a href="#cdaar">cdaar</a>
  2137. <a href="#cdadr">cdadr</a>
  2138. <a href="#cddar">cddar</a>
  2139. <a href="#cdddr">cdddr</a>
  2140. <a href="#caaaar">caaaar</a>
  2141. <a href="#caaadr">caaadr</a>
  2142. <a href="#caadar">caadar</a>
  2143. <a href="#caaddr">caaddr</a>
  2144. <a href="#cadaar">cadaar</a>
  2145. <a href="#cadadr">cadadr</a>
  2146. <a href="#caddar">caddar</a>
  2147. <a href="#cadddr">cadddr</a>
  2148. <a href="#cdaaar">cdaaar</a>
  2149. <a href="#cdaadr">cdaadr</a>
  2150. <a href="#cdadar">cdadar</a>
  2151. <a href="#cdaddr">cdaddr</a>
  2152. <a href="#cddaar">cddaar</a>
  2153. <a href="#cddadr">cddadr</a>
  2154. <a href="#cdddar">cdddar</a>
  2155. <a href="#cddddr">cddddr</a>
  2156. <a href="#nth">nth</a>
  2157. <a href="#con">con</a>
  2158. <a href="#cons">cons</a>
  2159. <a href="#conc">conc</a>
  2160. <a href="#circ">circ</a>
  2161. <a href="#rot">rot</a>
  2162. <a href="#list">list</a>
  2163. <a href="#need">need</a>
  2164. <a href="#range">range</a>
  2165. <a href="#full">full</a>
  2166. <a href="#make">make</a>
  2167. <a href="#made">made</a>
  2168. <a href="#chain">chain</a>
  2169. <a href="#link">link</a>
  2170. <a href="#yoke">yoke</a>
  2171. <a href="#copy">copy</a>
  2172. <a href="#mix">mix</a>
  2173. <a href="#append">append</a>
  2174. <a href="#delete">delete</a>
  2175. <a href="#delq">delq</a>
  2176. <a href="#replace">replace</a>
  2177. <a href="#insert">insert</a>
  2178. <a href="#remove">remove</a>
  2179. <a href="#place">place</a>
  2180. <a href="#strip">strip</a>
  2181. <a href="#split">split</a>
  2182. <a href="#reverse">reverse</a>
  2183. <a href="#flip">flip</a>
  2184. <a href="#trim">trim</a>
  2185. <a href="#clip">clip</a>
  2186. <a href="#head">head</a>
  2187. <a href="#tail">tail</a>
  2188. <a href="#stem">stem</a>
  2189. <a href="#fin">fin</a>
  2190. <a href="#last">last</a>
  2191. <a href="#member">member</a>
  2192. <a href="#memq">memq</a>
  2193. <a href="#mmeq">mmeq</a>
  2194. <a href="#sect">sect</a>
  2195. <a href="#diff">diff</a>
  2196. <a href="#index">index</a>
  2197. <a href="#offset">offset</a>
  2198. <a href="#prior">prior</a>
  2199. <a href="#assoc">assoc</a>
  2200. <a href="#rassoc">rassoc</a>
  2201. <a href="#asoq">asoq</a>
  2202. <a href="#rank">rank</a>
  2203. <a href="#sort">sort</a>
  2204. <a href="#uniq">uniq</a>
  2205. <a href="#group">group</a>
  2206. <a href="#length">length</a>
  2207. <a href="#size">size</a>
  2208. <a href="#bytes">bytes</a>
  2209. <a href="#val">val</a>
  2210. <a href="#set">set</a>
  2211. <a href="#xchg">xchg</a>
  2212. <a href="#push">push</a>
  2213. <a href="#push1">push1</a>
  2214. <a href="#push1q">push1q</a>
  2215. <a href="#pop">pop</a>
  2216. <a href="#cut">cut</a>
  2217. <a href="#queue">queue</a>
  2218. <a href="#fifo">fifo</a>
  2219. <a href="#idx">idx</a>
  2220. <a href="#balance">balance</a>
  2221. <a href="#get">get</a>
  2222. <a href="#fill">fill</a>
  2223. <a href="#apply">apply</a>
  2224. </code>
  2225.  
  2226. <dt>Control Flow
  2227. <dd><code>
  2228. <a href="#load">load</a>
  2229. <a href="#args">args</a>
  2230. <a href="#next">next</a>
  2231. <a href="#arg">arg</a>
  2232. <a href="#rest">rest</a>
  2233. <a href="#pass">pass</a>
  2234. <a href="#quote">quote</a>
  2235. <a href="#as">as</a>
  2236. <a href="#lit">lit</a>
  2237. <a href="#eval">eval</a>
  2238. <a href="#run">run</a>
  2239. <a href="#macro">macro</a>
  2240. <a href="#curry">curry</a>
  2241. <a href="#def">def</a>
  2242. <a href="#de">de</a>
  2243. <a href="#dm">dm</a>
  2244. <a href="#recur">recur</a>
  2245. <a href="#recurse">recurse</a>
  2246. <a href="#undef">undef</a>
  2247. <a href="#box">box</a>
  2248. <a href="#new">new</a>
  2249. <a href="#type">type</a>
  2250. <a href="#isa">isa</a>
  2251. <a href="#method">method</a>
  2252. <a href="#meth">meth</a>
  2253. <a href="#send">send</a>
  2254. <a href="#try">try</a>
  2255. <a href="#super">super</a>
  2256. <a href="#extra">extra</a>
  2257. <a href="#with">with</a>
  2258. <a href="#bind">bind</a>
  2259. <a href="#job">job</a>
  2260. <a href="#let">let</a>
  2261. <a href="#let?">let?</a>
  2262. <a href="#use">use</a>
  2263. <a href="#and">and</a>
  2264. <a href="#or">or</a>
  2265. <a href="#nand">nand</a>
  2266. <a href="#nor">nor</a>
  2267. <a href="#xor">xor</a>
  2268. <a href="#bool">bool</a>
  2269. <a href="#not">not</a>
  2270. <a href="#nil">nil</a>
  2271. <a href="#t">t</a>
  2272. <a href="#prog">prog</a>
  2273. <a href="#prog1">prog1</a>
  2274. <a href="#prog2">prog2</a>
  2275. <a href="#if">if</a>
  2276. <a href="#if2">if2</a>
  2277. <a href="#ifn">ifn</a>
  2278. <a href="#when">when</a>
  2279. <a href="#unless">unless</a>
  2280. <a href="#cond">cond</a>
  2281. <a href="#nond">nond</a>
  2282. <a href="#case">case</a>
  2283. <a href="#casq">casq</a>
  2284. <a href="#state">state</a>
  2285. <a href="#while">while</a>
  2286. <a href="#until">until</a>
  2287. <a href="#loop">loop</a>
  2288. <a href="#do">do</a>
  2289. <a href="#at">at</a>
  2290. <a href="#for">for</a>
  2291. <a href="#catch">catch</a>
  2292. <a href="#throw">throw</a>
  2293. <a href="#finally">finally</a>
  2294. <a href="#co">co</a>
  2295. <a href="#yield">yield</a>
  2296. <a href="#!">!</a>
  2297. <a href="#e">e</a>
  2298. <a href="#$">$</a>
  2299. <a href="#call">call</a>
  2300. <a href="#tick">tick</a>
  2301. <a href="#ipid">ipid</a>
  2302. <a href="#opid">opid</a>
  2303. <a href="#kill">kill</a>
  2304. <a href="#quit">quit</a>
  2305. <a href="#task">task</a>
  2306. <a href="#fork">fork</a>
  2307. <a href="#pipe">pipe</a>
  2308. <a href="#later">later</a>
  2309. <a href="#timeout">timeout</a>
  2310. <a href="#abort">abort</a>
  2311. <a href="#bye">bye</a>
  2312. </code>
  2313.  
  2314. <dt>Mapping
  2315. <dd><code>
  2316. <a href="#apply">apply</a>
  2317. <a href="#pass">pass</a>
  2318. <a href="#maps">maps</a>
  2319. <a href="#map">map</a>
  2320. <a href="#mapc">mapc</a>
  2321. <a href="#maplist">maplist</a>
  2322. <a href="#mapcar">mapcar</a>
  2323. <a href="#mapcon">mapcon</a>
  2324. <a href="#mapcan">mapcan</a>
  2325. <a href="#filter">filter</a>
  2326. <a href="#extract">extract</a>
  2327. <a href="#seek">seek</a>
  2328. <a href="#find">find</a>
  2329. <a href="#pick">pick</a>
  2330. <a href="#fully">fully</a>
  2331. <a href="#cnt">cnt</a>
  2332. <a href="#sum">sum</a>
  2333. <a href="#maxi">maxi</a>
  2334. <a href="#mini">mini</a>
  2335. <a href="#fish">fish</a>
  2336. <a href="#by">by</a>
  2337. </code>
  2338.  
  2339. <dt>Input/Output
  2340. <dd><code>
  2341. <a href="#path">path</a>
  2342. <a href="#in">in</a>
  2343. <a href="#out">out</a>
  2344. <a href="#err">err</a>
  2345. <a href="#ctl">ctl</a>
  2346. <a href="#ipid">ipid</a>
  2347. <a href="#opid">opid</a>
  2348. <a href="#pipe">pipe</a>
  2349. <a href="#any">any</a>
  2350. <a href="#sym">sym</a>
  2351. <a href="#str">str</a>
  2352. <a href="#load">load</a>
  2353. <a href="#hear">hear</a>
  2354. <a href="#tell">tell</a>
  2355. <a href="#key">key</a>
  2356. <a href="#poll">poll</a>
  2357. <a href="#peek">peek</a>
  2358. <a href="#char">char</a>
  2359. <a href="#skip">skip</a>
  2360. <a href="#eol">eol</a>
  2361. <a href="#eof">eof</a>
  2362. <a href="#from">from</a>
  2363. <a href="#till">till</a>
  2364. <a href="#line">line</a>
  2365. <a href="#format">format</a>
  2366. <a href="#scl">scl</a>
  2367. <a href="#read">read</a>
  2368. <a href="#print">print</a>
  2369. <a href="#println">println</a>
  2370. <a href="#printsp">printsp</a>
  2371. <a href="#prin">prin</a>
  2372. <a href="#prinl">prinl</a>
  2373. <a href="#msg">msg</a>
  2374. <a href="#space">space</a>
  2375. <a href="#beep">beep</a>
  2376. <a href="#tab">tab</a>
  2377. <a href="#flush">flush</a>
  2378. <a href="#rewind">rewind</a>
  2379. <a href="#rd">rd</a>
  2380. <a href="#pr">pr</a>
  2381. <a href="#wr">wr</a>
  2382. <a href="#wait">wait</a>
  2383. <a href="#sync">sync</a>
  2384. <a href="#echo">echo</a>
  2385. <a href="#info">info</a>
  2386. <a href="#file">file</a>
  2387. <a href="#dir">dir</a>
  2388. <a href="#lines">lines</a>
  2389. <a href="#open">open</a>
  2390. <a href="#close">close</a>
  2391. <a href="#port">port</a>
  2392. <a href="#listen">listen</a>
  2393. <a href="#accept">accept</a>
  2394. <a href="#host">host</a>
  2395. <a href="#connect">connect</a>
  2396. <a href="#udp">udp</a>
  2397. <a href="#script">script</a>
  2398. <a href="#once">once</a>
  2399. <a href="#rc">rc</a>
  2400. <a href="#acquire">acquire</a>
  2401. <a href="#release">release</a>
  2402. <a href="#tmp">tmp</a>
  2403. <a href="#pretty">pretty</a>
  2404. <a href="#pp">pp</a>
  2405. <a href="#show">show</a>
  2406. <a href="#view">view</a>
  2407. <a href="#here">here</a>
  2408. <a href="#prEval">prEval</a>
  2409. <a href="#mail">mail</a>
  2410. </code>
  2411.  
  2412. <dt>Object Orientation
  2413. <dd><code>
  2414. <a href="#*Class">*Class</a>
  2415. <a href="#class">class</a>
  2416. <a href="#dm">dm</a>
  2417. <a href="#rel">rel</a>
  2418. <a href="#var">var</a>
  2419. <a href="#var:">var:</a>
  2420. <a href="#new">new</a>
  2421. <a href="#type">type</a>
  2422. <a href="#isa">isa</a>
  2423. <a href="#method">method</a>
  2424. <a href="#meth">meth</a>
  2425. <a href="#send">send</a>
  2426. <a href="#try">try</a>
  2427. <a href="#object">object</a>
  2428. <a href="#extend">extend</a>
  2429. <a href="#super">super</a>
  2430. <a href="#extra">extra</a>
  2431. <a href="#with">with</a>
  2432. <a href="#This">This</a>
  2433. <a href="#can">can</a>
  2434. <a href="#dep">dep</a>
  2435. </code>
  2436.  
  2437. <dt>Database
  2438. <dd><code>
  2439. <a href="#pool">pool</a>
  2440. <a href="#journal">journal</a>
  2441. <a href="#id">id</a>
  2442. <a href="#seq">seq</a>
  2443. <a href="#lieu">lieu</a>
  2444. <a href="#lock">lock</a>
  2445. <a href="#commit">commit</a>
  2446. <a href="#rollback">rollback</a>
  2447. <a href="#mark">mark</a>
  2448. <a href="#free">free</a>
  2449. <a href="#dbck">dbck</a>
  2450. <a href="#dbs">dbs</a>
  2451. <a href="#dbs+">dbs+</a>
  2452. <a href="#db:">db:</a>
  2453. <a href="#tree">tree</a>
  2454. <a href="#db">db</a>
  2455. <a href="#aux">aux</a>
  2456. <a href="#collect">collect</a>
  2457. <a href="#genKey">genKey</a>
  2458. <a href="#genStrKey">genStrKey</a>
  2459. <a href="#useKey">useKey</a>
  2460. <a href="#+relation">+relation</a>
  2461. <a href="#+Any">+Any</a>
  2462. <a href="#+Bag">+Bag</a>
  2463. <a href="#+Bool">+Bool</a>
  2464. <a href="#+Number">+Number</a>
  2465. <a href="#+Date">+Date</a>
  2466. <a href="#+Time">+Time</a>
  2467. <a href="#+Symbol">+Symbol</a>
  2468. <a href="#+String">+String</a>
  2469. <a href="#+Link">+Link</a>
  2470. <a href="#+Joint">+Joint</a>
  2471. <a href="#+Blob">+Blob</a>
  2472. <a href="#+Hook">+Hook</a>
  2473. <a href="#+Hook2">+Hook2</a>
  2474. <a href="#+index">+index</a>
  2475. <a href="#+Key">+Key</a>
  2476. <a href="#+Ref">+Ref</a>
  2477. <a href="#+Ref2">+Ref2</a>
  2478. <a href="#+Idx">+Idx</a>
  2479. <a href="#+Sn">+Sn</a>
  2480. <a href="#+Fold">+Fold</a>
  2481. <a href="#+IdxFold">+IdxFold</a>
  2482. <a href="#+Aux">+Aux</a>
  2483. <a href="#+UB">+UB</a>
  2484. <a href="#+Dep">+Dep</a>
  2485. <a href="#+List">+List</a>
  2486. <a href="#+Need">+Need</a>
  2487. <a href="#+Mis">+Mis</a>
  2488. <a href="#+Alt">+Alt</a>
  2489. <a href="#+Swap">+Swap</a>
  2490. <a href="#+Entity">+Entity</a>
  2491. <a href="#blob">blob</a>
  2492. <a href="#dbSync">dbSync</a>
  2493. <a href="#new!">new!</a>
  2494. <a href="#set!">set!</a>
  2495. <a href="#put!">put!</a>
  2496. <a href="#inc!">inc!</a>
  2497. <a href="#blob!">blob!</a>
  2498. <a href="#upd">upd</a>
  2499. <a href="#rel">rel</a>
  2500. <a href="#request">request</a>
  2501. <a href="#obj">obj</a>
  2502. <a href="#fmt64">fmt64</a>
  2503. <a href="#root">root</a>
  2504. <a href="#fetch">fetch</a>
  2505. <a href="#store">store</a>
  2506. <a href="#count">count</a>
  2507. <a href="#leaf">leaf</a>
  2508. <a href="#minKey">minKey</a>
  2509. <a href="#maxKey">maxKey</a>
  2510. <a href="#init">init</a>
  2511. <a href="#step">step</a>
  2512. <a href="#scan">scan</a>
  2513. <a href="#iter">iter</a>
  2514. <a href="#ubIter">ubIter</a>
  2515. <a href="#prune">prune</a>
  2516. <a href="#zapTree">zapTree</a>
  2517. <a href="#chkTree">chkTree</a>
  2518. <a href="#db/3">db/3</a>
  2519. <a href="#db/4">db/4</a>
  2520. <a href="#db/5">db/5</a>
  2521. <a href="#val/3">val/3</a>
  2522. <a href="#lst/3">lst/3</a>
  2523. <a href="#map/3">map/3</a>
  2524. <a href="#isa/2">isa/2</a>
  2525. <a href="#same/3">same/3</a>
  2526. <a href="#bool/3">bool/3</a>
  2527. <a href="#range/3">range/3</a>
  2528. <a href="#head/3">head/3</a>
  2529. <a href="#fold/3">fold/3</a>
  2530. <a href="#part/3">part/3</a>
  2531. <a href="#tolr/3">tolr/3</a>
  2532. <a href="#select/3">select/3</a>
  2533. <a href="#remote/2">remote/2</a>
  2534. </code>
  2535.  
  2536. <dt>Pilog
  2537. <dd><code>
  2538. <a href="#prove">prove</a>
  2539. <a href="#->">-&gt</a>
  2540. <a href="#unify">unify</a>
  2541. <a href="#be">be</a>
  2542. <a href="#clause">clause</a>
  2543. <a href="#repeat">repeat</a>
  2544. <a href="#asserta">asserta</a>
  2545. <a href="#assertz">assertz</a>
  2546. <a href="#retract">retract</a>
  2547. <a href="#rules">rules</a>
  2548. <a href="#goal">goal</a>
  2549. <a href="#fail">fail</a>
  2550. <a href="#pilog">pilog</a>
  2551. <a href="#solve">solve</a>
  2552. <a href="#query">query</a>
  2553. <a href="#?">?</a>
  2554. <a href="#repeat/0">repeat/0</a>
  2555. <a href="#fail/0">fail/0</a>
  2556. <a href="#true/0">true/0</a>
  2557. <a href="#not/1">not/1</a>
  2558. <a href="#call/1">call/1</a>
  2559. <a href="#or/2">or/2</a>
  2560. <a href="#nil/1">nil/1</a>
  2561. <a href="#equal/2">equal/2</a>
  2562. <a href="#different/2">different/2</a>
  2563. <a href="#append/3">append/3</a>
  2564. <a href="#member/2">member/2</a>
  2565. <a href="#delete/3">delete/3</a>
  2566. <a href="#permute/2">permute/2</a>
  2567. <a href="#uniq/2">uniq/2</a>
  2568. <a href="#asserta/1">asserta/1</a>
  2569. <a href="#assertz/1">assertz/1</a>
  2570. <a href="#retract/1">retract/1</a>
  2571. <a href="#clause/2">clause/2</a>
  2572. <a href="#show/1">show/1</a>
  2573. <a href="#for/2">for/2</a>
  2574. <a href="#for/3">for/3</a>
  2575. <a href="#for/4">for/4</a>
  2576. <a href="#db/3">db/3</a>
  2577. <a href="#db/4">db/4</a>
  2578. <a href="#db/5">db/5</a>
  2579. <a href="#val/3">val/3</a>
  2580. <a href="#lst/3">lst/3</a>
  2581. <a href="#map/3">map/3</a>
  2582. <a href="#isa/2">isa/2</a>
  2583. <a href="#same/3">same/3</a>
  2584. <a href="#bool/3">bool/3</a>
  2585. <a href="#range/3">range/3</a>
  2586. <a href="#head/3">head/3</a>
  2587. <a href="#fold/3">fold/3</a>
  2588. <a href="#part/3">part/3</a>
  2589. <a href="#tolr/3">tolr/3</a>
  2590. <a href="#select/3">select/3</a>
  2591. <a href="#remote/2">remote/2</a>
  2592. </code>
  2593.  
  2594. <dt>Debugging
  2595. <dd><code>
  2596. <a href="#pretty">pretty</a>
  2597. <a href="#pp">pp</a>
  2598. <a href="#show">show</a>
  2599. <a href="#loc">loc</a>
  2600. <a href="#*Dbg">*Dbg</a>
  2601. <a href="#doc">doc</a>
  2602. <a href="#more">more</a>
  2603. <a href="#depth">depth</a>
  2604. <a href="#what">what</a>
  2605. <a href="#who">who</a>
  2606. <a href="#can">can</a>
  2607. <a href="#dep">dep</a>
  2608. <a href="#debug">debug</a>
  2609. <a href="#d">d</a>
  2610. <a href="#unbug">unbug</a>
  2611. <a href="#u">u</a>
  2612. <a href="#vi">vi</a>
  2613. <a href="#em">em</a>
  2614. <a href="#ld">ld</a>
  2615. <a href="#trace">trace</a>
  2616. <a href="#untrace">untrace</a>
  2617. <a href="#traceAll">traceAll</a>
  2618. <a href="#proc">proc</a>
  2619. <a href="#hd">hd</a>
  2620. <a href="#bench">bench</a>
  2621. <a href="#bt">bt</a>
  2622. <a href="#edit">edit</a>
  2623. <a href="#lint">lint</a>
  2624. <a href="#lintAll">lintAll</a>
  2625. <a href="#select">select</a>
  2626. <a href="#update">update</a>
  2627. </code>
  2628.  
  2629. <dt>System Functions
  2630. <dd><code>
  2631. <a href="#cmd">cmd</a>
  2632. <a href="#argv">argv</a>
  2633. <a href="#opt">opt</a>
  2634. <a href="#version">version</a>
  2635. <a href="#gc">gc</a>
  2636. <a href="#raw">raw</a>
  2637. <a href="#alarm">alarm</a>
  2638. <a href="#sigio">sigio</a>
  2639. <a href="#kids">kids</a>
  2640. <a href="#protect">protect</a>
  2641. <a href="#heap">heap</a>
  2642. <a href="#stack">stack</a>
  2643. <a href="#adr">adr</a>
  2644. <a href="#env">env</a>
  2645. <a href="#trail">trail</a>
  2646. <a href="#up">up</a>
  2647. <a href="#sys">sys</a>
  2648. <a href="#date">date</a>
  2649. <a href="#time">time</a>
  2650. <a href="#usec">usec</a>
  2651. <a href="#stamp">stamp</a>
  2652. <a href="#dat$">dat$</a>
  2653. <a href="#$dat">$dat</a>
  2654. <a href="#datSym">datSym</a>
  2655. <a href="#datStr">datStr</a>
  2656. <a href="#strDat">strDat</a>
  2657. <a href="#expDat">expDat</a>
  2658. <a href="#day">day</a>
  2659. <a href="#week">week</a>
  2660. <a href="#ultimo">ultimo</a>
  2661. <a href="#tim$">tim$</a>
  2662. <a href="#$tim">$tim</a>
  2663. <a href="#telStr">telStr</a>
  2664. <a href="#expTel">expTel</a>
  2665. <a href="#locale">locale</a>
  2666. <a href="#allowed">allowed</a>
  2667. <a href="#allow">allow</a>
  2668. <a href="#pwd">pwd</a>
  2669. <a href="#cd">cd</a>
  2670. <a href="#chdir">chdir</a>
  2671. <a href="#ctty">ctty</a>
  2672. <a href="#info">info</a>
  2673. <a href="#dir">dir</a>
  2674. <a href="#dirname">dirname</a>
  2675. <a href="#errno">errno</a>
  2676. <a href="#native">native</a>
  2677. <a href="#struct">struct</a>
  2678. <a href="#lisp">lisp</a>
  2679. <a href="#exec">exec</a>
  2680. <a href="#call">call</a>
  2681. <a href="#tick">tick</a>
  2682. <a href="#kill">kill</a>
  2683. <a href="#quit">quit</a>
  2684. <a href="#task">task</a>
  2685. <a href="#fork">fork</a>
  2686. <a href="#forked">forked</a>
  2687. <a href="#pipe">pipe</a>
  2688. <a href="#timeout">timeout</a>
  2689. <a href="#mail">mail</a>
  2690. <a href="#assert">assert</a>
  2691. <a href="#test">test</a>
  2692. <a href="#bye">bye</a>
  2693. </code>
  2694.  
  2695. <dt>Globals
  2696. <dd><code>
  2697. <a href="#nilSym">NIL</a>
  2698. <a href="#pico">pico</a>
  2699. <a href="#*CPU">*CPU</a>
  2700. <a href="#*OS">*OS</a>
  2701. <a href="#*DB">*DB</a>
  2702. <a href="#T">T</a>
  2703. <a href="#*Solo">*Solo</a>
  2704. <a href="#*PPid">*PPid</a>
  2705. <a href="#*Pid">*Pid</a>
  2706. <a href="#@">@</a>
  2707. <a href="#@@">@@</a>
  2708. <a href="#@@@">@@@</a>
  2709. <a href="#This">This</a>
  2710. <a href="#*Prompt">*Prompt</a>
  2711. <a href="#*Dbg">*Dbg</a>
  2712. <a href="#*Zap">*Zap</a>
  2713. <a href="#*Scl">*Scl</a>
  2714. <a href="#*Class">*Class</a>
  2715. <a href="#*Dbs">*Dbs</a>
  2716. <a href="#*Run">*Run</a>
  2717. <a href="#*Hup">*Hup</a>
  2718. <a href="#*Sig1">*Sig1</a>
  2719. <a href="#*Sig2">*Sig2</a>
  2720. <a href="#^">^</a>
  2721. <a href="#*Err">*Err</a>
  2722. <a href="#*Msg">*Msg</a>
  2723. <a href="#*Uni">*Uni</a>
  2724. <a href="#*Led">*Led</a>
  2725. <a href="#*Tsm">*Tsm</a>
  2726. <a href="#*Adr">*Adr</a>
  2727. <a href="#*Allow">*Allow</a>
  2728. <a href="#*Fork">*Fork</a>
  2729. <a href="#*Bye">*Bye</a>
  2730. </code>
  2731.  
  2732. </dl>
  2733.  
  2734. <p><hr>
  2735. <h2><a name="down">Download</a></h2>
  2736.  
  2737. <p>The <code>PicoLisp</code> system can be downloaded from the <a
  2738. href="http://software-lab.de/down.html">PicoLisp Download</a> page.
  2739.  
  2740. <script type="text/javascript">
  2741. var sortBtn;
  2742.  
  2743. if (document.querySelectorAll) {
  2744. sortBtn = document.createElement("input");
  2745. sortBtn.setAttribute("type", "button");
  2746. sortBtn.setAttribute("onclick", "sortFunWords()");
  2747. sortBtn.value = "Sort Words Alphabetically";
  2748. document.getElementById("sortBtnHome").appendChild(sortBtn);
  2749. };
  2750.  
  2751. function sortFunWords() {
  2752. var dls = document.querySelectorAll("dl"), funDl = dls[dls.length-1];
  2753. var cats = funDl.querySelectorAll("dd code");
  2754. for (var c=0; c<cats.length; c++) {
  2755. var aElems = cats[c].querySelectorAll("a"), aArr = [];
  2756. for (var i=0; i<aElems.length; i++) { aArr.push(aElems[i]); }
  2757. aArr.sort(function(a,b) { return (a.innerHTML < b.innerHTML) ? -1 : 1; });
  2758. var dd = cats[c].parentNode;
  2759. dd.removeChild(cats[c]);
  2760. var newCode = document.createElement("code");
  2761. dd.appendChild(newCode);
  2762. for (var i=0; i<aArr.length; i++) {
  2763. newCode.appendChild(aArr[i]);
  2764. newCode.appendChild(document.createTextNode(" "));
  2765. }
  2766. }
  2767. sortBtn.setAttribute("disabled", "disabled");
  2768. }
  2769. </script>
  2770.  
  2771. </body>
  2772. </html>
  2773. <h1><a name="A">A</a></h1>
  2774.  
  2775. <dl>
  2776.  
  2777. <dt><a name="*Adr"><code>*Adr</code></a>
  2778. <dd>A global variable holding the IP address of last recently accepted client.
  2779. See also <code><a href="#listen">listen</a></code> and <code><a
  2780. href="#accept">accept</a></code>.
  2781.  
  2782. <pre><code>
  2783. : *Adr
  2784. -> "127.0.0.1"
  2785. </code></pre>
  2786.  
  2787. <dt><a name="adr"><code>(adr 'var) -> num</code></a>
  2788. <dt><code>(adr 'num) -> var</code>
  2789. <dd>Converts, in the first form, a variable <code>var</code> (a symbol or a cons
  2790. pair) into <code>num</code> (actually an encoded pointer). A symbol will result
  2791. in a negative number, and a cons pair in a positive number. The second form
  2792. converts a pointer back into the original <code>var</code>.
  2793.  
  2794. <pre><code>
  2795. : (setq X (box 7))
  2796. -> $53063416137450
  2797. : (adr X)
  2798. -> -2961853431592
  2799. : (adr @)
  2800. -> $53063416137450
  2801. : (val @)
  2802. -> 7
  2803. </code></pre>
  2804.  
  2805. <dt><a name="*Allow"><code>*Allow</code></a>
  2806. <dd>A global variable holding allowed access patterns. If its value is
  2807. non-<code>NIL</code>, it should contain a list where the CAR is an <code><a
  2808. href="#idx">idx</a></code> tree of allowed items, and the CDR a list of
  2809. prefix strings. See also <code><a href="#allow">allow</a></code>,
  2810. <code><a href="#allowed">allowed</a></code> and <code><a
  2811. href="#pre?">pre?</a></code>.
  2812.  
  2813. <pre><code>
  2814. : (allowed ("app/") # Initialize
  2815. "!start" "!stop" "lib.css" "!psh" )
  2816. -> NIL
  2817. : (allow "!myFoo") # additional item
  2818. -> "!myFoo"
  2819. : (allow "myDir/" T) # additional prefix
  2820. -> "myDir/"
  2821.  
  2822. : *Allow
  2823. -> (("!start" ("!psh" ("!myFoo")) "!stop" NIL "lib.css") "app/" "myDir/")
  2824.  
  2825. : (idx *Allow) # items
  2826. -> ("!myFoo" "!psh" "!start" "!stop" "lib.css")
  2827. : (cdr *Allow) # prefixes
  2828. -> ("app/" "myDir/")
  2829. </code></pre>
  2830.  
  2831. <dt><a name="+Alt"><code>+Alt</code></a>
  2832. <dd>Prefix class specifying an alternative class for a <code><a
  2833. href="#+relation">+relation</a></code>. This allows indexes or other
  2834. side effects to be maintained in a class different from the current one. See
  2835. also <a href="#dbase">Database</a>.
  2836.  
  2837. <pre><code>
  2838. (class +EuOrd +Ord) # EU-specific order subclass
  2839. (rel nr (+Alt +Key +Number) +XyOrd) # Maintain the key in the +XyOrd index
  2840. </code></pre>
  2841.  
  2842. <dt><a name="+Any"><code>+Any</code></a>
  2843. <dd>Class for unspecified relations, a subclass of <code><a
  2844. href="#+relation">+relation</a></code>. Objects of that class accept
  2845. and maintain any type of Lisp data. Used often when there is no other suitable
  2846. relation class available. See also <a href="#dbase">Database</a>.
  2847.  
  2848. <p>In the following example <code>+Any</code> is used simply for the reason that
  2849. there is no direct way to specify dotted pairs:
  2850.  
  2851. <pre><code>
  2852. (rel loc (+Any)) # Locale, e.g. ("DE" . "de")
  2853. </code></pre>
  2854.  
  2855. <dt><a name="+Aux"><code>+Aux</code></a>
  2856. <dd>Prefix class maintaining auxiliary keys for <code><a
  2857. href="#+relation">+relation</a></code>s, in addition to <code><a
  2858. href="#+Ref">+Ref</a></code> or <code><a
  2859. href="#+Idx">+Idx</a></code> indexes. Expects a list of auxiliary
  2860. attributes of the same object, and combines all keys in that order into a single
  2861. index key. See also <code><a href="#+UB">+UB</a></code>, <code><a
  2862. href="#aux">aux</a></code> and <a href="ref.html#dbase">Database</a>.
  2863.  
  2864. <pre><code>
  2865. (rel nr (+Ref +Number)) # Normal, non-unique index
  2866. (rel nm (+Aux +Ref +String) (nr txt)) # Combined name/number/text index
  2867. (rel txt (+Aux +Sn +Idx +String) (nr)) # Text/number plus tolerant text index
  2868. </code></pre>
  2869.  
  2870. <dt><a name="abort"><code>(abort 'cnt . prg) -> any</code></a>
  2871. <dd>Aborts the execution of <code>prg</code> if it takes longer than
  2872. <code>cnt</code> seconds, and returns <code>NIL</code>. Otherwise, the result of
  2873. <code>prg</code> is returned. <code><a href="#alarm">alarm</a></code>
  2874. is used internally, so care must be taken not to interfer with other calls to
  2875. <code>alarm</code>.
  2876.  
  2877. <pre><code>
  2878. : (abort 20 (in Sock (rd))) # Wait maximally 20 seconds for socket data
  2879. </code></pre>
  2880.  
  2881. <dt><a name="abs"><code>(abs 'num) -> num</code></a>
  2882. <dd>Returns the absolute value of the <code>num</code> argument.
  2883.  
  2884. <pre><code>
  2885. : (abs -7)
  2886. -> 7
  2887. : (abs 7)
  2888. -> 7
  2889. </code></pre>
  2890.  
  2891. <dt><a name="accept"><code>(accept 'cnt) -> cnt | NIL</code></a>
  2892. <dd>Accepts a connection on descriptor <code>cnt</code> (as received by <code><a
  2893. href="#port">port</a></code>), and returns the new socket descriptor
  2894. <code>cnt</code>. The global variable <code>*Adr</code> is set to the IP address
  2895. of the client. See also <code><a href="#listen">listen</a></code>,
  2896. <code><a href="#connect">connect</a></code> and <code><a
  2897. href="#*Adr">*Adr</a></code>.
  2898.  
  2899. <pre><code>
  2900. : (setq *Socket
  2901. (accept (port 6789)) ) # Accept connection at port 6789
  2902. -> 4
  2903. </code></pre>
  2904.  
  2905. <dt><a name="accu"><code>(accu 'var 'any 'num)</code></a>
  2906. <dd>Accumulates <code>num</code> into a sum, using the key <code>any</code> in
  2907. an association list stored in <code>var</code>. See also <code><a
  2908. href="#assoc">assoc</a></code>.
  2909.  
  2910. <pre><code>
  2911. : (off Sum)
  2912. -> NIL
  2913. : (accu 'Sum 'a 1)
  2914. -> (a . 1)
  2915. : (accu 'Sum 'a 5)
  2916. -> 6
  2917. : (accu 'Sum 22 100)
  2918. -> (22 . 100)
  2919. : Sum
  2920. -> ((22 . 100) (a . 6))
  2921. </code></pre>
  2922.  
  2923. <dt><a name="acquire"><code>(acquire 'sym) -> flg</code></a>
  2924. <dd>Tries to acquire the mutex represented by the file <code>sym</code>, by
  2925. obtaining an exclusive lock on that file with <code><a
  2926. href="#ctl">ctl</a></code>, and then trying to write the PID of the
  2927. current process into that file. It fails if the file already holds the PID of
  2928. some other existing process. See also <code><a
  2929. href="#release">release</a></code>, <code><a
  2930. href="#*Pid">*Pid</a></code> and <code><a
  2931. href="#rc">rc</a></code>.
  2932.  
  2933. <pre><code>
  2934. : (acquire "sema1")
  2935. -> 28255
  2936. </code></pre>
  2937.  
  2938. <dt><a name="alarm"><code>(alarm 'cnt . prg) -> cnt</code></a>
  2939. <dd>Sets an alarm timer scheduling <code>prg</code> to be executed after
  2940. <code>cnt</code> seconds, and returns the number of seconds remaining until any
  2941. previously scheduled alarm was due to be delivered. Calling <code>(alarm
  2942. 0)</code> will cancel an alarm. See also <code><a
  2943. href="#abort">abort</a></code>, <code><a
  2944. href="#sigio">sigio</a></code>, <code><a
  2945. href="#*Hup">*Hup</a></code> and <code><a
  2946. href="#*Sig1">*Sig[12]</a></code>.
  2947.  
  2948. <pre><code>
  2949. : (prinl (tim$ (time) T)) (alarm 10 (prinl (tim$ (time) T)))
  2950. 16:36:14
  2951. -> 0
  2952. : 16:36:24
  2953.  
  2954. : (alarm 10 (bye 0))
  2955. -> 0
  2956. $
  2957. </code></pre>
  2958.  
  2959. <dt><a name="align"><code>(align 'cnt 'any) -> sym</code></a>
  2960. <dt><code>(align 'lst 'any ..) -> sym</code>
  2961. <dd>Returns a transient symbol with all <code>any</code> arguments <code><a
  2962. href="#pack">pack</a></code>ed in an aligned format. In the first form,
  2963. <code>any</code> will be left-aligned if <code>cnt</code> ist negative,
  2964. otherwise right-aligned. In the second form, all <code>any</code> arguments are
  2965. packed according to the numbers in <code>lst</code>. See also <code><a
  2966. href="#tab">tab</a></code>, <code><a
  2967. href="#center">center</a></code> and <code><a
  2968. href="#wrap">wrap</a></code>.
  2969.  
  2970. <pre><code>
  2971. : (align 4 "a")
  2972. -> " a"
  2973. : (align -4 12)
  2974. -> "12 "
  2975. : (align (4 4 4) "a" 12 "b")
  2976. -> " a 12 b"
  2977. </code></pre>
  2978.  
  2979. <dt><a name="all"><code>(all ['T | '0]) -> lst</code></a>
  2980. <dd>Returns a new list of all <a href="#internal">internal</a> symbols
  2981. in the system (if called without arguments, or with <code>NIL</code>). Otherwise
  2982. (if the argument is <code>T</code>), all current <a
  2983. href="#transient">transient</a> symbols are returned. Else all current
  2984. <a href="#external">external</a> symbols are returned.
  2985.  
  2986. <pre><code>
  2987. : (all) # All internal symbols
  2988. -> (inc> leaf nil inc! accept ...
  2989.  
  2990. # Find all symbols starting with an underscore character
  2991. : (filter '((X) (= "_" (car (chop X)))) (all))
  2992. -> (_put _nacs _oct _lintq _lst _map _iter _dbg2 _getLine _led ...
  2993. </code></pre>
  2994.  
  2995. <dt><a name="allow"><code>(allow 'sym ['flg]) -> sym</code></a>
  2996. <dd>Maintains an index structure of allowed access patterns in the global
  2997. variable <code><a href="#*Allow">*Allow</a></code>. If the value of
  2998. <code>*Allow</code> is non-<code>NIL</code>, <code>sym</code> is added to the
  2999. <code><a href="#idx">idx</a></code> tree in the CAR of
  3000. <code>*Allow</code> (if <code>flg</code> is <code>NIL</code>), or to the list of
  3001. prefix strings (if <code>flg</code> is non-<code>NIL</code>). See also <code><a
  3002. href="#allowed">allowed</a></code>.
  3003.  
  3004. <pre><code>
  3005. : *Allow
  3006. -> (("!start" ("!psh") "!stop" NIL "lib.css") "app/")
  3007. : (allow "!myFoo") # additionally allowed item
  3008. -> "!myFoo"
  3009. : (allow "myDir/" T) # additionally allowed prefix
  3010. -> "myDir/"
  3011. </code></pre>
  3012.  
  3013. <dt><a name="allowed"><code>(allowed lst [sym ..])</code></a>
  3014. <dd>Creates an index structure of allowed access patterns in the global variable
  3015. <code><a href="#*Allow">*Allow</a></code>. <code>lst</code> should
  3016. consist of prefix strings (to be checked at runtime with <code><a
  3017. href="#pre?">pre?</a></code>), and the <code>sym</code> arguments
  3018. should specify the initially allowed items. See also <code><a
  3019. href="#allow">allow</a></code>.
  3020.  
  3021. <pre><code>
  3022. : (allowed ("app/") # allowed prefixes
  3023. "!start" "!stop" "lib.css" "!psh" ) # allowed items
  3024. -> NIL
  3025. </code></pre>
  3026.  
  3027. <dt><a name="and"><code>(and 'any ..) -> any</code></a>
  3028. <dd>Logical AND. The expressions <code>any</code> are evaluated from left to
  3029. right. If <code>NIL</code> is encountered, <code>NIL</code> is returned
  3030. immediately. Else the result of the last expression is returned.
  3031.  
  3032. <pre><code>
  3033. : (and (= 3 3) (read))
  3034. abc # User input
  3035. -> abc
  3036. : (and (= 3 4) (read))
  3037. -> NIL
  3038. </code></pre>
  3039.  
  3040. <dt><a name="any"><code>(any 'sym) -> any</code></a>
  3041. <dd>Parses <code>any</code> from the name of <code>sym</code>. This is the
  3042. reverse operation of <code><a href="#sym">sym</a></code>. See also
  3043. <code><a href="#str">str</a></code>, <code>(any 'sym)</code> is
  3044. equivalent to <code>(car (str 'sym))</code>.
  3045.  
  3046. <pre><code>
  3047. : (any "(a b # Comment^Jc d)")
  3048. -> (a b c d)
  3049. : (any "\"A String\"")
  3050. -> "A String"
  3051. </code></pre>
  3052.  
  3053. <dt><a name="append"><code>(append 'lst ..) -> lst</code></a>
  3054. <dd>Appends all argument lists. See also <code><a
  3055. href="#conc">conc</a></code>, <code><a
  3056. href="#insert">insert</a></code>, <code><a
  3057. href="#delete">delete</a></code> and <code><a
  3058. href="#remove">remove</a></code>.
  3059.  
  3060. <pre><code>
  3061. : (append '(a b c) (1 2 3))
  3062. -> (a b c 1 2 3)
  3063. : (append (1) (2) (3) 4)
  3064. -> (1 2 3 . 4)
  3065. </code></pre>
  3066.  
  3067. <dt><a name="append/3"><code>append/3</code></a>
  3068. <dd><a href="#pilog">Pilog</a> predicate that succeeds if appending the
  3069. first two list arguments is equal to the third argument. See also <code><a
  3070. href="#append">append</a></code> and <code><a
  3071. href="#member/2">member/2</a></code>.
  3072.  
  3073. <pre><code>
  3074. : (? (append @X @Y (a b c)))
  3075. @X=NIL @Y=(a b c)
  3076. @X=(a) @Y=(b c)
  3077. @X=(a b) @Y=(c)
  3078. @X=(a b c) @Y=NIL
  3079. -> NIL
  3080. </code></pre>
  3081.  
  3082. <dt><a name="apply"><code>(apply 'fun 'lst ['any ..]) -> any</code></a>
  3083. <dd>Applies <code>fun</code> to <code>lst</code>. If additional <code>any</code>
  3084. arguments are given, they are applied as leading elements of <code>lst</code>.
  3085. <code>(apply 'fun 'lst 'any1 'any2)</code> is equivalent to <code>(apply 'fun
  3086. (cons 'any1 'any2 'lst))</code>.
  3087.  
  3088. <pre><code>
  3089. : (apply + (1 2 3))
  3090. -> 6
  3091. : (apply * (5 6) 3 4)
  3092. -> 360
  3093. : (apply '((X Y Z) (* X (+ Y Z))) (3 4 5))
  3094. -> 27
  3095. : (apply println (3 4) 1 2)
  3096. 1 2 3 4
  3097. -> 4
  3098. </code></pre>
  3099.  
  3100. <dt><a name="arg"><code>(arg ['cnt]) -> any</code></a>
  3101. <dd>Can only be used inside functions with a variable number of arguments (with
  3102. <code>@</code>). If <code>cnt</code> is not given, the value that was returned
  3103. from the last call to <code>next</code>) is returned. Otherwise, the
  3104. <code>cnt</code>'th remaining argument is returned. See also <code><a
  3105. href="#args">args</a></code>, <code><a
  3106. href="#next">next</a></code>, <code><a
  3107. href="#rest">rest</a></code> and <code><a
  3108. href="#pass">pass</a></code>.
  3109.  
  3110. <pre><code>
  3111. : (de foo @ (println (next) (arg))) # Print argument twice
  3112. -> foo
  3113. : (foo 123)
  3114. 123 123
  3115. -> 123
  3116. : (de foo @
  3117. (println (arg 1) (arg 2))
  3118. (println (next))
  3119. (println (arg 1) (arg 2)) )
  3120. -> foo
  3121. : (foo 'a 'b 'c)
  3122. a b
  3123. a
  3124. b c
  3125. -> c
  3126. </code></pre>
  3127.  
  3128. <dt><a name="args"><code>(args) -> flg</code></a>
  3129. <dd>Can only be used inside functions with a variable number of arguments (with
  3130. <code>@</code>). Returns <code>T</code> when there are more arguments to be
  3131. fetched from the internal list. See also <code><a
  3132. href="#next">next</a></code>, <code><a
  3133. href="#arg">arg</a></code>, <code><a
  3134. href="#rest">rest</a></code> and <code><a
  3135. href="#pass">pass</a></code>.
  3136.  
  3137. <pre><code>
  3138. : (de foo @ (println (args))) # Test for arguments
  3139. -> foo
  3140. : (foo) # No arguments
  3141. NIL
  3142. -> NIL
  3143. : (foo NIL) # One argument
  3144. T
  3145. -> T
  3146. : (foo 123) # One argument
  3147. T
  3148. -> T
  3149. </code></pre>
  3150.  
  3151. <dt><a name="argv"><code>(argv [var ..] [. sym]) -> lst|sym</code></a>
  3152. <dd>If called without arguments, <code>argv</code> returns a list of strings
  3153. containing all remaining command line arguments. Otherwise, the
  3154. <code>var/sym</code> arguments are subsequently bound to the command line
  3155. arguments. A hyphen "<code>-</code>" can be used to inhibit the automatic
  3156. <code>load</code>ing further arguments. See also <code><a
  3157. href="#cmd">cmd</a></code>, <a href="ref.html#invoc">Invocation</a> and
  3158. <code><a href="#opt">opt</a></code>.
  3159.  
  3160. <pre><code>
  3161. $ pil -"println 'OK" - abc 123 +
  3162. OK
  3163. : (argv)
  3164. -> ("abc" "123")
  3165. : (argv A B)
  3166. -> "123"
  3167. : A
  3168. -> "abc"
  3169. : B
  3170. -> "123"
  3171. : (argv . Lst)
  3172. -> ("abc" "123")
  3173. : Lst
  3174. -> ("abc" "123")
  3175. </code></pre>
  3176.  
  3177. <dt><a name="as"><code>(as 'any1 . any2) -> any2 | NIL</code></a>
  3178. <dd>Returns <code>any2</code> unevaluated when <code>any1</code> evaluates to
  3179. non-<code>NIL</code>. Otherwise <code>NIL</code> is returned. <code>(as Flg A B
  3180. C)</code> is equivalent to <code>(and Flg '(A B C))</code>. See also <code><a
  3181. href="#quote">quote</a></code>.
  3182.  
  3183. <pre><code>
  3184. : (as (= 3 3) A B C)
  3185. -> (A B C)
  3186. </code></pre>
  3187.  
  3188. <dt><a name="asoq"><code>(asoq 'any 'lst) -> lst</code></a>
  3189. <dd>Searches an association list. Returns the first element from
  3190. <code>lst</code> with <code>any</code> as its CAR, or <code>NIL</code> if no
  3191. match is found. <code><a href="#==">==</a></code> is used for
  3192. comparison (pointer equality). See also <code><a
  3193. href="#assoc">assoc</a></code>, <code><a
  3194. href="#push1q">push1q</a></code>, <code><a
  3195. href="#delq">delq</a></code>, <code><a
  3196. href="#memq">memq</a></code>, <code><a
  3197. href="#mmeq">mmeq</a></code> and <a href="ref.html#cmp">Comparing</a>.
  3198.  
  3199. <pre><code>
  3200. : (asoq 999 '((999 1 2 3) (b . 7) ("ok" "Hello")))
  3201. -> NIL
  3202. : (asoq 'b '((999 1 2 3) (b . 7) ("ok" "Hello")))
  3203. -> (b . 7)
  3204. </code></pre>
  3205.  
  3206. <dt><a name="assert"><code>(assert exe ..) -> prg | NIL</code></a>
  3207. <dd>When in debug mode (<code><a href="#*Dbg">*Dbg</a></code> is
  3208. non-<code>NIL</code>), <code>assert</code> returns a <code>prg</code> list which
  3209. tests all <code>exe</code> conditions, and issues an error via <code><a
  3210. href="#quit">quit</a></code> if one of the results evaluates to
  3211. <code>NIL</code>. Otherwise, <code>NIL</code> is returned. Used typically in
  3212. combination with the <code>~</code> tilde <code><a
  3213. href="#macro-io">read-macro</a></code> to insert the test code only when
  3214. in debug mode. See also <code><a href="#test">test</a></code>.
  3215.  
  3216. <pre><code>
  3217. # Start in debug mode
  3218. $ pil +
  3219. : (de foo (N)
  3220. ~(assert (>= 90 N 10))
  3221. (bar N) )
  3222. -> foo
  3223. : (pp 'foo) # Pretty-print 'foo'
  3224. (de foo (N)
  3225. (unless (>= 90 N 10) # Assertion code exists
  3226. (quit "'assert' failed" '(>= 90 N 10)) )
  3227. (bar N) )
  3228. -> foo
  3229. : (foo 7) # Try it
  3230. (>= 90 N 10) -- Assertion failed
  3231. ?
  3232.  
  3233. # Start in non-debug mode
  3234. $ pil
  3235. : (de foo (N)
  3236. ~(assert (>= 90 N 10))
  3237. (bar N) )
  3238. -> foo
  3239. : (pp 'foo) # Pretty-print 'foo'
  3240. (de foo (N)
  3241. (bar N) ) # Assertion code does not exist
  3242. -> foo
  3243. </code></pre>
  3244.  
  3245. <dt><a name="asserta"><code>(asserta 'lst) -> lst</code></a>
  3246. <dd>Inserts a new <a href="#pilog">Pilog</a> fact or rule before all
  3247. other rules. See also <code><a href="#be">be</a></code>, <code><a
  3248. href="#clause">clause</a></code>, <code><a
  3249. href="#assertz">assertz</a></code> and <code><a
  3250. href="#retract">retract</a></code>.
  3251.  
  3252. <pre><code>
  3253. : (be a (2)) # Define two facts
  3254. -> a
  3255. : (be a (3))
  3256. -> a
  3257.  
  3258. : (asserta '(a (1))) # Insert new fact in front
  3259. -> ((1))
  3260.  
  3261. : (? (a @N)) # Query
  3262. @N=1
  3263. @N=2
  3264. @N=3
  3265. -> NIL
  3266. </code></pre>
  3267.  
  3268. <dt><a name="asserta/1"><code>asserta/1</code></a>
  3269. <dd><a href="#pilog">Pilog</a> predicate that inserts a new fact or rule
  3270. before all other rules. See also <code><a
  3271. href="#asserta">asserta</a></code>, <code><a
  3272. href="#assertz/1">assertz/1</a></code> and <code><a
  3273. href="#retract/1">retract/1</a></code>.
  3274.  
  3275. <pre><code>
  3276. : (? (asserta (a (2))))
  3277. -> T
  3278. : (? (asserta (a (1))))
  3279. -> T
  3280. : (rules 'a)
  3281. 1 (be a (1))
  3282. 2 (be a (2))
  3283. -> a
  3284. </code></pre>
  3285.  
  3286. <dt><a name="assertz"><code>(assertz 'lst) -> lst</code></a>
  3287. <dd>Appends a new <a href="#pilog">Pilog</a> fact or rule behind all
  3288. other rules. See also <code><a href="#be">be</a></code>, <code><a
  3289. href="#clause">clause</a></code>, <code><a
  3290. href="#asserta">asserta</a></code> and <code><a
  3291. href="#retract">retract</a></code>.
  3292.  
  3293. <pre><code>
  3294. : (be a (1)) # Define two facts
  3295. -> a
  3296. : (be a (2))
  3297. -> a
  3298.  
  3299. : (assertz '(a (3))) # Append new fact at the end
  3300. -> ((3))
  3301.  
  3302. : (? (a @N)) # Query
  3303. @N=1
  3304. @N=2
  3305. @N=3
  3306. -> NIL
  3307. </code></pre>
  3308.  
  3309. <dt><a name="assertz/1"><code>assertz/1</code></a>
  3310. <dd><a href="#pilog">Pilog</a> predicate that appends a new fact or rule
  3311. behind all other rules. See also <code><a
  3312. href="#assertz">assertz</a></code>, <code><a
  3313. href="#asserta/1">asserta/1</a></code> and <code><a
  3314. href="#retract/1">retract/1</a></code>.
  3315.  
  3316. <pre><code>
  3317. : (? (assertz (a (1))))
  3318. -> T
  3319. : (? (assertz (a (2))))
  3320. -> T
  3321. : (rules 'a)
  3322. 1 (be a (1))
  3323. 2 (be a (2))
  3324. -> a
  3325. </code></pre>
  3326.  
  3327. <dt><a name="assoc"><code>(assoc 'any 'lst) -> lst</code></a>
  3328. <dd>Searches an association list. Returns the first element from
  3329. <code>lst</code> with its CAR equal to <code>any</code>, or <code>NIL</code> if
  3330. no match is found. See also <code><a href="#asoq">asoq</a></code> and
  3331. <code><a href="#rassoc">rassoc</a></code>.
  3332.  
  3333. <pre><code>
  3334. : (assoc "b" '((999 1 2 3) ("b" . 7) ("ok" "Hello")))
  3335. -> ("b" . 7)
  3336. : (assoc 999 '((999 1 2 3) ("b" . 7) ("ok" "Hello")))
  3337. -> (999 1 2 3)
  3338. : (assoc 'u '((999 1 2 3) ("b" . 7) ("ok" "Hello")))
  3339. -> NIL
  3340. </code></pre>
  3341.  
  3342. <dt><a name="at"><code>(at '(cnt1 . cnt2|NIL) . prg) -> any</code></a>
  3343. <dd>Increments <code>cnt1</code> (destructively), and returns <code>NIL</code>
  3344. when it is less than <code>cnt2</code>. Both <code>cnt1</code> and
  3345. <code>cnt2</code> should be positive. Otherwise, <code>cnt1</code> is reset to
  3346. zero and <code>prg</code> is executed. Returns the result of <code>prg</code>.
  3347. If <code>cnt2</code> is <code>NIL</code>, nothing is done, and <code>NIL</code>
  3348. is returned immediately.
  3349.  
  3350. <pre><code>
  3351. : (do 11 (prin ".") (at (0 . 3) (prin "!")))
  3352. ...!...!...!..-> NIL
  3353. </code></pre>
  3354.  
  3355. <dt><a name="atom"><code>(atom 'any) -> flg</code></a> <dd>Returns
  3356. <code>T</code> when the argument <code>any</code> is an atom (a number or a
  3357. symbol). See also <code><a href="#num?">num?</a></code>, <code><a
  3358. href="#sym?">sym?</a></code> and <code><a
  3359. href="#pair">pair</a></code>.
  3360.  
  3361. <pre><code>
  3362. : (atom 123)
  3363. -> T
  3364. : (atom 'a)
  3365. -> T
  3366. : (atom NIL)
  3367. -> T
  3368. : (atom (123))
  3369. -> NIL
  3370. </code></pre>
  3371.  
  3372. <dt><a name="aux"><code>(aux 'sym 'cls ['hook] 'any ..) -> sym</code></a>
  3373. <dd>Returns a database object of class <code>cls</code>, where the value for
  3374. <code>sym</code> corresponds to <code>any</code> and the following arguments.
  3375. <code>sym</code>, <code>cls</code> and <code>hook</code> should specify a
  3376. <code><a href="#tree">tree</a></code> for <code>cls</code> or one of
  3377. its superclasses, for a relation with auxiliary keys. For multi-key accesses,
  3378. <code>aux</code> is similar to - but faster than - <code>db</code>, because it
  3379. can use a single tree access. See also <code><a
  3380. href="#db">db</a></code>, <code><a
  3381. href="#collect">collect</a></code>, <code><a
  3382. href="#fetch">fetch</a></code>, <code><a
  3383. href="#init">init</a></code>, <code><a
  3384. href="#step">step</a></code> and <code><a
  3385. href="#+Aux">+Aux</a></code>.
  3386.  
  3387. <pre><code>
  3388. (class +PS +Entity)
  3389. (rel par (+Dep +Joint) (sup) ps (+Part)) # Part
  3390. (rel sup (+Aux +Ref +Link) (par) NIL (+Supp)) # Supplier
  3391. ...
  3392. (aux 'sup '+PS # Access PS object
  3393. (db 'nr '+Supp 1234)
  3394. (db 'nr '+Part 5678) )
  3395. </code></pre>
  3396.  
  3397. </dl>
  3398.  
  3399. <h1><a name="B">B</a></h1>
  3400.  
  3401. <dl>
  3402.  
  3403. <dt><a name="*Blob"><code>*Blob</code></a>
  3404. <dd>A global variable holding the pathname of the database blob directory. See
  3405. also <code><a href="#blob">blob</a></code>.
  3406.  
  3407. <pre><code>
  3408. : *Blob
  3409. -> "blob/app/"
  3410. </code></pre>
  3411.  
  3412. <dt><a name="*Bye"><code>*Bye</code></a>
  3413. <dd>A global variable holding a (possibly empty) <code>prg</code> body, to be
  3414. executed just before the termination of the PicoLisp interpreter. See also
  3415. <code><a href="#bye">bye</a></code> and <code><a
  3416. href="#tmp">tmp</a></code>.
  3417.  
  3418. <pre><code>
  3419. : (push1 '*Bye '(call 'rm "myfile.tmp")) # Remove a temporary file
  3420. -> (call 'rm "myfile.tmp")
  3421. </code></pre>
  3422.  
  3423. <dt><a name="+Bag"><code>+Bag</code></a>
  3424. <dd>Class for a list of arbitrary relations, a subclass of <code><a
  3425. href="#+relation">+relation</a></code>. Objects of that class maintain
  3426. a list of heterogeneous relations. Typically used in combination with the
  3427. <code><a href="#+List">+List</a></code> prefix class, to maintain small
  3428. two-dimensional tables within objects. See also <a
  3429. href="#dbase">Database</a>.
  3430.  
  3431. <pre><code>
  3432. (rel pos (+List +Bag) # Positions
  3433. ((+Ref +Link) NIL (+Item)) # Item
  3434. ((+Number) 2) # Price
  3435. ((+Number)) # Quantity
  3436. ((+String)) # Memo text
  3437. ((+Number) 2) ) # Total amount
  3438. </code></pre>
  3439.  
  3440. <dt><a name="+Blob"><code>+Blob</code></a>
  3441. <dd>Class for blob relations, a subclass of <code><a
  3442. href="#+relation">+relation</a></code>. Objects of that class maintain
  3443. blobs, as stubs in database objects pointing to actual files for arbitrary
  3444. (often binary) data. The files themselves reside below the path specified by the
  3445. <code><a href="#*Blob">*Blob</a></code> variable. See also <a
  3446. href="#dbase">Database</a>.
  3447.  
  3448. <pre><code>
  3449. (rel jpg (+Blob)) # Picture
  3450. </code></pre>
  3451.  
  3452. <dt><a name="+Bool">+Bool<code></code></a>
  3453. <dd>Class for boolean relations, a subclass of <code><a
  3454. href="#+relation">+relation</a></code>. Objects of that class expect
  3455. either <code>T</code> or <code>NIL</code> as value (though, as always, only
  3456. non-<code>NIL</code> will be physically stored in objects). See also <a
  3457. href="#dbase">Database</a>.
  3458.  
  3459. <pre><code>
  3460. (rel ok (+Ref +Bool)) # Indexed flag
  3461. </code></pre>
  3462.  
  3463. <dt><a name="balance"><code>(balance 'var 'lst ['flg])</code></a>
  3464. <dd>Builds a balanced binary <code><a href="#idx">idx</a></code> tree
  3465. in <code>var</code>, from the sorted list in <code>lst</code>. Normally (if
  3466. random or, in the worst case, ordered data) are inserted with <code>idx</code>,
  3467. the tree will not be balanced. But if <code>lst</code> is properly sorted, its
  3468. contents will be inserted in an optimally balanced way. If <code>flg</code> is
  3469. non-<code>NIL</code>, the index tree will be augmented instead of being
  3470. overwritten. See also <code><a href="#cmp">Comparing</a></code> and
  3471. <code><a href="#sort">sort</a></code>.
  3472.  
  3473. <pre><code>
  3474. # Normal idx insert
  3475. : (off I)
  3476. -> NIL
  3477. : (for X (1 4 2 5 3 6 7 9 8) (idx 'I X T))
  3478. -> NIL
  3479. : (depth I)
  3480. -> (7 . 4)
  3481.  
  3482. # Balanced insert
  3483. : (balance 'I (sort (1 4 2 5 3 6 7 9 8)))
  3484. -> NIL
  3485. : (depth I)
  3486. -> 4
  3487.  
  3488. # Augment
  3489. : (balance 'I (sort (10 40 20 50 30 60 70 90 80)) T)
  3490. -> NIL
  3491. : (idx 'I)
  3492. -> (1 2 3 4 5 6 7 8 9 10 20 30 40 50 60 70 80 90)
  3493. </code></pre>
  3494.  
  3495. <dt><a name="basename"><code>(basename 'any) -> sym</code></a>
  3496. <dd>Returns the filename part of a path name <code>any</code>. See also <code><a
  3497. href="#dirname">dirname</a></code> and <code><a
  3498. href="#path">path</a></code>.
  3499.  
  3500. <pre><code>
  3501. : (basename "a/b/c/d")
  3502. -> "d"
  3503. </code></pre>
  3504.  
  3505. <dt><a name="be"><code>(be sym . any) -> sym</code></a>
  3506. <dd>Declares a <a href="#pilog">Pilog</a> fact or rule for the
  3507. <code>sym</code> argument, by concatenating the <code>any</code> argument to the
  3508. <code>T</code> property of <code>sym</code>. Groups of declarations are
  3509. collected for a given <code>sym</code>. When <code>sym</code> changes, i.e. when
  3510. it differs from the one in the previous declaration, the current group is
  3511. considered to be complete and a new group is started. Later <code>be</code>
  3512. declarations for a previously completed symbol will reset its rules, to allow
  3513. repeated re<code><a href="#load">load</a></code>ing of source files.
  3514. See also <code><a href="#clause">clause</a></code>, <code><a
  3515. href="#asserta">asserta</a></code>, <code><a
  3516. href="#assertz">assertz</a></code>, <code><a
  3517. href="#retract">retract</a></code>, <code><a
  3518. href="#rules">rules</a></code>, <code><a
  3519. href="#goal">goal</a></code> and <code><a
  3520. href="#prove">prove</a></code>.
  3521.  
  3522. <pre><code>
  3523. : (be likes (John Mary))
  3524. -> likes
  3525. : (be likes (John @X) (likes @X wine) (likes @X food))
  3526. -> likes
  3527.  
  3528. : (get 'likes T)
  3529. -> (((John Mary)) ((John @X) (likes @X wine) (likes @X food)))
  3530.  
  3531. : (rules 'likes)
  3532. 1 (be likes (John Mary))
  3533. 2 (be likes (John @X) (likes @X wine) (likes @X food))
  3534. -> likes
  3535.  
  3536. : (? (likes John @X))
  3537. @X=Mary
  3538. -> NIL
  3539. </code></pre>
  3540.  
  3541. <dt><a name="beep"><code>(beep) -> any</code></a>
  3542. <dd>Send the bell character to the console. See also <code><a
  3543. href="#space">space</a></code>, <code><a
  3544. href="#prin">prin</a></code> and <code><a
  3545. href="#char">char</a></code>.
  3546.  
  3547. <pre><code>
  3548. : (beep)
  3549. -> "^G"
  3550. </code></pre>
  3551.  
  3552. <dt><a name="bench"><code>(bench . prg) -> any</code></a>
  3553. <dd>(Debug mode only) Benchmarks <code>prg</code>, by printing the time it took
  3554. to execute, and returns the result. See also <code><a
  3555. href="#usec">usec</a></code>.
  3556.  
  3557. <pre><code>
  3558. : (bench (wait 2000))
  3559. 1.996 sec
  3560. -> NIL
  3561. </code></pre>
  3562.  
  3563. <dt><a name="bin"><code>(bin 'num ['num]) -> sym</code></a>
  3564. <dt><code>(bin 'sym) -> num</code>
  3565. <dd>Converts a number <code>num</code> to a binary string, or a binary string
  3566. <code>sym</code> to a number. In the first case, if the second argument is
  3567. given, the result is separated by spaces into groups of such many digits. See
  3568. also <code><a href="#oct">oct</a></code>, <code><a
  3569. href="#hex">hex</a></code>, <code><a
  3570. href="#fmt64">fmt64</a></code>, <code><a
  3571. href="#hax">hax</a></code> and <code><a
  3572. href="#format">format</a></code>.
  3573.  
  3574. <pre><code>
  3575. : (bin 73)
  3576. -> "1001001"
  3577. : (bin "1001001")
  3578. -> 73
  3579. : (bin 1234567 4)
  3580. -> "1 0010 1101 0110 1000 0111"
  3581. </code></pre>
  3582.  
  3583. <dt><a name="bind"><code>(bind 'sym|lst . prg) -> any</code></a>
  3584. <dd>Binds value(s) to symbol(s). The first argument must evaluate to a symbol,
  3585. or a list of symbols or symbol-value pairs. The values of these symbols are
  3586. saved (and the symbols bound to the values in the case of pairs),
  3587. <code>prg</code> is executed, then the symbols are restored to their original
  3588. values. During execution of <code>prg</code>, the values of the symbols can be
  3589. temporarily modified. The return value is the result of <code>prg</code>. See
  3590. also <code><a href="#let">let</a></code>, <code><a
  3591. href="#job">job</a></code> and <code><a
  3592. href="#use">use</a></code>.
  3593.  
  3594. <pre><code>
  3595. : (setq X 123) # X is 123
  3596. -> 123
  3597. : (bind 'X (setq X "Hello") (println X)) # Set X to "Hello", print it
  3598. "Hello"
  3599. -> "Hello"
  3600. : (bind '((X . 3) (Y . 4)) (println X Y) (* X Y))
  3601. 3 4
  3602. -> 12
  3603. : X
  3604. -> 123 # X is restored to 123
  3605. </code></pre>
  3606.  
  3607. <dt><a name="bit?"><code>(bit? 'num ..) -> num | NIL</code></a>
  3608. <dd>Returns the first <code>num</code> argument when all bits which are 1 in the
  3609. first argument are also 1 in all following arguments, otherwise
  3610. <code>NIL</code>. When one of those arguments evaluates to <code>NIL</code>, it
  3611. is returned immediately. See also <code><a href="#&">&</a></code>,
  3612. <code><a href="#|">|</a></code> and <code><a
  3613. href="#x|">x|</a></code>.
  3614.  
  3615. <pre><code>
  3616. : (bit? 7 15 255)
  3617. -> 7
  3618. : (bit? 1 3)
  3619. -> 1
  3620. : (bit? 1 2)
  3621. -> NIL
  3622. </code></pre>
  3623.  
  3624. <dt><a name="blob"><code>(blob 'obj 'sym) -> sym</code></a>
  3625. <dd>Returns the blob file name for <code>var</code> in <code>obj</code>. See
  3626. also <code><a href="#*Blob">*Blob</a></code>, <code><a
  3627. href="#blob!">blob!</a></code> and <code><a
  3628. href="#pack">pack</a></code>.
  3629.  
  3630. <pre><code>
  3631. : (show (db 'nr '+Item 1))
  3632. {3-1} (+Item)
  3633. jpg
  3634. pr 29900
  3635. inv 100
  3636. sup {2-1}
  3637. nm "Main Part"
  3638. nr 1
  3639. -> {3-1}
  3640. : (blob '{3-1} 'jpg)
  3641. -> "blob/app/3/-/1.jpg"
  3642. </code></pre>
  3643.  
  3644. <dt><a name="blob!"><code>(blob! 'obj 'sym 'file)</code></a>
  3645. <dd>Stores the contents of <code>file</code> in a <code><a
  3646. href="#blob">blob</a></code>. See also <code><a
  3647. href="#entityMesssages">put!></a></code>.
  3648.  
  3649. <pre><code>
  3650. (blob! *ID 'jpg "picture.jpg")
  3651. </code></pre>
  3652.  
  3653. <dt><a name="bool"><code>(bool 'any) -> flg</code></a>
  3654. <dd>Returns <code>T</code> when the argument <code>any</code> is
  3655. non-<code>NIL</code>. This function is only needed when <code>T</code> is
  3656. strictly required for a "true" condition (Usually, any non-<code>NIL</code>
  3657. value is considered to be "true"). See also <code><a
  3658. href="#flg?">flg?</a></code>.
  3659.  
  3660. <pre><code>
  3661. : (and 3 4)
  3662. -> 4
  3663. : (bool (and 3 4))
  3664. -> T
  3665. </code></pre>
  3666.  
  3667. <dt><a name="bool/3"><code>bool/3</code></a>
  3668. <dd><a href="#pilog">Pilog</a> predicate that succeeds if the first
  3669. argument has the same truth value as the result of applying the <code><a
  3670. href="#get">get</a></code> algorithm to the following arguments.
  3671. Typically used as filter predicate in <code><a
  3672. href="#select/3">select/3</a></code> database queries. See also
  3673. <code><a href="#bool">bool</a></code>, <code><a
  3674. href="#isa/2">isa/2</a></code>, <code><a
  3675. href="#same/3">same/3</a></code>, <code><a
  3676. href="#range/3">range/3</a></code>, <code><a
  3677. href="#head/3">head/3</a></code>, <code><a
  3678. href="#fold/3">fold/3</a></code>, <code><a
  3679. href="#part/3">part/3</a></code> and <code><a
  3680. href="#tolr/3">tolr/3</a></code>.
  3681.  
  3682. <pre><code>
  3683. : (? @OK NIL # Find orders where the 'ok' flag is not set
  3684. (db nr +Ord @Ord)
  3685. (bool @OK @Ord ok) )
  3686. @OK=NIL @Ord={3-7}
  3687. -> NIL
  3688. </code></pre>
  3689.  
  3690. <dt><a name="box"><code>(box 'any) -> sym</code></a>
  3691. <dd>Creates and returns a new anonymous symbol. The initial value is set to the
  3692. <code>any</code> argument. See also <code><a href="#new">new</a></code>
  3693. and <code><a href="#box?">box?</a></code>.
  3694.  
  3695. <pre><code>
  3696. : (show (box '(A B C)))
  3697. $134425627 (A B C)
  3698. -> $134425627
  3699. </code></pre>
  3700.  
  3701. <dt><a name="box?"><code>(box? 'any) -> sym | NIL</code></a>
  3702. <dd>Returns the argument <code>any</code> when it is an anonymous symbol,
  3703. otherwise <code>NIL</code>. See also <code><a
  3704. href="#box">box</a></code>, <code><a
  3705. href="#str?">str?</a></code> and <code><a
  3706. href="#ext?">ext?</a></code>.
  3707.  
  3708. <pre><code>
  3709. : (box? (new))
  3710. -> $134563468
  3711. : (box? 123)
  3712. -> NIL
  3713. : (box? 'a)
  3714. -> NIL
  3715. : (box? NIL)
  3716. -> NIL
  3717. </code></pre>
  3718.  
  3719. <dt><a name="bt"><code>(bt ['flg]) -> flg</code></a>
  3720. <dd>(Debug mode 64-bit version only) Formatted stack backtrace printing (see
  3721. <code><a href="#trail">trail</a></code>) for the current point of
  3722. program execution. For each bind frame, the function call (reduced with <code><a
  3723. href="#less">less</a></code>) is <code><a
  3724. href="#pretty">pretty</a></code>-printed, followed by indented
  3725. variable-value-pairs. If <code>flg</code> is <code>NIL</code>, <code>bt</code>
  3726. then waits for console input, and terminates when a non-empty line is entered
  3727. (like <code><a href="#more">more</a></code>). See also <code><a
  3728. href="#up">up</a></code> and <code><a
  3729. href="#env">env</a></code>.
  3730.  
  3731. <pre><code>
  3732. : (de f (A B)
  3733. (let F 7
  3734. (g (inc A) (dec B)) ) )
  3735. -> f
  3736. : (de g (C D)
  3737. (let G 8
  3738. (/ C D) ) )
  3739. -> g
  3740.  
  3741. : (f 2 1)
  3742. !? (/ C D)
  3743. Div/0
  3744. ? (bt)
  3745. (g (inc A) (dec B))
  3746. C 3
  3747. D 0
  3748. G 8
  3749. (f 2 1)
  3750. A 2
  3751. B 1
  3752. F 7
  3753. -> NIL
  3754. </code></pre>
  3755.  
  3756. <dt><a name="by"><code>(by 'fun1 'fun2 'lst ..) -> lst</code></a>
  3757. <dd>Applies <code>fun1</code> to each element of <code>lst</code>. When
  3758. additional <code>lst</code> arguments are given, their elements are also passed
  3759. to <code>fun1</code>. Each result of <code>fun1</code> is CONSed with its
  3760. corresponding argument form the original <code>lst</code>, and collected into a
  3761. list which is passed to <code>fun2</code>. For the list returned from
  3762. <code>fun2</code>, the CAR elements returned by <code>fun1</code> are
  3763. (destructively) removed from each element ("decorate-apply-undecorate" idiom).
  3764.  
  3765. <pre><code>
  3766. : (let (A 1 B 2 C 3) (by val sort '(C A B)))
  3767. -> (A B C)
  3768. : (by '((N) (bit? 1 N)) group (3 11 6 2 9 5 4 10 12 7 8 1))
  3769. -> ((3 11 9 5 7 1) (6 2 4 10 12 8))
  3770. </code></pre>
  3771.  
  3772. <dt><a name="bye"><code>(bye 'cnt|NIL)</code></a>
  3773. <dd>Executes all pending <code><a href="#finally">finally</a></code>
  3774. expressions, closes all open files, executes the <code>VAL</code> of the global
  3775. variable <code><a href="#*Bye">*Bye</a></code> (should be a
  3776. <code>prg</code>), flushes standard output, and then exits the PicoLisp
  3777. interpreter. The process return value is <code>cnt</code>, or 0 if the argument
  3778. is missing or <code>NIL</code>.
  3779.  
  3780. <pre><code>
  3781. : (setq *Bye '((println 'OK) (println 'bye)))
  3782. -> ((println 'OK) (println 'bye))
  3783. : (bye)
  3784. OK
  3785. bye
  3786. $
  3787. </code></pre>
  3788.  
  3789. <dt><a name="bytes"><code>(bytes 'any) -> cnt</code></a>
  3790. <dd>Returns the number of bytes <code>any</code> would occupy in encoded binary
  3791. format (as generated by <code><a href="#pr">pr</a></code>). See also
  3792. <code><a href="#size">size</a></code> and <code><a
  3793. href="#length">length</a></code>.
  3794.  
  3795. <pre><code>
  3796. : (bytes "abc")
  3797. -> 4
  3798. : (bytes "äbc")
  3799. -> 5
  3800. : (bytes 127)
  3801. -> 2
  3802. : (bytes 128)
  3803. -> 3
  3804. : (bytes (101 (102) 103))
  3805. -> 10
  3806. : (bytes (101 102 103 .))
  3807. -> 9
  3808. </code></pre>
  3809.  
  3810. </dl>
  3811.  
  3812. <h1><a name="C">C</a></h1>
  3813.  
  3814. <dl>
  3815.  
  3816. <dt><a name="*CPU"><code>*CPU</code></a>
  3817. <dd>(64-bit version only) A global variable holding the target CPU
  3818. (architecture). Possible values include <code>"x86-64"</code>,
  3819. <code>"ppc64"</code>, <code>"emu"</code> or <code>"JVM"</code>. See also
  3820. <code><a href="#*OS">*OS</a></code> and <code><a
  3821. href="#version">version</a></code>.
  3822.  
  3823. <pre><code>
  3824. : *CPU
  3825. -> "x86-64"
  3826. </code></pre>
  3827.  
  3828. <dt><a name="*Class"><code>*Class</code></a>
  3829. <dd>A global variable holding the current class. See also <a
  3830. href="#oop">OO Concepts</a>, <code><a
  3831. href="#class">class</a></code>, <code><a
  3832. href="#extend">extend</a></code>, <code><a
  3833. href="#dm">dm</a></code> and <code><a
  3834. href="#var">var</a></code> and <code><a
  3835. href="#rel">rel</a></code>.
  3836.  
  3837. <pre><code>
  3838. : (class +Test)
  3839. -> +Test
  3840. : *Class
  3841. -> +Test
  3842. </code></pre>
  3843.  
  3844. <dt><a name="cache"><code>(cache 'var 'any . prg) -> any</code></a>
  3845. <dd>Speeds up some calculations by maintaining a tree of previously calculated
  3846. results in an <code><a href="#idx">idx</a></code> structure
  3847. ("memoization") in <code>var</code>. A <code><a
  3848. href="#hash">hash</a></code> of the argument <code>any</code> is used
  3849. internally to build the index key.
  3850.  
  3851. <pre><code>
  3852. : (de fibonacci (N)
  3853. (cache '(NIL) N
  3854. (if (>= 2 N)
  3855. 1
  3856. (+ (fibonacci (dec N)) (fibonacci (- N 2))) ) ) )
  3857. -> fibonacci
  3858.  
  3859. : (fibonacci 22)
  3860. -> 17711
  3861.  
  3862. : (fibonacci 10000)
  3863. -> 3364476487643178326662161200510754331030 ... # (2090 digits)
  3864. </code></pre>
  3865.  
  3866. <dt><a name="call"><code>(call 'any ..) -> flg</code></a>
  3867. <dd>Calls an external system command. The <code>any</code> arguments specify the
  3868. command and its arguments. Returns <code>T</code> if the command was executed
  3869. successfully. The (system dependent) exit status code of the child process is
  3870. stored in the global variable <code><a href="#@@">@@</a></code>. See
  3871. also <code><a href="#exec">exec</a></code>.
  3872.  
  3873. <pre><code>
  3874. : (when (call 'test "-r" "file.l") # Test if file exists and is readable
  3875. (load "file.l") # Load it
  3876. (call 'rm "file.l") ) # Remove it
  3877.  
  3878. : (cons (call "sh" "-c" "kill -SEGV $$") @@ (hex @@))
  3879. -> (NIL 11 . "B")
  3880. </code></pre>
  3881.  
  3882. <dt><a name="call/1"><code>call/1</code></a>
  3883. <dd><a href="#pilog">Pilog</a> predicate that succeeds if the argument
  3884. term can be proven.
  3885.  
  3886. <pre><code>
  3887. : (be mapcar (@ NIL NIL))
  3888. -> mapcar
  3889. : (be mapcar (@P (@X . @L) (@Y . @M))
  3890. (call @P @X @Y) # Call the given predicate
  3891. (mapcar @P @L @M) )
  3892. -> mapcar
  3893. : (? (mapcar permute ((a b c) (d e f)) @X))
  3894. @X=((a b c) (d e f))
  3895. @X=((a b c) (d f e))
  3896. @X=((a b c) (e d f))
  3897. ...
  3898. @X=((a c b) (d e f))
  3899. @X=((a c b) (d f e))
  3900. @X=((a c b) (e d f))
  3901. ...
  3902. </code></pre>
  3903.  
  3904. <dt><a name="can"><code>(can 'msg) -> lst</code></a>
  3905. <dd>(Debug mode only) Returns a list of all classes that accept the message
  3906. <code>msg</code>. See also <a href="#oop">OO Concepts</a>, <code><a
  3907. href="#class">class</a></code>, <code><a
  3908. href="#has">has</a></code>, <code><a
  3909. href="#dep">dep</a></code>, <code><a
  3910. href="#what">what</a></code> and <code><a
  3911. href="#who">who</a></code>.
  3912.  
  3913. <pre><code>
  3914. : (can 'zap>)
  3915. -> ((zap> . +relation) (zap> . +Blob) (zap> . +Entity))
  3916. : (more @ pp)
  3917. (dm (zap> . +relation) (Obj Val))
  3918.  
  3919. (dm (zap> . +Blob) (Obj Val)
  3920. (and
  3921. Val
  3922. (call 'rm "-f" (blob Obj (: var))) ) )
  3923.  
  3924. (dm (zap> . +Entity) NIL
  3925. (for X (getl This)
  3926. (let V (or (atom X) (pop 'X))
  3927. (and (meta This X) (zap> @ This V)) ) ) )
  3928.  
  3929. -> NIL
  3930. </code></pre>
  3931.  
  3932. <dt><a name="car"><code>(car 'var) -> any</code></a>
  3933. <dd>List access: Returns the value of <code>var</code> if it is a symbol, or the
  3934. first element if it is a list. See also <code><a
  3935. href="#cdr">cdr</a></code> and <code><a
  3936. href="#cXr">c..r</a></code>.
  3937.  
  3938. <pre><code>
  3939. : (car (1 2 3 4 5 6))
  3940. -> 1
  3941. </code></pre>
  3942.  
  3943. <dt>
  3944. <a name="caar"></a>
  3945. <a name="cadr"></a>
  3946. <a name="cdar"></a>
  3947. <a name="cddr"></a>
  3948. <a name="caaar"></a>
  3949. <a name="caadr"></a>
  3950. <a name="cadar"></a>
  3951. <a name="caddr"></a>
  3952. <a name="cdaar"></a>
  3953. <a name="cdadr"></a>
  3954. <a name="cddar"></a>
  3955. <a name="cdddr"></a>
  3956. <a name="caaaar"></a>
  3957. <a name="caaadr"></a>
  3958. <a name="caadar"></a>
  3959. <a name="caaddr"></a>
  3960. <a name="cadaar"></a>
  3961. <a name="cadadr"></a>
  3962. <a name="caddar"></a>
  3963. <a name="cadddr"></a>
  3964. <a name="cdaaar"></a>
  3965. <a name="cdaadr"></a>
  3966. <a name="cdadar"></a>
  3967. <a name="cdaddr"></a>
  3968. <a name="cddaar"></a>
  3969. <a name="cddadr"></a>
  3970. <a name="cdddar"></a>
  3971. <a name="cddddr"></a>
  3972. <a name="cXr"><code>(c[ad]*ar 'var) -> any</code></a>
  3973. <dt><code>(c[ad]*dr 'lst) -> any</code>
  3974. <dd>List access shortcuts. Combinations of the <code><a
  3975. href="#car">car</a></code> and <code><a
  3976. href="#cdr">cdr</a></code> functions, with up to four letters 'a' and
  3977. 'd'.
  3978.  
  3979. <pre><code>
  3980. : (cdar '((1 . 2) . 3))
  3981. -> 2
  3982. </code></pre>
  3983.  
  3984. <dt><a name="case"><code>(case 'any (any1 . prg1) (any2 . prg2) ..) -> any</code></a>
  3985. <dd>Multi-way branch: <code>any</code> is evaluated and compared to the CAR
  3986. elements <code>anyN</code> of each clause. If one of them is a list,
  3987. <code>any</code> is in turn compared to all elements of that list.
  3988. <code>T</code> is a catch-all for any value. If a comparison succeeds,
  3989. <code>prgN</code> is executed, and the result returned. Otherwise
  3990. <code>NIL</code> is returned. See also <code><a
  3991. href="#casq">casq</a></code> and <code><a
  3992. href="#state">state</a></code> .
  3993.  
  3994. <pre><code>
  3995. : (case (char 66) ("A" (+ 1 2 3)) (("B" "C") "Bambi") ("D" (* 1 2 3)))
  3996. -> "Bambi"
  3997. : (case 'b (a 1) ("b" 2) (b 3) (c 4))
  3998. -> 2
  3999. </code></pre>
  4000.  
  4001. <dt><a name="casq"><code>(casq 'any (any1 . prg1) (any2 . prg2) ..) -> any</code></a>
  4002. <dd>Multi-way branch: <code>any</code> is evaluated and compared to the CAR
  4003. elements <code>anyN</code> of each clause. <code><a
  4004. href="#==">==</a></code> is used for comparison (pointer equality). If
  4005. one of them is a list, <code>any</code> is in turn compared to all elements of
  4006. that list. <code>T</code> is a catch-all for any value. If a comparison
  4007. succeeds, <code>prgN</code> is executed, and the result returned. Otherwise
  4008. <code>NIL</code> is returned. See also <code><a
  4009. href="#case">case</a></code> and <code><a
  4010. href="#state">state</a></code>.
  4011.  
  4012. <pre><code>
  4013. : (casq 'b (a 1) ("b" 2) (b 3) (c 4))
  4014. -> 3
  4015. : (casq 'b (a 1) ("b" 2) ((a b c) 3) (c 4))
  4016. -> 3
  4017. </code></pre>
  4018.  
  4019. <dt><a name="catch"><code>(catch 'any . prg) -> any</code></a>
  4020. <dd>Sets up the environment for a non-local jump which may be caused by <code><a
  4021. href="#throw">throw</a></code> or by a runtime error. If
  4022. <code>any</code> is an atom, it is used by <code>throw</code> as a jump label
  4023. (with <code>T</code> being a catch-all for any label), and a <code>throw</code>
  4024. called during the execution of <code>prg</code> will immediately return the
  4025. thrown value. Otherwise, <code>any</code> should be a list of strings, to catch
  4026. any error whose message contains one of these strings, and this will immediately
  4027. return the matching string. If neither <code>throw</code> nor an error occurs,
  4028. the result of <code>prg</code> is returned. See also <code><a
  4029. href="#finally">finally</a></code>, <code><a
  4030. href="#quit">quit</a></code> and
  4031. <code><a href="#errors">Error Handling</a></code>.
  4032.  
  4033. <pre><code>
  4034. : (catch 'OK (println 1) (throw 'OK 999) (println 2))
  4035. 1
  4036. -> 999
  4037. : (catch '("No such file") (in "doesntExist" (foo)))
  4038. -> "No such file"
  4039. </code></pre>
  4040.  
  4041. <dt><a name="cd"><code>(cd 'any) -> sym</code></a>
  4042. <dd>Changes the current directory to <code>any</code>. The old directory is
  4043. returned on success, otherwise <code>NIL</code>. See also <code><a
  4044. href="#chdir">chdir</a></code>, <code><a
  4045. href="#dir">dir</a></code> and <code><a
  4046. href="#pwd">pwd</a></code>.
  4047.  
  4048. <pre><code>
  4049. : (when (cd "lib")
  4050. (println (sum lines (dir)))
  4051. (cd @) )
  4052. 10955
  4053. </code></pre>
  4054.  
  4055. <dt><a name="cdr"><code>(cdr 'lst) -> any</code></a>
  4056. <dd>List access: Returns all but the first element of <code>lst</code>. See also
  4057. <code><a href="#car">car</a></code> and <code><a
  4058. href="#cXr">c..r</a></code>.
  4059.  
  4060. <pre><code>
  4061. : (cdr (1 2 3 4 5 6))
  4062. -> (2 3 4 5 6)
  4063. </code></pre>
  4064.  
  4065. <dt><a name="center"><code>(center 'cnt|lst 'any ..) -> sym</code></a>
  4066. <dd>Returns a transient symbol with all <code>any</code> arguments <code><a
  4067. href="#pack">pack</a></code>ed in a centered format. Trailing blanks
  4068. are omitted. See also <code><a href="#align">align</a></code>, <code><a
  4069. href="#tab">tab</a></code> and <code><a
  4070. href="#wrap">wrap</a></code>.
  4071.  
  4072. <pre><code>
  4073. : (center 4 12)
  4074. -> " 12"
  4075. : (center 4 "a")
  4076. -> " a"
  4077. : (center 7 "a")
  4078. -> " a"
  4079. : (center (3 3 3) "a" "b" "c")
  4080. -> " a b c"
  4081. </code></pre>
  4082.  
  4083. <dt><a name="chain"><code>(chain 'lst ..) -> lst</code></a>
  4084. <dd>Concatenates (destructively) one or several new list elements
  4085. <code>lst</code> to the end of the list in the current <code><a
  4086. href="#make">make</a></code> environment. This operation is efficient
  4087. also for long lists, because a pointer to the last element of the result list is
  4088. maintained. <code>chain</code> returns the last linked argument. See also
  4089. <code><a href="#link">link</a></code>, <code><a
  4090. href="#yoke">yoke</a></code> and <code><a
  4091. href="#made">made</a></code>.
  4092.  
  4093. <pre><code>
  4094. : (make (chain (list 1 2 3) NIL (cons 4)) (chain (list 5 6)))
  4095. -> (1 2 3 4 5 6)
  4096. </code></pre>
  4097.  
  4098. <dt><a name="char"><code>(char) -> sym</code></a>
  4099. <dt><code>(char 'cnt) -> sym</code>
  4100. <dt><code>(char T) -> sym</code>
  4101. <dt><code>(char 'sym) -> cnt</code>
  4102. <dd>When called without arguments, the next character from the current input
  4103. stream is returned as a single-character transient symbol, or <code>NIL</code>
  4104. upon end of file. When called with a number <code>cnt</code>, a character with
  4105. the corresponding unicode value is returned. As a special case, <code>T</code>
  4106. is accepted to produce a byte value greater than any first byte in a UTF-8
  4107. character (used as a top value in comparisons). Otherwise, when called with a
  4108. symbol <code>sym</code>, the numeric unicode value of the first character of the
  4109. name of that symbol is returned. See also <code><a
  4110. href="#peek">peek</a></code>, <code><a
  4111. href="#skip">skip</a></code>, <code><a
  4112. href="#key">key</a></code>, <code><a
  4113. href="#line">line</a></code>, <code><a
  4114. href="#till">till</a></code> and <code><a
  4115. href="#eof">eof</a></code>.
  4116.  
  4117. <pre><code>
  4118. : (char) # Read character from console
  4119. A # (typed 'A' and a space/return)
  4120. -> "A"
  4121. : (char 100) # Convert unicode to symbol
  4122. -> "d"
  4123. : (char "d") # Convert symbol to unicode
  4124. -> 100
  4125.  
  4126. : (char T) # Special case
  4127. -> # (not printable)
  4128.  
  4129. : (char 0)
  4130. -> NIL
  4131. : (char NIL)
  4132. -> 0
  4133. </code></pre>
  4134.  
  4135. <dt><a name="chdir"><code>(chdir 'any . prg) -> any</code></a>
  4136. <dd>Changes the current directory to <code>any</code> with <code><a
  4137. href="#cd">cd</a></code> during the execution of <code>prg</code>. Then
  4138. the previous directory will be restored and the result of <code>prg</code>
  4139. returned. See also <code><a href="#dir">dir</a></code> and <code><a
  4140. href="#pwd">pwd</a></code>.
  4141.  
  4142. <pre><code>
  4143. : (pwd)
  4144. -> "/usr/abu/pico"
  4145. : (chdir "src" (pwd))
  4146. -> "/usr/abu/pico/src"
  4147. : (pwd)
  4148. -> "/usr/abu/pico"
  4149. </code></pre>
  4150.  
  4151. <dt><a name="chkTree"><code>(chkTree 'sym ['fun]) -> num</code></a>
  4152. <dd>Checks a database tree node (and recursively all sub-nodes) for consistency.
  4153. Returns the total number of nodes checked. Optionally, <code>fun</code> is
  4154. called with the key and value of each node, and should return <code>NIL</code>
  4155. for failure. See also <code><a href="#tree">tree</a></code> and
  4156. <code><a href="#root">root</a></code>.
  4157.  
  4158. <pre><code>
  4159. : (show *DB '+Item)
  4160. {C} NIL
  4161. sup (7 . {7-3})
  4162. nr (7 . {7-1}) # 7 nodes in the 'nr' tree, base node is {7-1}
  4163. pr (7 . {7-4})
  4164. nm (77 . {7-6})
  4165. -> {C}
  4166. : (chkTree '{7-1}) # Check that node
  4167. -> 7
  4168. </code></pre>
  4169.  
  4170. <dt><a name="chop"><code>(chop 'any) -> lst</code></a>
  4171. <dd>Returns <code>any</code> as a list of single-character strings. If
  4172. <code>any</code> is <code>NIL</code> or a symbol with no name, <code>NIL</code>
  4173. is returned. A list argument is returned unchanged.
  4174.  
  4175. <pre><code>
  4176. : (chop 'car)
  4177. -> ("c" "a" "r")
  4178. : (chop "Hello")
  4179. -> ("H" "e" "l" "l" "o")
  4180. </code></pre>
  4181.  
  4182. <dt><a name="circ"><code>(circ 'any ..) -> lst</code></a>
  4183. <dd>Produces a circular list of all <code>any</code> arguments by <code><a
  4184. href="#cons">cons</a></code>ing them to a list and then connecting the
  4185. CDR of the last cell to the first cell. See also <code><a
  4186. href="#circ?">circ?</a></code> and <code><a
  4187. href="#list">list</a></code>.
  4188.  
  4189. <pre><code>
  4190. : (circ 'a 'b 'c)
  4191. -> (a b c .)
  4192. </code></pre>
  4193.  
  4194. <dt><a name="circ?"><code>(circ? 'any) -> any</code></a> <dd>Returs the circular
  4195. (sub)list if <code>any</code> is a circular list, else <code>NIL</code>. See
  4196. also <code><a href="#circ">circ</a></code>.
  4197.  
  4198. <pre><code>
  4199. : (circ? 'a)
  4200. -> NIL
  4201. : (circ? (1 2 3))
  4202. -> NIL
  4203. : (circ? (1 . (2 3 .)))
  4204. -> (2 3 .)
  4205. </code></pre>
  4206.  
  4207. <dt><a name="class"><code>(class sym . typ) -> obj</code></a>
  4208. <dd>Defines <code>sym</code> as a class with the superclass(es)
  4209. <code>typ</code>. As a side effect, the global variable <code><a
  4210. href="#*Class">*Class</a></code> is set to <code>obj</code>. See also
  4211. <code><a href="#extend">extend</a></code>, <code><a
  4212. href="#dm">dm</a></code>, <code><a href="refV.html#var">var</a></code>,
  4213. <code><a href="#rel">rel</a></code>, <code><a
  4214. href="#type">type</a></code>, <code><a
  4215. href="#isa">isa</a></code> and <code><a
  4216. href="#object">object</a></code>.
  4217.  
  4218. <pre><code>
  4219. : (class +A +B +C +D)
  4220. -> +A
  4221. : +A
  4222. -> (+B +C +D)
  4223. : (dm foo> (X) (bar X))
  4224. -> foo>
  4225. : +A
  4226. -> ((foo> (X) (bar X)) +B +C +D)
  4227. </code></pre>
  4228.  
  4229. <dt><a name="clause"><code>(clause '(sym . any)) -> sym</code></a>
  4230. <dd>Declares a <a href="#pilog">Pilog</a> fact or rule for the
  4231. <code>sym</code> argument, by concatenating the <code>any</code> argument to the
  4232. <code>T</code> property of <code>sym</code>. See also <code><a
  4233. href="#be">be</a></code>.
  4234.  
  4235. <pre><code>
  4236. : (clause '(likes (John Mary)))
  4237. -> likes
  4238. : (clause '(likes (John @X) (likes @X wine) (likes @X food)))
  4239. -> likes
  4240. : (? (likes @X @Y))
  4241. @X=John @Y=Mary
  4242. -> NIL
  4243. </code></pre>
  4244.  
  4245. <dt><a name="clause/2"><code>clause/2</code></a>
  4246. <dd><a href="#pilog">Pilog</a> predicate that succeeds if the first
  4247. argument is a predicate which has the second argument defined as a clause.
  4248.  
  4249. <pre><code>
  4250. : (? (clause append ((NIL @X @X))))
  4251. -> T
  4252.  
  4253. : (? (clause append @C))
  4254. @C=((NIL @X @X))
  4255. @C=(((@A . @X) @Y (@A . @Z)) (append @X @Y @Z))
  4256. -> NIL
  4257. </code></pre>
  4258.  
  4259. <dt><a name="clip"><code>(clip 'lst) -> lst</code></a>
  4260. <dd>Returns a copy of <code>lst</code> with all whitespace characters or
  4261. <code>NIL</code> elements removed from both sides. See also <code><a
  4262. href="#trim">trim</a></code>.
  4263.  
  4264. <pre><code>
  4265. : (clip '(NIL 1 NIL 2 NIL))
  4266. -> (1 NIL 2)
  4267. : (clip '(" " a " " b " "))
  4268. -> (a " " b)
  4269. </code></pre>
  4270.  
  4271. <dt><a name="close"><code>(close 'cnt) -> cnt | NIL</code></a>
  4272. <dd>Closes a file descriptor <code>cnt</code>, and returns it when successful.
  4273. Should not be called inside an <code><a href="#out">out</a></code> body
  4274. for that descriptor. See also <code><a href="#open">open</a></code>,
  4275. <code><a href="#poll">poll</a></code>,
  4276. <code><a href="#listen">listen</a></code> and <code><a
  4277. href="#connect">connect</a></code>.
  4278.  
  4279. <pre><code>
  4280. : (close 2) # Close standard error
  4281. -> 2
  4282. </code></pre>
  4283.  
  4284. <dt><a name="cmd"><code>(cmd ['any]) -> sym</code></a>
  4285. <dd>When called without an argument, the name of the command that invoked the
  4286. picolisp interpreter is returned. Otherwise, the command name is set to
  4287. <code>any</code>. Setting the name may not work on some operating systems. Note
  4288. that the new name must not be longer than the original one. See also <code><a
  4289. href="#argv">argv</a></code>, <code><a
  4290. href="#file">file</a></code> and <a
  4291. href="#invoc">Invocation</a>.
  4292.  
  4293. <pre><code>
  4294. $ pil +
  4295. : (cmd)
  4296. -> "/usr/bin/picolisp"
  4297. : (cmd "!/bin/picolust")
  4298. -> "!/bin/picolust"
  4299. : (cmd)
  4300. -> "!/bin/picolust"
  4301. </code></pre>
  4302.  
  4303. <dt><a name="cnt"><code>(cnt 'fun 'lst ..) -> cnt</code></a>
  4304. <dd>Applies <code>fun</code> to each element of <code>lst</code>. When
  4305. additional <code>lst</code> arguments are given, their elements are also passed
  4306. to <code>fun</code>. Returns the count of non-<code>NIL</code> values returned
  4307. from <code>fun</code>.
  4308.  
  4309. <pre><code>
  4310. : (cnt cdr '((1 . T) (2) (3 4) (5)))
  4311. -> 2
  4312. </code></pre>
  4313.  
  4314. <dt><a name="collect"><code>(collect 'sym 'cls ['hook] ['any|beg ['end [sym|cnt ..]]])</code></a>
  4315. <dd>Returns a list of all database objects of class <code>cls</code>, where the
  4316. values for the <code>sym</code> arguments correspond to the <code>any</code>
  4317. arguments, or where the values for the <code>sym</code> arguments are in the
  4318. range <code>beg</code> .. <code>end</code>. <code>sym</code>, <code>cls</code>
  4319. and <code>hook</code> should specify a <code><a
  4320. href="#tree">tree</a></code> for <code>cls</code> or one of its
  4321. superclasses. If additional <code>sym|cnt</code> arguments are given, the final
  4322. values for the result list are obtained by applying the <code><a
  4323. href="#get">get</a></code> algorithm. See also <code><a
  4324. href="#db">db</a></code>, <code><a href="refA.html#aux">aux</a></code>,
  4325. <code><a href="#fetch">fetch</a></code>, <code><a
  4326. href="#init">init</a></code> and <code><a
  4327. href="#step">step</a></code>.
  4328.  
  4329. <pre><code>
  4330. : (collect 'nr '+Item)
  4331. -> ({3-1} {3-2} {3-3} {3-4} {3-5} {3-6} {3-8})
  4332. : (collect 'nr '+Item 3 6 'nr)
  4333. -> (3 4 5 6)
  4334. : (collect 'nr '+Item 3 6 'nm)
  4335. -> ("Auxiliary Construction" "Enhancement Additive" "Metal Fittings" "Gadget Appliance")
  4336. : (collect 'nm '+Item "Main Part")
  4337. -> ({3-1})
  4338. </code></pre>
  4339.  
  4340. <dt><a name="commit"><code>(commit ['any] [exe1] [exe2]) -> T</code></a>
  4341. <dd>Closes a transaction, by writing all new or modified external symbols to,
  4342. and removing all deleted external symbols from the database. When
  4343. <code>any</code> is given, it is implicitly sent (with all modified objects) via
  4344. the <code><a href="#tell">tell</a></code> mechanism to all family
  4345. members. If <code>exe1</code> or <code>exe2</code> are given, they are executed
  4346. as pre- or post-expressions while the database is <code><a
  4347. href="#lock">lock</a></code>ed and <code><a
  4348. href="#protect">protect</a></code>ed. See also <code><a
  4349. href="#rollback">rollback</a></code>.
  4350.  
  4351. <pre><code>
  4352. : (pool "db")
  4353. -> T
  4354. : (put '{1} 'str "Hello")
  4355. -> "Hello"
  4356. : (commit)
  4357. -> T
  4358. </code></pre>
  4359.  
  4360. <dt><a name="con"><code>(con 'lst 'any) -> any</code></a>
  4361. <dd>Connects <code>any</code> to the first cell of <code>lst</code>, by
  4362. (destructively) storing <code>any</code> in the CDR of <code>lst</code>. See
  4363. also <code><a href="#conc">conc</a></code>.
  4364.  
  4365. <pre><code>
  4366. : (setq C (1 . a))
  4367. -> (1 . a)
  4368. : (con C '(b c d))
  4369. -> (b c d)
  4370. : C
  4371. -> (1 b c d)
  4372. </code></pre>
  4373.  
  4374. <dt><a name="conc"><code>(conc 'lst ..) -> lst</code></a>
  4375. <dd>Concatenates all argument lists (destructively). See also <code><a
  4376. href="#append">append</a></code> and <code><a
  4377. href="#con">con</a></code>.
  4378.  
  4379. <pre><code>
  4380. : (setq A (1 2 3) B '(a b c))
  4381. -> (a b c)
  4382. : (conc A B) # Concatenate lists in 'A' and 'B'
  4383. -> (1 2 3 a b c)
  4384. : A
  4385. -> (1 2 3 a b c) # Side effect: List in 'A' is modified!
  4386. </code></pre>
  4387.  
  4388. <dt><a name="cond"><code>(cond ('any1 . prg1) ('any2 . prg2) ..) -> any</code></a>
  4389. <dd>Multi-way conditional: If any of the <code>anyN</code> conditions evaluates
  4390. to non-<code>NIL</code>, <code>prgN</code> is executed and the result returned.
  4391. Otherwise (all conditions evaluate to <code>NIL</code>), <code>NIL</code> is
  4392. returned. See also <code><a href="#nond">nond</a></code>, <code><a
  4393. href="#if">if</a></code>, <code><a href="refI.html#if2">if2</a></code>
  4394. and <code><a href="#when">when</a></code>.
  4395.  
  4396. <pre><code>
  4397. : (cond
  4398. ((= 3 4) (println 1))
  4399. ((= 3 3) (println 2))
  4400. (T (println 3)) )
  4401. 2
  4402. -> 2
  4403. </code></pre>
  4404.  
  4405. <dt><a name="connect"><code>(connect 'any1 'any2) -> cnt | NIL</code></a>
  4406. <dd>Tries to establish a TCP/IP connection to a server listening at host
  4407. <code>any1</code>, port <code>any2</code>. <code>any1</code> may be either a
  4408. hostname or a standard internet address in numbers-and-dots/colons notation
  4409. (IPv4/IPv6). <code>any2</code> may be either a port number or a service name.
  4410. Returns a socket descriptor <code>cnt</code>, or <code>NIL</code> if the
  4411. connection cannot be established. See also <code><a
  4412. href="#listen">listen</a></code> and <code><a
  4413. href="#udp">udp</a></code>.
  4414.  
  4415. <pre><code>
  4416. : (connect "localhost" 4444)
  4417. -> 3
  4418. : (connect "some.host.org" "http")
  4419. -> 4
  4420. </code></pre>
  4421.  
  4422. <dt><a name="cons"><code>(cons 'any ['any ..]) -> lst</code></a>
  4423. <dd>Constructs a new list cell with the first argument in the CAR and the second
  4424. argument in the CDR. If more than two arguments are given, a corresponding chain
  4425. of cells is built. <code>(cons 'a 'b 'c 'd)</code> is equivalent to <code>(cons
  4426. 'a (cons 'b (cons 'c 'd)))</code>. See also <code><a
  4427. href="#list">list</a></code>.
  4428.  
  4429. <pre><code>
  4430. : (cons 1 2)
  4431. -> (1 . 2)
  4432. : (cons 'a '(b c d))
  4433. -> (a b c d)
  4434. : (cons '(a b) '(c d))
  4435. -> ((a b) c d)
  4436. : (cons 'a 'b 'c 'd)
  4437. -> (a b c . d)
  4438. </code></pre>
  4439.  
  4440. <dt><a name="copy"><code>(copy 'any) -> any</code></a>
  4441. <dd>Copies the argument <code>any</code>. For lists, the top level cells are
  4442. copied, while atoms are returned unchanged.
  4443.  
  4444. <pre><code>
  4445. : (=T (copy T)) # Atoms are not copied
  4446. -> T
  4447. : (setq L (1 2 3))
  4448. -> (1 2 3)
  4449. : (== L L)
  4450. -> T
  4451. : (== L (copy L)) # The copy is not identical to the original
  4452. -> NIL
  4453. : (= L (copy L)) # But the copy is equal to the original
  4454. -> T
  4455. </code></pre>
  4456.  
  4457. <dt><a name="co"><code>(co 'sym [. prg]) -> any</code></a>
  4458. <dd>(64-bit version only) Starts, resumes or stops a <a
  4459. href="#coroutines">coroutine</a> with the tag given by <code>sym</code>.
  4460. If <code>prg</code> is not given, a coroutine with that tag will be stopped.
  4461. Otherwise, if a coroutine running with that tag is found (pointer equality is
  4462. used for comparison), its execution is resumed. Else a new coroutine with that
  4463. tag is initialized and started. <code>prg</code> will be executed until it
  4464. either terminates normally, or until <code><a
  4465. href="#yield">yield</a></code> is called. In the latter case
  4466. <code>co</code> returns, or transfers control to some other, already running,
  4467. coroutine. A coroutine cannot resume itself directly or indirectly. See also
  4468. <code><a href="#stack">stack</a></code>, <code><a
  4469. href="#catch">catch</a></code> and <code><a
  4470. href="#throw">throw</a></code>.
  4471.  
  4472. <pre><code>
  4473. : (de pythag (N) # A generator function
  4474. (if (=T N)
  4475. (co 'rt) # Stop
  4476. (co 'rt
  4477. (for X N
  4478. (for Y (range X N)
  4479. (for Z (range Y N)
  4480. (when (= (+ (* X X) (* Y Y)) (* Z Z))
  4481. (yield (list X Y Z)) ) ) ) ) ) ) )
  4482.  
  4483. : (pythag 20)
  4484. -> (3 4 5)
  4485. : (pythag 20)
  4486. -> (5 12 13)
  4487. : (pythag 20)
  4488. -> (6 8 10)
  4489.  
  4490. </code></pre>
  4491.  
  4492. <dt><a name="count"><code>(count 'tree) -> num</code></a>
  4493. <dd>Returns the number of nodes in a database tree. See also <code><a
  4494. href="#tree">tree</a></code> and <code><a
  4495. href="#root">root</a></code>.
  4496.  
  4497. <pre><code>
  4498. : (count (tree 'nr '+Item))
  4499. -> 7
  4500. </code></pre>
  4501.  
  4502. <dt><a name="ctl"><code>(ctl 'sym . prg) -> any</code></a>
  4503. <dd>Waits until a write (exclusive) lock (or a read (shared) lock if the first
  4504. character of <code>sym</code> is "<code>+</code>") can be set on the file
  4505. <code>sym</code>, then executes <code>prg</code> and releases the lock. If the
  4506. file does not exist, it will be created. When <code>sym</code> is
  4507. <code>NIL</code>, a shared lock is tried on the current innermost I/O channel,
  4508. and when it is <code>T</code>, an exclusive lock is tried instead. See also
  4509. <code><a href="#in">in</a></code>, <code><a
  4510. href="#out">out</a></code>, <code><a
  4511. href="#err">err</a></code> and <code><a
  4512. href="#pipe">pipe</a></code>.
  4513.  
  4514. <pre><code>
  4515. $ echo 9 >count # Write '9' to file "count"
  4516. $ pil +
  4517. : (ctl ".ctl" # Exclusive control, using ".ctl"
  4518. (in "count"
  4519. (let Cnt (read) # Read '9'
  4520. (out "count"
  4521. (println (dec Cnt)) ) ) ) ) # Write '8'
  4522. -> 8
  4523. :
  4524. $ cat count # Check "count"
  4525. 8
  4526. </code></pre>
  4527.  
  4528. <dt><a name="ctty"><code>(ctty 'sym|pid) -> flg</code></a>
  4529. <dd>When called with a symbolic argument, <code>ctty</code> changes the current
  4530. TTY device to <code>sym</code>. Otherwise, the local console is prepared for
  4531. serving the PicoLisp process with the process ID <code>pid</code>. See also
  4532. <code><a href="#raw">raw</a></code>.
  4533.  
  4534. <pre><code>
  4535. : (ctty "/dev/tty")
  4536. -> T
  4537. </code></pre>
  4538.  
  4539. <dt><a name="curry"><code>(curry lst . fun) -> fun</code></a>
  4540. <dd>Builds a new function from the list of symbols or symbol-value pairs
  4541. <code>lst</code> and the functional expression <code>fun</code>. Each member in
  4542. <code>lst</code> that is a <code><a href="#pat?">pat?</a></code> symbol
  4543. is substituted inside <code>fun</code> by its value. All other symbols in
  4544. <code>lst</code> are collected into a <code><a
  4545. href="#job">job</a></code> environment.
  4546.  
  4547. <pre><code>
  4548. : (de multiplier (@X)
  4549. (curry (@X) (N) (* @X N)) )
  4550. -> multiplier
  4551. : (multiplier 7)
  4552. -> ((N) (* 7 N))
  4553. : ((multiplier 7) 3)
  4554. -> 21
  4555.  
  4556. : (def 'fiboCounter
  4557. (curry ((N1 . 0) (N2 . 1)) (Cnt)
  4558. (do Cnt
  4559. (println
  4560. (prog1
  4561. (+ N1 N2)
  4562. (setq N1 N2 N2 @) ) ) ) ) )
  4563. -> fiboCounter
  4564. : (pp 'fiboCounter)
  4565. (de fiboCounter (Cnt)
  4566. (job '((N2 . 1) (N1 . 0))
  4567. (do Cnt
  4568. (println
  4569. (prog1 (+ N1 N2) (setq N1 N2 N2 @)) ) ) ) )
  4570. -> fiboCounter
  4571. : (fiboCounter 5)
  4572. 1
  4573. 2
  4574. 3
  4575. 5
  4576. 8
  4577. -> 8
  4578. : (fiboCounter 5)
  4579. 13
  4580. 21
  4581. 34
  4582. 55
  4583. 89
  4584. -> 89
  4585. </code></pre>
  4586.  
  4587. <dt><a name="cut"><code>(cut 'cnt 'var) -> lst</code></a>
  4588. <dd>Pops the first <code>cnt</code> elements (CAR) from the stack in
  4589. <code>var</code>. See also <code><a href="#pop">pop</a></code> and
  4590. <code><a href="#del">del</a></code>.
  4591.  
  4592. <pre><code>
  4593. : (setq S '(1 2 3 4 5 6 7 8))
  4594. -> (1 2 3 4 5 6 7 8)
  4595. : (cut 3 'S)
  4596. -> (1 2 3)
  4597. : S
  4598. -> (4 5 6 7 8)
  4599. </code></pre>
  4600.  
  4601. </dl>
  4602.  
  4603. <h1><a name="D">D</a></h1>
  4604.  
  4605. <dl>
  4606.  
  4607. <dt><a name="*DB"><code>*DB</code></a>
  4608. <dd>A global constant holding the external symbol <code>{1}</code>, the <a
  4609. href="#dbase">database</a> root. All transient symbols in a database can
  4610. be reached from that root. Except during debugging, any explicit literal access
  4611. to symbols in the database should be avoided, because otherwise a memory leak
  4612. might occur (The garbage collector temporarily sets <code>*DB</code> to
  4613. <code>NIL</code> and restores its value after collection, thus disposing of all
  4614. external symbols not currently used in the program).
  4615.  
  4616. <pre><code>
  4617. : (show *DB)
  4618. {1} NIL
  4619. +City {P}
  4620. +Person {3}
  4621. -> {1}
  4622. : (show '{P})
  4623. {P} NIL
  4624. nm (566 . {AhDx})
  4625. -> {P}
  4626. : (show '{3})
  4627. {3} NIL
  4628. tel (681376 . {Agyl})
  4629. nm (1461322 . {2gu7})
  4630. -> {3}
  4631. </code></pre>
  4632.  
  4633. <dt><a name="*Dbg"><code>*Dbg</code></a>
  4634. <dd>A boolean variable indicating "debug mode". It can be conveniently switched
  4635. on with a trailing <code>+</code> command line argument (see <a
  4636. href="#invoc">Invocation</a>). When non-<code>NIL</code>, the <code><a
  4637. href="#$">$</a></code> (tracing) and <code><a
  4638. href="#!">!</a></code> (breakpoint) functions are enabled, and the
  4639. current line number and file name will be stored in symbol properties by
  4640. <code><a href="#de">de</a></code>, <code><a
  4641. href="#def">def</a></code> and <code><a
  4642. href="#dm">dm</a></code>. See also <code><a
  4643. href="#debug">debug</a></code>, <code><a
  4644. href="#trace">trace</a></code> and <code><a
  4645. href="#lint">lint</a></code>.
  4646.  
  4647. <pre><code>
  4648. : (de foo (A B) (* A B))
  4649. -> foo
  4650. : (trace 'foo)
  4651. -> foo
  4652. : (foo 3 4)
  4653. foo : 3 4
  4654. foo = 12
  4655. -> 12
  4656. : (let *Dbg NIL (foo 3 4))
  4657. -> 12
  4658. </code></pre>
  4659.  
  4660. <dt><a name="*Dbs"><code>*Dbs</code></a>
  4661. <dd>A global variable holding a list of numbers (block size scale factors, as
  4662. needed by <code><a href="#pool">pool</a></code>). It is typically set
  4663. by <code><a href="#dbs">dbs</a></code>
  4664. and <code><a href="#dbs+">dbs+</a></code>.
  4665.  
  4666. <pre><code>
  4667. : *Dbs
  4668. -> (1 2 1 0 2 3 3 3)
  4669. </code></pre>
  4670.  
  4671. <dt><a name="+Date"><code>+Date</code></a>
  4672. <dd>Class for calender dates (as calculated by <code><a
  4673. href="#date">date</a></code>), a subclass of <code><a
  4674. href="#+Number">+Number</a></code>. See also <a
  4675. href="#dbase">Database</a>.
  4676.  
  4677. <pre><code>
  4678. (rel dat (+Ref +Date)) # Indexed date
  4679. </code></pre>
  4680.  
  4681. <dt><a name="+Dep"><code>+Dep</code></a>
  4682. <dd>Prefix class for maintaining dependencies between <code><a
  4683. href="#+relation">+relation</a></code>s. Expects a list of (symbolic)
  4684. attributes that depend on this relation. Whenever this relations is cleared
  4685. (receives a value of <code>NIL</code>), the dependent relations will also be
  4686. cleared, triggering all required side-effects. See also <a
  4687. href="#dbase">Database</a>.
  4688.  
  4689. <p>In the following example, the index entry for the item pointing to the
  4690. position (and, therefore, to the order) is cleared in case the order is deleted,
  4691. or this position is deleted from the order:
  4692.  
  4693. <pre><code>
  4694. (class +Pos +Entity) # Position class
  4695. (rel ord (+Dep +Joint) # Order of that position
  4696. (itm) # 'itm' specifies the dependency
  4697. pos (+Ord) ) # Arguments to '+Joint'
  4698. (rel itm (+Ref +Link) NIL (+Item)) # Item depends on the order
  4699. </code></pre>
  4700.  
  4701. <dt><a name="d"><code>(d) -> T</code></a>
  4702. <dd>(Debug mode only) Inserts <code><a href="#!">!</a></code>
  4703. breakpoints into all subexpressions of the current breakpoint. Typically used
  4704. when single-stepping a function or method with <code><a
  4705. href="#debug">debug</a></code>. See also <code><a
  4706. href="#u">u</a></code> and <code><a
  4707. href="#unbug">unbug</a></code>.
  4708.  
  4709. <pre><code>
  4710. ! (d) # Debug subexpression(s) at breakpoint
  4711. -> T
  4712. </code></pre>
  4713.  
  4714. <dt><a name="daemon"><code>(daemon 'sym . prg) -> fun</code></a>
  4715. <dt><code>(daemon '(sym . cls) . prg) -> fun</code>
  4716. <dt><code>(daemon '(sym sym2 [. cls]) . prg) -> fun</code>
  4717. <dd>Inserts <code>prg</code> in the beginning of the function (first form), the
  4718. method body of <code>sym</code> in <code>cls</code> (second form) or in the
  4719. class obtained by <code><a href="#get">get</a></code>ting
  4720. <code>sym2</code> from <code><a href="#*Class">*Class</a></code> (or
  4721. <code>cls</code> if given) (third form). Built-in functions (C-function pointer)
  4722. are automatically converted to Lisp expressions. See also <code><a
  4723. href="#trace">trace</a></code>, <code><a
  4724. href="#expr">expr</a></code>, <code><a
  4725. href="#patch">patch</a></code> and <code><a
  4726. href="#redef">redef</a></code>.
  4727.  
  4728. <pre><code>
  4729. : (de hello () (prinl "Hello world!"))
  4730. -> hello
  4731.  
  4732. : (daemon 'hello (prinl "# This is the hello world program"))
  4733. -> (NIL (prinl "# This is the hello world program") (prinl "Hello world!"))
  4734. : (hello)
  4735. # This is the hello world program
  4736. Hello world!
  4737. -> "Hello world!"
  4738.  
  4739. : (daemon '* (msg 'Multiplying))
  4740. -> (@ (msg 'Multiplying) (pass $134532148))
  4741. : *
  4742. -> (@ (msg 'Multiplying) (pass $134532148))
  4743. : (* 1 2 3)
  4744. Multiplying
  4745. -> 6
  4746. </code></pre>
  4747.  
  4748. <dt><a name="dat$"><code>(dat$ 'dat ['sym]) -> sym</code></a>
  4749. <dd>Formats a <code><a href="#date">date</a></code> <code>dat</code> in
  4750. ISO format, with an optional delimiter character <code>sym</code>. See also
  4751. <code><a href="#$dat">$dat</a></code>, <code><a
  4752. href="#tim$">tim$</a></code>, <code><a
  4753. href="#datStr">datStr</a></code> and <code><a
  4754. href="#datSym">datSym</a></code>.
  4755.  
  4756. <pre><code>
  4757. : (dat$ (date))
  4758. -> "20070601"
  4759. : (dat$ (date) "-")
  4760. -> "2007-06-01"
  4761. </code></pre>
  4762.  
  4763. <dt><a name="datStr"><code>(datStr 'dat ['flg]) -> sym</code></a>
  4764. <dd>Formats a <code><a href="#date">date</a></code> according to the
  4765. current <code><a href="#locale">locale</a></code>. If <code>flg</code>
  4766. is non-<code>NIL</code>, the year will be formatted modulo 100. See also
  4767. <code><a href="#dat$">dat$</a></code>, <code><a
  4768. href="#datSym">datSym</a></code>, <code><a
  4769. href="#strDat">strDat</a></code>, <code><a
  4770. href="#expDat">expDat</a></code>, <code><a
  4771. href="#expTel">expTel</a></code> and <code><a
  4772. href="#day">day</a></code>.
  4773.  
  4774. <pre><code>
  4775. : (datStr (date))
  4776. -> "2007-06-01"
  4777. : (locale "DE" "de")
  4778. -> NIL
  4779. : (datStr (date))
  4780. -> "01.06.2007"
  4781. : (datStr (date) T)
  4782. -> "01.06.07"
  4783. </code></pre>
  4784.  
  4785. <dt><a name="datSym"><code>(datSym 'dat) -> sym</code></a>
  4786. <dd>Formats a <code><a href="#date">date</a></code> <code>dat</code> in
  4787. in symbolic format (DDmmmYY). See also <code><a
  4788. href="#dat$">dat$</a></code> and <code><a
  4789. href="#datStr">datStr</a></code>.
  4790.  
  4791. <pre><code>
  4792. : (datSym (date))
  4793. -> "01jun07"
  4794. </code></pre>
  4795.  
  4796. <dt><a name="date"><code>(date ['T]) -> dat</code></a>
  4797. <dt><code>(date 'dat) -> (y m d)</code>
  4798. <dt><code>(date 'y 'm 'd) -> dat | NIL</code>
  4799. <dt><code>(date '(y m d)) -> dat | NIL</code>
  4800. <dd>Calculates a (gregorian) calendar date. It is represented as a day number,
  4801. starting first of March of the year 0 AD. When called without arguments, the
  4802. current date is returned. When called with a <code>T</code> argument, the
  4803. current Coordinated Universal Time (UTC) is returned. When called with a single
  4804. number <code>dat</code>, it is taken as a date and a list with the corresponding
  4805. year, month and day is returned. When called with three numbers (or a list of
  4806. three numbers) for the year, month and day, the corresponding date is returned
  4807. (or <code>NIL</code> if they do not represent a legal date). See also <code><a
  4808. href="#time">time</a></code>, <code><a
  4809. href="#stamp">stamp</a></code>, <code><a
  4810. href="#$dat">$dat</a></code>, <code><a
  4811. href="#dat$">dat$</a></code>, <code><a
  4812. href="#datSym">datSym</a></code>, <code><a
  4813. href="#datStr">datStr</a></code>, <code><a
  4814. href="#strDat">strDat</a></code>, <code><a
  4815. href="#expDat">expDat</a></code>, <code><a
  4816. href="#day">day</a></code>, <code><a
  4817. href="#week">week</a></code> and <code><a
  4818. href="#ultimo">ultimo</a></code>.
  4819.  
  4820. <pre><code>
  4821. : (date) # Today
  4822. -> 730589
  4823. : (date 2000 6 12) # 12-06-2000
  4824. -> 730589
  4825. : (date 2000 22 5) # Illegal date
  4826. -> NIL
  4827. : (date (date)) # Today's year, month and day
  4828. -> (2000 6 12)
  4829. : (- (date) (date 2000 1 1)) # Number of days since first of January
  4830. -> 163
  4831. </code></pre>
  4832.  
  4833. <dt><a name="day"><code>(day 'dat ['lst]) -> sym</code></a>
  4834. <dd>Returns the name of the day for a given <code><a
  4835. href="#date">date</a></code> <code>dat</code>, in the language of the
  4836. current <code><a href="#locale">locale</a></code>. If <code>lst</code>
  4837. is given, it should be a list of alternative weekday names. See also <code><a
  4838. href="#week">week</a></code>, <code><a
  4839. href="#datStr">datStr</a></code> and <code><a
  4840. href="#strDat">strDat</a></code>.
  4841.  
  4842. <pre><code>
  4843. : (day (date))
  4844. -> "Friday"
  4845. : (locale "DE" "de")
  4846. -> NIL
  4847. : (day (date))
  4848. -> "Freitag"
  4849. : (day (date) '("Mo" "Tu" "We" "Th" "Fr" "Sa" "Su"))
  4850. -> "Fr"
  4851. </code></pre>
  4852.  
  4853. <dt><a name="db"><code>(db 'sym 'cls ['hook] 'any ['sym 'any ..]) -> sym | NIL</code></a>
  4854. <dd>Returns a database object of class <code>cls</code>, where the values for
  4855. the <code>sym</code> arguments correspond to the <code>any</code> arguments. If
  4856. a matching object cannot be found, <code>NIL</code> is returned.
  4857. <code>sym</code>, <code>cls</code> and <code>hook</code> should specify a
  4858. <code><a href="#tree">tree</a></code> for <code>cls</code> or one of
  4859. its superclasses. See also <code><a href="#aux">aux</a></code>,
  4860. <code><a href="#collect">collect</a></code>, <code><a
  4861. href="#request">request</a></code>, <code><a
  4862. href="#fetch">fetch</a></code>, <code><a
  4863. href="#init">init</a></code> and <code><a
  4864. href="#step">step</a></code>.
  4865.  
  4866. <pre><code>
  4867. : (db 'nr '+Item 1)
  4868. -> {3-1}
  4869. : (db 'nm '+Item "Main Part")
  4870. -> {3-1}
  4871. </code></pre>
  4872.  
  4873. <dt><a name="db/3"><code>db/3</code></a>
  4874. <dt><a name="db/4"><code>db/4</code></a>
  4875. <dt><a name="db/5"><code>db/5</code></a>
  4876. <dd><a href="#pilog">Pilog</a> database predicate that returns objects
  4877. matching the given key/value (and optional hook) relation. The relation should
  4878. be of type <code><a href="#+index">+index</a></code>. For the key
  4879. pattern applies:
  4880.  
  4881. <p><ul>
  4882. <li>a symbol (string) returns all entries which start with that string
  4883. <li>other atoms (numbers, external symbols) match as they are
  4884. <li>cons pairs constitute a range, returning objects
  4885. <ul>
  4886. <li>in increasing order if the CDR is greater than the CAR
  4887. <li>in decreasing order otherwise
  4888. </ul>
  4889. <li>other lists are matched for <code><a href="#+Aux">+Aux</a></code>
  4890. key combinations
  4891. </ul>
  4892.  
  4893. <p>The optional hook can be supplied as the third argument. See also <code><a
  4894. href="#select/3">select/3</a></code> and <code><a
  4895. href="#remote/2">remote/2</a></code>.
  4896.  
  4897. <pre><code>
  4898. : (? (db nr +Item @Item)) # No value given
  4899. @Item={3-1}
  4900. @Item={3-2}
  4901. @Item={3-3}
  4902. @Item={3-4}
  4903. @Item={3-5}
  4904. @Item={3-6}
  4905. -> NIL
  4906.  
  4907. : (? (db nr +Item 2 @Item)) # Get item no. 2
  4908. @Item={3-2}
  4909. -> NIL
  4910.  
  4911. : (? (db nm +Item Spare @Item) (show @Item)) # Search for "Spare.."
  4912. {3-2} (+Item)
  4913. pr 1250
  4914. inv 100
  4915. sup {2-2}
  4916. nm "Spare Part"
  4917. nr 2
  4918. @Item={3-2}
  4919. -> NIL
  4920. </code></pre>
  4921.  
  4922. <dt><a name="db:"><code>(db: cls ..) -> num</code></a>
  4923. <dd>Returns the database file number for objects of the type given by the
  4924. <code>cls</code> argument(s). Needed, for example, for the creation of <code><a
  4925. href="#new">new</a></code> objects. See also <code><a
  4926. href="#dbs">dbs</a></code>.
  4927.  
  4928. <pre><code>
  4929. : (db: +Item)
  4930. -> 3
  4931. </code></pre>
  4932.  
  4933. <dt><a name="dbSync"><code>(dbSync) -> flg</code></a>
  4934. <dd>Starts a database transaction, by trying to obtain a <code><a
  4935. href="#lock">lock</a></code> on the database root object <code><a
  4936. href="#*DB">*DB</a></code>, and then calling <code><a
  4937. href="#sync">sync</a></code> to synchronize with possible changes from
  4938. other processes. When all desired modifications to external symbols are done,
  4939. <code>(<a href="#commit">commit</a> 'upd)</code> should be called. See
  4940. also <a href="#dbase">Database</a>.
  4941.  
  4942. <pre><code>
  4943. (let? Obj (rd) # Get object?
  4944. (dbSync) # Yes: Start transaction
  4945. (put> Obj 'nm (rd)) # Update
  4946. (put> Obj 'nr (rd))
  4947. (put> Obj 'val (rd))
  4948. (commit 'upd) ) # Close transaction
  4949. </code></pre>
  4950.  
  4951. <dt><a name="dbck"><code>(dbck ['cnt] 'flg) -> any</code></a>
  4952. <dd>Performs a low-level integrity check of the current (or <code>cnt</code>'th)
  4953. database file, and returns <code>NIL</code> (or the number of blocks and symbols
  4954. if <code>flg</code> is non-<code>NIL</code>) if everything seems correct.
  4955. Otherwise, a string indicating an error is returned. As a side effect, possibly
  4956. unused blocks (as there might be when a <code><a
  4957. href="#rollback">rollback</a></code> is done before <code><a
  4958. href="#commit">commit</a></code>ting newly allocated (<code><a
  4959. href="#new">new</a></code>) external symbols) are appended to the free
  4960. list.
  4961.  
  4962. <pre><code>
  4963. : (pool "db")
  4964. -> T
  4965. : (dbck)
  4966. -> NIL
  4967. </code></pre>
  4968.  
  4969. <dt><a name="dbs"><code>(dbs . lst)</code></a>
  4970. <dd>Initializes the global variable <code><a
  4971. href="#*Dbs">*Dbs</a></code>. Each element in <code>lst</code> has a
  4972. number in its CAR (the block size scale factor of a database file, to be stored
  4973. in <code>*Dbs</code>). The CDR elements are either classes (so that objects of
  4974. that class are later stored in the corresponding file), or lists with a class in
  4975. the CARs and a list of relations in the CDRs (so that index trees for these
  4976. relations go into that file). See also <code><a
  4977. href="#dbs+">dbs+</a></code> and <code><a
  4978. href="#pool">pool</a></code>.
  4979.  
  4980. <pre><code>
  4981. (dbs
  4982. (3 +Role +User +Sal) # 512 Prevalent objects
  4983. (0 +Pos) # A:64 Tiny objects
  4984. (1 +Item +Ord) # B:128 Small objects
  4985. (2 +CuSu) # C:256 Normal objects
  4986. (2 (+Role nm) (+User nm) (+Sal nm)) # D:256 Small indexes
  4987. (4 (+CuSu nr plz tel mob)) # E:1024 Normal indexes
  4988. (4 (+CuSu nm)) # F:1024
  4989. (4 (+CuSu ort)) # G:1024
  4990. (4 (+Item nr sup pr)) # H:1024
  4991. (4 (+Item nm)) # I:1024
  4992. (4 (+Ord nr dat cus)) # J:1024
  4993. (4 (+Pos itm)) ) # K:1024
  4994.  
  4995. : *Dbs
  4996. -> (1 2 1 0 2 4 4 4 4 4 4 4)
  4997. : (get '+Item 'Dbf)
  4998. -> (3 . 128)
  4999. : (get '+Item 'nr 'dbf)
  5000. -> (9 . 1024)
  5001. </code></pre>
  5002.  
  5003. <dt><a name="dbs+"><code>(dbs+ 'num . lst)</code></a>
  5004. <dd>Extends the list of database sizes stored in <code><a
  5005. href="#*Dbs">*Dbs</a></code>. <code>num</code> is the initial offset
  5006. into the list. See also <code><a href="#dbs">dbs</a></code>.
  5007.  
  5008. <pre><code>
  5009. (dbs+ 9
  5010. (1 +NewCls) # (9 . 128)
  5011. (3 (+NewCls nr nm)) ) # (10 . 512)
  5012. </code></pre>
  5013.  
  5014. <dt><a name="de"><code>(de sym . any) -> sym</code></a>
  5015. <dd>Assigns a definition to the <code>sym</code> argument, by setting its
  5016. <code>VAL</code> to the <code>any</code> argument. If the symbol has already
  5017. another value, a "redefined" message is issued. When the value of the global
  5018. variable <a href="#*Dbg">*Dbg</a> is non-<code>NIL</code>, the current
  5019. line number and file name (if any) are stored in the <code>*Dbg</code> property
  5020. of <code>sym</code>. <code>de</code> is the standard way to define a function.
  5021. See also <code><a href="#def">def</a></code>, <code><a
  5022. href="#dm">dm</a></code> and <code><a
  5023. href="#undef">undef</a></code>.
  5024.  
  5025. <pre><code>
  5026. : (de foo (X Y) (* X (+ X Y))) # Define a function
  5027. -> foo
  5028. : (foo 3 4)
  5029. -> 21
  5030.  
  5031. : (de *Var . 123) # Define a variable value
  5032. : *Var
  5033. -> 123
  5034. </code></pre>
  5035.  
  5036. <dt><a name="debug"><code>(debug 'sym) -> T</code></a>
  5037. <dt><code>(debug 'sym 'cls) -> T</code>
  5038. <dt><code>(debug '(sym . cls)) -> T</code>
  5039. <dd>(Debug mode only) Inserts a <code><a href="#!">!</a></code>
  5040. breakpoint function call at the beginning and all top-level expressions of the
  5041. function or method body of <code>sym</code>, to allow a stepwise execution.
  5042. Typing <code>(<a href="#d">d</a>)</code> at a breakpoint will also
  5043. debug the current subexpression, and <code>(<a href="#e">e</a>)</code>
  5044. will evaluate the current subexpression. The current subexpression is stored in
  5045. the global variable <code><a href="#^">^</a></code>. See also <code><a
  5046. href="#unbug">unbug</a></code>, <code><a
  5047. href="#*Dbg">*Dbg</a></code>, <code><a
  5048. href="#trace">trace</a></code> and <code><a
  5049. href="#lint">lint</a></code>.
  5050.  
  5051. <pre><code>
  5052. : (de tst (N) # Define tst
  5053. (println (+ 3 N)) )
  5054. -> tst
  5055. : (debug 'tst) # Set breakpoints
  5056. -> T
  5057. : (pp 'tst)
  5058. (de tst (N)
  5059. (! println (+ 3 N)) ) # Breakpoint '!'
  5060. -> tst
  5061. : (tst 7) # Execute
  5062. (println (+ 3 N)) # Stopped at beginning of 'tst'
  5063. ! (d) # Debug subexpression
  5064. -> T
  5065. ! # Continue
  5066. (+ 3 N) # Stopped in subexpression
  5067. ! N # Inspect variable 'N'
  5068. -> 7
  5069. ! # Continue
  5070. 10 # Output of print statement
  5071. -> 10 # Done
  5072. : (unbug 'tst)
  5073. -> T
  5074. : (pp 'tst) # Restore to original
  5075. (de tst (N)
  5076. (println (+ 3 N)) )
  5077. -> tst
  5078. </code></pre>
  5079.  
  5080. <dt><a name="dec"><code>(dec 'num) -> num</code></a>
  5081. <dt><code>(dec 'var ['num]) -> num</code>
  5082. <dd>The first form returns the value of <code>num</code> decremented by 1. The
  5083. second form decrements the <code>VAL</code> of <code>var</code> by 1, or by
  5084. <code>num</code>. If the first argument is <code>NIL</code>, it is returned
  5085. immediately. <code>(dec Num)</code> is equivalent to <code>(- Num 1)</code> and
  5086. <code>(dec 'Var)</code> is equivalent to <code>(set 'Var (- Var 1))</code>. See
  5087. also <code><a href="#inc">inc</a></code> and <code><a
  5088. href="#-">-</a></code>.
  5089.  
  5090. <pre><code>
  5091. : (dec -1)
  5092. -> -2
  5093. : (dec 7)
  5094. -> 6
  5095. : (setq N 7)
  5096. -> 7
  5097. : (dec 'N)
  5098. -> 6
  5099. : (dec 'N 3)
  5100. -> 3
  5101. </code></pre>
  5102.  
  5103. <dt><a name="def"><code>(def 'sym 'any) -> sym</code></a>
  5104. <dt><code>(def 'sym1 'sym2 'any) -> sym1</code>
  5105. <dd>The first form assigns a definition to the first <code>sym</code> argument,
  5106. by setting its <code>VAL</code>'s to <code>any</code>. The second form defines a
  5107. property value <code>any</code> for the first argument's <code>sym2</code> key.
  5108. If any of these values existed and was changed in the process, a "redefined"
  5109. message is issued. When the value of the global variable <a
  5110. href="#*Dbg">*Dbg</a> is non-<code>NIL</code>, the current line number
  5111. and file name (if any) are stored in the <code>*Dbg</code> property of
  5112. <code>sym</code>. See also <code><a href="#de">de</a></code> and
  5113. <code><a href="#dm">dm</a></code>.
  5114.  
  5115. <pre><code>
  5116. : (def 'b '((X Y) (* X (+ X Y))))
  5117. -> b
  5118. : (def 'b 999)
  5119. # b redefined
  5120. -> b
  5121. </code></pre>
  5122.  
  5123. <dt><a name="default"><code>(default var 'any ..) -> any</code></a>
  5124. <dd>Stores new values <code>any</code> in the <code>var</code> arguments only if
  5125. their current values are <code>NIL</code>. Otherwise, their values are left
  5126. unchanged. In any case, the last <code>var</code>'s value is returned.
  5127. <code>default</code> is used typically in functions to initialize optional
  5128. arguments.
  5129.  
  5130. <pre><code>
  5131. : (de foo (A B) # Function with two optional arguments
  5132. (default A 1 B 2) # The default values are 1 and 2
  5133. (list A B) )
  5134. -> foo
  5135. : (foo 333 444) # Called with two arguments
  5136. -> (333 444)
  5137. : (foo 333) # Called with one arguments
  5138. -> (333 2)
  5139. : (foo) # Called without arguments
  5140. -> (1 2)
  5141. </code></pre>
  5142.  
  5143. <dt><a name="del"><code>(del 'any 'var) -> lst</code></a>
  5144. <dd>Deletes <code>any</code> from the list in the value of <code>var</code>, and
  5145. returns the remaining list. <code>(del 'any 'var)</code> is equivalent to
  5146. <code>(set 'var (delete 'any var))</code>. See also <code><a
  5147. href="#delete">delete</a></code>, <code><a
  5148. href="#cut">cut</a></code> and <code><a
  5149. href="#pop">pop</a></code>.
  5150.  
  5151. <pre><code>
  5152. : (setq S '((a b c) (d e f)))
  5153. -> ((a b c) (d e f))
  5154. : (del '(d e f) 'S)
  5155. -> ((a b c))
  5156. : (del 'b S)
  5157. -> (a c)
  5158. </code></pre>
  5159.  
  5160. <dt><a name="delete"><code>(delete 'any 'lst) -> lst</code></a>
  5161. <dd>Deletes <code>any</code> from <code>lst</code>. If <code>any</code> is
  5162. contained more than once in <code>lst</code>, only the first occurrence is
  5163. deleted. See also <code><a href="#delq">delq</a></code>, <code><a
  5164. href="#del">del</a></code>, <code><a
  5165. href="#remove">remove</a></code> and <code><a
  5166. href="#insert">insert</a></code>.
  5167.  
  5168. <pre><code>
  5169. : (delete 2 (1 2 3))
  5170. -> (1 3)
  5171. : (delete (3 4) '((1 2) (3 4) (5 6) (3 4)))
  5172. -> ((1 2) (5 6) (3 4))
  5173. </code></pre>
  5174.  
  5175. <dt><a name="delete/3"><code>delete/3</code></a>
  5176. <dd><a href="#pilog">Pilog</a> predicate that succeeds if deleting the
  5177. first argument from the list in the second argument is equal to the third
  5178. argument. See also <code><a href="#delete">delete</a></code> and
  5179. <code><a href="#member/2">member/2</a></code>.
  5180.  
  5181. <pre><code>
  5182. : (? (delete b (a b c) @X))
  5183. @X=(a c)
  5184. -> NIL
  5185. </code></pre>
  5186.  
  5187. <dt><a name="delq"><code>(delq 'any 'lst) -> lst</code></a>
  5188. <dd>Deletes <code>any</code> from <code>lst</code>. If <code>any</code> is
  5189. contained more than once in <code>lst</code>, only the first occurrence is
  5190. deleted. <code><a href="#==">==</a></code> is used for comparison
  5191. (pointer equality). See also <code><a href="#delete">delete</a></code>,
  5192. <code><a href="#asoq">asoq</a></code>, <code><a
  5193. href="#push1q">push1q</a></code>, <code><a
  5194. href="#memq">memq</a></code>, <code><a
  5195. href="#mmeq">mmeq</a></code> and <a href="ref.html#cmp">Comparing</a>.
  5196.  
  5197. <pre><code>
  5198. : (delq 'b '(a b c))
  5199. -> (a c)
  5200. : (delq (2) (1 (2) 3))
  5201. -> (1 (2) 3)
  5202. </code></pre>
  5203.  
  5204. <dt><a name="dep"><code>(dep 'cls) -> cls</code></a>
  5205. <dd>(Debug mode only) Displays the "dependencies" of <code>cls</code>, i.e. the
  5206. tree of superclasses and the tree of subclasses. See also <a
  5207. href="#oop">OO Concepts</a>, <code><a
  5208. href="#methods">methods</a></code>, <code><a
  5209. href="#class">class</a></code>, <code><a
  5210. href="#what">what</a></code>, <code><a
  5211. href="#who">who</a></code>, <code><a
  5212. href="#has">has</a></code> and and <code><a
  5213. href="#can">can</a></code>.
  5214.  
  5215. <pre><code>
  5216. : (dep '+Number) # Dependencies of '+Number'
  5217. +relation # Single superclass is '+relation'
  5218. +Number
  5219. +Date # Subclasses are '+Date' and '+Time'
  5220. +Time
  5221. -> +Number
  5222. </code></pre>
  5223.  
  5224. <dt><a name="depth"><code>(depth 'lst) -> (cnt1 . cnt2)</code></a>
  5225. <dd>Returns the maximal (<code>cnt1</code>) and the average (<code>cnt2</code>)
  5226. "depth" of a tree structure as maintained by <code><a
  5227. href="#idx">idx</a></code>. The total number of nodes is stored in the
  5228. global variable <code><a href="#@@">@@</a></code>. See also <code><a
  5229. href="#length">length</a></code> and <code><a
  5230. href="#size">size</a></code>.
  5231.  
  5232. <pre><code>
  5233. : (off X) # Clear variable
  5234. -> NIL
  5235. : (for N (1 2 3 4 5 6 7) (idx 'X N T)) # Build a degenerated tree
  5236. -> NIL
  5237. : X
  5238. -> (1 NIL 2 NIL 3 NIL 4 NIL 5 NIL 6 NIL 7) # Only right branches
  5239. : (depth X)
  5240. -> (7 . 4) # Depth is 7, average 4
  5241.  
  5242. : (balance 'X (1 2 3 4 5 6 7)) # Build a balanced tree
  5243. -> NIL
  5244. : (depth X)
  5245. -> (3 . 2) # Depth is 3, average 2
  5246. </code></pre>
  5247.  
  5248. <dt><a name="diff"><code>(diff 'lst 'lst) -> lst</code></a>
  5249. <dd>Returns the difference of the <code>lst</code> arguments. See also <code><a
  5250. href="#sect">sect</a></code>.
  5251.  
  5252. <pre><code>
  5253. : (diff (1 2 3 4 5) (2 4))
  5254. -> (1 3 5)
  5255. : (diff (1 2 3) (1 2 3))
  5256. -> NIL
  5257. </code></pre>
  5258.  
  5259. <dt><a name="different/2"><code>different/2</code></a>
  5260. <dd><a href="#pilog">Pilog</a> predicate that succeeds if the two
  5261. arguments are different. See also <code><a
  5262. href="#equal/2">equal/2</a></code>.
  5263.  
  5264. <pre><code>
  5265. : (? (different 3 4))
  5266. -> T
  5267. </code></pre>
  5268.  
  5269. <dt><a name="dir"><code>(dir ['any] ['flg]) -> lst</code></a>
  5270. <dd>Returns a list of all filenames in the directory <code>any</code>. Names
  5271. starting with a dot '<code>.</code>' are ignored, unless <code>flg</code> is
  5272. non-<code>NIL</code>. See also <code><a href="#cd">cd</a></code> and
  5273. <code><a href="#info">info</a></code>.
  5274.  
  5275. <pre><code>
  5276. : (filter '((F) (tail '(. c) (chop F))) (dir "src/"))
  5277. -> ("main.c" "subr.c" "gc.c" "io.c" "big.c" "sym.c" "tab.c" "flow.c" ..
  5278. </code></pre>
  5279.  
  5280. <dt><a name="dirname"><code>(dirname 'any) -> sym</code></a>
  5281. <dd>Returns the directory part of a path name <code>any</code>. See also
  5282. <code><a href="#basename">basename</a></code> and <code><a
  5283. href="#path">path</a></code>.
  5284.  
  5285. <pre><code>
  5286. : (dirname "a/b/c/d")
  5287. -> "a/b/c/"
  5288. </code></pre>
  5289.  
  5290. <dt><a name="dm"><code>(dm sym . fun|cls2) -> sym</code></a>
  5291. <dt><code>(dm (sym . cls) . fun|cls2) -> sym</code>
  5292. <dt><code>(dm (sym sym2 [. cls]) . fun|cls2) -> sym</code>
  5293. <dd>Defines a method for the message <code>sym</code> in the current class,
  5294. implicitly given by the value of the global variable <code><a
  5295. href="#*Class">*Class</a></code>, or - in the second form - for the
  5296. explicitly given class <code>cls</code>. In the third form, the class object is
  5297. obtained by <code><a href="#get">get</a></code>ting <code>sym2</code>
  5298. from <code><a href="#*Class">*Class</a></code> (or <code>cls</code> if
  5299. given). If the method for that class existed and was changed in the process, a
  5300. "redefined" message is issued. If - instead of a method <code>fun</code> - a
  5301. symbol specifying another class <code>cls2</code> is given, the method from that
  5302. class is used (explicit inheritance). When the value of the global variable <a
  5303. href="#*Dbg">*Dbg</a> is non-<code>NIL</code>, the current line number
  5304. and file name (if any) are stored in the <code>*Dbg</code> property of
  5305. <code>sym</code>. See also <a href="#oop">OO Concepts</a>, <code><a
  5306. href="#de">de</a></code>, <code><a
  5307. href="#undef">undef</a></code>, <a href="refC.html#class">class</a>, <a
  5308. href="#rel">rel</a>, <a href="refV.html#var">var</a>, <a
  5309. href="#method">method</a>, <a href="refS.html#send">send</a> and <a
  5310. href="#try">try</a>.
  5311.  
  5312. <pre><code>
  5313. : (dm start> ()
  5314. (super)
  5315. (mapc 'start> (: fields))
  5316. (mapc 'start> (: arrays)) )
  5317.  
  5318. : (dm foo> . +OtherClass) # Explicitly inherit 'foo>' from '+OtherClass'
  5319. </code></pre>
  5320.  
  5321. <dt><a name="do"><code>(do 'flg|num ['any | (NIL 'any . prg) | (T 'any . prg) ..]) -> any</code></a>
  5322. <dd>Counted loop with multiple conditional exits: The body is executed at most
  5323. <code>num</code> times (or never (if the first argument is <code>NIL</code>), or
  5324. an infinite number of times (if the first argument is <code>T</code>)). If a
  5325. clause has <code>NIL</code> or <code>T</code> as its CAR, the clause's second
  5326. element is evaluated as a condition and - if the result is <code>NIL</code> or
  5327. non-<code>NIL</code>, respectively - the <code>prg</code> is executed and the
  5328. result returned. Otherwise (if count drops to zero), the result of the last
  5329. expression is returned. See also <code><a href="#loop">loop</a></code>
  5330. and <code><a href="#for">for</a></code>.
  5331.  
  5332. <pre><code>
  5333. : (do 4 (printsp 'OK))
  5334. OK OK OK OK -> OK
  5335. : (do 4 (printsp 'OK) (T (= 3 3) (printsp 'done)))
  5336. OK done -> done
  5337. </code></pre>
  5338.  
  5339. <dt><a name="doc"><code>(doc ['sym1] ['sym2])</code></a>
  5340. <dd>(Debug mode only) Opens a browser, and tries to display the reference
  5341. documentation for <code>sym1</code>. <code>sym2</code> may be the name of a
  5342. browser. If not given, the value of the environment variable
  5343. <code>BROWSER</code>, or the <code>w3m</code> browser is tried. If
  5344. <code>sym1</code> is <code>NIL</code>, the <a href="">PicoLisp
  5345. Reference</a> manual is opened. See also <a href="#fun">Function
  5346. Reference</a> and <code><a href="#vi">vi</a></code>.
  5347.  
  5348. <pre><code>
  5349. : (doc '+) # Function reference
  5350. -> T
  5351. : (doc '+relation) # Class reference
  5352. -> T
  5353. : (doc) # Reference manual
  5354. -> T
  5355. : (doc 'vi "firefox") # Use alternative browser
  5356. -> T
  5357. </code></pre>
  5358.  
  5359. </dl>
  5360.  
  5361. <h1><a name="E">E</a></h1>
  5362.  
  5363. <dl>
  5364.  
  5365. <dt><a name="*Err"><code>*Err</code></a>
  5366. <dd>A global variable holding a (possibly empty) <code>prg</code> body, which
  5367. will be executed during error processing. See also <code><a
  5368. href="#errors">Error Handling</a></code>, <code><a
  5369. href="#*Msg">*Msg</a></code> and <code><a
  5370. href="#^">^</a></code>.
  5371.  
  5372. <pre><code>
  5373. : (de *Err (prinl "Fatal error!"))
  5374. -> *Err
  5375. : (/ 3 0)
  5376. !? (/ 3 0)
  5377. Div/0
  5378. Fatal error!
  5379. ?
  5380. </code></pre>
  5381.  
  5382. <dt><a name="*Ext"><code>*Ext</code></a>
  5383. <dd>A global variable holding a sorted list of cons pairs. The CAR of each pair
  5384. specifies an external symbol offset (suitable for <code><a
  5385. href="#ext">ext</a></code>), and the CDR should be a function taking a
  5386. single external symbol as an argument. This function should return a list, with
  5387. the value for that symbol in its CAR, and the property list (in the format used
  5388. by <code><a href="#getl">getl</a></code> and <code><a
  5389. href="#putl">putl</a></code>) in its CDR. The symbol will be set to
  5390. this value and property list upon access. Typically this function will access
  5391. the corresponding symbol in a remote database process. See also <code><a
  5392. href="#qsym">qsym</a></code> and <code><a
  5393. href="#external">external symbols</a></code>.
  5394.  
  5395. <pre><code>
  5396. ### On the local machine ###
  5397. : (setq *Ext # Define extension functions
  5398. (mapcar
  5399. '((@Host @Ext)
  5400. (cons @Ext
  5401. (curry (@Host @Ext (Sock)) (Obj)
  5402. (when (or Sock (setq Sock (connect @Host 4040)))
  5403. (ext @Ext
  5404. (out Sock (pr (cons 'qsym Obj)))
  5405. (prog1
  5406. (in Sock (rd))
  5407. (unless @
  5408. (close Sock)
  5409. (off Sock) ) ) ) ) ) ) )
  5410. '("10.10.12.1" "10.10.12.2" "10.10.12.3" "10.10.12.4")
  5411. (20 40 60 80) ) )
  5412.  
  5413. ### On the remote machines ###
  5414. (de go ()
  5415. ...
  5416. (task (port 4040) # Set up background query server
  5417. (let? Sock (accept @) # Accept a connection
  5418. (unless (fork) # In child process
  5419. (in Sock
  5420. (while (rd) # Handle requests
  5421. (sync)
  5422. (out Sock
  5423. (pr (eval @)) ) ) )
  5424. (bye) ) # Exit child process
  5425. (close Sock) ) )
  5426. (forked) # Close task in children
  5427. ...
  5428.  
  5429. </code></pre>
  5430.  
  5431. <dt><a name="+Entity"><code>+Entity</code></a>
  5432. <dd>Base class of all database objects. See also <code><a
  5433. href="#+relation">+relation</a></code> and <a
  5434. href="#dbase">Database</a>.
  5435.  
  5436. <p><a name="entityMesssages">Messages</a> to entity objects include
  5437.  
  5438. <pre><code>
  5439. zap> () # Clean up relational structures, for removal from the DB
  5440. url> (Tab) # Call the GUI on that object (in optional Tab)
  5441. upd> (X Old) # Callback method when object is created/modified/deleted
  5442. has> (Var Val) # Check if value is present
  5443. put> (Var Val) # Put a new value
  5444. put!> (Var Val) # Put a new value, single transaction
  5445. del> (Var Val) # Delete value (also partial)
  5446. del!> (Var Val) # Delete value (also partial), single transaction
  5447. inc> (Var Val) # Increment numeric value
  5448. inc!> (Var Val) # Increment numeric value, single transaction
  5449. dec> (Var Val) # Decrement numeric value
  5450. dec!> (Var Val) # Decrement numeric value, single transaction
  5451. mis> (Var Val) # Return error message if value or type mismatch
  5452. lose1> (Var) # Delete relational structures for a single attribute
  5453. lose> (Lst) # Delete relational structures (excluding 'Lst')
  5454. lose!> () # Delete relational structures, single transaction
  5455. keep1> (Var) # Restore relational structures for single attribute
  5456. keep> (Lst) # Restore relational structures (excluding 'Lst')
  5457. keep?> (Lst) # Test for restauration (excluding 'Lst')
  5458. keep!> () # Restore relational structures, single transaction
  5459. set> (Val) # Set the value (type, i.e. class list)
  5460. set!> (Val) # Set the value, single transaction
  5461. clone> () # Object copy
  5462. clone!> () # Object copy, single transaction
  5463. </code></pre>
  5464.  
  5465. <dt><a name="e"><code>(e . prg) -> any</code></a>
  5466. <dd>Used in a breakpoint. Evaluates <code>prg</code> in the execution
  5467. environment, or the currently executed expression if <code>prg</code> is not
  5468. given. See also <code><a href="#debug">debug</a></code>, <code><a
  5469. href="#!">!</a></code>, <code><a href="ref_.html#^">^</a></code> and
  5470. <code><a href="#*Dbg">*Dbg</a></code>.
  5471.  
  5472. <pre><code>
  5473. : (! + 3 4)
  5474. (+ 3 4)
  5475. ! (e)
  5476. -> 7
  5477. </code></pre>
  5478.  
  5479. <dt><a name="echo"><code>(echo ['cnt ['cnt]] | ['sym ..]) -> sym</code></a>
  5480. <dd>Reads the current input channel, and writes to the current output channel.
  5481. If <code>cnt</code> is given, only that many bytes are actually echoed. In case
  5482. of two <code>cnt</code> arguments, the first one specifies the number of bytes
  5483. to skip in the input stream. Otherwise, if one or more <code>sym</code>
  5484. arguments are given, the echo process stops as soon as one of the symbol's names
  5485. is encountered in the input stream. In this case the name will be read and
  5486. returned, but not written. Returns non-<code>NIL</code> if the operation was
  5487. successfully completed. See also <code><a href="#from">from</a></code>.
  5488.  
  5489. <pre><code>
  5490. : (in "x.l" (echo)) # Display file on console
  5491. ..
  5492.  
  5493. : (out "x2.l" (in "x.l" (echo))) # Copy file "x.l" to "x2.l"
  5494. </code></pre>
  5495.  
  5496. <dt><a name="edit"><code>(edit 'sym ..) -> NIL</code></a>
  5497. <dd>(Debug mode only) Edits the value and property list of the argument
  5498. symbol(s) by calling the <code>vim</code> editor on a temporary file with these
  5499. data. When closing the editor, the modified data are read and stored into the
  5500. symbol(s). During the edit session, individual symbols are separated by the
  5501. pattern <code>(=======)</code>. These separators should not be modified. When
  5502. moving the cursor to the beginning of a symbol (no matter if internal, transient
  5503. or external), and hitting '<code>K</code>', that symbol is added to the
  5504. currently edited symbols. Hitting '<code>Q</code>' will go back one step and
  5505. return to the previously edited list of symbols.
  5506.  
  5507. <p><code>edit</code> is especially useful for browsing through the database
  5508. (with '<code>K</code>' and '<code>Q</code>'), inspecting external symbols, but
  5509. care must be taken when modifying any data as then the <a
  5510. href="#er">entity/relation</a> mechanisms are circumvented, and
  5511. <code><a href="#commit">commit</a></code> has to be called manually if
  5512. the changes should be persistent.
  5513.  
  5514. <p>Another typical use case is inserting or removing <code><a
  5515. href="#!">!</a></code> breakpoints at arbitrary code locations, or
  5516. doing other temporary changes to the code for debugging purposes.
  5517.  
  5518. <p>See also <code><a href="#update">update</a></code>, <code><a
  5519. href="#show">show</a></code>, <code><a
  5520. href="#vi">vi</a></code> and <code><a
  5521. href="#em">em</a></code>.
  5522.  
  5523. <pre><code>
  5524. : (edit (db 'nr '+Item 1)) # Edit a database symbol
  5525. ### 'vim' shows this ###
  5526. {3-1} (+Item)
  5527. nr 1
  5528. inv 100
  5529. pr 29900
  5530. sup {2-1} # (+CuSu)
  5531. nm "Main Part"
  5532.  
  5533. (=======)
  5534. ### Hitting 'K' on the '{' of '{2-1} ###
  5535. {2-1} (+CuSu)
  5536. nr 1
  5537. plz "3425"
  5538. mob "37 176 86303"
  5539. tel "37 4967 6846-0"
  5540. fax "37 4967 68462"
  5541. nm "Active Parts Inc."
  5542. nm2 "East Division"
  5543. ort "Freetown"
  5544. str "Wildcat Lane"
  5545. em "info@api.tld"
  5546.  
  5547. (=======)
  5548.  
  5549. {3-1} (+Item)
  5550. nr 1
  5551. inv 100
  5552. pr 29900
  5553. sup {2-1} # (+CuSu)
  5554. nm "Main Part"
  5555.  
  5556. (=======)
  5557. ### Entering ':q' in vim ###
  5558. -> NIL
  5559. </code></pre>
  5560.  
  5561. <dt><a name="em"><code>(em 'sym) -> sym</code></a>
  5562. <dt><code>(em 'sym 'cls) -> sym</code>
  5563. <dt><code>(em '(sym . cls)) -> sym</code>
  5564. <dt><code>(em) -> NIL</code>
  5565. <dd>(Debug mode only) Opens the "emacs" editor on the function or method
  5566. definition of <code>sym</code>. A call to <code><a
  5567. href="#ld">ld</a></code> thereafter will <code><a
  5568. href="#load">load</a></code> the modified file. A call without
  5569. arguments permanently switches the REPL line editor and the <code><a
  5570. href="#edit">edit</a></code> function to "emacs" mode. See also
  5571. <code><a href="#doc">doc</a></code>, <code><a
  5572. href="#edit">edit</a></code>, <code><a
  5573. href="#vi">vi</a></code>, <code><a
  5574. href="#*Dbg">*Dbg</a></code>, <code><a
  5575. href="#debug">debug</a></code> and <code><a
  5576. href="#pp">pp</a></code>.
  5577.  
  5578. <pre><code>
  5579. : (em 'url> '+CuSu) # Edit the method's source code, then exit from 'emacs'
  5580. -> T
  5581. </code></pre>
  5582.  
  5583. <dt><a name="env"><code>(env ['lst] | ['sym 'val] ..) -> lst</code></a>
  5584. <dd>Return a list of symbol-value pairs of all dynamically bound symbols if
  5585. called without arguments, or of the symbols or symbol-value pairs in
  5586. <code>lst</code>, or the explicitly given <code>sym</code>-<code>val</code>
  5587. arguments. See also <code><a href="#bind">bind</a></code>, <code><a
  5588. href="#job">job</a></code>, <code><a
  5589. href="#trail">trail</a></code> and <code><a
  5590. href="#up">up</a></code>.
  5591.  
  5592. <pre><code>
  5593. : (env)
  5594. -> NIL
  5595. : (let (A 1 B 2) (env))
  5596. -> ((A . 1) (B . 2))
  5597. : (let (A 1 B 2) (env '(A B)))
  5598. -> ((B . 2) (A . 1))
  5599. : (let (A 1 B 2) (env 'X 7 '(A B (C . 3)) 'Y 8))
  5600. -> ((Y . 8) (C . 3) (B . 2) (A . 1) (X . 7))
  5601. </code></pre>
  5602.  
  5603. <dt><a name="eof"><code>(eof ['flg]) -> flg</code></a>
  5604. <dd>Returns the end-of-file status of the current input channel. If
  5605. <code>flg</code> is non-<code>NIL</code>, the channel's status is forced to
  5606. end-of-file, so that the next call to <code>eof</code> will return
  5607. <code>T</code>, and calls to <code><a href="#char">char</a></code>,
  5608. <code><a href="#peek">peek</a></code>, <code><a
  5609. href="#line">line</a></code>, <code><a
  5610. href="#from">from</a></code>, <code><a
  5611. href="#till">till</a></code>, <code><a
  5612. href="#read">read</a></code> or <code><a
  5613. href="#skip">skip</a></code> will return <code>NIL</code>. Note that
  5614. <code>eof</code> cannot be used with the binary <code><a
  5615. href="#rd">rd</a></code> function. See also <code><a
  5616. href="#eol">eol</a></code>.
  5617.  
  5618. <pre><code>
  5619. : (in "file" (until (eof) (println (line T))))
  5620. ...
  5621. </code></pre>
  5622.  
  5623. <dt><a name="eol"><code>(eol) -> flg</code></a>
  5624. <dd>Returns the end-of-line status of the current input channel.
  5625. See also <code><a href="#eof">eof</a></code>.
  5626.  
  5627. <pre><code>
  5628. : (make (until (prog (link (read)) (eol)))) # Read line into a list
  5629. a b c (d e f) 123
  5630. -> (a b c (d e f) 123)
  5631. </code></pre>
  5632.  
  5633. <dt><a name="equal/2"><code>equal/2</code></a>
  5634. <dd><a href="#pilog">Pilog</a> predicate that succeeds if the two
  5635. arguments are equal. See also <code><a href="#=">=</a></code>, <code><a
  5636. href="#different/2">different/2</a></code> and <code><a
  5637. href="#member/2">member/2</a></code>.
  5638.  
  5639. <pre><code>
  5640. : (? (equal 3 4))
  5641. -> NIL
  5642. : (? (equal @N 7))
  5643. @N=7
  5644. -> NIL
  5645. </code></pre>
  5646.  
  5647. <dt><a name="err"><code>(err 'sym . prg) -> any</code></a>
  5648. <dd>Redirects the standard error stream to <code>sym</code> during the execution
  5649. of <code>prg</code>. The current standard error stream will be saved and
  5650. restored appropriately. If the argument is <code>NIL</code>, the current output
  5651. stream will be used. Otherwise, <code>sym</code> is taken as a file name (opened
  5652. in "append" mode if the first character is "+"), where standard error is to be
  5653. written to. See also <code><a href="#in">in</a></code>, <code><a
  5654. href="#out">out</a></code> and <code><a
  5655. href="#ctl">ctl</a></code>.
  5656.  
  5657. <pre><code>
  5658. : (err "/dev/null" # Suppress error messages
  5659. (call 'ls 'noSuchFile) )
  5660. -> NIL
  5661. </code></pre>
  5662.  
  5663. <dt><a name="errno"><code>(errno) -> cnt</code></a>
  5664. <dd>(64-bit version only) Returns the value of the standard I/O 'errno'
  5665. variable. See also <code><a href="#native">native</a></code>.
  5666.  
  5667. <pre><code>
  5668. : (in "foo") # Produce an error
  5669. !? (in "foo")
  5670. "foo" -- Open error: No such file or directory
  5671. ? (errno)
  5672. -> 2 # Returned 'ENOENT'
  5673. </code></pre>
  5674.  
  5675. <dt><a name="eval"><code>(eval 'any ['cnt ['lst]]) -> any</code></a>
  5676. <dd>Evaluates <code>any</code>. Note that because of the standard argument
  5677. evaluation, <code>any</code> is actually evaluated twice. If a binding
  5678. environment offset <code>cnt</code> is given, the second evaluation takes place
  5679. in the corresponding environment, and an optional <code>lst</code> of excluded
  5680. symbols can be supplied. See also <code><a href="#run">run</a></code>
  5681. and <code><a href="#up">up</a></code>.
  5682.  
  5683. <pre><code>
  5684. : (eval (list '+ 1 2 3))
  5685. -> 6
  5686. : (setq X 'Y Y 7)
  5687. -> 7
  5688. : X
  5689. -> Y
  5690. : Y
  5691. -> 7
  5692. : (eval X)
  5693. -> 7
  5694.  
  5695. : (de f (A)
  5696. (list
  5697. (eval 'A)
  5698. (eval 'A 1)
  5699. (eval 'A 2) ) )
  5700. -> f
  5701. : (de g (A)
  5702. (f (inc A)) )
  5703. -> g
  5704. : (one A)
  5705. -> 1
  5706. : (g (inc A))
  5707. -> (3 2 1)
  5708. </code></pre>
  5709.  
  5710. <dt><a name="expDat"><code>(expDat 'sym) -> dat</code></a>
  5711. <dd>Expands a <code><a href="#date">date</a></code> string according to
  5712. the current <code><a href="#locale">locale</a></code> (delimiter, and
  5713. order of year, month and day). Accepts abbreviated input, without delimiter and
  5714. with only the day, or the day and month, or the day, month and year of current
  5715. century. See also <code><a href="#datStr">datStr</a></code>, <code><a
  5716. href="#day">day</a></code>, <code><a
  5717. href="#expTel">expTel</a></code>.
  5718.  
  5719. <pre><code>
  5720. : (date)
  5721. -> 733133
  5722. : (date (date))
  5723. -> (2007 5 31)
  5724. : (expDat "31")
  5725. -> 733133
  5726. : (expDat "315")
  5727. -> 733133
  5728. : (expDat "3105")
  5729. -> 733133
  5730. : (expDat "31057")
  5731. -> 733133
  5732. : (expDat "310507")
  5733. -> 733133
  5734. : (expDat "2007-05-31")
  5735. -> 733133
  5736. : (expDat "7-5-31")
  5737. -> 733133
  5738.  
  5739. : (locale "DE" "de")
  5740. -> NIL
  5741. : (expDat "31.5")
  5742. -> 733133
  5743. : (expDat "31.5.7")
  5744. -> 733133
  5745. </code></pre>
  5746.  
  5747. <dt><a name="exec"><code>(exec 'any ..)</code></a>
  5748. <dd>Executes an external system command. The <code>any</code> arguments specify
  5749. the command and its arguments. Does not return to the caller; the current
  5750. process is replaced with a new process image. See also <code><a
  5751. href="#fork">fork</a></code> and <code><a
  5752. href="#call">call</a></code>.
  5753.  
  5754. <pre><code>
  5755. : (pipe (exec 'echo 123 "abc")
  5756. (list (read) (read)) )
  5757. -> (123 abc)
  5758.  
  5759. (unless (fork)
  5760. (exec "@bin/ssl" # Start replication process
  5761. "10.11.12.13" 443
  5762. "app/!replica" "key/app" "fifo/app" "db/app/blob/" 20 ) )
  5763. </code></pre>
  5764.  
  5765. <dt><a name="expTel"><code>(expTel 'sym) -> sym</code></a>
  5766. <dd>Expands a telephone number string. Multiple spaces or hyphens are coalesced.
  5767. A leading <code>+</code> or <code>00</code> is removed, a leading <code>0</code>
  5768. is replaced with the current country code. Otherwise, <code>NIL</code> is
  5769. returned. See also <code><a href="#telStr">telStr</a></code>, <code><a
  5770. href="#expDat">expDat</a></code> and <code><a
  5771. href="#locale">locale</a></code>.
  5772.  
  5773. <pre><code>
  5774. : (expTel "+49 1234 5678-0")
  5775. -> "49 1234 5678-0"
  5776. : (expTel "0049 1234 5678-0")
  5777. -> "49 1234 5678-0"
  5778. : (expTel "01234 5678-0")
  5779. -> NIL
  5780. : (locale "DE" "de")
  5781. -> NIL
  5782. : (expTel "01234 5678-0")
  5783. -> "49 1234 5678-0"
  5784. </code></pre>
  5785.  
  5786. <dt><a name="expr"><code>(expr 'sym) -> fun</code></a>
  5787. <dd>Converts a C-function ("subr") to a Lisp-function. Useful only for normal
  5788. functions (i.e. functions that evaluate all arguments). See also <code><a
  5789. href="#subr">subr</a></code>.
  5790.  
  5791. <pre><code>
  5792. : car
  5793. -> 67313448
  5794. : (expr 'car)
  5795. -> (@ (pass $385260187))
  5796. : (car (1 2 3))
  5797. -> 1
  5798. </code></pre>
  5799.  
  5800. <dt><a name="ext"><code>(ext 'cnt . prg) -> any</code></a>
  5801. <dd>During the execution of <code>prg</code>, all <code><a
  5802. href="#external">external symbols</a></code> processed by <code><a
  5803. href="#rd">rd</a></code>, <code><a href="refP.html#pr">pr</a></code> or
  5804. <code><a href="#udp">udp</a></code> are modified by an offset
  5805. <code>cnt</code> suitable for mapping via the <code><a
  5806. href="#*Ext">*Ext</a></code> mechanism. All external symbol's file
  5807. numbers are decremented by <code>cnt</code> during output, and incremented by
  5808. <code>cnt</code> during input.
  5809.  
  5810. <pre><code>
  5811. : (out 'a (ext 5 (pr '({6-2} ({8-9} . a) ({7-7} . b)))))
  5812. -> ({6-2} ({8-9} . a) ({7-7} . b))
  5813.  
  5814. : (in 'a (rd))
  5815. -> ({2} ({3-9} . a) ({2-7} . b))
  5816.  
  5817. : (in 'a (ext 5 (rd)))
  5818. -> ({6-2} ({8-9} . a) ({7-7} . b))
  5819. </code></pre>
  5820.  
  5821. <dt><a name="ext?"><code>(ext? 'any) -> sym | NIL</code></a>
  5822. <dd>Returns the argument <code>any</code> when it is an existing external
  5823. symbol, otherwise <code>NIL</code>. See also <code><a
  5824. href="#sym?">sym?</a></code>, <code><a
  5825. href="#box?">box?</a></code>, <code><a
  5826. href="#str?">str?</a></code>, <code><a
  5827. href="#extern">extern</a></code> and <code><a
  5828. href="#lieu">lieu</a></code>.
  5829.  
  5830. <pre><code>
  5831. : (ext? *DB)
  5832. -> {1}
  5833. : (ext? 'abc)
  5834. -> NIL
  5835. : (ext? "abc")
  5836. -> NIL
  5837. : (ext? 123)
  5838. -> NIL
  5839. </code></pre>
  5840.  
  5841. <dt><a name="extend"><code>(extend cls) -> cls</code></a>
  5842. <dd>Extends the class <code>cls</code>, by storing it in the global variable
  5843. <code><a href="#*Class">*Class</a></code>. As a consequence, all
  5844. following method, relation and class variable definitions are applied to that
  5845. class. See also <a href="#oop">OO Concepts</a>, <code><a
  5846. href="#class">class</a></code>, <code><a
  5847. href="#dm">dm</a></code>, <code><a href="refV.html#var">var</a></code>,
  5848. <code><a href="#rel">rel</a></code>, <code><a
  5849. href="#type">type</a></code> and <code><a
  5850. href="#isa">isa</a></code>.
  5851.  
  5852. <pre><code>
  5853. </code></pre>
  5854.  
  5855. <dt><a name="extern"><code>(extern 'sym) -> sym | NIL</code></a>
  5856. <dd>Creates or finds an external symbol. If a symbol with the name
  5857. <code>sym</code> is already extern, it is returned. Otherwise, a new external
  5858. symbol is returned. <code>NIL</code> is returned if <code>sym</code> does not
  5859. exist in the database. See also <code><a
  5860. href="#intern">intern</a></code> and <code><a
  5861. href="#ext?">ext?</a></code>.
  5862.  
  5863. <pre><code>
  5864. : (extern "A1b")
  5865. -> {A1b}
  5866. : (extern "{A1b}")
  5867. -> {A1b}
  5868. </code></pre>
  5869.  
  5870. <dt><a name="extra"><code>(extra ['any ..]) -> any</code></a>
  5871. <dd>Can only be used inside methods. Sends the current message to the current
  5872. object <code>This</code>, this time starting the search for a method at the
  5873. remaining branches of the inheritance tree of the class where the current method
  5874. was found. See also <a href="#oop">OO Concepts</a>, <code><a
  5875. href="#super">super</a></code>, <code><a
  5876. href="#method">method</a></code>, <code><a
  5877. href="#meth">meth</a></code>, <code><a
  5878. href="#send">send</a></code> and <code><a
  5879. href="#try">try</a></code>.
  5880.  
  5881. <pre><code>
  5882. (dm key> (C) # 'key>' method of the '+Uppc' class
  5883. (uppc (extra C)) ) # Convert 'key>' of extra classes to upper case
  5884. </code></pre>
  5885.  
  5886. <dt><a name="extract"><code>(extract 'fun 'lst ..) -> lst</code></a>
  5887. <dd>Applies <code>fun</code> to each element of <code>lst</code>. When
  5888. additional <code>lst</code> arguments are given, their elements are also passed
  5889. to <code>fun</code>. Returns a list of all non-<code>NIL</code> values returned
  5890. by <code>fun</code>. <code>(extract 'fun 'lst)</code> is equivalent to
  5891. <code>(mapcar 'fun (filter 'fun 'lst))</code> or, for non-NIL results, to
  5892. <code>(mapcan '((X) (and (fun X) (cons @))) 'lst)</code>. See also <code><a
  5893. href="#filter">filter</a></code>, <code><a
  5894. href="#find">find</a></code>, <code><a
  5895. href="#pick">pick</a></code> and <code><a
  5896. href="#mapcan">mapcan</a></code>.
  5897.  
  5898. <pre><code>
  5899. : (setq A NIL B 1 C NIL D 2 E NIL F 3)
  5900. -> 3
  5901. : (filter val '(A B C D E F))
  5902. -> (B D F)
  5903. : (extract val '(A B C D E F))
  5904. -> (1 2 3)
  5905. </code></pre>
  5906.  
  5907. </dl>
  5908.  
  5909. <h1><a name="F">F</a></h1>
  5910.  
  5911. <dl>
  5912.  
  5913. <dt><a name="*Fork"><code>*Fork</code></a>
  5914. <dd>A global variable holding a (possibly empty) <code>prg</code> body, to be
  5915. executed after a call to <code><a href="#fork">fork</a></code> in the
  5916. child process.
  5917.  
  5918. <pre><code>
  5919. : (push '*Fork '(off *Tmp)) # Clear '*Tmp' in child process
  5920. -> (off *Tmp)
  5921. </code></pre>
  5922.  
  5923. <dt><a name="+Fold"><code>+Fold</code></a>
  5924. <dd>Prefix class for maintaining <code><a
  5925. href="#fold">fold</a></code>ed indexes to <code><a
  5926. href="#+String">+String</a></code> relations. Typically used in
  5927. combination with the <code><a href="#+Ref">+Ref</a></code> or <code><a
  5928. href="#+Idx">+Idx</a></code> prefix classes. See also <code><a
  5929. href="#+IdxFold">+IdxFold</a></code> and <a
  5930. href="#dbase">Database</a>.
  5931.  
  5932. <pre><code>
  5933. (rel nm (+Fold +Idx +String)) # Item Description
  5934. ...
  5935. (rel tel (+Fold +Ref +String)) # Phone number
  5936. </code></pre>
  5937.  
  5938. <dt><a name="fail"><code>(fail) -> lst</code></a>
  5939. <dd>Constructs an empty <a href="#pilog">Pilog</a> query, i.e. a query
  5940. that will always fail. See also <code><a href="#goal">goal</a></code>.
  5941.  
  5942. <pre><code>
  5943. (dm clr> () # Clear query chart in search dialogs
  5944. (query> This (fail)) )
  5945. </code></pre>
  5946.  
  5947. <dt><a name="fail/0"><code>fail/0</code></a>
  5948. <dd><a href="#pilog">Pilog</a> predicate that always fails. See also
  5949. <code><a href="#true/0">true/0</a></code>.
  5950.  
  5951. <pre><code>
  5952. : (? (fail))
  5953. -> NIL
  5954. </code></pre>
  5955.  
  5956. <dt><a name="fetch"><code>(fetch 'tree 'any) -> any</code></a>
  5957. <dd>Fetches a value for the key <code>any</code> from a database tree. See also
  5958. <code><a href="#tree">tree</a></code> and <code><a
  5959. href="#store">store</a></code>.
  5960.  
  5961. <pre><code>
  5962. : (fetch (tree 'nr '+Item) 2)
  5963. -> {3-2}
  5964. </code></pre>
  5965.  
  5966. <dt><a name="fifo"><code>(fifo 'var ['any ..]) -> any</code></a>
  5967. <dd>Implements a first-in-first-out structure using a circular list. When called
  5968. with <code>any</code> arguments, they will be concatenated to end of the
  5969. structure. Otherwise, the first element is removed from the structure and
  5970. returned. See also <code><a href="#queue">queue</a></code>, <code><a
  5971. href="#push">push</a></code>, <code><a
  5972. href="#pop">pop</a></code>, <code><a
  5973. href="#rot">rot</a></code> and <code><a
  5974. href="#circ">circ</a></code>.
  5975.  
  5976. <pre><code>
  5977. : (fifo 'X 1)
  5978. -> 1
  5979. : (fifo 'X 2 3)
  5980. -> 3
  5981. : X
  5982. -> (3 1 2 .)
  5983. : (fifo 'X)
  5984. -> 1
  5985. : (fifo 'X)
  5986. -> 2
  5987. : X
  5988. -> (3 .)
  5989. </code></pre>
  5990.  
  5991. <dt><a name="file"><code>(file) -> (sym1 sym2 . num) | NIL</code></a>
  5992. <dd>Returns for the current input channel the path name <code>sym1</code>, the
  5993. file name <code>sym2</code>, and the current line number <code>num</code>. If
  5994. the current input channel is not a file, <code>NIL</code> is returned. See also
  5995. <code><a href="#info">info</a></code>, <code><a
  5996. href="#in">in</a></code> and <code><a
  5997. href="#load">load</a></code>.
  5998.  
  5999. <pre><code>
  6000. : (load (pack (car (file)) "localFile.l")) # Load a file in same directory
  6001. </code></pre>
  6002.  
  6003. <dt><a name="fill"><code>(fill 'any ['sym|lst]) -> any</code></a>
  6004. <dd>Non-destructively fills a pattern <code>any</code>, by substituting
  6005. <code>sym</code>, or all symbols in <code>lst</code>, or - if no second argument
  6006. is given - each pattern symbol in <code>any</code> (see <code><a
  6007. href="#pat?">pat?</a></code>), with its current value. <code>@</code>
  6008. itself is not considered a pattern symbol here. Unmodified subexpressions are
  6009. shared. In any case, expressions following the symbol <code>^</code> should
  6010. evaluate to lists which are then (destructively) spliced into the result. See
  6011. also <code><a href="#match">match</a></code>.
  6012.  
  6013. <pre><code>
  6014. : (setq @X 1234 @Y (1 2 3 4))
  6015. -> (1 2 3 4)
  6016. : (fill '@X)
  6017. -> 1234
  6018. : (fill '(a b (c @X) ((@Y . d) e)))
  6019. -> (a b (c 1234) (((1 2 3 4) . d) e))
  6020. : (let X 2 (fill (1 X 3) 'X))
  6021. -> (1 2 3)
  6022.  
  6023. : (fill (1 ^ (list 'a 'b 'c) 9))
  6024. -> (1 a b c 9)
  6025.  
  6026. : (match '(This is @X) '(This is a pen))
  6027. -> T
  6028. : (fill '(Got ^ @X))
  6029. -> (Got a pen)
  6030. </code></pre>
  6031.  
  6032. <dt><a name="filter"><code>(filter 'fun 'lst ..) -> lst</code></a>
  6033. <dd>Applies <code>fun</code> to each element of <code>lst</code>. When
  6034. additional <code>lst</code> arguments are given, their elements are also passed
  6035. to <code>fun</code>. Returns a list of all elements of <code>lst</code> where
  6036. <code>fun</code> returned non-<code>NIL</code>. See also <code><a
  6037. href="#fish">fish</a></code>, <code><a
  6038. href="#find">find</a></code>, <code><a
  6039. href="#pick">pick</a></code> and <code><a
  6040. href="#extract">extract</a></code>.
  6041.  
  6042. <pre><code>
  6043. : (filter num? (1 A 2 (B) 3 CDE))
  6044. -> (1 2 3)
  6045. </code></pre>
  6046.  
  6047. <dt><a name="fin"><code>(fin 'any) -> num|sym</code></a>
  6048. <dd>Returns <code>any</code> if it is an atom, otherwise the CDR of its last
  6049. cell. See also <code><a href="#last">last</a></code> and <code><a
  6050. href="#tail">tail</a></code>.
  6051.  
  6052. <pre><code>
  6053. : (fin 'a)
  6054. -> a
  6055. : (fin '(a . b))
  6056. -> b
  6057. : (fin '(a b . c))
  6058. -> c
  6059. : (fin '(a b c))
  6060. -> NIL
  6061. </code></pre>
  6062.  
  6063. <dt><a name="finally"><code>(finally exe . prg) -> any</code></a>
  6064. <dd><code>prg</code> is executed, then <code>exe</code> is evaluated, and the
  6065. result of <code>prg</code> is returned. <code>exe</code> will also be evaluated
  6066. if <code>prg</code> does not terminate normally due to a runtime error or a call
  6067. to <code><a href="#throw">throw</a></code>. See also <code><a
  6068. href="#bye">bye</a></code>, <code><a
  6069. href="#catch">catch</a></code>, <code><a
  6070. href="#quit">quit</a></code> and <code><a href="ref.html#errors">Error
  6071. Handling</a></code>.
  6072.  
  6073. <pre><code>
  6074. : (finally (prinl "Done!")
  6075. (println 123)
  6076. (quit)
  6077. (println 456) )
  6078. 123
  6079. Done!
  6080. : (catch 'A
  6081. (finally (prinl "Done!")
  6082. (println 1)
  6083. (throw 'A 123)
  6084. (println 2) ) )
  6085. 1
  6086. Done!
  6087. -> 123
  6088. </code></pre>
  6089.  
  6090. <dt><a name="find"><code>(find 'fun 'lst ..) -> any</code></a>
  6091. <dd>Applies <code>fun</code> to successive elements of <code>lst</code> until
  6092. non-<code>NIL</code> is returned. Returns that element (and stores the
  6093. non-<code>NIL</code> value in the global variable <code><a
  6094. href="#@@">@@</a></code>), or <code>NIL</code> if <code>fun</code> did
  6095. not return non-<code>NIL</code> for any element of <code>lst</code>. When
  6096. additional <code>lst</code> arguments are given, their elements are also passed
  6097. to <code>fun</code>. See also <code><a href="#seek">seek</a></code>,
  6098. <code><a href="#pick">pick</a></code>, <code><a
  6099. href="#fully">fully</a></code> and <code><a
  6100. href="#filter">filter</a></code>.
  6101.  
  6102. <pre><code>
  6103. : (find pair (1 A 2 (B) 3 CDE))
  6104. -> (B)
  6105. : (find '((A B) (> A B)) (1 2 3 4 5 6) (6 5 4 3 2 1))
  6106. -> 4
  6107. : (find > (1 2 3 4 5 6) (6 5 4 3 2 1)) # shorter
  6108. -> 4
  6109. </code></pre>
  6110.  
  6111. <dt><a name="fish"><code>(fish 'fun 'any) -> lst</code></a>
  6112. <dd>Applies <code>fun</code> to each element - and recursively to all sublists -
  6113. of <code>any</code>. Returns a list of all items where <code>fun</code> returned
  6114. non-<code>NIL</code>. See also <code><a
  6115. href="#filter">filter</a></code>.
  6116.  
  6117. <pre><code>
  6118. : (fish gt0 '(a -2 (1 b (-3 c 2)) 3 d -1))
  6119. -> (1 2 3)
  6120. : (fish sym? '(a -2 (1 b (-3 c 2)) 3 d -1))
  6121. -> (a b c d)
  6122. </code></pre>
  6123.  
  6124. <dt><a name="flg?"><code>(flg? 'any) -> flg</code></a>
  6125. <dd>Returns <code>T</code> when the argument <code>any</code> is either
  6126. <code>NIL</code> or <code>T</code>. See also <code><a
  6127. href="#bool">bool</a></code>. <code>(flg? X)</code> is equivalent to
  6128. <code>(or (not X) (=T X))</code>.
  6129.  
  6130. <pre><code>
  6131. : (flg? (= 3 3))
  6132. -> T
  6133. : (flg? (= 3 4))
  6134. -> T
  6135. : (flg? (+ 3 4))
  6136. -> NIL
  6137. </code></pre>
  6138.  
  6139. <dt><a name="flip"><code>(flip 'lst ['cnt]) -> lst</code></a>
  6140. <dd>Returns <code>lst</code> (destructively) reversed. Without the optional
  6141. <code>cnt</code> argument, the whole list is flipped, otherwise only the first
  6142. <code>cnt</code> elements. See also <code><a
  6143. href="#reverse">reverse</a></code> and <code><a
  6144. href="#rot">rot</a></code>.
  6145.  
  6146. <pre><code>
  6147. : (flip (1 2 3 4)) # Flip all four elements
  6148. -> (4 3 2 1)
  6149. : (flip (1 2 3 4 5 6) 3) # Flip only the first three elements
  6150. -> (3 2 1 4 5 6)
  6151. </code></pre>
  6152.  
  6153. <dt><a name="flush"><code>(flush) -> flg</code></a>
  6154. <dd>Flushes the current output stream by writing all buffered data. A call to
  6155. <code>flush</code> for standard output is done automatically before a call to
  6156. <code><a href="#key">key</a></code>. Returns <code>T</code> when
  6157. successful. See also <code><a href="#rewind">rewind</a></code>.
  6158.  
  6159. <pre><code>
  6160. : (flush)
  6161. -> T
  6162. </code></pre>
  6163.  
  6164. <dt><a name="fmt64"><code>(fmt64 'num) -> sym</code></a>
  6165. <dt><code>(fmt64 'sym) -> num</code>
  6166. <dd>Converts a number <code>num</code> to a string in base-64 notation, or a
  6167. base-64 formatted string to a number. The digits are represented with the
  6168. characters <code>0</code> - <code>9</code>, <code>:</code>, <code>;</code>,
  6169. <code>A</code> - <code>Z</code> and <code>a</code> - <code>z</code>. This format
  6170. is used internally for the names of <code><a
  6171. href="#external-io">external symbols</a></code> in the 32-bit version.
  6172. See also <code><a href="#hax">hax</a></code>, <code><a
  6173. href="#hex">hex</a></code>, <code><a
  6174. href="#bin">bin</a></code> and <code><a
  6175. href="#oct">oct</a></code>.
  6176.  
  6177. <pre><code>
  6178. : (fmt64 9)
  6179. -> "9"
  6180. : (fmt64 10)
  6181. -> ":"
  6182. : (fmt64 11)
  6183. -> ";"
  6184. : (fmt64 12)
  6185. -> "A"
  6186. : (fmt64 "100")
  6187. -> 4096
  6188. </code></pre>
  6189.  
  6190. <dt><a name="fold"><code>(fold 'any ['cnt]) -> sym</code></a>
  6191. <dd>Folding to a canonical form: If <code>any</code> is not a symbol, it is
  6192. returned as it is. Otherwise, a new transient symbol with all digits and all
  6193. letters of <code>any</code>, converted to lower case, is returned. If the
  6194. <code>cnt</code> argument is given and non-zero, the result is truncated to that
  6195. length. See also <code><a href="#lowc">lowc</a></code>.
  6196.  
  6197. <pre><code>
  6198. : (fold " 1A 2-b/3")
  6199. -> "1a2b3"
  6200. : (fold " 1A 2-B/3" 3)
  6201. -> "1a2"
  6202. </code></pre>
  6203.  
  6204. <dt><a name="fold/3"><code>fold/3</code></a>
  6205. <dd><a href="#pilog">Pilog</a> predicate that succeeds if the first
  6206. argument, after <code><a href="#fold">fold</a></code>ing it to a
  6207. canonical form, is a <i>prefix</i> of the folded string representation of the
  6208. result of applying the <code><a href="#get">get</a></code> algorithm to
  6209. the following arguments. Typically used as filter predicate in <code><a
  6210. href="#select/3">select/3</a></code> database queries. See also
  6211. <code><a href="#pre?">pre?</a></code>, <code><a
  6212. href="#isa/2">isa/2</a></code>, <code><a
  6213. href="#same/3">same/3</a></code>, <code><a
  6214. href="#bool/3">bool/3</a></code>, <code><a
  6215. href="#range/3">range/3</a></code>, <code><a
  6216. href="#head/3">head/3</a></code>, <code><a
  6217. href="#part/3">part/3</a></code> and <code><a
  6218. href="#tolr/3">tolr/3</a></code>.
  6219.  
  6220. <pre><code>
  6221. : (?
  6222. @Nr (1 . 5)
  6223. @Nm "main"
  6224. (select (@Item)
  6225. ((nr +Item @Nr) (nm +Item @Nm))
  6226. (range @Nr @Item nr)
  6227. (fold @Nm @Item nm) ) )
  6228. @Nr=(1 . 5) @Nm="main" @Item={3-1}
  6229. -> NIL
  6230. </code></pre>
  6231.  
  6232. <dt><a name="for"><code>(for sym 'num ['any | (NIL 'any . prg) | (T 'any . prg) ..]) -> any</code></a>
  6233. <dt><code>(for sym|(sym2 . sym) 'lst ['any | (NIL 'any . prg) | (T 'any . prg) ..]) -> any</code>
  6234. <dt><code>(for (sym|(sym2 . sym) 'any1 'any2 [. prg]) ['any | (NIL 'any . prg) | (T 'any . prg) ..]) -> any</code>
  6235. <dd>Conditional loop with local variable(s) and multiple conditional exits:<br>
  6236. In the first form, the value of <code>sym</code> is saved, <code>sym</code> is
  6237. bound to <code>1</code>, and the body is executed with increasing values up to
  6238. (and including) <code>num</code>.<br>
  6239.  
  6240. In the second form, the value of <code>sym</code> is saved, <code>sym</code> is
  6241. subsequently bound to the elements of <code>lst</code>, and the body is executed
  6242. each time.<br>
  6243.  
  6244. In the third form, the value of <code>sym</code> is saved, and <code>sym</code>
  6245. is bound to <code>any1</code>. If <code>sym2</code> is given, it is treated as a
  6246. counter variable, first bound to 1 and then incremented for each execution of
  6247. the body. While the condition <code>any2</code> evaluates to
  6248. non-<code>NIL</code>, the body is repeatedly executed and, if <code>prg</code>
  6249. is given, <code>sym</code> is re-bound to the result of its evaluation.<br>
  6250.  
  6251. If a clause has <code>NIL</code> or <code>T</code> as its CAR, the clause's
  6252. second element is evaluated as a condition and - if the result is
  6253. <code>NIL</code> or non-<code>NIL</code>, respectively - the <code>prg</code> is
  6254. executed and the result returned. If the body is never executed,
  6255. <code>NIL</code> is returned.<br>
  6256.  
  6257. See also <code><a href="#do">do</a></code> and <code><a
  6258. href="#loop">loop</a></code>.
  6259.  
  6260. <pre><code>
  6261. # First form:
  6262. : (for N 5 (printsp N))
  6263. 1 2 3 4 5 -> 5
  6264. : (for N 5 (printsp N) (NIL (< N 3) (printsp 'enough)))
  6265. 1 2 3 enough -> enough
  6266. : (for N 5 (T (> N 3) (printsp 'enough)) (printsp N))
  6267. 1 2 3 enough -> enough
  6268.  
  6269. # Second form:
  6270. : (for X (1 a 2 b) (printsp X))
  6271. 1 a 2 b -> b
  6272. : (for (I . X) '(a b c) (println I X))
  6273. 1 a
  6274. 2 b
  6275. 3 c
  6276. -> c
  6277.  
  6278. # Third form:
  6279. : (for (L (1 2 3 4 5) L) (printsp (pop 'L)))
  6280. 1 2 3 4 5 -> 5
  6281. : (for (N 1 (>= 5 N) (inc N)) (printsp N))
  6282. 1 2 3 4 5 -> 5
  6283. : (for ((I . L) '(a b c d e f) L (cddr L)) (println I L))
  6284. 1 (a b c d e f)
  6285. 2 (c d e f)
  6286. 3 (e f)
  6287. -> (e f)
  6288. </code></pre>
  6289.  
  6290. <dt><a name="for/2"><code>for/2</code></a>
  6291. <dt><a name="for/3"><code>for/3</code></a>
  6292. <dt><a name="for/4"><code>for/4</code></a>
  6293. <dd><a href="#pilog">Pilog</a> predicate that generates a sequence of
  6294. numbers. See also <code><a href="#for">for</a></code> and <code><a
  6295. href="#range">range</a></code>.
  6296.  
  6297. <pre><code>
  6298. : (? (for @I 3))
  6299. @I=1
  6300. @I=2
  6301. @I=3
  6302. -> NIL
  6303.  
  6304. : (? (for @I 3 7))
  6305. @I=3
  6306. @I=4
  6307. @I=5
  6308. @I=6
  6309. @I=7
  6310. -> NIL
  6311.  
  6312. : (? (for @I 7 3 2))
  6313. @I=7
  6314. @I=5
  6315. @I=3
  6316. -> NIL
  6317. </code></pre>
  6318.  
  6319. <dt><a name="fork"><code>(fork) -> pid | NIL</code></a>
  6320. <dd>Forks a child process. Returns <code>NIL</code> in the child, and the
  6321. child's process ID <code>pid</code> in the parent. In the child, the
  6322. <code>VAL</code> of the global variable <code><a
  6323. href="#*Fork">*Fork</a></code> (should be a <code>prg</code>) is
  6324. executed. See also <code><a href="#exec">exec</a></code>, <code><a
  6325. href="#kids">kids</a></code>, <code><a
  6326. href="#pipe">pipe</a></code> and <code><a
  6327. href="#tell">tell</a></code>.
  6328.  
  6329. <pre><code>
  6330. : (unless (fork) (do 5 (println 'OK) (wait 1000)) (bye))
  6331. -> NIL
  6332. OK # Child's output
  6333. : OK
  6334. OK
  6335. OK
  6336. OK
  6337. </code></pre>
  6338.  
  6339. <dt><a name="forked"><code>(forked)</code></a>
  6340. <dd>Installs maintenance code in <code><a
  6341. href="#*Fork">*Fork</a></code> to close server sockets and clean up
  6342. <code><a href="#*Run">*Run</a></code> code in child processes. Should
  6343. only be called immediately after <code><a href="#task">task</a></code>.
  6344.  
  6345. <pre><code>
  6346. : (task -60000 60000 (msg 'OK)) # Install timer task
  6347. -> (-60000 60000 (msg 'OK))
  6348. : (forked) # No timer in child processes
  6349. -> (task -60000)
  6350. : *Run
  6351. -> ((-60000 56432 (msg 'OK)))
  6352. : *Fork
  6353. -> ((task -60000) (del '(saveHistory) '*Bye))
  6354. </code></pre>
  6355.  
  6356. <dt><a name="format"><code>(format 'num ['cnt ['sym1 ['sym2]]]) -> sym</code></a>
  6357. <dt><code>(format 'sym|lst ['cnt ['sym1 ['sym2]]]) -> num</code>
  6358. <dd>Converts a number <code>num</code> to a string, or a string
  6359. <code>sym|lst</code> to a number. In both cases, optionally a precision
  6360. <code>cnt</code>, a decimal-separator <code>sym1</code> and a
  6361. thousands-separator <code>sym2</code> can be supplied. Returns
  6362. <code>NIL</code> if the conversion is unsuccessful. See also <a
  6363. href="#num-io">Numbers</a>, <code><a
  6364. href="#pad">pad</a></code>, <code><a
  6365. href="#hex">hex</a></code>, <code><a
  6366. href="#oct">oct</a></code>, <code><a
  6367. href="#bin">bin</a></code> and <code><a
  6368. href="#round">round</a></code>.
  6369.  
  6370. <pre><code>
  6371. : (format 123456789) # Integer conversion
  6372. -> "123456789"
  6373. : (format 123456789 2) # Fixed point
  6374. -> "1234567.89"
  6375. : (format 123456789 2 ",") # Comma as decimal-separator
  6376. -> "1234567,89"
  6377. : (format 123456789 2 "," ".") # and period as thousands-separator
  6378. -> "1.234.567,89"
  6379.  
  6380. : (format "123456789") # String to number
  6381. -> 123456789
  6382. : (format (1 "23" (4 5 6)))
  6383. -> 123456
  6384. : (format "1234567.89" 4) # scaled to four digits
  6385. -> 12345678900
  6386. : (format "1.234.567,89") # separators not recognized
  6387. -> NIL
  6388. : (format "1234567,89" 4 ",")
  6389. -> 12345678900
  6390. : (format "1.234.567,89" 4 ",") # thousands-separator not recognized
  6391. -> NIL
  6392. : (format "1.234.567,89" 4 "," ".")
  6393. -> 12345678900
  6394. </code></pre>
  6395.  
  6396. <dt><a name="free"><code>(free 'cnt) -> (sym . lst)</code></a>
  6397. <dd>Returns, for the <code>cnt</code>'th database file, the next available
  6398. symbol <code>sym</code> (i.e. the first symbol greater than any symbol in the
  6399. database), and the list <code>lst</code> of free symbols. See also <code><a
  6400. href="#seq">seq</a></code>, <code><a
  6401. href="#zap">zap</a></code> and <code><a
  6402. href="#dbck">dbck</a></code>.
  6403.  
  6404. <pre><code>
  6405. : (pool "x") # A new database
  6406. -> T
  6407. : (new T) # Create a new symbol
  6408. -> {2}
  6409. : (new T) # Create another symbol
  6410. -> {3}
  6411. : (commit) # Commit changes
  6412. -> T
  6413. : (zap '{2}) # Delete the first symbol
  6414. -> {2}
  6415. : (free 1) # Show free list
  6416. -> ({4}) # {3} was the last symbol allocated
  6417. : (commit) # Commit the deletion of {2}
  6418. -> T
  6419. : (free 1) # Now {2} is in the free list
  6420. -> ({4} {2})
  6421. </code></pre>
  6422.  
  6423. <dt><a name="from"><code>(from 'any ..) -> sym</code></a>
  6424. <dd>Skips the current input channel until one of the strings <code>any</code> is
  6425. found, and starts subsequent reading from that point. The found <code>any</code>
  6426. argument, or <code>NIL</code> (if none is found) is returned. See also <code><a
  6427. href="#till">till</a></code> and <code><a
  6428. href="#echo">echo</a></code>.
  6429.  
  6430. <pre><code>
  6431. : (and (from "val='") (till "'" T))
  6432. test val='abc'
  6433. -> "abc"
  6434. </code></pre>
  6435.  
  6436. <dt><a name="full"><code>(full 'any) -> bool</code></a>
  6437. <dd>Returns <code>NIL</code> if <code>any</code> is a non-empty list with at
  6438. least one <code>NIL</code> element, otherwise <code>T</code>. <code>(full
  6439. X)</code> is equivalent to <code>(not (memq NIL X))</code>. See also <code><a
  6440. href="#fully">fully</a></code>.
  6441.  
  6442. <pre><code>
  6443. : (full (1 2 3))
  6444. -> T
  6445. : (full (1 NIL 3))
  6446. -> NIL
  6447. : (full 123)
  6448. -> T
  6449. </code></pre>
  6450.  
  6451. <dt><a name="fully"><code>(fully 'fun 'lst ..) -> flg</code></a>
  6452. <dd>Applies <code>fun</code> to successive elements of <code>lst</code>, and
  6453. returns <code>NIL</code> immediately if one of the results is <code>NIL</code>.
  6454. Otherwise, <code>T</code> is returned. When additional <code>lst</code>
  6455. arguments are given, their elements are also passed to <code>fun</code>.
  6456. <code>(fully foo Lst)</code> is equivalent to <code>(not (find '((X) (not (foo
  6457. X))) Lst))</code>. See also <code><a href="#find">find</a></code> and
  6458. <code><a href="#full">full</a></code>.
  6459.  
  6460. <pre><code>
  6461. : (fully gt0 (1 2 3))
  6462. -> T
  6463. : (fully gt0 (1 -2 3))
  6464. -> NIL
  6465. </code></pre>
  6466.  
  6467. <dt><a name="fun?"><code>(fun? 'any) -> any</code></a>
  6468. <dd>Returns <code>NIL</code> when the argument <code>any</code> is neither a
  6469. number suitable for a code-pointer, nor a list suitable for a lambda expression
  6470. (function). Otherwise a number is returned for a code-pointer, <code>T</code>
  6471. for a function without arguments, and a single formal parameter or a list of
  6472. formal parameters for a function. See also <code><a
  6473. href="#getd">getd</a></code>.
  6474.  
  6475. <pre><code>
  6476. : (fun? 1000000000) # Might be a code pointer
  6477. -> 1000000000
  6478. : (fun? 10000000000000000000) # Too big for a code pointer
  6479. -> NIL
  6480. : (fun? '((A B) (* A B))) # Lambda expression
  6481. -> (A B)
  6482. : (fun? '((A B) (* A B) . C)) # Not a lambda expression
  6483. -> NIL
  6484. : (fun? '(1 2 3 4)) # Not a lambda expression
  6485. -> NIL
  6486. : (fun? '((A 2 B) (* A B))) # Not a lambda expression
  6487. -> NIL
  6488. </code></pre>
  6489.  
  6490. </dl>
  6491.  
  6492. <h1><a name="G">G</a></h1>
  6493.  
  6494. <dl>
  6495.  
  6496. <dt><a name="gc"><code>(gc ['cnt [cnt2]]) -> cnt | NIL</code></a>
  6497. <dd>Forces a garbage collection. When <code>cnt</code> is given, so many
  6498. megabytes of free cells are reserved, increasing the heap size if necessary. If
  6499. <code>cnt</code> is zero, all currently unused heap blocks are purged,
  6500. decreasing the heap size if possible. If <code>cnt2</code> (64-bit version only)
  6501. is given, the reserve size (defaults to 1 megabyte) is set to that value. Before
  6502. collection (but after argument evaluation) the global variables <code><a
  6503. href="#@">@</a></code> and <code><a href="ref_.html#@@">@@</a></code>
  6504. are set to <code>NIL</code>. See also <code><a
  6505. href="#heap">heap</a></code>.
  6506.  
  6507. <pre><code>
  6508. : (gc)
  6509. -> NIL
  6510. : (heap)
  6511. -> 2
  6512. : (gc 4)
  6513. -> 4
  6514. : (heap)
  6515. -> 5
  6516. </code></pre>
  6517.  
  6518. <dt><a name="ge0"><code>(ge0 'any) -> num | NIL</code></a>
  6519. <dd>Returns <code>num</code> when the argument is a number and greater or equal
  6520. zero, otherwise <code>NIL</code>. See also <code><a
  6521. href="#lt0">lt0</a></code>, <code><a
  6522. href="#le0">le0</a></code>, <code><a
  6523. href="#gt0">gt0</a></code>, <code><a href="ref_.html#=0">=0</a></code>
  6524. and <code><a href="#n0">n0</a></code>.
  6525.  
  6526. <pre><code>
  6527. : (ge0 -2)
  6528. -> NIL
  6529. : (ge0 3)
  6530. -> 3
  6531. : (ge0 0)
  6532. -> 0
  6533. </code></pre>
  6534.  
  6535. <dt><a name="genKey"><code>(genKey 'sym 'cls ['hook ['num1 ['num2]]]) -> num</code></a>
  6536. <dd>Generates a key for a database tree. If a minimal key <code>num1</code>
  6537. and/or a maximal key <code>num2</code> is given, the next free number in that
  6538. range is returned. Otherwise, the current maximal key plus one is returned. See
  6539. also <code><a href="#useKey">useKey</a></code>, <code><a
  6540. href="#genStrKey">genStrKey</a></code> and <code><a
  6541. href="#maxKey">maxKey</a></code>.
  6542.  
  6543. <pre><code>
  6544. : (maxKey (tree 'nr '+Item))
  6545. -> 8
  6546. : (genKey 'nr '+Item)
  6547. -> 9
  6548. </code></pre>
  6549.  
  6550. <dt><a name="genStrKey"><code>(genStrKey 'sym 'sym 'cls ['hook]) -> sym</code></a>
  6551. <dd>Generates a unique string for a database tree, by prepending as many "# "
  6552. sequences as necessary. See also <code><a
  6553. href="#genKey">genKey</a></code>.
  6554.  
  6555. <pre><code>
  6556. : (genStrKey "ben" 'nm '+User)
  6557. -> "# ben"
  6558. </code></pre>
  6559.  
  6560. <dt><a name="get"><code>(get 'sym1|lst ['sym2|cnt ..]) -> any</code></a>
  6561. <dd>Fetches a value <code>any</code> from the properties of a symbol, or from a
  6562. list. From the first argument <code>sym1|lst</code>, values are retrieved in
  6563. successive steps by either extracting the value (if the next argument is zero)
  6564. or a property from a symbol, the <code><a
  6565. href="#asoq">asoq</a></code>ed element (if the next argument is a
  6566. symbol), the n'th element (if the next argument is a positive number) or the
  6567. n'th CDR (if the next argument is a negative number) from a list. See also
  6568. <code><a href="#put">put</a></code>, <code><a
  6569. href="#;">;</a></code> and <code><a href="ref_.html#:">:</a></code>.
  6570.  
  6571. <pre><code>
  6572. : (put 'X 'a 1)
  6573. -> 1
  6574. : (get 'X 'a)
  6575. -> 1
  6576. : (put 'Y 'link 'X)
  6577. -> X
  6578. : (get 'Y 'link)
  6579. -> X
  6580. : (get 'Y 'link 'a)
  6581. -> 1
  6582. : (get '((a (b . 1) (c . 2)) (d (e . 3) (f . 4))) 'a 'b)
  6583. -> 1
  6584. : (get '((a (b . 1) (c . 2)) (d (e . 3) (f . 4))) 'd 'f)
  6585. -> 4
  6586. : (get '(X Y Z) 2)
  6587. -> Y
  6588. : (get '(X Y Z) 2 'link 'a)
  6589. -> 1
  6590. </code></pre>
  6591.  
  6592. <dt><a name="getd"><code>(getd 'any) -> fun | NIL</code></a>
  6593. <dd>Returns <code>fun</code> if <code>any</code> is a symbol that has a function
  6594. definition, otherwise <code>NIL</code>. See also <code><a
  6595. href="#fun?">fun?</a></code>.
  6596.  
  6597. <pre><code>
  6598. : (getd '+)
  6599. -> 67327232
  6600. : (getd 'script)
  6601. -> ((File . @) (load File))
  6602. : (getd 1)
  6603. -> NIL
  6604.  
  6605. : ht:Fmt # Initially undefined
  6606. -> NIL
  6607. : (getd 'ht:Fmt) # Check shared library
  6608. -> 8790207171188
  6609. : ht:Fmt # Now defined
  6610. -> 8790207171188
  6611. </code></pre>
  6612.  
  6613. <dt><a name="getl"><code>(getl 'sym1|lst1 ['sym2|cnt ..]) -> lst</code></a>
  6614. <dd>Fetches the complete property list <code>lst</code> from a symbol. That
  6615. symbol is <code>sym1</code> (if no other arguments are given), or a symbol found
  6616. by applying the <code><a href="#get">get</a></code> algorithm to
  6617. <code>sym1|lst1</code> and the following arguments. See also <code><a
  6618. href="#putl">putl</a></code> and <code><a
  6619. href="#maps">maps</a></code>.
  6620.  
  6621. <pre><code>
  6622. : (put 'X 'a 1)
  6623. -> 1
  6624. : (put 'X 'b 2)
  6625. -> 2
  6626. : (put 'X 'flg T)
  6627. -> T
  6628. : (getl 'X)
  6629. -> (flg (2 . b) (1 . a))
  6630. </code></pre>
  6631.  
  6632. <dt><a name="glue"><code>(glue 'any 'lst) -> sym</code></a>
  6633. <dd>Builds a new transient symbol (string) by <code><a
  6634. href="#pack">pack</a></code>ing the <code>any</code> argument between
  6635. the individual elements of <code>lst</code>. See also <code><a
  6636. href="#text">text</a></code>.
  6637.  
  6638. <pre><code>
  6639. : (glue "," '(a b c d))
  6640. -> "a,b,c,d"
  6641. </code></pre>
  6642.  
  6643. <dt><a name="goal"><code>(goal '([pat 'any ..] . lst) ['sym 'any ..]) -> lst</code></a>
  6644. <dd>Constructs a <a href="#pilog">Pilog</a> query list from the list of
  6645. clauses <code>lst</code>. The head of the argument list may consist of a
  6646. sequence of pattern symbols (Pilog variables) and expressions, which are used
  6647. together with the optional <code>sym</code> and <code>any</code> arguments to
  6648. form an initial environment. See also <code><a
  6649. href="#prove">prove</a></code> and <code><a
  6650. href="#fail">fail</a></code>.
  6651.  
  6652. <pre><code>
  6653. : (goal '((likes John @X)))
  6654. -> (((1 (0) NIL ((likes John @X)) NIL T)))
  6655. : (goal '(@X 'John (likes @X @Y)))
  6656. -> (((1 (0) NIL ((likes @X @Y)) NIL ((0 . @X) 1 . John) T)))
  6657. </code></pre>
  6658.  
  6659. <dt><a name="group"><code>(group 'lst) -> lst</code></a>
  6660. <dd>Builds a list of lists, by grouping all elements of <code>lst</code> with
  6661. the same CAR into a common sublist. See also <a
  6662. href="#cmp">Comparing</a>, <code><a
  6663. href="#by">by</a></code>, <code><a
  6664. href="#sort">sort</a></code> and <code><a
  6665. href="#uniq">uniq</a></code>.
  6666.  
  6667. <pre><code>
  6668. : (group '((1 . a) (1 . b) (1 . c) (2 . d) (2 . e) (2 . f)))
  6669. -> ((1 a b c) (2 d e f))
  6670. : (by name group '("x" "x" "y" "z" "x" "z")))
  6671. -> (("x" "x" "x") ("y") ("z" "z"))
  6672. : (by length group '(123 (1 2) "abcd" "xyz" (1 2 3 4) "XY"))
  6673. -> ((123 "xyz") ((1 2) "XY") ("abcd" (1 2 3 4))
  6674. </code></pre>
  6675.  
  6676. <dt><a name="gt0"><code>(gt0 'any) -> num | NIL</code></a>
  6677. <dd>Returns <code>num</code> when the argument is a number and greater than
  6678. zero, otherwise <code>NIL</code>. See also <code><a
  6679. href="#lt0">lt0</a></code>, <code><a
  6680. href="#le0">le0</a></code>, <code><a
  6681. href="#ge0">ge0</a></code>, <code><a href="ref_.html#=0">=0</a></code>
  6682. and <code><a href="#n0">n0</a></code>.
  6683.  
  6684. <pre><code>
  6685. : (gt0 -2)
  6686. -> NIL
  6687. : (gt0 3)
  6688. -> 3
  6689. </code></pre>
  6690.  
  6691. </dl>
  6692.  
  6693. <h1><a name="H">H</a></h1>
  6694.  
  6695. <dl>
  6696.  
  6697. <dt><a name="*Hup"><code>*Hup</code></a>
  6698. <dd>Global variable holding a (possibly empty) <code>prg</code> body, which will
  6699. be executed when a SIGHUP signal is sent to the current process. See also
  6700. <code><a href="#alarm">alarm</a></code>, <code><a
  6701. href="#sigio">sigio</a></code> and <code><a
  6702. href="#*Sig1">*Sig[12]</a></code>.
  6703.  
  6704. <pre><code>
  6705. : (de *Hup (msg 'SIGHUP))
  6706. -> *Hup
  6707. </code></pre>
  6708.  
  6709. <dt><a name="+Hook"><code>+Hook</code></a>
  6710. <dd>Prefix class for <code><a href="#+relation">+relation</a></code>s,
  6711. typically <code><a href="#+Link">+Link</a></code> or <code><a
  6712. href="#+Joint">+Joint</a></code>. In essence, this maintains an local
  6713. database in the referred object. See also <a href="#dbase">Database</a>.
  6714.  
  6715. <pre><code>
  6716. (rel sup (+Hook +Link) (+Sup)) # Supplier
  6717. (rel nr (+Key +Number) sup) # Item number, unique per supplier
  6718. (rel dsc (+Ref +String) sup) # Item description, indexed per supplier
  6719. </code></pre>
  6720.  
  6721. <dt><a name="+Hook2"><code>+Hook2</code></a>
  6722. <dd>Prefix class for <code><a href="#+index">+index</a></code>
  6723. relations. It maintains both a normal (global) index, and an object-local index
  6724. in the corresponding <code><a href="#+Hook">+Hook</a></code> object.
  6725. See also <a href="#dbase">Database</a>.
  6726.  
  6727. <pre><code>
  6728. (rel nm (+Hook2 +IdxFold +String) 3 shop) # Global and shop-local index
  6729. </code></pre>
  6730.  
  6731. <dt><a name="has"><code>(has 'any) -> lst</code></a>
  6732. <dd>(Debug mode only) Returns a list of all internal symbols which have the
  6733. value <code>any</code>. See also <code><a href="#who">who</a></code>,
  6734. <code><a href="#can">can</a></code>, <code><a
  6735. href="#what">what</a></code> and <code><a
  6736. href="#dep">dep</a></code>.
  6737.  
  6738. <pre><code>
  6739. : +
  6740. -> 270310
  6741. : (has 270310)
  6742. -> (+ @)
  6743. : meth
  6744. -> 267259
  6745. : (has 267259)
  6746. -> (@ js> dec> inc> upd> ele> log> chk> val> del> rel> all> url> zap> clr> str> has>
  6747. </code></pre>
  6748.  
  6749. <dt><a name="hash"><code>(hash 'any) -> cnt</code></a>
  6750. <dd>Generates a 16-bit number (1-65536) from <code>any</code>, suitable as a
  6751. hash value for various purposes, like randomly balanced <code><a
  6752. href="#idx">idx</a></code> structures. See also <code><a
  6753. href="#cache">cache</a></code> and <code><a
  6754. href="#seed">seed</a></code>.
  6755.  
  6756. <pre><code>
  6757. : (hash 0)
  6758. -> 1
  6759. : (hash 1)
  6760. -> 55682
  6761. : (hash "abc")
  6762. -> 45454
  6763. </code></pre>
  6764.  
  6765. <dt><a name="hax"><code>(hax 'num) -> sym</code></a>
  6766. <dt><code>(hax 'sym) -> num</code>
  6767. <dd>Converts a number <code>num</code> to a string in hexadecimal/alpha
  6768. notation, or a hexadecimal/alpha formatted string to a number. The digits are
  6769. represented with '<code>@</code>' (zero) and the letters '<code>A</code>' -
  6770. '<code>O</code>' (from "alpha" to "omega"). This format is used internally for
  6771. the names of <code><a href="#external-io">external symbols</a></code> in
  6772. the 64-bit version. See also <code><a href="#fmt64">fmt64</a></code>,
  6773. <code><a href="#hex">hex</a></code>, <code><a
  6774. href="#bin">bin</a></code> and <code><a
  6775. href="#oct">oct</a></code>.
  6776.  
  6777. <pre><code>
  6778. : (hax 7)
  6779. -> "G"
  6780. : (hax 16)
  6781. -> "A@"
  6782. : (hax 255)
  6783. -> "OO"
  6784. : (hax "A")
  6785. -> 1
  6786. </code></pre>
  6787.  
  6788. <dt><a name="hd"><code>(hd 'sym ['cnt]) -> NIL</code></a>
  6789. <dd>(Debug mode only) Displays a hexadecimal dump of the file given by
  6790. <code>sym</code>, limited to <code>cnt</code> lines. See also <code><a
  6791. href="#proc">proc</a></code>.
  6792.  
  6793. <pre><code>
  6794. : (hd "lib.l" 4)
  6795. 00000000 23 20 32 33 64 65 63 30 39 61 62 75 0A 23 20 28 # 23dec09abu.# (
  6796. 00000010 63 29 20 53 6F 66 74 77 61 72 65 20 4C 61 62 2E c) Software Lab.
  6797. 00000020 20 41 6C 65 78 61 6E 64 65 72 20 42 75 72 67 65 Alexander Burge
  6798. 00000030 72 0A 0A 28 64 65 20 74 61 73 6B 20 28 4B 65 79 r..(de task (Key
  6799. -> NIL
  6800. </code></pre>
  6801.  
  6802. <dt><a name="head"><code>(head 'cnt|lst 'lst) -> lst</code></a>
  6803. <dd>Returns a new list made of the first <code>cnt</code> elements of
  6804. <code>lst</code>. If <code>cnt</code> is negative, it is added to the length of
  6805. <code>lst</code>. If the first argument is a <code>lst</code>, <code>head</code>
  6806. is a predicate function returning that argument list if it is <code>equal</code>
  6807. to the head of the second argument, and <code>NIL</code> otherwise. See also
  6808. <code><a href="#tail">tail</a></code> and <code><a
  6809. href="#pre?">pre?</a></code>.
  6810.  
  6811. <pre><code>
  6812. : (head 3 '(a b c d e f))
  6813. -> (a b c)
  6814. : (head 0 '(a b c d e f))
  6815. -> NIL
  6816. : (head 10 '(a b c d e f))
  6817. -> (a b c d e f)
  6818. : (head -2 '(a b c d e f))
  6819. -> (a b c d)
  6820. : (head '(a b c) '(a b c d e f))
  6821. -> (a b c)
  6822. </code></pre>
  6823.  
  6824. <dt><a name="head/3"><code>head/3</code></a>
  6825. <dd><a href="#pilog">Pilog</a> predicate that succeeds if the first
  6826. (string) argument is a prefix of the string representation of the result of
  6827. applying the <code><a href="#get">get</a></code> algorithm to the
  6828. following arguments. Typically used as filter predicate in <code><a
  6829. href="#select/3">select/3</a></code> database queries. See also
  6830. <code><a href="#pre?">pre?</a></code>, <code><a
  6831. href="#isa/2">isa/2</a></code>, <code><a
  6832. href="#same/3">same/3</a></code>, <code><a
  6833. href="#bool/3">bool/3</a></code>, <code><a
  6834. href="#range/3">range/3</a></code>, <code><a
  6835. href="#fold/3">fold/3</a></code>, <code><a
  6836. href="#part/3">part/3</a></code> and <code><a
  6837. href="#tolr/3">tolr/3</a></code>.
  6838.  
  6839. <pre><code>
  6840. : (?
  6841. @Nm "Muller"
  6842. @Tel "37"
  6843. (select (@CuSu)
  6844. ((nm +CuSu @Nm) (tel +CuSu @Tel))
  6845. (tolr @Nm @CuSu nm)
  6846. (head @Tel @CuSu tel) )
  6847. (val @Name @CuSu nm)
  6848. (val @Phone @CuSu tel) )
  6849. @Nm="Muller" @Tel="37" @CuSu={2-3} @Name="Miller" @Phone="37 4773 82534"
  6850. -> NIL
  6851. </code></pre>
  6852.  
  6853. <dt><a name="heap"><code>(heap 'flg) -> cnt</code></a>
  6854. <dd>Returns the total size of the cell heap space in megabytes. If
  6855. <code>flg</code> is non-<code>NIL</code>, the size of the currently free space
  6856. is returned. See also <code><a href="#stack">stack</a></code> and
  6857. <code><a href="#gc">gc</a></code>.
  6858.  
  6859. <pre><code>
  6860. : (gc 4)
  6861. -> 4
  6862. : (heap)
  6863. -> 5
  6864. : (heap T)
  6865. -> 4
  6866. </code></pre>
  6867.  
  6868. <dt><a name="hear"><code>(hear 'cnt) -> cnt</code></a>
  6869. <dd>Uses the file descriptor <code>cnt</code> as an asynchronous command input
  6870. channel. Any executable list received via this channel will be executed in the
  6871. background. As this mechanism is also used for inter-family communication (see
  6872. <code><a href="#tell">tell</a></code>), <code>hear</code> is usually
  6873. only called explicitly by a top level parent process.
  6874.  
  6875. <pre><code>
  6876. : (call 'mkfifo "fifo/cmd")
  6877. -> T
  6878. : (hear (open "fifo/cmd"))
  6879. -> 3
  6880. </code></pre>
  6881.  
  6882. <dt><a name="here"><code>(here ['sym]) -> sym</code></a>
  6883. <dd>Echoes the current input stream until <code>sym</code> is encountered, or
  6884. until end of file. See also <code><a href="#echo">echo</a></code>.
  6885.  
  6886. <pre><code>
  6887. $ cat hello.l
  6888. (html 0 "Hello" "lib.css" NIL
  6889. (&lt;h2&gt; NIL "Hello")
  6890. (here) )
  6891. &lt;p&gt;Hello!&lt;/p&gt;
  6892. &lt;p&gt;This is a test.&lt;/p&gt;
  6893.  
  6894. $ pil @lib/http.l @lib/xhtml.l hello.l
  6895. HTTP/1.0 200 OK
  6896. Server: PicoLisp
  6897. Date: Sun, 03 Jun 2007 11:41:27 GMT
  6898. Cache-Control: max-age=0
  6899. Cache-Control: no-cache
  6900. Content-Type: text/html; charset=utf-8
  6901.  
  6902. &lt;!DOCTYPE html&gt;
  6903. &lt;html lang="en"&gt;
  6904. &lt;head&gt;
  6905. &lt;meta name="viewport" content="width=device-width"/&gt;
  6906. &lt;title&gt;Hello&lt;/title&gt;
  6907. &lt;link rel="stylesheet" href="http://:/lib.css" type="text/css"/&gt;
  6908. &lt;/head&gt;
  6909. &lt;body&gt;&lt;h2&gt;Hello&lt;/h2&gt;
  6910. &lt;p&gt;Hello!&lt;/p&gt;
  6911. &lt;p&gt;This is a test.&lt;/p&gt;
  6912. &lt;/body&gt;&lt;/html&gt;
  6913. </code></pre>
  6914.  
  6915. <dt><a name="hex"><code>(hex 'num ['num]) -> sym</code></a>
  6916. <dt><code>(hex 'sym) -> num</code>
  6917. <dd>Converts a number <code>num</code> to a hexadecimal string, or a hexadecimal
  6918. string <code>sym</code> to a number. In the first case, if the second argument
  6919. is given, the result is separated by spaces into groups of such many digits. See
  6920. also <code><a href="#bin">bin</a></code>, <code><a
  6921. href="#oct">oct</a></code>, <code><a
  6922. href="#fmt64">fmt64</a></code>, <code><a
  6923. href="#hax">hax</a></code> and <code><a
  6924. href="#format">format</a></code>.
  6925.  
  6926. <pre><code>
  6927. : (hex 273)
  6928. -> "111"
  6929. : (hex "111")
  6930. -> 273
  6931. : (hex 1234567 4)
  6932. -> "12 D687"
  6933. </code></pre>
  6934.  
  6935. <dt><a name="host"><code>(host 'any) -> sym</code></a>
  6936. <dd>Returns the hostname corresponding to the given IP address. See also
  6937. <code><a href="#*Adr">*Adr</a></code>.
  6938.  
  6939. <pre><code>
  6940. : (host "80.190.158.9")
  6941. -> "www.leo.org"
  6942. </code></pre>
  6943.  
  6944. </dl>
  6945.  
  6946. <h1><a name="_">Other</a></h1>
  6947.  
  6948. <dl>
  6949.  
  6950. <dt><a name="!"><code>(! . exe) -> any</code></a>
  6951. <dd>Low level breakpoint function: The current execution environment is saved
  6952. and the I/O channels are redirected to the console. Then <code>exe</code> is
  6953. displayed, and a read-eval-print-loop is entered (with <code>!</code> as its
  6954. prompt character), to evaluate expressions and examine the current program
  6955. environment. An empty input line terminates the read-eval-print-loop, the
  6956. environment and I/O channels are restored, and the result of <code>exe</code> is
  6957. returned. <code>!</code> is normally inserted into existing programs with the
  6958. <code><a href="#debug">debug</a></code> function. See also <code><a
  6959. href="#e">e</a></code>, <code><a href="ref_.html#^">^</a></code> and
  6960. <code><a href="#*Dbg">*Dbg</a></code>.
  6961.  
  6962. <pre><code>
  6963. : (de foo (N) (and (println 1) (! println N) (println 2)))
  6964. -> foo
  6965. : (foo 7)
  6966. 1 # Executed '(println 1)'
  6967. (println N) # Entered breakpoint
  6968. ! N # Examine the value of 'N'
  6969. -> 7
  6970. ! (e) # Evaluate '^', i.e. (println N)
  6971. 7
  6972. -> 7
  6973. ! (e @) # Evaluate '@' -> the result of '(println 1)'
  6974. -> 1
  6975. ! # Empty line: continue
  6976. 7 # Executed '(println N)'
  6977. 2 # Executed '(println 2)'
  6978. -> 2
  6979. </code></pre>
  6980.  
  6981. <dt><a name="$"><code>($ sym|lst lst . prg) -> any</code></a>
  6982. <dd>Low level trace function: The first argument <code>sym|lst</code> is printed
  6983. to the console with a proper indentation, followed by a colon <code>:</code>. If
  6984. a function is traced, the first argument is the function symbol, else if a
  6985. method is traced, it is a cons pair of message and class. The second argument
  6986. <code>lst</code> should be a list of symbols, identical to the function's
  6987. argument list. The current values of these symbols are printed, followed by a
  6988. newline. Then <code>prg</code> is executed, and its return value printed in a
  6989. similar way (this time with an equals sign <code>=</code> instead of a colon)
  6990. and returned. <code>$</code> is normally inserted into existing programs with
  6991. the <code><a href="#trace">trace</a></code> function.
  6992.  
  6993. <pre><code>
  6994. : (de foo (A B) ($ foo (A B) (* A B)))
  6995. -> foo
  6996. : (foo 3 4)
  6997. foo : 3 4 # Function entry, arguments 3 and 4
  6998. foo = 12 # Function exit, return value 12
  6999. -> 12
  7000. </code></pre>
  7001.  
  7002. <dt><a name="$dat"><code>($dat 'sym1 ['sym2]) -> dat</code></a>
  7003. <dd>Converts a string <code>sym1</code> in ISO format to a <code><a
  7004. href="#date">date</a></code>, optionally using a delimiter character
  7005. <code>sym2</code>. See also <code><a href="#dat$">dat$</a></code>,
  7006. <code><a href="#$tim">$tim</a></code>, <code><a
  7007. href="#strDat">strDat</a></code> and <code><a
  7008. href="#expDat">expDat</a></code>.
  7009.  
  7010. <pre><code>
  7011. : ($dat "20070601")
  7012. -> 733134
  7013. : ($dat "2007-06-01" "-")
  7014. -> 733134
  7015. </code></pre>
  7016.  
  7017. <dt><a name="$tim"><code>($tim 'sym) -> tim</code></a>
  7018. <dd>Converts a string to a <code><a href="#time">time</a></code>. The
  7019. minutes and seconds are optional and default to zero. See also <code><a
  7020. href="#tim$">tim$</a></code> and <code><a
  7021. href="#$dat">$dat</a></code>.
  7022.  
  7023. <pre><code>
  7024. : (time ($tim "10:57:56"))
  7025. -> (10 57 56)
  7026. : (time ($tim "10:57"))
  7027. -> (10 57 0)
  7028. : (time ($tim "10"))
  7029. -> (10 0 0)
  7030. </code></pre>
  7031.  
  7032. <dt><a name="%"><code>(% 'num ..) -> num</code></a>
  7033. <dd>Returns the remainder from the divisions of successive <code>num</code>
  7034. arguments. The sign of the result is that of the first argument. When one of the
  7035. arguments evaluates to <code>NIL</code>, it is returned immediately. See also
  7036. <code><a href="#/">/</a></code> and <code><a
  7037. href="#*/">*/</a></code> .
  7038.  
  7039. <pre><code>
  7040. : (% 17 5)
  7041. -> 2
  7042. : (% -17 5) # Sign is that of the first argument
  7043. -> -2
  7044. : (% 5 2)
  7045. -> 1
  7046. : (% 15 10)
  7047. -> 5
  7048. : (% 15 10 2) # (% 15 10) -> 5, then (% 5 2) -> 1
  7049. -> 1
  7050. </code></pre>
  7051.  
  7052. <dt><a name="&"><code>(& 'num ..) -> num</code></a>
  7053. <dd>Returns the bitwise <code>AND</code> of all <code>num</code> arguments. When
  7054. one of the arguments evaluates to <code>NIL</code>, it is returned immediately.
  7055. See also <code><a href="#|">|</a></code>, <code><a
  7056. href="#x|">x|</a></code> and <code><a
  7057. href="#bit?">bit?</a></code>.
  7058.  
  7059. <pre><code>
  7060. : (& 6 3)
  7061. -> 2
  7062. : (& 7 3 1)
  7063. -> 1
  7064. </code></pre>
  7065.  
  7066. <dt><a name="*"><code>(* 'num ..) -> num</code></a>
  7067. <dd>Returns the product of all <code>num</code> arguments. When one of the
  7068. arguments evaluates to <code>NIL</code>, it is returned immediately. See also
  7069. <code><a href="#/">/</a></code>, <code><a
  7070. href="#*/">*/</a></code>, <code><a href="ref_.html#+">+</a></code> and
  7071. <code><a href="#-">-</a></code>.
  7072.  
  7073. <pre><code>
  7074. : (* 1 2 3)
  7075. -> 6
  7076. : (* 5 3 2 2)
  7077. -> 60
  7078. </code></pre>
  7079.  
  7080. <dt><a name="**"><code>(** 'num1 'num2) -> num</code></a>
  7081. <dd>Integer exponentiation: Returns <code>num1</code> to the power of
  7082. <code>num2</code>.
  7083.  
  7084. <pre><code>
  7085. : (** 2 3)
  7086. -> 8
  7087. : (** 100 100)
  7088. -> 10000000000000000000000000000000000000000000000000000000000000000000000000000
  7089. 00000000000000000000000000000000000000000000000000000000000000000000000000000000
  7090. 00000000000000000000000000000000000000000000
  7091. </code></pre>
  7092.  
  7093. <dt><a name="*/"><code>(*/ 'num1 ['num2 ..] 'num3) -> num</code></a>
  7094. <dd>Returns the product of <code>num1</code> and all following <code>num2</code>
  7095. arguments, divided by the <code>num3</code> argument. The result is rounded to
  7096. the nearest integer value. When one of the arguments evaluates to
  7097. <code>NIL</code>, it is returned immediately. Note that <code>*/</code> is
  7098. especially useful for fixed point arithmetic, by multiplying with (or dividing
  7099. by) the scale factor. See also <code><a href="#*">*</a></code>,
  7100. <code><a href="#/">/</a></code>, <code><a
  7101. href="#+">+</a></code>, <code><a href="ref_.html#-">-</a></code> and
  7102. <code><a href="#sqrt">sqrt</a></code>.
  7103.  
  7104. <pre><code>
  7105. : (*/ 3 4 2)
  7106. -> 6
  7107. : (*/ 1234 2 10)
  7108. -> 247
  7109. : (*/ 100 6)
  7110. -> 17
  7111.  
  7112. : (scl 2)
  7113. -> 2
  7114. : (format (*/ 3.0 1.5 1.0) *Scl)
  7115. -> "4.50"
  7116. </code></pre>
  7117.  
  7118. <dt><a name="+"><code>(+ 'num ..) -> num</code></a>
  7119. <dd>Returns the sum of all <code>num</code> arguments. When one of the arguments
  7120. evaluates to <code>NIL</code>, it is returned immediately. See also <code><a
  7121. href="#inc">inc</a></code>, <code><a href="ref_.html#-">-</a></code>,
  7122. <code><a href="#*">*</a></code>, <code><a
  7123. href="#/">/</a></code> and <code><a href="ref_.html#*/">*/</a></code>.
  7124.  
  7125. <pre><code>
  7126. : (+ 1 2 3)
  7127. -> 6
  7128. </code></pre>
  7129.  
  7130. <dt><a name="-"><code>(- 'num ..) -> num</code></a>
  7131. <dd>Returns the difference of the first <code>num</code> argument and all
  7132. following arguments. If only a single argument is given, it is negated. When one
  7133. of the arguments evaluates to <code>NIL</code>, it is returned immediately. See
  7134. also <code><a href="#dec">dec</a></code>, <code><a
  7135. href="#+">+</a></code>, <code><a href="ref_.html#*">*</a></code>,
  7136. <code><a href="#/">/</a></code> and <code><a
  7137. href="#*/">*/</a></code>.
  7138.  
  7139. <pre><code>
  7140. : (- 7)
  7141. -> -7
  7142. : (- 7 2 1)
  7143. -> 4
  7144. </code></pre>
  7145.  
  7146. <dt><a name="->"><code>(-&gt any [num]) -> any</code></a>
  7147. <dd>Searches for the value of <code>any</code> (typically a <a
  7148. href="#pilog">Pilog</a> variable, or an expression of variables) at top
  7149. level (or level <code>num</code>) in the current environment. See also <code><a
  7150. href="#prove">prove</a></code> and <code><a
  7151. href="#unify">unify</a></code>.
  7152.  
  7153. <pre><code>
  7154. : (? (append (1 2 3) (4 5 6) @X) (^ @ (println 'X '= (-> @X))))
  7155. X = (1 2 3 4 5 6)
  7156. @X=(1 2 3 4 5 6)
  7157. -> NIL
  7158. </code></pre>
  7159.  
  7160. <dt><a name="/"><code>(/ 'num ..) -> num</code></a>
  7161. <dd>Returns the first <code>num</code> argument successively divided by all
  7162. following arguments. When one of the arguments evaluates to <code>NIL</code>, it
  7163. is returned immediately. See also <code><a href="#*">*</a></code>,
  7164. <code><a href="#*/">*/</a></code>, <code><a
  7165. href="#%">%</a></code>, <code><a href="ref_.html#+">+</a></code> and
  7166. <code><a href="#-">-</a></code>.
  7167.  
  7168. <pre><code>
  7169. : (/ 12 3)
  7170. -> 4
  7171. : (/ 60 -3 2 2)
  7172. -> -5
  7173. </code></pre>
  7174.  
  7175. <dt><a name=":"><code>(: sym|0 [sym1|cnt ..]) -> any</code></a>
  7176. <dd>Fetches a value <code>any</code> from the properties of a symbol, or from a
  7177. list, by applying the <code><a href="#get">get</a></code> algorithm to
  7178. <code>This</code> and the following arguments. Used typically in methods or
  7179. <code><a href="#with">with</a></code> bodies. <code>(: ..)</code> is
  7180. equivalent to <code>(; This ..)</code>. See also <code><a
  7181. href="#;">;</a></code>, <code><a href="ref_.html#=:">=:</a></code> and
  7182. <code><a href="#::">::</a></code>.
  7183.  
  7184. <pre><code>
  7185. : (put 'X 'a 1)
  7186. -> 1
  7187. : (with 'X (: a))
  7188. -> 1
  7189. </code></pre>
  7190.  
  7191. <dt><a name="::"><code>(:: sym [sym1|cnt .. sym2]) -> var</code></a>
  7192. <dd>Fetches a property for a property key <code>sym</code> or <code>sym2</code>
  7193. from a symbol. That symbol is <code>This</code> (if no other arguments are
  7194. given), or a symbol found by applying the <code><a
  7195. href="#get">get</a></code> algorithm to <code>This</code> and the
  7196. following arguments. The property (the cons pair, not just its value) is
  7197. returned, suitable for direct (destructive) manipulations with functions
  7198. expecting a <code>var</code> argument. Used typically in methods or <code><a
  7199. href="#with">with</a></code> bodies. See also <code><a
  7200. href="#=:">=:</a></code>, <code><a
  7201. href="#prop">prop</a></code> and <code><a
  7202. href="#:">:</a></code>.
  7203.  
  7204. <pre><code>
  7205. : (with 'X (=: cnt 0) (inc (:: cnt)) (: cnt))
  7206. -> 1
  7207. </code></pre>
  7208.  
  7209. <dt><a name=";"><code>(; 'sym1|lst [sym2|cnt ..]) -> any</code></a>
  7210. <dd>Fetches a value <code>any</code> from the properties of a symbol, or from a
  7211. list, by applying the <code><a href="#get">get</a></code> algorithm to
  7212. <code>sym1|lst</code> and the following arguments. See also <code><a
  7213. href="#:">:</a></code>, <code><a href="ref_.html#=:">=:</a></code> and
  7214. <code><a href="#::">::</a></code>.
  7215.  
  7216. <pre><code>
  7217. : (put 'A 'a 1)
  7218. -> 1
  7219. : (put 'A 'b 'B)
  7220. -> B
  7221. : (put 'B 'c 7)
  7222. -> 7
  7223. : (; 'A a)
  7224. -> 1
  7225. : (; 'A b c)
  7226. -> 7
  7227. </code></pre>
  7228.  
  7229. <dt><a name="<"><code>(< 'any ..) -> flg</code></a>
  7230. <dd>Returns <code>T</code> when all arguments <code>any</code> are in strictly
  7231. increasing order. See also <a href="#cmp">Comparing</a>.
  7232.  
  7233. <pre><code>
  7234. : (< 3 4)
  7235. -> T
  7236. : (< 'a 'b 'c)
  7237. -> T
  7238. : (< 999 'a)
  7239. -> T
  7240. </code></pre>
  7241.  
  7242. <dt><a name="<="><code>(<= 'any ..) -> flg</code></a>
  7243. <dd>Returns <code>T</code> when all arguments <code>any</code> are in strictly
  7244. non-decreasing order. See also <a href="#cmp">Comparing</a>.
  7245.  
  7246. <pre><code>
  7247. : (<= 3 3)
  7248. -> T
  7249. : (<= 1 2 3)
  7250. -> T
  7251. : (<= "abc" "abc" "def")
  7252. -> T
  7253. </code></pre>
  7254.  
  7255. <dt><a name="<>"><code>(<&gt 'any ..) -> flg</code></a>
  7256. <dd>Returns <code>T</code> when not all <code>any</code> arguments are equal
  7257. (structure equality). <code>(<&gt 'any ..)</code> is equivalent to <code>(not (=
  7258. 'any ..))</code>. See also <a href="#cmp">Comparing</a>.
  7259.  
  7260. <pre><code>
  7261. : (<&gt 'a 'b)
  7262. -> T
  7263. : (<&gt 'a 'b 'b)
  7264. -> T
  7265. : (<&gt 'a 'a 'a)
  7266. -> NIL
  7267. </code></pre>
  7268.  
  7269. <dt><a name="="><code>(= 'any ..) -> flg</code></a>
  7270. <dd>Returns <code>T</code> when all <code>any</code> arguments are equal
  7271. (structure equality). See also <a href="#cmp">Comparing</a>.
  7272.  
  7273. <pre><code>
  7274. : (= 6 (* 1 2 3))
  7275. -> T
  7276. : (= "a" "a")
  7277. -> T
  7278. : (== "a" "a")
  7279. -> T
  7280. : (= (1 (2) 3) (1 (2) 3))
  7281. -> T
  7282. </code></pre>
  7283.  
  7284. <dt><a name="=0"><code>(=0 'any) -> 0 | NIL</code></a>
  7285. <dd>Returns <code>0</code> when <code>any</code> is a number with value zero.
  7286. See also <code><a href="#n0">n0</a></code>, <code><a
  7287. href="#lt0">lt0</a></code>, <code><a
  7288. href="#le0">le0</a></code>, <code><a
  7289. href="#ge0">ge0</a></code> and <code><a
  7290. href="#gt0">gt0</a></code>.
  7291.  
  7292. <pre><code>
  7293. : (=0 (- 6 3 2 1))
  7294. -> 0
  7295. : (=0 'a)
  7296. -> NIL
  7297. </code></pre>
  7298.  
  7299. <dt><a name="=:"><code>(=: sym|0 [sym1|cnt .. sym2|0] 'any)</code></a>
  7300. <dd>Stores a new value <code>any</code> for a property key <code>sym</code> or
  7301. <code>sym2</code> (or in the symbol value for zero) in a symbol. That symbol is
  7302. <code>This</code> (if no other arguments are given), or a symbol found by
  7303. applying the <code><a href="#get">get</a></code> algorithm to
  7304. <code>This</code> and the following arguments. Used typically in methods or
  7305. <code><a href="#with">with</a></code> bodies. See also <code><a
  7306. href="#put">put</a></code>, <code><a href="ref_.html#:">:</a></code>
  7307. and <code><a href="#::">::</a></code>.
  7308.  
  7309. <pre><code>
  7310. : (with 'X (=: a 1) (=: b 2))
  7311. -> 2
  7312. : (get 'X 'a)
  7313. -> 1
  7314. : (get 'X 'b)
  7315. -> 2
  7316. </code></pre>
  7317.  
  7318. <dt><a name="=="><code>(== 'any ..) -> flg</code></a>
  7319. <dd>Returns <code>T</code> when all <code>any</code> arguments are the same
  7320. (pointer equality). See also <code><a href="#n==">n==</a></code> and <a
  7321. href="#cmp">Comparing</a>.
  7322.  
  7323. <pre><code>
  7324. : (== 'a 'a)
  7325. -> T
  7326. : (== 'NIL NIL (val NIL) (car NIL) (cdr NIL))
  7327. -> T
  7328. : (== (1 2 3) (1 2 3))
  7329. -> NIL
  7330. </code></pre>
  7331.  
  7332. <dt><a name="===="><code>(==== ['sym ..]) -> NIL</code></a>
  7333. <dd>Close the current transient scope by clearing the transient index. All
  7334. transient symbols become hidden and inaccessible by the reader. Then any
  7335. optional <code>sym</code> arguments are (re-)inserted into the transient index.
  7336. See also <code><a href="#extern">extern</a></code> and <code><a
  7337. href="#intern">intern</a></code>.
  7338.  
  7339. <pre><code>
  7340. : (setq S "abc") # Read "abc"
  7341. -> "abc"
  7342. : (== S "abc") # Read again, get the same symbol
  7343. -> T
  7344. : (====) # Close scope
  7345. -> NIL
  7346. : (== S "abc") # Read again, get another symbol
  7347. -> NIL
  7348. </code></pre>
  7349.  
  7350. <dt><a name="=T"><code>(=T 'any) -> flg</code></a>
  7351. <dd>Returns <code>T</code> when <code>any</code> is the symbol <code>T</code>.
  7352. <code>(=T X)</code> is equivalent to <code>(== T X)</code>. See also <a
  7353. href="#nT">nT</a>.
  7354.  
  7355. <pre><code>
  7356. : (=T 0)
  7357. -> NIL
  7358. : (=T "T")
  7359. -> NIL
  7360. : (=T T)
  7361. -> T
  7362. </code></pre>
  7363.  
  7364. <dt><a name=">"><code>(> 'any ..) -> flg</code></a>
  7365. <dd>Returns <code>T</code> when all arguments <code>any</code> are in strictly
  7366. decreasing order. See also <a href="#cmp">Comparing</a>.
  7367.  
  7368. <pre><code>
  7369. : (> 4 3)
  7370. -> T
  7371. : (> 'A 999)
  7372. -> T
  7373. </code></pre>
  7374.  
  7375. <dt><a name=">="><code>(>= 'any ..) -> flg</code></a>
  7376. <dd>Returns <code>T</code> when all arguments <code>any</code> are in strictly
  7377. non-increasing order. See also <a href="#cmp">Comparing</a>.
  7378.  
  7379. <pre><code>
  7380. : (>= 'A 999)
  7381. -> T
  7382. : (>= 3 2 2 1)
  7383. -> T
  7384. </code></pre>
  7385.  
  7386. <dt><a name=">>"><code>(>> 'cnt 'num) -> num</code></a>
  7387. <dd>Shifts right the <code>num</code> argument by <code>cnt</code>
  7388. bit-positions. If <code>cnt</code> is negative, a corresponding left shift is
  7389. performed.
  7390.  
  7391. <pre><code>
  7392. : (>> 1 8)
  7393. -> 4
  7394. : (>> 3 16)
  7395. -> 2
  7396. : (>> -3 16)
  7397. -> 128
  7398. : (>> -1 -16)
  7399. -> -32
  7400. </code></pre>
  7401.  
  7402. <dt><a name="?"><code>(? [sym ..] [pat 'any ..] . lst) -> flg</code></a>
  7403. <dd>Top-level function for interactive <a href="#pilog">Pilog</a>
  7404. queries. <code>?</code> is a non-evaluating front-end to the <code><a
  7405. href="#query">query</a></code> function. It displays each result, waits
  7406. for console input, and terminates when a non-empty line is entered. If a
  7407. preceding list of (non-pattern-) symbols is given, they will be taken as rules
  7408. to be traced by <code><a href="#prove">prove</a></code>. The list of
  7409. variable/value pairs is passed to <code><a href="#goal">goal</a></code>
  7410. for an initial Pilog environment. See also <code><a
  7411. href="#pilog">pilog</a></code> and <code><a
  7412. href="#solve">solve</a></code>.
  7413.  
  7414. <pre><code>
  7415. : (? (append (a b c) (d e f) @X))
  7416. @X=(a b c d e f)
  7417. -> NIL
  7418.  
  7419. : (? (append @X @Y (a b c)))
  7420. @X=NIL @Y=(a b c)
  7421. @X=(a) @Y=(b c)
  7422. @X=(a b) @Y=(c)
  7423. @X=(a b c) @Y=NIL
  7424. -> NIL
  7425.  
  7426. : (? (append @X @Y (a b c)))
  7427. @X=NIL @Y=(a b c). # Stopped
  7428. -> NIL
  7429.  
  7430. : (? append (append @X @Y (a b c))) # Trace 'append'
  7431. 1 (append NIL (a b c) (a b c))
  7432. @X=NIL @Y=(a b c)
  7433. 2 (append (a . @X) @Y (a b c))
  7434. 1 (append NIL (b c) (b c))
  7435. @X=(a) @Y=(b c). # Stopped
  7436. -> NIL
  7437. </code></pre>
  7438.  
  7439. <dt><a name="@"><code>@</code></a>
  7440. <dd>Holds the result of the last top level expression in the current
  7441. read-eval-print loop, or the result of the conditional expression during the
  7442. evaluation of flow functions (see <code><a href="#atres">@
  7443. Result</a></code>). When <code>@</code> is used as a formal parameter in <a
  7444. href="#lambda">lambda expressions</a>, it denotes a variable number of
  7445. evaluated arguments.
  7446.  
  7447. <dt><a name="@@"><code>@@</code></a>
  7448. <dd>Holds the result of the second last top level expression in the current
  7449. read-eval-print loop (see <code><a href="#atres">@ Result</a></code>).
  7450. Some functions store a secondary return value in <code>@@</code>.
  7451.  
  7452. <dt><a name="@@@"><code>@@@</code></a>
  7453. <dd>Holds the result of the third last top level expression in the current
  7454. read-eval-print loop (see <code><a href="#atres">@ Result</a></code>).
  7455.  
  7456. <dt><a name="^"><code>^</code></a>
  7457. <dd>Holds the currently executed expression during a breakpoint or an error. See
  7458. also <code><a href="#debug">debug</a></code>, <code><a
  7459. href="#!">!</a></code>, <code><a href="refE.html#e">e</a></code> and
  7460. <code><a href="#*Dbg">*Dbg</a></code>.
  7461.  
  7462. <pre><code>
  7463. : (* (+ 3 4) (/ 7 0))
  7464. !? (/ 7 0)
  7465. Div/0
  7466. ? ^
  7467. -> (/ 7 0)
  7468. </code></pre>
  7469.  
  7470. <dt><a name="|"><code>(| 'num ..) -> num</code></a>
  7471. <dd>Returns the bitwise <code>OR</code> of all <code>num</code> arguments. When
  7472. one of the arguments evaluates to <code>NIL</code>, it is returned immediately.
  7473. See also <code><a href="#x|">x|</a></code>, <code><a
  7474. href="#&">&</a></code> and <code><a
  7475. href="#bit?">bit?</a></code>.
  7476.  
  7477. <pre><code>
  7478. : (| 1 2)
  7479. -> 3
  7480. : (| 1 2 4 8)
  7481. -> 15
  7482. </code></pre>
  7483.  
  7484. </dl>
  7485.  
  7486. <h1><a name="I">I</a></h1>
  7487.  
  7488. <dl>
  7489.  
  7490. <dt><a name="+Idx"><code>+Idx</code></a>
  7491. <dd>Prefix class for maintaining non-unique full-text indexes to <code><a
  7492. href="#+String">+String</a></code> relations, a subclass of <code><a
  7493. href="#+Ref">+Ref</a></code>. Accepts optional arguments for the
  7494. minimally indexed substring length (defaults to 3), and a <code><a
  7495. href="#+Hook">+Hook</a></code> attribute. Often used in combination
  7496. with the <code><a href="#+Sn">+Sn</a></code> soundex index, or the
  7497. <code><a href="#+Fold">+Fold</a></code> index prefix classes. See also
  7498. <a href="#dbase">Database</a>.
  7499.  
  7500. <pre><code>
  7501. (rel nm (+Sn +Idx +String)) # Name
  7502. </code></pre>
  7503.  
  7504. <dt><a name="+IdxFold"><code>+IdxFold</code></a>
  7505. <dd>Prefix class for maintaining non-unique indexes to subsequent substrings of
  7506. the <code><a href="#fold">fold</a></code>ed individual words of
  7507. <code><a href="#+String">+String</a></code> relations. Accepts optional
  7508. arguments for the minimally indexed substring length (defaults to 3), and a
  7509. <code><a href="#+Hook">+Hook</a></code> attribute. See also <code><a
  7510. href="#+Idx">+Idx</a></code> and <a href="ref.html#dbase">Database</a>.
  7511.  
  7512. <pre><code>
  7513. (rel nm (+IdxFold +String)) # Item Description
  7514. </code></pre>
  7515.  
  7516. <dt><a name="+index"><code>+index</code></a>
  7517. <dd>Abstract base class of all database B-Tree index relations (prefix classes
  7518. for <code><a href="#+relation">+relation</a></code>s). The class
  7519. hierarchy includes <code><a href="#+Key">+Key</a></code>, <code><a
  7520. href="#+Ref">+Ref</a></code>, <code><a
  7521. href="#+Idx">+Idx</a></code> and <code><a
  7522. href="#+IdxFold">+IdxFold</a></code>. See also <a
  7523. href="#dbase">Database</a>.
  7524.  
  7525. <pre><code>
  7526. (isa '+index Rel) # Check for an index relation
  7527. </code></pre>
  7528.  
  7529. <dt><a name="id"><code>(id 'num ['num]) -> sym</code></a>
  7530. <dt><code>(id 'sym [NIL]) -> num</code>
  7531. <dt><code>(id 'sym T) -> (num . num)</code>
  7532. <dd>Converts one or two numbers to an external symbol, or an external symbol to
  7533. a number or a pair of numbers.
  7534.  
  7535. <pre><code>
  7536. : (id 7)
  7537. -> {7}
  7538. : (id 1 2)
  7539. -> {2}
  7540. : (id '{1-2})
  7541. -> 2
  7542. : (id '{1-2} T)
  7543. -> (1 . 2)
  7544. </code></pre>
  7545.  
  7546. <dt><a name="idx"><code>(idx 'var 'any 'flg) -> lst<br>
  7547. (idx 'var 'any) -> lst<br>
  7548. (idx 'var) -> lst</code></a>
  7549. <dd>Maintains an index tree in <code>var</code>, and checks for the existence of
  7550. <code>any</code>. If <code>any</code> is contained in <code>var</code>, the
  7551. corresponding subtree is returned, otherwise <code>NIL</code>. In the first
  7552. form, <code>any</code> is destructively inserted into the tree if
  7553. <code>flg</code> is non-<code>NIL</code> (and <code>any</code> was not already
  7554. there), or deleted from the tree if <code>flg</code> is <code>NIL</code>. The
  7555. second form only checks for existence, but does not change the index tree. In
  7556. the third form (when called with a single <code>var</code> argument) the
  7557. contents of the tree are returned as a sorted list. If all elements are inserted
  7558. in sorted order, the tree degenerates into a linear list. See also <code><a
  7559. href="#lup">lup</a></code>, <code><a
  7560. href="#hash">hash</a></code>, <code><a
  7561. href="#depth">depth</a></code>, <code><a
  7562. href="#sort">sort</a></code>, <code><a
  7563. href="#balance">balance</a></code> and <code><a
  7564. href="#member">member</a></code>.
  7565.  
  7566. <pre><code>
  7567. : (idx 'X 'd T) # Insert data
  7568. -> NIL
  7569. : (idx 'X 2 T)
  7570. -> NIL
  7571. : (idx 'X '(a b c) T)
  7572. -> NIL
  7573. : (idx 'X 17 T)
  7574. -> NIL
  7575. : (idx 'X 'A T)
  7576. -> NIL
  7577. : (idx 'X 'd T)
  7578. -> (d (2 NIL 17 NIL A) (a b c)) # 'd' already existed
  7579. : (idx 'X T T)
  7580. -> NIL
  7581. : X # View the index tree
  7582. -> (d (2 NIL 17 NIL A) (a b c) NIL T)
  7583. : (idx 'X 'A) # Check for 'A'
  7584. -> (A)
  7585. : (idx 'X 'B) # Check for 'B'
  7586. -> NIL
  7587. : (idx 'X)
  7588. -> (2 17 A d (a b c) T) # Get list
  7589. : (idx 'X 17 NIL) # Delete '17'
  7590. -> (17 NIL A)
  7591. : X
  7592. -> (d (2 NIL A) (a b c) NIL T) # View it again
  7593. : (idx 'X)
  7594. -> (2 A d (a b c) T) # '17' is deleted
  7595. </code></pre>
  7596.  
  7597. <dt><a name="if"><code>(if 'any1 'any2 . prg) -> any</code></a>
  7598. <dd>Conditional execution: If the condition <code>any1</code> evaluates to
  7599. non-<code>NIL</code>, <code>any2</code> is evaluated and returned. Otherwise,
  7600. <code>prg</code> is executed and the result returned. See also <code><a
  7601. href="#cond">cond</a></code>, <code><a
  7602. href="#when">when</a></code> and <code><a
  7603. href="#if2">if2</a></code>.
  7604.  
  7605. <pre><code>
  7606. : (if (> 4 3) (println 'OK) (println 'Bad))
  7607. OK
  7608. -> OK
  7609. : (if (> 3 4) (println 'OK) (println 'Bad))
  7610. Bad
  7611. -> Bad
  7612. </code></pre>
  7613.  
  7614. <dt><a name="if2"><code>(if2 'any1 'any2 'any3 'any4 'any5 . prg) -> any</code></a>
  7615. <dd>Four-way conditional execution for two conditions: If both conditions
  7616. <code>any1</code> and <code>any2</code> evaluate to non-<code>NIL</code>,
  7617. <code>any3</code> is evaluated and returned. Otherwise, <code>any4</code> or
  7618. <code>any5</code> is evaluated and returned if <code>any1</code> or
  7619. <code>any2</code> evaluate to non-<code>NIL</code>, respectively. If none of the
  7620. conditions evaluate to non-<code>NIL</code>, <code>prg</code> is executed and
  7621. the result returned. See also <code><a href="#if">if</a></code> and
  7622. <code><a href="#cond">cond</a></code>.
  7623.  
  7624. <pre><code>
  7625. : (if2 T T 'both 'first 'second 'none)
  7626. -> both
  7627. : (if2 T NIL 'both 'first 'second 'none)
  7628. -> first
  7629. : (if2 NIL T 'both 'first 'second 'none)
  7630. -> second
  7631. : (if2 NIL NIL 'both 'first 'second 'none)
  7632. -> none
  7633. </code></pre>
  7634.  
  7635. <dt><a name="ifn"><code>(ifn 'any1 'any2 . prg) -> any</code></a>
  7636. <dd>Conditional execution ("If not"): If the condition <code>any1</code>
  7637. evaluates to <code>NIL</code>, <code>any2</code> is evaluated and returned.
  7638. Otherwise, <code>prg</code> is executed and the result returned.
  7639.  
  7640. <pre><code>
  7641. : (ifn (= 3 4) (println 'OK) (println 'Bad))
  7642. OK
  7643. -> OK
  7644. </code></pre>
  7645.  
  7646. <dt><a name="import"><code>(import . lst) -> NIL</code></a>
  7647. <dd>Wrapper function for <code><a href="#intern">intern</a></code>.
  7648. Typically used to import symbols from other namespaces, as created by <code><a
  7649. href="#symbols">symbols</a></code>. <code>lst</code> should be a list
  7650. of symbols. An import conflict error is issued when a symbol with the same name
  7651. already exists in the current namespace. See also <code><a
  7652. href="#pico">pico</a></code> and <code><a
  7653. href="#local">local</a></code>.
  7654.  
  7655. <pre><code>
  7656. : (import libA~foo libB~bar)
  7657. -> NIL
  7658. </code></pre>
  7659.  
  7660. <dt><a name="in"><code>(in 'any . prg) -> any</code></a>
  7661. <dd>Opens <code>any</code> as input channel during the execution of
  7662. <code>prg</code>. The current input channel will be saved and restored
  7663. appropriately. If the argument is <code>NIL</code>, standard input is used. If
  7664. the argument is a symbol, it is used as a file name (opened for reading
  7665. <i>and</i> writing if the first character is "<code>+</code>"). If it is a
  7666. positive number, it is used as the descriptor of an open file. If it is a
  7667. negative number, the saved input channel such many levels above the current one
  7668. is used. Otherwise (if it is a list), it is taken as a command with arguments,
  7669. and a pipe is opened for input. See also <code><a
  7670. href="#ipid">ipid</a></code>, <code><a
  7671. href="#call">call</a></code>, <code><a
  7672. href="#load">load</a></code>, <code><a
  7673. href="#file">file</a></code>, <code><a
  7674. href="#out">out</a></code>, <code><a
  7675. href="#err">err</a></code>, <code><a
  7676. href="#poll">poll</a></code>, <code><a
  7677. href="#pipe">pipe</a></code> and <code><a
  7678. href="#ctl">ctl</a></code>.
  7679.  
  7680. <pre><code>
  7681. : (in "a" (list (read) (read) (read))) # Read three items from file "a"
  7682. -> (123 (a b c) def)
  7683. </code></pre>
  7684.  
  7685. <dt><a name="inc"><code>(inc 'num) -> num<br>
  7686. (inc 'var ['num]) -> num</code></a>
  7687. <dd>The first form returns the value of <code>num</code> incremented by 1. The
  7688. second form increments the <code>VAL</code> of <code>var</code> by 1, or by
  7689. <code>num</code>. If the first argument is <code>NIL</code>, it is returned
  7690. immediately. <code>(inc Num)</code> is equivalent to <code>(+ Num 1)</code> and
  7691. <code>(inc 'Var)</code> is equivalent to <code>(set 'Var (+ Var 1))</code>. See
  7692. also <code><a href="#dec">dec</a></code> and <code><a
  7693. href="#+">+</a></code>.
  7694.  
  7695. <pre><code>
  7696. : (inc 7)
  7697. -> 8
  7698. : (inc -1)
  7699. -> 0
  7700. : (zero N)
  7701. -> 0
  7702. : (inc 'N)
  7703. -> 1
  7704. : (inc 'N 7)
  7705. -> 8
  7706. : N
  7707. -> 8
  7708.  
  7709. : (setq L (1 2 3 4))
  7710. -> (1 2 3 4)
  7711. : (inc (cdr L))
  7712. -> 3
  7713. : L
  7714. -> (1 3 3 4)
  7715. </code></pre>
  7716.  
  7717. <dt><a name="inc!"><code>(inc! 'obj 'sym ['num]) -> num</code></a>
  7718. <dd><a href="#trans">Transaction</a> wrapper function for <code><a
  7719. href="#inc">inc</a></code>. <code>num</code> defaults to 1. Note that
  7720. for incrementing a property value of an entity typically the <code><a
  7721. href="#entityMesssages">inc!></a></code> message is used. See also
  7722. <code><a href="#new!">new!</a></code>, <code><a
  7723. href="#set!">set!</a></code> and <code><a
  7724. href="#put!">put!</a></code>.
  7725.  
  7726. <pre><code>
  7727. (inc! Obj 'cnt 0) # Incrementing a property of a non-entity object
  7728. </code></pre>
  7729.  
  7730. <dt><a name="index"><code>(index 'any 'lst) -> cnt | NIL</code></a>
  7731. <dd>Returns the <code>cnt</code> position of <code>any</code> in
  7732. <code>lst</code>, or <code>NIL</code> if it is not found. See also <code><a
  7733. href="#offset">offset</a></code> and <code><a
  7734. href="#sub?">sub?</a></code>.
  7735.  
  7736. <pre><code>
  7737. : (index 'c '(a b c d e f))
  7738. -> 3
  7739. : (index '(5 6) '((1 2) (3 4) (5 6) (7 8)))
  7740. -> 3
  7741. </code></pre>
  7742.  
  7743. <dt><a name="info"><code>(info 'any ['flg]) -> (cnt|T dat . tim)</code></a>
  7744. <dd>Returns information about a file with the name <code>any</code>: The current
  7745. size <code>cnt</code> in bytes, and the modification date and time (UTC). For
  7746. directories, <code>T</code> is returned instead of the size. If <code>flg</code>
  7747. is non-<code>NIL</code> and <code>any</code> is the name of a symbolic link,
  7748. then the link itself is used, not the file that it refers to. See also <code><a
  7749. href="#dir">dir</a></code>, <code><a
  7750. href="#date">date</a></code>, <code><a
  7751. href="#time">time</a></code> and <code><a
  7752. href="#lines">lines</a></code>.
  7753.  
  7754. <pre><code>
  7755. $ ls -l x.l
  7756. -rw-r--r-- 1 abu users 208 Jun 17 08:58 x.l
  7757. $ pil +
  7758. : (info "x.l")
  7759. -> (208 730594 . 32315)
  7760. : (stamp 730594 32315)
  7761. -> "2000-06-17 08:58:35"
  7762. </code></pre>
  7763.  
  7764. <dt><a name="init"><code>(init 'tree ['any1] ['any2]) -> lst</code></a>
  7765. <dd>Initializes a structure for stepping iteratively through a database tree.
  7766. <code>any1</code> and <code>any2</code> may specify a range of keys. If
  7767. <code>any2</code> is greater than <code>any1</code>, the traversal will be in
  7768. opposite direction. See also <code><a href="#tree">tree</a></code>,
  7769. <code><a href="#step">step</a></code>, <code><a
  7770. href="#iter">iter</a></code> and <code><a
  7771. href="#scan">scan</a></code>.
  7772.  
  7773. <pre><code>
  7774. : (init (tree 'nr '+Item) 3 5)
  7775. -> (((3 . 5) ((3 NIL . {3-3}) (4 NIL . {3-4}) (5 NIL . {3-5}) (6 NIL . {3-6}) (7 NIL . {3-8}))))
  7776. </code></pre>
  7777.  
  7778. <dt><a name="insert"><code>(insert 'cnt 'lst 'any) -> lst</code></a>
  7779. <dd>Inserts <code>any</code> into <code>lst</code> at position <code>cnt</code>.
  7780. This is a non-destructive operation. See also <code><a
  7781. href="#remove">remove</a></code>, <code><a
  7782. href="#place">place</a></code>, <code><a
  7783. href="#append">append</a></code>, <code><a
  7784. href="#delete">delete</a></code> and <code><a
  7785. href="#replace">replace</a></code>.
  7786.  
  7787. <pre><code>
  7788. : (insert 3 '(a b c d e) 777)
  7789. -> (a b 777 c d e)
  7790. : (insert 1 '(a b c d e) 777)
  7791. -> (777 a b c d e)
  7792. : (insert 9 '(a b c d e) 777)
  7793. -> (a b c d e 777)
  7794. </code></pre>
  7795.  
  7796. <dt><a name="intern"><code>(intern 'sym) -> sym</code></a>
  7797. <dd>Creates or finds an internal symbol. If a symbol with the name
  7798. <code>sym</code> is already intern, it is returned. Otherwise, <code>sym</code>
  7799. is interned and returned. See also <code><a
  7800. href="#symbols">symbols</a></code>, <code><a
  7801. href="#zap">zap</a></code>, <code><a
  7802. href="#extern">extern</a></code> and <code><a
  7803. href="#====">====</a></code>.
  7804.  
  7805. <pre><code>
  7806. : (intern "abc")
  7807. -> abc
  7808. : (intern 'car)
  7809. -> car
  7810. : ((intern (pack "c" "a" "r")) (1 2 3))
  7811. -> 1
  7812. </code></pre>
  7813.  
  7814. <dt><a name="ipid"><code>(ipid) -> pid | NIL</code></a>
  7815. <dd>Returns the corresponding process ID when the current input channel is
  7816. reading from a pipe, otherwise <code>NIL</code>. See also <code><a
  7817. href="#opid">opid</a></code>, <code><a
  7818. href="#in">in</a></code>, <code><a
  7819. href="#pipe">pipe</a></code> and <code><a
  7820. href="#load">load</a></code>.
  7821.  
  7822. <pre><code>
  7823. : (in '(ls "-l") (println (line T)) (kill (ipid)))
  7824. "total 7364"
  7825. -> T
  7826. </code></pre>
  7827.  
  7828. <dt><a name="isa"><code>(isa 'cls|typ 'obj) -> obj | NIL</code></a>
  7829. <dd>Returns <code>obj</code> when it is an object that inherits from
  7830. <code>cls</code> or <code>type</code>. See also <a href="#oop">OO
  7831. Concepts</a>, <code><a href="#class">class</a></code>, <code><a
  7832. href="#type">type</a></code>, <code><a
  7833. href="#new">new</a></code> and <code><a
  7834. href="#object">object</a></code>.
  7835.  
  7836. <pre><code>
  7837. : (isa '+Address Obj)
  7838. -> {1-17}
  7839. : (isa '(+Male +Person) Obj)
  7840. -> NIL
  7841. </code></pre>
  7842.  
  7843. <dt><a name="isa/2"><code>isa/2</code></a>
  7844. <dd><a href="#pilog">Pilog</a> predicate that succeeds if the second
  7845. argument is of the type or class given by the first argument, according to the
  7846. <code><a href="#isa">isa</a></code> function. Typically used in
  7847. <code><a href="#db/3">db/3</a></code> or <code><a
  7848. href="#select/3">select/3</a></code> database queries. See also
  7849. <code><a href="#same/3">same/3</a></code>, <code><a
  7850. href="#bool/3">bool/3</a></code>, <code><a
  7851. href="#range/3">range/3</a></code>, <code><a
  7852. href="#head/3">head/3</a></code>, <code><a
  7853. href="#fold/3">fold/3</a></code>, <code><a
  7854. href="#part/3">part/3</a></code> and <code><a
  7855. href="#tolr/3">tolr/3</a></code>.
  7856.  
  7857. <pre><code>
  7858. : (? (db nm +Person @Prs) (isa +Woman @Prs) (val @Nm @Prs nm))
  7859. @Prs={2-Y} @Nm="Alexandra of Denmark"
  7860. @Prs={2-1I} @Nm="Alice Maud Mary"
  7861. @Prs={2-F} @Nm="Anne"
  7862. @Prs={2-j} @Nm="Augusta Victoria". # Stop
  7863. </code></pre>
  7864.  
  7865. <dt><a name="iter"><code>(iter 'tree ['fun] ['any1] ['any2] ['flg])</code></a>
  7866. <dd>Iterates through a database tree by applying <code>fun</code> to all values.
  7867. <code>fun</code> defaults to <code><a
  7868. href="#println">println</a></code>. <code>any1</code> and
  7869. <code>any2</code> may specify a range of keys. If <code>any2</code> is greater
  7870. than <code>any1</code>, the traversal will be in opposite direction. Note that
  7871. the keys need not to be atomic, depending on the application's index structure.
  7872. If <code>flg</code> is non-<code>NIL</code>, partial keys are skipped. See also
  7873. <code><a href="#tree">tree</a></code>, <code><a
  7874. href="#ubIter">ubIter</a></code>, <code><a
  7875. href="#scan">scan</a></code>, <code><a
  7876. href="#init">init</a></code> and <code><a
  7877. href="#step">step</a></code>.
  7878.  
  7879. <pre><code>
  7880. : (iter (tree 'nr '+Item))
  7881. {3-1}
  7882. {3-2}
  7883. {3-3}
  7884. {3-4}
  7885. {3-5}
  7886. {3-6}
  7887. {3-8}
  7888. -> {7-1}
  7889. : (iter (tree 'nr '+Item) '((This) (println (: nm))))
  7890. "Main Part"
  7891. "Spare Part"
  7892. "Auxiliary Construction"
  7893. "Enhancement Additive"
  7894. "Metal Fittings"
  7895. "Gadget Appliance"
  7896. "Testartikel"
  7897. -> {7-1}
  7898. </code></pre>
  7899.  
  7900. </dl>
  7901.  
  7902. <h1><a name="J">J</a></h1>
  7903.  
  7904. <dl>
  7905.  
  7906. <dt><a name="+Joint"><code>+Joint</code></a>
  7907. <dd>Class for bidirectional object relations, a subclass of <code><a
  7908. href="#+Link">+Link</a></code>. Expects a (symbolic) attribute, and
  7909. list of classes as <code><a href="#type">type</a></code> of the
  7910. referred database object (of class <code><a
  7911. href="#+Entity">+Entity</a></code>). A <code>+Joint</code> corresponds
  7912. to two <code>+Link</code>s, where the attribute argument is the relation of the
  7913. back-link in the referred object. See also <a
  7914. href="#dbase">Database</a>.
  7915.  
  7916. <pre><code>
  7917. (class +Ord +Entity) # Order class
  7918. (rel pos (+List +Joint) ord (+Pos)) # List of positions in that order
  7919. ...
  7920. (class +Pos +Entity) # Position class
  7921. (rel ord (+Joint) # Back-link to the parent order
  7922. </code></pre>
  7923.  
  7924. <dt><a name="job"><code>(job 'lst . prg) -> any</code></a>
  7925. <dd>Executes a job within its own environment (as specified by symbol-value
  7926. pairs in <code>lst</code>). The current values of all symbols are saved, the
  7927. symbols are bound to the values in <code>lst</code>, <code>prg</code> is
  7928. executed, then the (possibly modified) symbol values are (destructively) stored
  7929. in the environment list, and the symbols are restored to their original values.
  7930. The return value is the result of <code>prg</code>. Typically used in <code><a
  7931. href="#curry">curried</a></code> functions and <code><a
  7932. href="#*Run">*Run</a></code> tasks. See also <code><a
  7933. href="#env">env</a></code>, <code><a
  7934. href="#bind">bind</a></code>, <code><a
  7935. href="#let">let</a></code>, <code><a
  7936. href="#use">use</a></code> and <code><a
  7937. href="#state">state</a></code>.
  7938.  
  7939. <pre><code>
  7940. : (de tst ()
  7941. (job '((A . 0) (B . 0))
  7942. (println (inc 'A) (inc 'B 2)) ) )
  7943. -> tst
  7944. : (tst)
  7945. 1 2
  7946. -> 2
  7947. : (tst)
  7948. 2 4
  7949. -> 4
  7950. : (tst)
  7951. 3 6
  7952. -> 6
  7953. : (pp 'tst)
  7954. (de tst NIL
  7955. (job '((A . 3) (B . 6))
  7956. (println (inc 'A) (inc 'B 2)) ) )
  7957. -> tst
  7958. </code></pre>
  7959.  
  7960. <dt><a name="journal"><code>(journal 'any ..) -> T</code></a>
  7961. <dd>Reads journal data from the files with the names <code>any</code>, and
  7962. writes all changes to the database. See also <code><a
  7963. href="#pool">pool</a></code>.
  7964.  
  7965. <pre><code>
  7966. : (journal "db.log")
  7967. -> T
  7968. </code></pre>
  7969.  
  7970. </dl>
  7971.  
  7972. <h1><a name="K">K</a></h1>
  7973.  
  7974. <dl>
  7975.  
  7976. <dt><a name="+Key"><code>+Key</code></a>
  7977. <dd>Prefix class for maintaining unique indexes to <code><a
  7978. href="#+relation">+relation</a></code>s, a subclass of <code><a
  7979. href="#+index">+index</a></code>. Accepts an optional argument for a
  7980. <code><a href="#+Hook">+Hook</a></code> attribute. See also <a
  7981. href="#dbase">Database</a>.
  7982.  
  7983. <pre><code>
  7984. (rel nr (+Need +Key +Number)) # Mandatory, unique Customer/Supplier number
  7985. </code></pre>
  7986.  
  7987. <dt><a name="key"><code>(key ['cnt]) -> sym</code></a>
  7988. <dd>Returns the next character from standard input as a single-character
  7989. transient symbol. The console is set to raw mode. While waiting for a key press,
  7990. a <code>select</code> system call is executed for all file descriptors and
  7991. timers in the <code>VAL</code> of the global variable <code><a
  7992. href="#*Run">*Run</a></code>. If <code>cnt</code> is
  7993. non-<code>NIL</code>, that amount of milliseconds is waited maximally, and
  7994. <code>NIL</code> is returned upon timeout. See also <code><a
  7995. href="#raw">raw</a></code> and <code><a
  7996. href="#wait">wait</a></code>.
  7997.  
  7998. <pre><code>
  7999. : (key) # Wait for a key
  8000. -> "a" # 'a' pressed
  8001. </code></pre>
  8002.  
  8003. <dt><a name="kids"><code>(kids) -> lst</code></a>
  8004. <dd>Returns a list of process IDs of all running child processes. See also
  8005. <code><a href="#fork">fork</a></code>, <code><a
  8006. href="#pipe">pipe</a></code>, <code><a
  8007. href="#tell">tell</a></code>, <code><a
  8008. href="#proc">proc</a></code> and <code><a
  8009. href="#kill">kill</a></code>.
  8010.  
  8011. <pre><code>
  8012. : (unless (fork) (wait 60000) (bye))
  8013. -> NIL
  8014. : (unless (fork) (wait 60000) (bye))
  8015. -> NIL
  8016.  
  8017. : (proc 'pil)
  8018. PID PPID STARTED SIZE %CPU WCHAN CMD
  8019. 2205 22853 19:45:24 1336 0.1 - /usr/bin/picolisp /usr/lib/picolisp/lib.l /usr/bin/pil +
  8020. 2266 2205 19:45:30 1336 0.0 - /usr/bin/picolisp /usr/lib/picolisp/lib.l /usr/bin/pil +
  8021. 2300 2205 19:45:33 1336 0.0 - /usr/bin/picolisp /usr/lib/picolisp/lib.l /usr/bin/pil +
  8022. -> T
  8023.  
  8024. : (kids)
  8025. -> (2300 2266)
  8026. </code></pre>
  8027.  
  8028. <dt><a name="kill"><code>(kill 'pid ['cnt]) -> flg</code></a>
  8029. <dd>Sends a signal with the signal number <code>cnt</code> (or SIGTERM if
  8030. <code>cnt</code> is not given) to the process with the ID <code>pid</code>.
  8031. Returns <code>T</code> if successful.
  8032.  
  8033. <pre><code>
  8034. : (kill *Pid 20) # Stop current process
  8035.  
  8036. [2]+ Stopped pil + # Unix shell
  8037. $ fg # Job control: Foreground
  8038. pil +
  8039. -> T # 'kill' was successful
  8040. </code></pre>
  8041.  
  8042. </dl>
  8043.  
  8044. <h1><a name="L">L</a></h1>
  8045.  
  8046. <dl>
  8047.  
  8048. <dt><a name="*Led"><code>*Led</code></a>
  8049. <dd>(Debug mode only) A global variable holding a (possibly empty)
  8050. <code>prg</code> body that implements a "Line editor". When
  8051. non-<code>NIL</code>, it should return a single symbol (string) upon execution.
  8052.  
  8053. <pre><code>
  8054. : (de *Led "(bye)")
  8055. # *Led redefined
  8056. -> *Led
  8057. : $ # Exit
  8058. </code></pre>
  8059.  
  8060. <dt><a name="+Link"><code>+Link</code></a>
  8061. <dd>Class for object relations, a subclass of <code><a
  8062. href="#+relation">+relation</a></code>. Expects a list of classes as
  8063. <code><a href="#type">type</a></code> of the referred database object
  8064. (of class <code><a href="#+Entity">+Entity</a></code>). See also <a
  8065. href="#dbase">Database</a>.
  8066.  
  8067. <pre><code>
  8068. (rel sup (+Ref +Link) NIL (+CuSu)) # Supplier (class Customer/Supplier)
  8069. </code></pre>
  8070.  
  8071. <dt><a name="+List"><code>+List</code></a>
  8072. <dd>Prefix class for a list of identical relations. Objects of that class
  8073. maintain a list of Lisp data of uniform type. See also <a
  8074. href="#dbase">Database</a>.
  8075.  
  8076. <pre><code>
  8077. (rel pos (+List +Joint) ord (+Pos)) # Positions
  8078. (rel nm (+List +Ref +String)) # List of indexed strings
  8079. (rel val (+Ref +List +Number)) # Indexed list of numeric values
  8080. </code></pre>
  8081.  
  8082. <dt><a name="last"><code>(last 'lst) -> any</code></a>
  8083. <dd>Returns the last element of <code>lst</code>. See also <code><a
  8084. href="#fin">fin</a></code> and <code><a
  8085. href="#tail">tail</a></code>.
  8086.  
  8087. <pre><code>
  8088. : (last (1 2 3 4))
  8089. -> 4
  8090. : (last '((a b) c (d e f)))
  8091. -> (d e f)
  8092. </code></pre>
  8093.  
  8094. <dt><a name="later"><code>(later 'var . prg) -> var</code></a>
  8095. <dd>Executes <code>prg</code> in a <code><a
  8096. href="#pipe">pipe</a></code>'ed child process. The return value of
  8097. <code>prg</code> will later be available in <code>var</code>.
  8098.  
  8099. <pre><code>
  8100. : (prog1 # Parallel background calculation of square numbers
  8101. (mapcan '((N) (later (cons) (* N N))) (1 2 3 4))
  8102. (wait NIL (full @)) )
  8103. -> (1 4 9 16)
  8104. </code></pre>
  8105.  
  8106. <dt><a name="ld"><code>(ld) -> any</code></a>
  8107. <dd>(Debug mode only) <code><a href="#load">load</a></code>s the last
  8108. file edited with <code><a href="#vi">vi</a></code> or <code><a
  8109. href="#em">em</a></code>.
  8110.  
  8111. <pre><code>
  8112. : (vi 'main)
  8113. -> T
  8114. : (ld)
  8115. # main redefined
  8116. -> go
  8117. </code></pre>
  8118.  
  8119. <dt><a name="le0"><code>(le0 'any) -> num | NIL</code></a>
  8120. <dd>Returns <code>num</code> when the argument is a number less or equal zero,
  8121. otherwise <code>NIL</code>. See also <code><a
  8122. href="#lt0">lt0</a></code>, <code><a
  8123. href="#ge0">ge0</a></code>, <code><a
  8124. href="#gt0">gt0</a></code>, <code><a href="ref_.html#=0">=0</a></code>
  8125. and <code><a href="#n0">n0</a></code>.
  8126.  
  8127. <pre><code>
  8128. : (le0 -2)
  8129. -> -2
  8130. : (le0 0)
  8131. -> 0
  8132. : (le0 3)
  8133. -> NIL
  8134. </code></pre>
  8135.  
  8136. <dt><a name="leaf"><code>(leaf 'tree) -> any</code></a>
  8137. <dd>Returns the first leaf (i.e. the value of the smallest key) in a database
  8138. tree. See also <code><a href="#tree">tree</a></code>, <code><a
  8139. href="#minKey">minKey</a></code>, <code><a
  8140. href="#maxKey">maxKey</a></code> and <code><a
  8141. href="#step">step</a></code>.
  8142.  
  8143. <pre><code>
  8144. : (leaf (tree 'nr '+Item))
  8145. -> {3-1}
  8146. : (db 'nr '+Item (minKey (tree 'nr '+Item)))
  8147. -> {3-1}
  8148. </code></pre>
  8149.  
  8150. <dt><a name="length"><code>(length 'any) -> cnt | T</code></a>
  8151. <dd>Returns the "length" of <code>any</code>. For numbers this is the number of
  8152. decimal digits in the value (plus 1 for negative values), for symbols it is the
  8153. number of characters in the name, and for lists it is the number of cells (or
  8154. <code>T</code> for circular lists). See also <code><a
  8155. href="#size">size</a></code> and <code><a
  8156. href="#bytes">bytes</a></code>.
  8157.  
  8158. <pre><code>
  8159. : (length "abc")
  8160. -> 3
  8161. : (length "äbc")
  8162. -> 3
  8163. : (length 123)
  8164. -> 3
  8165. : (length (1 (2) 3))
  8166. -> 3
  8167. : (length (1 2 3 .))
  8168. -> T
  8169. </code></pre>
  8170.  
  8171. <dt><a name="less"><code>(less 'any) -> any</code></a>
  8172. <dd>(Debug mode only) Returns a reduced form of <code>any</code>, where for each
  8173. list and its sublists only the first two elements, possibly followed by
  8174. <code>..</code>, are retained.
  8175.  
  8176. <pre><code>
  8177. : (less '(a b c d))
  8178. -> (a b ..)
  8179. : (less '((a b c) ((d e f) g h) i j))
  8180. -> ((a b ..) ((d e ..) g ..) ..)
  8181. </code></pre>
  8182.  
  8183. <dt><a name="let"><code>(let sym 'any . prg) -> any</code></a>
  8184. <dt><code>(let (sym|lst 'any ..) . prg) -> any</code>
  8185. <dd>Defines local variables. The value of the symbol <code>sym</code> - or the
  8186. values of the symbols <code>sym</code> in the list of the second form - are
  8187. saved and the symbols are bound to the evaluated <code>any</code> arguments. The
  8188. 64-bit version also accepts <code>lst</code> arguments in the second form; they
  8189. may consist only of symbols and sublists, and match the <code>any</code>
  8190. argument (destructuring bind). <code>prg</code> is executed, then the symbols
  8191. are restored to their original values. The result of <code>prg</code> is
  8192. returned. It is an error condition to pass <code>NIL</code> as a
  8193. <code>sym</code> argument. In destructuring patterns, <code>NIL</code> denotes a
  8194. "don't care" position. See also <code><a href="#let?">let?</a></code>,
  8195. <code><a href="#bind">bind</a></code>, <code><a
  8196. href="#recur">recur</a></code>, <code><a
  8197. href="#with">with</a></code>, <code><a
  8198. href="#for">for</a></code>, <code><a
  8199. href="#job">job</a></code> and <code><a
  8200. href="#use">use</a></code>.
  8201.  
  8202. <pre><code>
  8203. : (setq X 123 Y 456)
  8204. -> 456
  8205. : (let X "Hello" (println X))
  8206. "Hello"
  8207. -> "Hello"
  8208. : (let (X "Hello" Y "world") (prinl X " " Y))
  8209. Hello world
  8210. -> "world"
  8211. : X
  8212. -> 123
  8213. : Y
  8214. -> 456
  8215.  
  8216. # 64-bit version
  8217. : (let (A 1 (B . C) (2 3) D 4)
  8218. (list A B C D) )
  8219. -> (1 2 (3) 4)
  8220.  
  8221. : (let (((A . B) (C) . D) '((1 2 3) (4 5 6) 7 8 9))
  8222. (list A B C D) )
  8223. -> (1 (2 3) 4 (7 8 9))
  8224.  
  8225. : (let (((A . NIL) NIL NIL D) '((1 2 3) (4 5 6) 7 8 9))
  8226. (trail T) )
  8227. -> (A 1 D 8)
  8228. </code></pre>
  8229.  
  8230. <dt><a name="let?"><code>(let? sym 'any . prg) -> any</code></a>
  8231. <dd>Conditional local variable binding and execution: If <code>any</code>
  8232. evaluates to <code>NIL</code>, <code>NIL</code> is returned. Otherwise, the
  8233. value of the symbol <code>sym</code> is saved and <code>sym</code> is bound to
  8234. the evaluated <code>any</code> argument. <code>prg</code> is executed, then
  8235. <code>sym</code> is restored to its original value. The result of
  8236. <code>prg</code> is returned. It is an error condition to pass <code>NIL</code>
  8237. as the <code>sym</code> argument. <code>(let? sym 'any ..)</code> is equivalent
  8238. to <code>(when 'any (let sym @ ..))</code>. See also <code><a
  8239. href="#let">let</a></code>, <code><a
  8240. href="#bind">bind</a></code>, <code><a
  8241. href="#job">job</a></code> and <code><a
  8242. href="#use">use</a></code>.
  8243.  
  8244. <pre><code>
  8245. : (setq Lst (1 NIL 2 NIL 3))
  8246. -> (1 NIL 2 NIL 3)
  8247. : (let? A (pop 'Lst) (println 'A A))
  8248. A 1
  8249. -> 1
  8250. : (let? A (pop 'Lst) (println 'A A))
  8251. -> NIL
  8252. </code></pre>
  8253.  
  8254. <dt><a name="lieu"><code>(lieu 'any) -> sym | NIL</code></a>
  8255. <dd>Returns the argument <code>any</code> when it is an external symbol and
  8256. currently manifest in heap space, otherwise <code>NIL</code>. See also <code><a
  8257. href="#ext?">ext?</a></code>.
  8258.  
  8259. <pre><code>
  8260. : (lieu *DB)
  8261. -> {1}
  8262. </code></pre>
  8263.  
  8264. <dt><a name="line"><code>(line 'flg ['cnt ..]) -> lst|sym</code></a>
  8265. <dd>Reads a line of characters from the current input channel. End of line is
  8266. recognized as linefeed (hex "0A"), carriage return (hex "0D"), or the
  8267. combination of both. (Note that a single carriage return may not work on network
  8268. connections, because the character look-ahead to distinguish from
  8269. return+linefeed can block the connection.) If <code>flg</code> is
  8270. <code>NIL</code>, a list of single-character transient symbols is returned. When
  8271. <code>cnt</code> arguments are given, subsequent characters of the input line
  8272. are grouped into sublists, to allow parsing of fixed field length records. If
  8273. <code>flg</code> is non-<code>NIL</code>, strings are returned instead of
  8274. single-character lists. <code>NIL</code> is returned upon end of file. See also
  8275. <code><a href="#char">char</a></code>, <code><a
  8276. href="#read">read</a></code>, <code><a
  8277. href="#till">till</a></code> and <code><a
  8278. href="#eof">eof</a></code>.
  8279.  
  8280. <pre><code>
  8281. : (line)
  8282. abcdefghijkl
  8283. -> ("a" "b" "c" "d" "e" "f" "g" "h" "i" "j" "k" "l")
  8284. : (line T)
  8285. abcdefghijkl
  8286. -> "abcdefghijkl"
  8287. : (line NIL 1 2 3)
  8288. abcdefghijkl
  8289. -> (("a") ("b" "c") ("d" "e" "f") "g" "h" "i" "j" "k" "l")
  8290. : (line T 1 2 3)
  8291. abcdefghijkl
  8292. -> ("a" "bc" "def" "g" "h" "i" "j" "k" "l")
  8293. </code></pre>
  8294.  
  8295. <dt><a name="lines"><code>(lines 'any ..) -> cnt</code></a>
  8296. <dd>Returns the sum of the number of lines in the files with the names
  8297. <code>any</code>, or <code>NIL</code> if none was found. See also <code><a
  8298. href="#info">info</a></code>.
  8299.  
  8300. <pre><code>
  8301. : (lines "x.l")
  8302. -> 11
  8303. </code></pre>
  8304.  
  8305. <dt><a name="link"><code>(link 'any ..) -> any</code></a>
  8306. <dd>Links one or several new elements <code>any</code> to the end of the list in
  8307. the current <code><a href="#make">make</a></code> environment. This
  8308. operation is efficient also for long lists, because a pointer to the last
  8309. element of the list is maintained. <code>link</code> returns the last linked
  8310. argument. See also <code><a href="#yoke">yoke</a></code>, <code><a
  8311. href="#chain">chain</a></code> and <code><a
  8312. href="#made">made</a></code>.
  8313.  
  8314. <pre><code>
  8315. : (make
  8316. (println (link 1))
  8317. (println (link 2 3)) )
  8318. 1
  8319. 3
  8320. -> (1 2 3)
  8321. </code></pre>
  8322.  
  8323. <dt><a name="lint"><code>(lint 'sym) -> lst</code></a>
  8324. <dt><code>(lint 'sym 'cls) -> lst</code>
  8325. <dt><code>(lint '(sym . cls)) -> lst</code>
  8326. <dd>(Debug mode only) Checks the function definition or file contents (in the
  8327. first form), or the method body of sym (second and third form), for possible
  8328. pitfalls. Returns an association list of diagnoses, where <code>var</code>
  8329. indicates improper variables, <code>dup</code> duplicate parameters,
  8330. <code>def</code> an undefined function, <code>bnd</code> an unbound variable,
  8331. and <code>use</code> unused variables. See also <code><a
  8332. href="#noLint">noLint</a></code>, <code><a
  8333. href="#lintAll">lintAll</a></code>, <code><a
  8334. href="#debug">debug</a></code>, <code><a
  8335. href="#trace">trace</a></code> and <code><a
  8336. href="#*Dbg">*Dbg</a></code>.
  8337.  
  8338. <pre><code>
  8339. : (de foo (R S T R) # 'T' is a improper parameter, 'R' is duplicated
  8340. (let N 7 # 'N' is unused
  8341. (bar X Y) ) ) # 'bar' is undefined, 'X' and 'Y' are not bound
  8342. -> foo
  8343. : (lint 'foo)
  8344. -> ((var T) (dup R) (def bar) (bnd Y X) (use N))
  8345. </code></pre>
  8346.  
  8347. <dt><a name="lintAll"><code>(lintAll ['sym ..]) -> lst</code></a>
  8348. <dd>(Debug mode only) Applies <code><a href="#lint">lint</a></code> to
  8349. <code><a href="#all">all</a></code> internal symbols - and optionally
  8350. to all files <code>sym</code> - and returns a list of diagnoses. See also
  8351. <code><a href="#noLint">noLint</a></code>.
  8352.  
  8353. <pre><code>
  8354. : (more (lintAll "file1.l" "file2.l"))
  8355. ...
  8356. </code></pre>
  8357.  
  8358. <dt><a name="lisp"><code>(lisp 'sym ['fun]) -> num</code></a>
  8359. <dd>(64-bit version only) Installs under the tag <code>sym</code> a callback
  8360. function <code>fun</code>, and returns a pointer <code>num</code> suitable to be
  8361. passed to a C function via 'native'. If <code>fun</code> is <code>NIL</code>,
  8362. the corresponding entry is freed. Maximally 24 callback functions can be
  8363. installed that way. 'fun' should be a function of maximally five numbers, and
  8364. should return a number. "Numbers" in this context are 64-bit scalars, and may
  8365. not only represent integers, but also pointers or other encoded data. See also
  8366. <code><a href="#native">native</a></code> and <code><a
  8367. href="#struct">struct</a></code>.
  8368.  
  8369. <pre><code>
  8370. (load "lib/native.l")
  8371.  
  8372. (gcc "ltest" NIL
  8373. (cbTest (Fun) cbTest 'N Fun) )
  8374.  
  8375. long cbTest(int(*fun)(int,int,int,int,int)) {
  8376. return fun(1,2,3,4,5);
  8377. }
  8378. /**/
  8379.  
  8380. : (cbTest
  8381. (lisp 'cbTest
  8382. '((A B C D E)
  8383. (msg (list A B C D E))
  8384. (* A B C D E) ) ) )
  8385. (1 2 3 4 5)
  8386. -> 120
  8387. </code></pre>
  8388.  
  8389. <dt><a name="list"><code>(list 'any ['any ..]) -> lst</code></a>
  8390. <dd>Returns a list of all <code>any</code> arguments. See also <code><a
  8391. href="#cons">cons</a></code>.
  8392.  
  8393. <pre><code>
  8394. : (list 1 2 3 4)
  8395. -> (1 2 3 4)
  8396. : (list 'a (2 3) "OK")
  8397. -> (a (2 3) "OK")
  8398. </code></pre>
  8399.  
  8400. <dt><a name="lst/3"><code>lst/3</code></a>
  8401. <dd><a href="#pilog">Pilog</a> predicate that returns subsequent list
  8402. elements, after applying the <code><a href="#get">get</a></code>
  8403. algorithm to that object and the following arguments. Often used in database
  8404. queries. See also <code><a href="#map/3">map/3</a></code>.
  8405.  
  8406. <pre><code>
  8407. : (? (db nr +Ord 1 @Ord) (lst @Pos @Ord pos))
  8408. @Ord={3-7} @Pos={4-1}
  8409. @Ord={3-7} @Pos={4-2}
  8410. @Ord={3-7} @Pos={4-3}
  8411. -> NIL
  8412. </code></pre>
  8413.  
  8414. <dt><a name="lst?"><code>(lst? 'any) -> flg</code></a>
  8415. <dd>Returns <code>T</code> when the argument <code>any</code> is a (possibly
  8416. empty) list (<code>NIL</code> or a cons pair). See also <code><a
  8417. href="#pair">pair</a></code>.
  8418.  
  8419. <pre><code>
  8420. : (lst? NIL)
  8421. -> T
  8422. : (lst? (1 . 2))
  8423. -> T
  8424. : (lst? (1 2 3))
  8425. -> T
  8426. </code></pre>
  8427.  
  8428. <dt><a name="listen"><code>(listen 'cnt1 ['cnt2]) -> cnt | NIL</code></a>
  8429. <dd>Listens at a socket descriptor <code>cnt1</code> (as received by <code><a
  8430. href="#port">port</a></code>) for an incoming connection, and returns
  8431. the new socket descriptor <code>cnt</code>. While waiting for a connection, a
  8432. <code>select</code> system call is executed for all file descriptors and timers
  8433. in the <code>VAL</code> of the global variable <code><a
  8434. href="#*Run">*Run</a></code>. If <code>cnt2</code> is
  8435. non-<code>NIL</code>, that amount of milliseconds is waited maximally, and
  8436. <code>NIL</code> is returned upon timeout. The global variable <code>*Adr</code>
  8437. is set to the IP address of the client. See also <code><a
  8438. href="#accept">accept</a></code>, <code><a
  8439. href="#connect">connect</a></code>, <code><a
  8440. href="#*Adr">*Adr</a></code>.
  8441.  
  8442. <pre><code>
  8443. : (setq *Socket
  8444. (listen (port 6789) 60000) ) # Listen at port 6789 for max 60 seconds
  8445. -> 4
  8446. : *Adr
  8447. -> "127.0.0.1"
  8448. </code></pre>
  8449.  
  8450. <dt><a name="lit"><code>(lit 'any) -> any</code></a>
  8451. <dd>Returns the literal (i.e. quoted) value of <code>any</code>, by
  8452. <code>cons</code>ing it with the <code><a
  8453. href="#quote">quote</a></code> function if necessary.
  8454.  
  8455. <pre><code>
  8456. : (lit T)
  8457. -> T
  8458. : (lit 1)
  8459. -> 1
  8460. : (lit '(1))
  8461. -> (1)
  8462. : (lit '(a))
  8463. -> '(a)
  8464. </code></pre>
  8465.  
  8466. <dt><a name="load"><code>(load 'any ..) -> any</code></a>
  8467. <dd>Loads all <code>any</code> arguments. Normally, the name of each argument is
  8468. taken as a file to be executed in a read-eval loop. The argument semantics are
  8469. identical to that of <code><a href="#in">in</a></code>, with the
  8470. exception that if an argument is a symbol and its first character is a hyphen
  8471. '-', then that argument is parsed as an executable list (without the surrounding
  8472. parentheses). When <code>any</code> is <code>T</code>, all remaining command
  8473. line arguments are <code>load</code>ed recursively. When <code>any</code> is
  8474. <code>NIL</code>, standard input is read, a prompt is issued before each read
  8475. operation, the results are printed to standard output (read-eval-print loop),
  8476. and <code>load</code> terminates when an empty line is entered. In any case,
  8477. <code>load</code> terminates upon end of file, or when <code>NIL</code> is read.
  8478. The index for transient symbols is cleared before and after the load, so that
  8479. all transient symbols in a file have a local scope. If the namespace was
  8480. switched (with <code><a href="#symbols">symbols</a></code>) while
  8481. executing a file, it is restored to the previous one. Returns the value of the
  8482. last evaluated expression. See also <code><a
  8483. href="#script">script</a></code>, <code><a
  8484. href="#ipid">ipid</a></code>, <code><a
  8485. href="#call">call</a></code>, <code><a
  8486. href="#file">file</a></code>, <code><a
  8487. href="#in">in</a></code>, <code><a href="refO.html#out">out</a></code>
  8488. and <code><a href="#str">str</a></code>.
  8489.  
  8490. <pre><code>
  8491. : (load "lib.l" "-* 1 2 3")
  8492. -> 6
  8493. </code></pre>
  8494.  
  8495. <dt><a name="loc"><code>(loc 'sym 'lst) -> sym</code></a>
  8496. <dd>Locates in <code>lst</code> a <code><a
  8497. href="#transient">transient</a></code> symbol with the same name as
  8498. <code>sym</code>. Allows to get hold of otherwise inaccessible symbols. See also
  8499. <code><a href="#====">====</a></code>.
  8500.  
  8501. <pre><code>
  8502. : (loc "X" curry)
  8503. -> "X"
  8504. : (== @ "X")
  8505. -> NIL
  8506. </code></pre>
  8507.  
  8508. <dt><a name="local"><code>(local . lst) -> sym</code></a>
  8509. <dd>Wrapper function for <code><a href="#zap">zap</a></code>. Typically
  8510. used to create namespace-local symbols. <code>lst</code> should be a list of
  8511. symbols. See also <code><a href="#pico">pico</a></code>, <code><a
  8512. href="#symbols">symbols</a></code>, <code><a
  8513. href="#import">import</a></code> and <code><a
  8514. href="#intern">intern</a></code>.
  8515.  
  8516. <pre><code>
  8517. : (symbols 'myLib 'pico)
  8518. -> pico
  8519. myLib: (local bar foo)
  8520. -> "foo"
  8521.  
  8522. myLib: (de foo (A) # 'foo' is local to 'myLib'
  8523. ...
  8524. myLib: (de bar (B) # 'bar' is local to 'myLib'
  8525. ...
  8526. </code></pre>
  8527.  
  8528. <dt><a name="locale"><code>(locale 'sym1 'sym2 ['sym ..])</code></a>
  8529. <dd>Sets the current locale to that given by the country file <code>sym1</code>
  8530. and the language file <code>sym2</code> (both located in the "loc/" directory),
  8531. and optional application-specific directories <code>sym</code>. The locale
  8532. influences the language, and numerical, date and other formats. See also
  8533. <code><a href="#*Uni">*Uni</a></code>, <code><a
  8534. href="#datStr">datStr</a></code>, <code><a
  8535. href="#strDat">strDat</a></code>, <code><a
  8536. href="#expDat">expDat</a></code>, <code><a
  8537. href="#day">day</a></code>, <code><a
  8538. href="#telStr">telStr</a></code>, <code><a
  8539. href="#expTel">expTel</a></code> and and <code><a
  8540. href="#money">money</a></code>.
  8541.  
  8542. <pre><code>
  8543. : (locale "DE" "de" "app/loc/")
  8544. -> "Zip"
  8545. : ,"Yes"
  8546. -> "Ja"
  8547. </code></pre>
  8548.  
  8549. <dt><a name="lock"><code>(lock ['sym]) -> cnt | NIL</code></a>
  8550. <dd>Write-locks an external symbol <code>sym</code> (file record locking), or
  8551. the whole database root file if <code>sym</code> is <code>NIL</code>. Returns
  8552. <code>NIL</code> if successful, or the ID of the process currently holding the
  8553. lock. When <code>sym</code> is non-<code>NIL</code>, the lock is released at the
  8554. next top level call to <code><a href="#commit">commit</a></code> or
  8555. <code><a href="#rollback">rollback</a></code>, otherwise only when
  8556. another database is opened with <code><a href="#pool">pool</a></code>,
  8557. or when the process terminates. See also <code><a
  8558. href="#*Solo">*Solo</a></code>.
  8559.  
  8560. <pre><code>
  8561. : (lock '{1}) # Lock single object
  8562. -> NIL
  8563. : (lock) # Lock whole database
  8564. -> NIL
  8565. </code></pre>
  8566.  
  8567. <dt><a name="loop"><code>(loop ['any | (NIL 'any . prg) | (T 'any . prg) ..]) -> any</code></a>
  8568. <dd>Endless loop with multiple conditional exits: The body is executed an
  8569. unlimited number of times. If a clause has <code>NIL</code> or <code>T</code> as
  8570. its CAR, the clause's second element is evaluated as a condition and - if the
  8571. result is <code>NIL</code> or non-<code>NIL</code>, respectively - the
  8572. <code>prg</code> is executed and the result returned. See also <code><a
  8573. href="#do">do</a></code> and <code><a
  8574. href="#for">for</a></code>.
  8575.  
  8576. <pre><code>
  8577. : (let N 3
  8578. (loop
  8579. (prinl N)
  8580. (T (=0 (dec 'N)) 'done) ) )
  8581. 3
  8582. 2
  8583. 1
  8584. -> done
  8585. </code></pre>
  8586.  
  8587. <dt><a name="low?"><code>(low? 'any) -> sym | NIL</code></a> <dd>Returns
  8588. <code>any</code> when the argument is a string (symbol) that starts with a
  8589. lowercase character. See also <code><a href="#lowc">lowc</a></code> and
  8590. <code><a href="#upp?">upp?</a></code>
  8591.  
  8592. <pre><code>
  8593. : (low? "a")
  8594. -> "a"
  8595. : (low? "A")
  8596. -> NIL
  8597. : (low? 123)
  8598. -> NIL
  8599. : (low? ".")
  8600. -> NIL
  8601. </code></pre>
  8602.  
  8603. <dt><a name="lowc"><code>(lowc 'any) -> any</code></a>
  8604. <dd>Lower case conversion: If <code>any</code> is not a symbol, it is returned
  8605. as it is. Otherwise, a new transient symbol with all characters of
  8606. <code>any</code>, converted to lower case, is returned. See also <code><a
  8607. href="#uppc">uppc</a></code>, <code><a
  8608. href="#fold">fold</a></code> and <code><a
  8609. href="#low?">low?</a></code>.
  8610.  
  8611. <pre><code>
  8612. : (lowc 123)
  8613. -> 123
  8614. : (lowc "ABC")
  8615. -> "abc"
  8616. </code></pre>
  8617.  
  8618. <dt><a name="lt0"><code>(lt0 'any) -> num | NIL</code></a>
  8619. <dd>Returns <code>num</code> when the argument is a number and less than zero,
  8620. otherwise <code>NIL</code>. See also <code><a
  8621. href="#le0">le0</a></code>, <code><a
  8622. href="#ge0">ge0</a></code>, <code><a
  8623. href="#gt0">gt0</a></code>, <code><a href="ref_.html#=0">=0</a></code>
  8624. and <code><a href="#n0">n0</a></code>.
  8625.  
  8626. <pre><code>
  8627. : (lt0 -2)
  8628. -> -2
  8629. : (lt0 3)
  8630. -> NIL
  8631. </code></pre>
  8632.  
  8633. <dt><a name="lup"><code>(lup 'lst 'any) -> lst</code></a>
  8634. <dt><code>(lup 'lst 'any 'any2) -> lst</code>
  8635. <dd>Looks up <code>any</code> in the CAR-elements of cons pairs stored in the
  8636. index tree <code>lst</code>, as built-up by <code><a
  8637. href="#idx">idx</a></code>. In the first form, the first found cons
  8638. pair is returned, in the second form a list of all pairs whose CAR is in the
  8639. range <code>any</code> .. <code>any2</code>. See also <code><a
  8640. href="#assoc">assoc</a></code>.
  8641.  
  8642. <pre><code>
  8643. : (idx 'A 'a T)
  8644. -> NIL
  8645. : (idx 'A (1 . b) T)
  8646. -> NIL
  8647. : (idx 'A 123 T)
  8648. -> NIL
  8649. : (idx 'A (1 . a) T)
  8650. -> NIL
  8651. : (idx 'A (1 . c) T)
  8652. -> NIL
  8653. : (idx 'A (2 . d) T)
  8654. -> NIL
  8655. : (idx 'A)
  8656. -> (123 a (1 . a) (1 . b) (1 . c) (2 . d))
  8657. : (lup A 1)
  8658. -> (1 . b)
  8659. : (lup A 2)
  8660. -> (2 . d)
  8661. : (lup A 1 1)
  8662. -> ((1 . a) (1 . b) (1 . c))
  8663. : (lup A 1 2)
  8664. -> ((1 . a) (1 . b) (1 . c) (2 . d))
  8665. </code></pre>
  8666.  
  8667. </dl>
  8668.  
  8669. <h1><a name="M">M</a></h1>
  8670.  
  8671. <dl>
  8672.  
  8673. <dt><a name="*Msg"><code>*Msg</code></a>
  8674. <dd>A global variable holding the last recently issued error message. See also
  8675. <code><a href="#errors">Error Handling</a></code>, <code><a
  8676. href="#*Err">*Err</a></code> and <code><a
  8677. href="#^">^</a></code>.
  8678.  
  8679. <pre><code>
  8680. : (+ 'A 2)
  8681. !? (+ 'A 2)
  8682. A -- Number expected
  8683. ?
  8684. :
  8685. : *Msg
  8686. -> "Number expected"
  8687. </code></pre>
  8688.  
  8689. <dt><a name="+Mis"><code>+Mis</code></a>
  8690. <dd>Prefix class to explicitly specify validation functions for <code><a
  8691. href="#+relation">+relation</a></code>s. Expects a function that takes
  8692. a value and an entity object, and returns <code>NIL</code> if everything is
  8693. correct, or an error string. See also <a href="#dbase">Database</a>.
  8694.  
  8695. <pre><code>
  8696. (class +Ord +Entity) # Order class
  8697. (rel pos (+Mis +List +Joint) # List of positions in that order
  8698. ((Val Obj)
  8699. (when (memq NIL Val)
  8700. "There are empty positions" ) )
  8701. ord (+Pos) )
  8702. </code></pre>
  8703.  
  8704. <dt><a name="macro"><code>(macro prg) -> any</code></a>
  8705. <dd>Substitues all <code><a href="#pat?">pat?</a></code> symbols in
  8706. <code>prg</code> (using <code><a href="#fill">fill</a></code>), and
  8707. executes the result with <code><a href="#run">run</a></code>. Used
  8708. occasionally to call functions which otherwise do not evaluate their arguments.
  8709.  
  8710. <pre><code>
  8711. : (de timerMessage (@N . @Prg)
  8712. (setq @N (- @N))
  8713. (macro
  8714. (task @N 0 . @Prg) ) )
  8715. -> timerMessage
  8716. : (timerMessage 6000 (println 'Timer 6000))
  8717. -> (-6000 0 (println 'Timer 6000))
  8718. : (timerMessage 12000 (println 'Timer 12000))
  8719. -> (-12000 0 (println 'Timer 12000))
  8720. : (more *Run)
  8721. (-12000 2616 (println 'Timer 12000))
  8722. (-6000 2100 (println 'Timer 6000))
  8723. -> NIL
  8724. : Timer 6000
  8725. Timer 12000
  8726. ...
  8727. </code></pre>
  8728.  
  8729. <dt><a name="made"><code>(made ['lst1 ['lst2]]) -> lst</code></a>
  8730. <dd>Initializes a new list value for the current <code><a
  8731. href="#make">make</a></code> environment. All list elements already
  8732. produced with <code><a href="#chain">chain</a></code> and <code><a
  8733. href="#link">link</a></code> are discarded, and <code>lst1</code> is
  8734. used instead. Optionally, <code>lst2</code> can be specified as the new linkage
  8735. cell, otherwise the last cell of <code>lst1</code> is used. When called without
  8736. arguments, <code>made</code> does not modify the environment. In any case, the
  8737. current list is returned.
  8738.  
  8739. <pre><code>
  8740. : (make
  8741. (link 'a 'b 'c) # Link three items
  8742. (println (made)) # Print current list (a b c)
  8743. (made (1 2 3)) # Discard it, start new with (1 2 3)
  8744. (link 4) ) # Link 4
  8745. (a b c)
  8746. -> (1 2 3 4)
  8747. </code></pre>
  8748.  
  8749. <dt><a name="mail"><code>(mail 'any 'cnt 'sym1 'sym2|lst1 'sym3 'lst2 . prg)'</code></a>
  8750. <dd>Sends an eMail via SMTP to a mail server at host <code>any</code>, port
  8751. <code>cnt</code>. <code>sym1</code> should be the "from" address,
  8752. <code>sym2|lst1</code> the "to" address(es), and <code>sym3</code> the subject.
  8753. <code>lst2</code> is a list of attachments, each one specified by three elements
  8754. for path, name and mime type. <code>prg</code> generates the mail body with
  8755. <code><a href="#prEval">prEval</a></code>. See also <code><a
  8756. href="#connect">connect</a></code>.
  8757.  
  8758. <pre><code>
  8759. (mail "localhost" 25 # Local mail server
  8760. "a@bc.de" # "From" address
  8761. "abu@software-lab.de" # "To" address
  8762. "Testmail" # Subject
  8763. (quote
  8764. "img/go.png" "go.png" "image/png" # First attachment
  8765. "img/7fach.gif" "7fach.gif" "image/gif" ) # Second attachment
  8766. "Hello," # First line
  8767. NIL # (empty line)
  8768. (prinl (pack "This is mail #" (+ 3 4))) ) # Third line
  8769. </code></pre>
  8770.  
  8771. <dt><a name="make"><code>(make .. [(made 'lst ..)] .. [(link 'any ..)] ..) -> any</code></a>
  8772. <dd>Initializes and executes a list-building process with the <code><a
  8773. href="#made">made</a></code>, <code><a
  8774. href="#chain">chain</a></code>, <code><a
  8775. href="#link">link</a></code> and <code><a
  8776. href="#yoke">yoke</a></code> functions, and returns the result list.
  8777. For efficiency, pointers to the head and the tail of the list are maintained
  8778. internally.
  8779.  
  8780. <pre><code>
  8781. : (make (link 1) (link 2 3) (link 4))
  8782. -> (1 2 3 4)
  8783. : (make (made (1 2 3)) (link 4))
  8784. -> (1 2 3 4)
  8785. </code></pre>
  8786.  
  8787. <dt><a name="map"><code>(map 'fun 'lst ..) -> lst</code></a>
  8788. <dd>Applies <code>fun</code> to <code>lst</code> and all successive CDRs. When
  8789. additional <code>lst</code> arguments are given, they are passed to
  8790. <code>fun</code> in the same way. Returns the result of the last application.
  8791. See also <code><a href="#mapc">mapc</a></code>, <code><a
  8792. href="#maplist">maplist</a></code>, <code><a
  8793. href="#mapcar">mapcar</a></code>, <code><a
  8794. href="#mapcon">mapcon</a></code>, <code><a
  8795. href="#mapcan">mapcan</a></code> and <code><a
  8796. href="#filter">filter</a></code>.
  8797.  
  8798. <pre><code>
  8799. : (map println (1 2 3 4) '(A B C))
  8800. (1 2 3 4) (A B C)
  8801. (2 3 4) (B C)
  8802. (3 4) (C)
  8803. (4) NIL
  8804. -> NIL
  8805. </code></pre>
  8806.  
  8807. <dt><a name="map/3"><code>map/3</code></a>
  8808. <dd><a href="#pilog">Pilog</a> predicate that returns a list and
  8809. subsequent CDRs of that list, after applying the <code><a
  8810. href="#get">get</a></code> algorithm to that object and the following
  8811. arguments. Often used in database queries. See also <code><a
  8812. href="#lst/3">lst/3</a></code>.
  8813.  
  8814. <pre><code>
  8815. : (? (db nr +Ord 1 @Ord) (map @L @Ord pos))
  8816. @Ord={3-7} @L=({4-1} {4-2} {4-3})
  8817. @Ord={3-7} @L=({4-2} {4-3})
  8818. @Ord={3-7} @L=({4-3})
  8819. -> NIL
  8820. </code></pre>
  8821.  
  8822. <dt><a name="mapc"><code>(mapc 'fun 'lst ..) -> any</code></a>
  8823. <dd>Applies <code>fun</code> to each element of <code>lst</code>. When
  8824. additional <code>lst</code> arguments are given, their elements are also passed
  8825. to <code>fun</code>. Returns the result of the last application. See also
  8826. <code><a href="#map">map</a></code>, <code><a
  8827. href="#maplist">maplist</a></code>, <code><a
  8828. href="#mapcar">mapcar</a></code>, <code><a
  8829. href="#mapcon">mapcon</a></code>, <code><a
  8830. href="#mapcan">mapcan</a></code> and <code><a
  8831. href="#filter">filter</a></code>.
  8832.  
  8833. <pre><code>
  8834. : (mapc println (1 2 3 4) '(A B C))
  8835. 1 A
  8836. 2 B
  8837. 3 C
  8838. 4 NIL
  8839. -> NIL
  8840. </code></pre>
  8841.  
  8842. <dt><a name="mapcan"><code>(mapcan 'fun 'lst ..) -> lst</code></a>
  8843. <dd>Applies <code>fun</code> to each element of <code>lst</code>. When
  8844. additional <code>lst</code> arguments are given, their elements are also passed
  8845. to <code>fun</code>. Returns a (destructively) concatenated list of all results.
  8846. See also <code><a href="#map">map</a></code>, <code><a
  8847. href="#mapc">mapc</a></code>, <code><a
  8848. href="#maplist">maplist</a></code>, <code><a
  8849. href="#mapcar">mapcar</a></code>, <code><a
  8850. href="#mapcon">mapcon</a></code>, <code><a
  8851. href="#filter">filter</a></code>.
  8852.  
  8853. <pre><code>
  8854. : (mapcan reverse '((a b c) (d e f) (g h i)))
  8855. -> (c b a f e d i h g)
  8856. </code></pre>
  8857.  
  8858. <dt><a name="mapcar"><code>(mapcar 'fun 'lst ..) -> lst</code></a>
  8859. <dd>Applies <code>fun</code> to each element of <code>lst</code>. When
  8860. additional <code>lst</code> arguments are given, their elements are also passed
  8861. to <code>fun</code>. Returns a list of all results. See also <code><a
  8862. href="#map">map</a></code>, <code><a
  8863. href="#mapc">mapc</a></code>, <code><a
  8864. href="#maplist">maplist</a></code>, <code><a
  8865. href="#mapcon">mapcon</a></code>, <code><a
  8866. href="#mapcan">mapcan</a></code> and <code><a
  8867. href="#filter">filter</a></code>.
  8868.  
  8869. <pre><code>
  8870. : (mapcar + (1 2 3) (4 5 6))
  8871. -> (5 7 9)
  8872. : (mapcar '((X Y) (+ X (* Y Y))) (1 2 3 4) (5 6 7 8))
  8873. -> (26 38 52 68)
  8874. </code></pre>
  8875.  
  8876. <dt><a name="mapcon"><code>(mapcon 'fun 'lst ..) -> lst</code></a>
  8877. <dd>Applies <code>fun</code> to <code>lst</code> and all successive CDRs. When
  8878. additional <code>lst</code> arguments are given, they are passed to
  8879. <code>fun</code> in the same way. Returns a (destructively) concatenated list of
  8880. all results. See also <code><a href="#map">map</a></code>, <code><a
  8881. href="#mapc">mapc</a></code>, <code><a
  8882. href="#maplist">maplist</a></code>, <code><a
  8883. href="#mapcar">mapcar</a></code>, <code><a
  8884. href="#mapcan">mapcan</a></code> and <code><a
  8885. href="#filter">filter</a></code>.
  8886.  
  8887. <pre><code>
  8888. : (mapcon copy '(1 2 3 4 5))
  8889. -> (1 2 3 4 5 2 3 4 5 3 4 5 4 5 5)
  8890. </code></pre>
  8891.  
  8892. <dt><a name="maplist"><code>(maplist 'fun 'lst ..) -> lst</code></a>
  8893. <dd>Applies <code>fun</code> to <code>lst</code> and all successive CDRs. When
  8894. additional <code>lst</code> arguments are given, they are passed to
  8895. <code>fun</code> in the same way. Returns a list of all results. See also
  8896. <code><a href="#map">map</a></code>, <code><a
  8897. href="#mapc">mapc</a></code>, <code><a
  8898. href="#mapcar">mapcar</a></code>, <code><a
  8899. href="#mapcon">mapcon</a></code>, <code><a
  8900. href="#mapcan">mapcan</a></code> and <code><a
  8901. href="#filter">filter</a></code>.
  8902.  
  8903. <pre><code>
  8904. : (maplist cons (1 2 3) '(A B C))
  8905. -> (((1 2 3) A B C) ((2 3) B C) ((3) C))
  8906. </code></pre>
  8907.  
  8908. <dt><a name="maps"><code>(maps 'fun 'sym ['lst ..]) -> any</code></a>
  8909. <dd>Applies <code>fun</code> to all properties of <code>sym</code>. When
  8910. additional <code>lst</code> arguments are given, their elements are also passed
  8911. to <code>fun</code>. Returns the result of the last application. Note that
  8912. 'maps' should only be used when the property list is not modified by
  8913. <code>fun</code>. Otherwise it is better to use a loop over the result of
  8914. <code><a href="#getl">getl</a></code>. See also <code><a
  8915. href="#putl">putl</a></code>.
  8916.  
  8917. <pre><code>
  8918. : (put 'X 'a 1)
  8919. -> 1
  8920. : (put 'X 'b 2)
  8921. -> 2
  8922. : (put 'X 'flg T)
  8923. -> T
  8924. : (getl 'X)
  8925. -> (flg (2 . b) (1 . a))
  8926. : (maps println 'X '(A B))
  8927. flg A
  8928. (2 . b) B
  8929. (1 . a) NIL
  8930. -> NIL
  8931. </code></pre>
  8932.  
  8933. <dt><a name="mark"><code>(mark 'sym|0 ['NIL | 'T | '0]) -> flg</code></a>
  8934. <dd>Tests, sets or resets a mark for <code>sym</code> in the database (for a
  8935. second argument of <code>NIL</code>, <code>T</code> or <code>0</code>,
  8936. respectively), and returns the old value. The marks are local to the current
  8937. process (not stored in the database), and vanish when the process terminates. If
  8938. the first argument is zero, all marks are cleared.
  8939.  
  8940. <pre><code>
  8941. : (pool "db")
  8942. -> T
  8943. : (mark '{1} T) # Mark
  8944. -> NIL
  8945. : (mark '{1}) # Test
  8946. -> T # -> marked
  8947. : (mark '{1} 0) # Unmark
  8948. -> T
  8949. : (mark '{1}) # Test
  8950. -> NIL # -> unmarked
  8951. </code></pre>
  8952.  
  8953. <dt><a name="match"><code>(match 'lst1 'lst2) -> flg</code></a>
  8954. <dd>Takes <code>lst1</code> as a pattern to be matched against
  8955. <code>lst2</code>, and returns <code>T</code> when successful. Atoms must be
  8956. equal, and sublists must match recursively. Symbols in the pattern list with
  8957. names starting with an at-mark "<code>@</code>" (see <code><a
  8958. href="#pat?">pat?</a></code>) are taken as wildcards. They can match
  8959. zero, one or more elements, and are bound to the corresponding data. See also
  8960. <code><a href="#chop">chop</a></code>, <code><a
  8961. href="#split">split</a></code> and <code><a
  8962. href="#fill">fill</a></code>.
  8963.  
  8964. <pre><code>
  8965. : (match '(@A is @B) '(This is a test))
  8966. -> T
  8967. : @A
  8968. -> (This)
  8969. : @B
  8970. -> (a test)
  8971. : (match '(@X (d @Y) @Z) '((a b c) (d (e f) g) h i))
  8972. -> T
  8973. : @X
  8974. -> ((a b c))
  8975. : @Y
  8976. -> ((e f) g)
  8977. : @Z
  8978. -> (h i)
  8979. </code></pre>
  8980.  
  8981. <dt><a name="max"><code>(max 'any ..) -> any</code></a>
  8982. <dd>Returns the largest of all <code>any</code> arguments. See also <a
  8983. href="#min">min</a> and <a href="ref.html#cmp">Comparing</a>.
  8984.  
  8985. <pre><code>
  8986. : (max 2 'a 'z 9)
  8987. -> z
  8988. : (max (5) (2 3) 'X)
  8989. -> (5)
  8990. </code></pre>
  8991.  
  8992. <dt><a name="maxKey"><code>(maxKey 'tree ['any1 ['any2]]) -> any</code></a>
  8993. <dd>Returns the largest key in a database tree. If a minimal key
  8994. <code>any1</code> and/or a maximal key <code>any2</code> is given, the largest
  8995. key from that range is returned. See also <code><a
  8996. href="#tree">tree</a></code>, <code><a
  8997. href="#leaf">leaf</a></code>, <code><a
  8998. href="#minKey">minKey</a></code> and <code><a
  8999. href="#genKey">genKey</a></code>.
  9000.  
  9001. <pre><code>
  9002. : (maxKey (tree 'nr '+Item))
  9003. -> 7
  9004. : (maxKey (tree 'nr '+Item) 3 5)
  9005. -> 5
  9006. </code></pre>
  9007.  
  9008. <dt><a name="maxi"><code>(maxi 'fun 'lst ..) -> any</code></a>
  9009. <dd>Applies <code>fun</code> to each element of <code>lst</code>. When
  9010. additional <code>lst</code> arguments are given, their elements are also passed
  9011. to <code>fun</code>. Returns that element from <code>lst</code> for which
  9012. <code>fun</code> returned a maximal value (and stores the maximal value in the
  9013. global variable <code><a href="#@@">@@</a></code>). See also <code><a
  9014. href="#mini">mini</a></code> and <code><a
  9015. href="#sort">sort</a></code>.
  9016.  
  9017. <pre><code>
  9018. : (setq A 1 B 2 C 3)
  9019. -> 3
  9020. : (maxi val '(A B C))
  9021. -> C
  9022. : (maxi # Symbol with largest list value
  9023. '((X)
  9024. (and (pair (val X)) (size @)) )
  9025. (all) )
  9026. -> pico
  9027. </code></pre>
  9028.  
  9029. <dt><a name="member"><code>(member 'any 'lst) -> any</code></a>
  9030. <dd>Returns the tail of <code>lst</code> that starts with <code>any</code> when
  9031. <code>any</code> is a member of <code>lst</code>, otherwise <code>NIL</code>.
  9032. See also <code><a href="#memq">memq</a></code>, <code><a
  9033. href="#assoc">assoc</a></code> and <code><a
  9034. href="#idx">idx</a></code>.
  9035.  
  9036. <pre><code>
  9037. : (member 3 (1 2 3 4 5 6))
  9038. -> (3 4 5 6)
  9039. : (member 9 (1 2 3 4 5 6))
  9040. -> NIL
  9041. : (member '(d e f) '((a b c) (d e f) (g h i)))
  9042. -> ((d e f) (g h i))
  9043. </code></pre>
  9044.  
  9045. <dt><a name="member/2"><code>member/2</code></a>
  9046. <dd><a href="#pilog">Pilog</a> predicate that succeeds if the the first
  9047. argument is a member of the list in the second argument. See also <code><a
  9048. href="#equal/2">equal/2</a></code> and <code><a
  9049. href="#member">member</a></code>.
  9050.  
  9051. <pre><code>
  9052. : (? (member @X (a b c)))
  9053. @X=a
  9054. @X=b
  9055. @X=c
  9056. -> NIL
  9057. </code></pre>
  9058.  
  9059. <dt><a name="memq"><code>(memq 'any 'lst) -> any</code></a>
  9060. <dd>Returns the tail of <code>lst</code> that starts with <code>any</code> when
  9061. <code>any</code> is a member of <code>lst</code>, otherwise <code>NIL</code>.
  9062. <code><a href="#==">==</a></code> is used for comparison (pointer
  9063. equality). See also <code><a href="#member">member</a></code>, <code><a
  9064. href="#mmeq">mmeq</a></code>, <code><a
  9065. href="#asoq">asoq</a></code>, <code><a
  9066. href="#push1q">push1q</a></code>, <code><a
  9067. href="#delq">delq</a></code> and <a href="ref.html#cmp">Comparing</a>.
  9068.  
  9069. <pre><code>
  9070. : (memq 'c '(a b c d e f))
  9071. -> (c d e f)
  9072. : (memq (2) '((1) (2) (3)))
  9073. -> NIL
  9074. </code></pre>
  9075.  
  9076. <dt><a name="meta"><code>(meta 'obj|typ 'sym ['sym2|cnt ..]) -> any</code></a>
  9077. <dd>Fetches a property value <code>any</code>, by searching the property lists
  9078. of the classes and superclasses of <code>obj</code>, or the classes in
  9079. <code>typ</code>, for the property key <code>sym</code>, and by applying the
  9080. <code><a href="#get">get</a></code> algorithm to the following optional
  9081. arguments. See also <code><a href="#var:">var:</a></code>.
  9082.  
  9083. <pre><code>
  9084. : (setq A '(B)) # Be 'A' an object of class 'B'
  9085. -> (B)
  9086. : (put 'B 'a 123)
  9087. -> 123
  9088. : (meta 'A 'a) # Fetch 'a' from 'B'
  9089. -> 123
  9090. </code></pre>
  9091.  
  9092. <dt><a name="meth"><code>(meth 'obj ['any ..]) -> any</code></a>
  9093. <dd>This function is usually not called directly, but is used by <code> <a
  9094. href="#dm">dm</a></code> as a template to initialize the
  9095. <code>VAL</code> of message symbols. It searches for itself in the methods of
  9096. <code>obj</code> and its classes and superclasses, and executes that method. An
  9097. error <code>"Bad message"</code> is issued if the search is unsuccessful. See
  9098. also <a href="#oop">OO Concepts</a>, <code><a
  9099. href="#method">method</a></code>, <code><a
  9100. href="#send">send</a></code> and <code><a
  9101. href="#try">try</a></code>.
  9102.  
  9103. <pre><code>
  9104. : meth
  9105. -> 67283504 # Value of 'meth'
  9106. : rel>
  9107. -> 67283504 # Value of any message
  9108. </code></pre>
  9109.  
  9110. <dt><a name="method"><code>(method 'msg 'obj) -> fun</code></a>
  9111. <dd>Returns the function body of the method that would be executed upon sending
  9112. the message <code>msg</code> to the object <code>obj</code>. If the message
  9113. cannot be located in <code>obj</code>, its classes and superclasses,
  9114. <code>NIL</code> is returned. See also <a href="#oop">OO Concepts</a>,
  9115. <code><a href="#send">send</a></code>, <code><a
  9116. href="#try">try</a></code>, <code><a
  9117. href="#meth">meth</a></code>, <code><a
  9118. href="#super">super</a></code>, <code><a
  9119. href="#extra">extra</a></code>, <code><a
  9120. href="#class">class</a></code>.
  9121.  
  9122. <pre><code>
  9123. : (method 'mis> '+Number)
  9124. -> ((Val Obj) (and Val (not (num? Val)) "Numeric input expected"))
  9125. </code></pre>
  9126.  
  9127. <dt><a name="methods"><code>(methods 'sym) -> lst</code></a>
  9128. <dd>(Debug mode only) Returns a list of method specifications for the object or
  9129. class <code>sym</code>, as they are inherited from <code>sym</code>'s classes
  9130. and superclasses. See also <a href="#oop">OO Concepts</a>, <code><a
  9131. href="#dep">dep</a></code>, <code><a
  9132. href="#class">class</a></code> and <code><a
  9133. href="#can">can</a></code>.
  9134.  
  9135. <pre><code>
  9136. : (more (methods '+Joint))
  9137. (keep> . +Joint)
  9138. (lose> . +Joint)
  9139. (rel> . +Joint)
  9140. (mis> . +Joint)
  9141. (T . +Joint)
  9142. (revise> . +relation)
  9143. (print> . +relation)
  9144. (zap> . +relation)
  9145. (del> . +relation)
  9146. (put> . +relation)
  9147. (has> . +relation)
  9148. (ele> . +relation)
  9149. </code></pre>
  9150.  
  9151. <dt><a name="min"><code>(min 'any ..) -> any</code></a>
  9152. <dd>Returns the smallest of all <code>any</code> arguments. See also <a
  9153. href="#max">max</a> and <a href="ref.html#cmp">Comparing</a>.
  9154.  
  9155. <pre><code>
  9156. : (min 2 'a 'z 9)
  9157. -> 2
  9158. : (min (5) (2 3) 'X)
  9159. -> X
  9160. </code></pre>
  9161.  
  9162. <dt><a name="minKey"><code>(minKey 'tree ['any1 ['any2]]) -> any</code></a>
  9163. <dd>Returns the smallest key in a database tree. If a minimal key
  9164. <code>any1</code> and/or a maximal key <code>any2</code> is given, the smallest
  9165. key from that range is returned. See also <code><a
  9166. href="#tree">tree</a></code>, <code><a
  9167. href="#leaf">leaf</a></code>, <code><a
  9168. href="#maxKey">maxKey</a></code> and <code><a
  9169. href="#genKey">genKey</a></code>.
  9170.  
  9171. <pre><code>
  9172. : (minKey (tree 'nr '+Item))
  9173. -> 1
  9174. : (minKey (tree 'nr '+Item) 3 5)
  9175. -> 3
  9176. </code></pre>
  9177.  
  9178. <dt><a name="mini"><code>(mini 'fun 'lst ..) -> any</code></a>
  9179. <dd>Applies <code>fun</code> to each element of <code>lst</code>. When
  9180. additional <code>lst</code> arguments are given, their elements are also passed
  9181. to <code>fun</code>. Returns that element from <code>lst</code> for which
  9182. <code>fun</code> returned a minimal value (and stores the minimal value in the
  9183. global variable <code><a href="#@@">@@</a></code>). See also <code><a
  9184. href="#maxi">maxi</a></code> and <code><a
  9185. href="#sort">sort</a></code>.
  9186.  
  9187. <pre><code>
  9188. : (setq A 1 B 2 C 3)
  9189. -> 3
  9190. : (mini val '(A B C))
  9191. -> A
  9192. </code></pre>
  9193.  
  9194. <dt><a name="mix"><code>(mix 'lst cnt|'any ..) -> lst</code></a>
  9195. <dd>Builds a list from the elements of the argument <code>lst</code>, as
  9196. specified by the following <code>cnt|'any</code> arguments. If such an argument
  9197. is a number, the <code>cnt</code>'th element from <code>lst</code> is taken,
  9198. otherwise that argument is evaluated and the result is used.
  9199.  
  9200. <pre><code>
  9201. : (mix '(a b c d) 3 4 1 2)
  9202. -> (c d a b)
  9203. : (mix '(a b c d) 1 'A 4 'D)
  9204. -> (a A d D)
  9205. </code></pre>
  9206.  
  9207. <dt><a name="mmeq"><code>(mmeq 'lst 'lst) -> any</code></a>
  9208. <dd>Returns the tail of the second argument <code>lst</code> that starts with a
  9209. member of the first argument <code>lst</code>, otherwise <code>NIL</code>.
  9210. <code><a href="#==">==</a></code> is used for comparison (pointer
  9211. equality). See also <code><a href="#member">member</a></code>, <code><a
  9212. href="#memq">memq</a></code>, <code><a
  9213. href="#asoq">asoq</a></code> and <code><a
  9214. href="#delq">delq</a></code>.
  9215.  
  9216. <pre><code>
  9217. : (mmeq '(a b c) '(d e f))
  9218. -> NIL
  9219. : (mmeq '(a b c) '(d b x))
  9220. -> (b x)
  9221. </code></pre>
  9222.  
  9223. <dt><a name="money"><code>(money 'num ['sym]) -> sym</code></a>
  9224. <dd>Formats a number <code>num</code> into a digit string with two decimal
  9225. places, according to the current <code><a
  9226. href="#locale">locale</a></code>. If an additional currency name is
  9227. given, it is appended (separated by a space). See also <code><a
  9228. href="#telStr">telStr</a></code>, <code><a
  9229. href="#datStr">datStr</a></code> and <code><a
  9230. href="#format">format</a></code>.
  9231.  
  9232. <pre><code>
  9233. : (money 123456789)
  9234. -> "1,234,567.89"
  9235. : (money 12345 "EUR")
  9236. -> "123.45 EUR"
  9237. : (locale "DE" "de")
  9238. -> NIL
  9239. : (money 123456789 "EUR")
  9240. -> "1.234.567,89 EUR"
  9241. </code></pre>
  9242.  
  9243. <dt><a name="more"><code>(more 'lst ['fun]) -> flg</code></a>
  9244. <dt><code>(more 'cls) -> any</code>
  9245. <dd>(Debug mode only) Displays the elements of <code>lst</code> (first form), or
  9246. the type and methods of <code>cls</code> (second form). <code>fun</code>
  9247. defaults to <code><a href="#print">print</a></code>. In the second
  9248. form, the method definitions of <code>cls</code> are pretty-printed with
  9249. <code><a href="#pp">pp</a></code>. After each step, <code>more</code>
  9250. waits for console input, and terminates when a non-empty line is entered. In
  9251. that case, <code>T</code> is returned, otherwise (when end of data is reached)
  9252. <code>NIL</code>. See also <code><a href="#query">query</a></code> and
  9253. <code><a href="#show">show</a></code>.
  9254.  
  9255. <pre><code>
  9256. : (more (all)) # Display all internal symbols
  9257. inc>
  9258. leaf
  9259. nil
  9260. inc!
  9261. accept. # Stop
  9262. -> T
  9263.  
  9264. : (more (all) show) # 'show' all internal symbols
  9265. inc> 67292896
  9266. *Dbg ((859 . "lib/db.l"))
  9267.  
  9268. leaf ((Tree) (let (Node (cdr (root Tree)) X) (while (val Node) (setq X (cadr @) Node (car @))) (cddr X)))
  9269. *Dbg ((173 . "lib/btree.l"))
  9270.  
  9271. nil 67284680
  9272. T (((@X) (^ @ (not (-> @X)))))
  9273. . # Stop
  9274. -> T
  9275.  
  9276. : (more '+Link) # Display a class
  9277. (+relation)
  9278.  
  9279. (dm mis> (Val Obj)
  9280. (and
  9281. Val
  9282. (nor (isa (: type) Val) (canQuery Val))
  9283. "Type error" ) )
  9284.  
  9285. (dm T (Var Lst)
  9286. (unless (=: type (car Lst)) (quit "No Link" Var))
  9287. (super Var (cdr Lst)) )
  9288.  
  9289. -> NIL
  9290. </code></pre>
  9291.  
  9292. <dt><a name="msg"><code>(msg 'any ['any ..]) -> any</code></a>
  9293. <dd>Prints <code>any</code> with <code><a
  9294. href="#print">print</a></code>, followed by all <code>any</code>
  9295. arguments (printed with <code><a href="#prin">prin</a></code>) and a
  9296. newline, to standard error. The first <code>any</code> argument is returned.
  9297.  
  9298. <pre><code>
  9299. : (msg (1 a 2 b 3 c) " is a mixed " "list")
  9300. (1 a 2 b 3 c) is a mixed list
  9301. -> (1 a 2 b 3 c)
  9302. </code></pre>
  9303.  
  9304. </dl>
  9305.  
  9306. <h1><a name="N">N</a></h1>
  9307.  
  9308. <dl>
  9309.  
  9310. <dt><a name="+Need"><code>+Need</code></a>
  9311. <dd>Prefix class for mandatory <code><a
  9312. href="#+relation">+relation</a></code>s. Note that this does not
  9313. enforce any requirements by itself, it only returns an error message if the
  9314. <code>mis&gt;</code> message is explicitly called, e.g. by GUI functions. See
  9315. also <a href="#dbase">Database</a>.
  9316.  
  9317. <pre><code>
  9318. (rel nr (+Need +Key +Number)) # Item number is mandatory
  9319. </code></pre>
  9320.  
  9321. <dt><a name="+Number"><code>+Number</code></a>
  9322. <dd>Class for numeric relations, a subclass of <code><a
  9323. href="#+relation">+relation</a></code>. Accepts an optional argument
  9324. for the fixpoint scale (currently not used). See also <a
  9325. href="#dbase">Database</a>.
  9326.  
  9327. <pre><code>
  9328. (rel pr (+Number) 2) # Price, with two decimal places
  9329. </code></pre>
  9330.  
  9331. <dt><a name="n=="><code>(n== 'any ..) -> flg</code></a>
  9332. <dd>Returns <code>T</code> when not all <code>any</code> arguments are the same
  9333. (pointer equality). <code>(n== 'any ..)</code> is equivalent to <code>(not (==
  9334. 'any ..))</code>. See also <code><a href="#==">==</a></code> and <a
  9335. href="#cmp">Comparing</a>.
  9336.  
  9337. <pre><code>
  9338. : (n== 'a 'a)
  9339. -> NIL
  9340. : (n== (1) (1))
  9341. -> T
  9342. </code></pre>
  9343.  
  9344. <dt><a name="n0"><code>(n0 'any) -> flg</code></a>
  9345. <dd>Returns <code>T</code> when <code>any</code> is not a number with value
  9346. zero. See also <code><a href="#=0">=0</a></code>, <code><a
  9347. href="#lt0">lt0</a></code>, <code><a
  9348. href="#le0">le0</a></code>, <code><a
  9349. href="#ge0">ge0</a></code> and <code><a
  9350. href="#gt0">gt0</a></code>.
  9351.  
  9352. <pre><code>
  9353. : (n0 (- 6 3 2 1))
  9354. -> NIL
  9355. : (n0 'a)
  9356. -> T
  9357. </code></pre>
  9358.  
  9359. <dt><a name="nT"><code>(nT 'any) -> flg</code></a>
  9360. <dd>Returns <code>T</code> when <code>any</code> is not the symbol
  9361. <code>T</code>. See also <a href="#=T">=T</a>.
  9362.  
  9363. <pre><code>
  9364. : (nT 0)
  9365. -> T
  9366. : (nT "T")
  9367. -> T
  9368. : (nT T)
  9369. -> NIL
  9370. </code></pre>
  9371.  
  9372. <dt><a name="name"><code>(name 'sym ['sym2]) -> sym</code></a>
  9373. <dd>Returns, if <code>sym2</code> is not given, a new transient symbol with the
  9374. name of <code>sym</code>. Otherwise <code>sym</code> must be a transient symbol,
  9375. and its name is changed to that of <code>sym2</code> (note that this may give
  9376. inconsistencies if the symbol is still referred to from other namespaces). See
  9377. also <code><a href="#str">str</a></code>, <code><a
  9378. href="#sym">sym</a></code>, <code><a
  9379. href="#symbols">symbols</a></code>, <code><a
  9380. href="#zap">zap</a></code> and <code><a
  9381. href="#intern">intern</a></code>.
  9382.  
  9383. <pre><code>
  9384. : (name 'abc)
  9385. -> "abc"
  9386. : (name "abc")
  9387. -> "abc"
  9388. : (name '{A17})
  9389. -> "A17"
  9390. : (name (new))
  9391. -> NIL
  9392. : (de foo (Lst) (car Lst)) # 'foo' calls 'car'
  9393. -> foo
  9394. : (intern (name (zap 'car) "xxx")) # Globally change the name of 'car'
  9395. -> xxx
  9396. : (xxx (1 2 3))
  9397. -> 1
  9398. : (pp 'foo)
  9399. (de foo (Lst)
  9400. (xxx Lst) ) # Name changed
  9401. -> foo
  9402. : (foo (1 2 3)) # 'foo' still works
  9403. -> 1
  9404. : (car (1 2 3)) # Reader returns a new 'car' symbol
  9405. !? (car (1 2 3))
  9406. car -- Undefined
  9407. ?
  9408. </code></pre>
  9409.  
  9410. <dt><a name="nand"><code>(nand 'any ..) -> flg</code></a>
  9411. <dd>Logical NAND. The expressions <code>any</code> are evaluated from left to
  9412. right. If <code>NIL</code> is encountered, <code>T</code> is returned
  9413. immediately. Else <code>NIL</code> is returned. <code>(nand ..)</code> is
  9414. equivalent to <code>(not (and ..))</code>.
  9415.  
  9416. <pre><code>
  9417. : (nand (lt0 7) (read))
  9418. -> T
  9419. : (nand (lt0 -7) (read))
  9420. abc
  9421. -> NIL
  9422. : (nand (lt0 -7) (read))
  9423. NIL
  9424. -> T
  9425. </code></pre>
  9426.  
  9427. <dt><a name="native"><code>(native 'cnt1|sym1 'cnt2|sym2 'any 'any ..) -> any</code></a>
  9428. <dd>(64-bit version only) Calls a native C function. The first argument should
  9429. specify a shared object library, either <code>"@"</code> (the current main
  9430. program), <code>sym1</code> (a library path name), or <code>cnt1</code> (a
  9431. library handle obtained by a previous call). The second argument should be a
  9432. symbol name <code>sym2</code>, or a function pointer <code>cnt2</code> obtained
  9433. by a previous call). Practically, the first two arguments will be always passed
  9434. as transient symbols, which will get the library handle and function pointer
  9435. assigned as values to be cached and used in subsequent calls. The third argument
  9436. <code>any</code> is a result specification, while all following arguments are
  9437. the arguments to the native function. The functionality is described in detail
  9438. in <a href="native.html">Native C Calls</a>.
  9439.  
  9440. <p><a name="natResult">The result specification</a> may either be one of the
  9441. atoms
  9442.  
  9443. <pre><code>
  9444. NIL void
  9445. B byte # Byte (unsigned 8 bit)
  9446. C char # Character (UTF-8, 1-3 bytes)
  9447. I int # Integer (signed 32 bit)
  9448. N long # Long or pointer (signed 64 bit)
  9449. S string # String (UTF-8)
  9450. -1.0 float # Scaled fixpoint number
  9451. +1.0 double # Scaled fixpoint number
  9452. </code></pre>
  9453.  
  9454. <p>or nested lists of these atoms with size specifications to denote arrays and
  9455. structures, e.g.
  9456.  
  9457. <pre><code>
  9458. (N . 4) # long[4]; -> (1 2 3 4)
  9459. (N (C . 4)) # {long; char[4];} -> (1234 ("a" "b" "c" NIL))
  9460. (N (B . 7)) # {long; byte[7];} -> (1234 (1 2 3 4 5 6 7))
  9461. </code></pre>
  9462.  
  9463. <p>Arguments can be
  9464. <ul>
  9465. <li>integers (up to 64-bit) or pointers, passed as numbers
  9466. <li>strings, passed as symbols
  9467. <li>fixpoint numbers, passed as cons pairs consisting of a the value and the
  9468. scale (if the scale is positive, the number is passed as a
  9469. <code>double</code>, otherwise as a <code>float</code>)
  9470. <li>structures, passed as lists with
  9471. <ul>
  9472. <li>a variable in the CAR (to receive the returned structure data, ignored
  9473. when the CAR is <code>NIL</code>)
  9474. <li>a cons pair for the size and result specification in the CADR (see
  9475. above), and
  9476. <li>an optional sequence of <a name="natItem">initialization items</a> in the
  9477. CDDR, where each may be
  9478. <ul>
  9479. <li>a positive number, stored as an unsigned byte value
  9480. <li>a negative number, whose absolute value is stored as an unsigned
  9481. integer
  9482. <li>a pair <code>(num . cnt)</code> where '<code>num</code>' is stored in
  9483. a field of '<code>cnt</code>' bytes
  9484. <li>a pair <code>(sym . cnt)</code> where '<code>sym</code>' is stored as
  9485. a null-terminated string in a field of '<code>cnt</code>' bytes
  9486. <li>a list <code>(1.0 num ...)</code> where the '<code>num</code>'
  9487. elements (scaled fixpoint numbers) are stored as a sequence of double
  9488. precision floating point numbers
  9489. <li>a list <code>(-1.0 num ...)</code> where the '<code>num</code>'
  9490. elements (scaled fixpoint numbers) are stored as a sequence of single
  9491. precision floating point numbers
  9492. </ul>
  9493. If the last CDR of the initialization sequence is a number, it is used
  9494. as a fill-byte value for the remaining space in the structure.
  9495. </ul>
  9496. </ul>
  9497.  
  9498. <p><code>native</code> takes care of allocating memory for strings, arrays or
  9499. structures, and frees that memory when done.
  9500.  
  9501. <p>The number of fixpoint arguments is limited to six. For NaN or negative
  9502. infinity <code>NIL</code>, and for positive infinity <code>T</code> is returned.
  9503.  
  9504. <p>The C function may in turn call a function
  9505.  
  9506. <pre><code>
  9507. long lisp(char*, long, long, long, long, long);
  9508. </code></pre>
  9509.  
  9510. <p>which accepts a symbol name as the first argument, and up to 5 numbers.
  9511. <code>lisp()</code> calls that symbol with the five numbers, and expects a
  9512. numeric return value. "Numbers" in this context are 64-bit scalars, and may not
  9513. only represent integers, but also pointers or other encoded data. See also
  9514. <code><a href="#struct">struct</a></code>, <code><a
  9515. href="#lisp">lisp</a></code> and <code><a
  9516. href="#errno">errno</a></code>.
  9517.  
  9518. <pre><code>
  9519. : (native "@" "getenv" 'S "TERM") # Same as (sys "TERM")
  9520. -> "xterm"
  9521.  
  9522. : (native "@" "printf" 'I "abc%d%s^J" (+ 3 4) (pack "X" "Y" "Z"))
  9523. abc7XYZ
  9524. -> 8
  9525.  
  9526. : (native "@" "printf" 'I "This is %.3f^J" (123456 . 1000))
  9527. This is 123.456
  9528. -> 16
  9529.  
  9530. : (use Tim
  9531. (native "@" "time" NIL '(Tim (8 B . 8))) # time_t 8 # Get time_t structure
  9532. (native "@" "localtime" '(I . 9) (cons NIL (8) Tim)) ) # Read local time
  9533. -> (32 18 13 31 11 109 4 364 0) # 13:18:32, Dec. 31st, 2009
  9534.  
  9535. : (native "libcrypto.so" "SHA1" '(B . 20) "abcd" 4 0)
  9536. -> (129 254 139 254 135 87 108 62 203 34 66 111 142 87 132 115 130 145 122 207)
  9537. </code></pre>
  9538.  
  9539. <dt><a name="need"><code>(need 'cnt ['lst ['any]]) -> lst</code></a>
  9540. <dt><code>(need 'cnt ['num|sym]) -> lst</code>
  9541. <dd>Produces a list of at least <code>cnt</code> elements. When called without
  9542. optional arguments, a list of <code>cnt</code> <code>NIL</code>'s is returned.
  9543. When <code>lst</code> is given, it is extended to the left (if <code>cnt</code>
  9544. is positive) or (destructively) to the right (if <code>cnt</code> is negative)
  9545. with <code>any</code> elements. In the second form, a list of <code>cnt</code>
  9546. atomic values is returned. See also <code><a
  9547. href="#range">range</a></code>.
  9548.  
  9549. <pre><code>
  9550. : (need 5)
  9551. -> (NIL NIL NIL NIL NIL) # Allocate 5 cells
  9552. : (need 5 '(a b c))
  9553. -> (NIL NIL a b c)
  9554. : (need -5 '(a b c))
  9555. -> (a b c NIL NIL)
  9556. : (need 5 '(a b c) " ") # String alignment
  9557. -> (" " " " a b c)
  9558. : (need 7 0)
  9559. -> (0 0 0 0 0 0 0)
  9560. </code></pre>
  9561.  
  9562. <dt><a name="new"><code>(new ['flg|num] ['typ ['any ..]]) -> obj</code></a>
  9563. <dd>Creates and returns a new object. If <code>flg</code> is given and
  9564. non-<code>NIL</code>, the new object will be an external symbol (created in
  9565. database file 1 if <code>T</code>, or in the corresponding database file if
  9566. <code>num</code> is given). <code>typ</code> (typically a list of classes) is
  9567. assigned to the <code>VAL</code>, and the initial <code>T</code> message is sent
  9568. with the arguments <code>any</code> to the new object. If no <code>T</code>
  9569. message is defined for the classes in <code>typ</code> or their superclasses,
  9570. the <code>any</code> arguments should evaluate to alternating keys and values
  9571. for the initialization of the new object. See also <code><a
  9572. href="#box">box</a></code>, <code><a
  9573. href="#object">object</a></code>, <code><a
  9574. href="#class">class</a></code>, <code><a
  9575. href="#type">type</a></code>, <code><a
  9576. href="#isa">isa</a></code>, <code><a
  9577. href="#send">send</a></code> and <a href="ref.html#dbase">Database</a>.
  9578.  
  9579. <pre><code>
  9580. : (new)
  9581. -> $134426427
  9582. : (new T '(+Address))
  9583. -> {1A;3}
  9584. </code></pre>
  9585.  
  9586. <dt><a name="new!"><code>(new! 'typ ['any ..]) -> obj</code></a>
  9587. <dd><a href="#trans">Transaction</a> wrapper function for <code><a
  9588. href="#new">new</a></code>. <code>(new! '(+Cls) 'key 'val ...)</code>
  9589. is equivalent to <code>(dbSync) (new (db: +Cls) '(+Cls) 'key 'val ...) (commit
  9590. 'upd)</code>. See also <code><a href="#set!">set!</a></code>, <code><a
  9591. href="#put!">put!</a></code> and <code><a
  9592. href="#inc!">inc!</a></code>.
  9593.  
  9594. <pre><code>
  9595. : (new! '(+Item) # Create a new item
  9596. 'nr 2 # Item number
  9597. 'nm "Spare Part" # Description
  9598. 'sup (db 'nr '+CuSu 2) # Supplier
  9599. 'inv 100 # Inventory
  9600. pr 12.50 ) # Price
  9601. </code></pre>
  9602.  
  9603. <dt><a name="next"><code>(next) -> any</code></a>
  9604. <dd>Can only be used inside functions with a variable number of arguments (with
  9605. <code>@</code>). Returns the next argument from the internal list. See also
  9606. <code><a href="#args">args</a></code>, <code><a
  9607. href="#arg">arg</a></code>, <code><a
  9608. href="#rest">rest</a></code>, and <code><a
  9609. href="#pass">pass</a></code>.
  9610.  
  9611. <pre><code>
  9612. : (de foo @ (println (next))) # Print next argument
  9613. -> foo
  9614. : (foo)
  9615. NIL
  9616. -> NIL
  9617. : (foo 123)
  9618. 123
  9619. -> 123
  9620. </code></pre>
  9621.  
  9622. <dt><a name="nil"><code>(nil . prg) -> NIL</code></a>
  9623. <dd>Executes <code>prg</code>, and returns <code>NIL</code>. See also <code><a
  9624. href="#t">t</a></code>, <code><a href="refP.html#prog">prog</a></code>,
  9625. <code><a href="#prog1">prog1</a></code> and <code><a
  9626. href="#prog2">prog2</a></code>.
  9627.  
  9628. <pre><code>
  9629. : (nil (println 'OK))
  9630. OK
  9631. -> NIL
  9632. </code></pre>
  9633.  
  9634. <dt><a name="nil/1"><code>nil/1</code></a>
  9635. <dd><a href="#pilog">Pilog</a> predicate expects an argument variable,
  9636. and succeeds if that variable is bound to <code>NIL</code>. See also <code><a
  9637. href="#not/1">not/1</a></code>.
  9638.  
  9639. <pre><code>
  9640. : (? @X NIL (nil @X))
  9641. @X=NIL
  9642. -> NIL
  9643. </code></pre>
  9644.  
  9645. <dt><a name="noLint"><code>(noLint 'sym)</code></a>
  9646. <dt><code>(noLint 'sym|(sym . cls) 'sym2)</code>
  9647. <dd>(Debug mode only) Excludes the check for a function definition of
  9648. <code>sym</code> (in the first form), or for variable binding and usage of
  9649. <code>sym2</code> in the function definition, file contents or method body of
  9650. <code>sym</code> (second form), during calls to <code><a
  9651. href="#lint">lint</a></code>. See also <code><a
  9652. href="#lintAll">lintAll</a></code>.
  9653.  
  9654. <pre><code>
  9655. : (de foo ()
  9656. (bar FreeVariable) )
  9657. -> foo
  9658. : (lint 'foo)
  9659. -> ((def bar) (bnd FreeVariable))
  9660. : (noLint 'bar)
  9661. -> bar
  9662. : (noLint 'foo 'FreeVariable)
  9663. -> (foo . FreeVariable)
  9664. : (lint 'foo)
  9665. -> NIL
  9666. </code></pre>
  9667.  
  9668. <dt><a name="nond"><code>(nond ('any1 . prg1) ('any2 . prg2) ..) -> any</code></a>
  9669. <dd>Negated ("non-cond") multi-way conditional: If any of the <code>anyN</code>
  9670. conditions evaluates to <code>NIL</code>, <code>prgN</code> is executed and the
  9671. result returned. Otherwise (all conditions evaluate to non-<code>NIL</code>),
  9672. <code>NIL</code> is returned. See also <code><a
  9673. href="#cond">cond</a></code>, <code><a
  9674. href="#ifn">ifn</a></code> and <code><a
  9675. href="#unless">unless</a></code>.
  9676.  
  9677. <pre><code>
  9678. : (nond
  9679. ((= 3 3) (println 1))
  9680. ((= 3 4) (println 2))
  9681. (NIL (println 3)) )
  9682. 2
  9683. -> 2
  9684. </code></pre>
  9685.  
  9686. <dt><a name="nor"><code>(nor 'any ..) -> flg</code></a>
  9687. <dd>Logical NOR. The expressions <code>any</code> are evaluated from left to
  9688. right. If a non-<code>NIL</code> value is encountered, <code>NIL</code> is
  9689. returned immediately. Else <code>T</code> is returned. <code>(nor ..)</code> is
  9690. equivalent to <code>(not (or ..))</code>.
  9691.  
  9692. <pre><code>
  9693. : (nor (lt0 7) (= 3 4))
  9694. -> T
  9695. </code></pre>
  9696.  
  9697. <dt><a name="not"><code>(not 'any) -> flg</code></a>
  9698. <dd>Logical negation. Returns <code>T</code> if <code>any</code> evaluates to
  9699. <code>NIL</code>.
  9700.  
  9701. <pre><code>
  9702. : (not (== 'a 'a))
  9703. -> NIL
  9704. : (not (get 'a 'a))
  9705. -> T
  9706. </code></pre>
  9707.  
  9708. <dt><a name="not/1"><code>not/1</code></a>
  9709. <dd><a href="#pilog">Pilog</a> predicate that succeeds if and only if
  9710. the goal cannot be proven. See also <code><a
  9711. href="#nil/1">nil/1</a></code>, <code><a
  9712. href="#true/0">true/0</a></code> and <code><a
  9713. href="#fail/0">fail/0</a></code>.
  9714.  
  9715. <pre><code>
  9716. : (? (equal 3 4))
  9717. -> NIL
  9718. : (? (not (equal 3 4)))
  9719. -> T
  9720. </code></pre>
  9721.  
  9722. <dt><a name="nth"><code>(nth 'lst 'cnt ..) -> lst</code></a>
  9723. <dd>Returns the tail of <code>lst</code> starting from the <code>cnt</code>'th
  9724. element of <code>lst</code>. Successive <code>cnt</code> arguments operate on
  9725. the results in the same way. <code>(nth 'lst 2)</code> is equivalent to
  9726. <code>(cdr 'lst)</code>. See also <code><a href="#get">get</a></code>.
  9727.  
  9728. <pre><code>
  9729. : (nth '(a b c d) 2)
  9730. -> (b c d)
  9731. : (nth '(a (b c) d) 2 2)
  9732. -> (c)
  9733. : (cdadr '(a (b c) d))
  9734. -> (c)
  9735. </code></pre>
  9736.  
  9737. <dt><a name="num?"><code>(num? 'any) -> num | NIL</code></a>
  9738. <dd>Returns <code>any</code> when the argument <code>any</code> is a number,
  9739. otherwise <code>NIL</code>. See also <code><a
  9740. href="#sym?">sym?</a></code>, <code><a
  9741. href="#atom">atom</a></code> and <code><a
  9742. href="#pair">pair</a></code>.
  9743.  
  9744. <pre><code>
  9745. : (num? 123)
  9746. -> 123
  9747. : (num? (1 2 3))
  9748. -> NIL
  9749. </code></pre>
  9750.  
  9751. </dl>
  9752.  
  9753. <h1><a name="O">O</a></h1>
  9754.  
  9755. <dl>
  9756.  
  9757. <dt><a name="*ObjIdx"><code>*ObjIdx</code></a>
  9758. <dd>Holds an <code><a href="#idx">idx</a></code> tree of objects
  9759. created by <code><a href="#obj">obj</a></code>.
  9760.  
  9761. <pre><code>
  9762. </code></pre>
  9763.  
  9764. <dt><a name="*Once"><code>*Once</code></a>
  9765. <dd>Holds an <code><a href="#idx">idx</a></code> tree of already
  9766. <code><a href="#load">load</a></code>ed source locations (as returned
  9767. by <code><a href="#file">file</a></code>) See also <code><a
  9768. href="#once">once</a></code>.
  9769.  
  9770. <pre><code>
  9771. : *Once
  9772. -> (("lib/" "misc.l" . 11) (("lib/" "http.l" . 9) (("lib/" "form.l" . 11))))
  9773. </code></pre>
  9774.  
  9775. <dt><a name="*OS"><code>*OS</code></a>
  9776. <dd>A global constant holding the name of the operating system. Possible values
  9777. include <code>"Linux"</code>, <code>"FreeBSD"</code>, <code>"Darwin"</code> or
  9778. <code>"Cygwin"</code>. See also <code><a href="#*CPU">*CPU</a></code>
  9779. and <code><a href="#version">version</a></code>.
  9780.  
  9781. <pre><code>
  9782. : *OS
  9783. -> "Linux"
  9784. </code></pre>
  9785.  
  9786. <dt><a name="obj"><code>(obj (typ sym [hook] val ..) [var1 val1 ..]) -> obj</code></a>
  9787. <dt><code>(obj typ any [var1 val1 ..]) -> obj</code>
  9788. <dd>Finds or creates a database object, and initializes additional properties
  9789. using the <code>varN</code> and <code>valN</code> arguments. In the first form,
  9790. a <code><a href="#request">request</a></code> for <code>(typ sym [hook]
  9791. val ..)</code> is called, while the second form uses <code><a
  9792. href="#cache">cache</a></code> to maintain objects without unique
  9793. <code><a href="#+Key">+Key</a></code>s by indexing <code><a
  9794. href="#*ObjIdx">*ObjIdx</a></code> with the <code>any</code> argument.
  9795.  
  9796. <pre><code>
  9797. : (obj ((+Item) nr 2) nm "Spare Part" sup `(db 'nr '+CuSu 2) inv 100 pr 1250)
  9798. -> {3-2}
  9799. </code></pre>
  9800.  
  9801. <dt><a name="object"><code>(object 'sym 'any ['sym2 'any2 ..]) -> obj</code></a>
  9802. <dd>Defines <code>sym</code> to be an object with the value (or type)
  9803. <code>any</code>. The property list is initialized with all optionally supplied
  9804. key-value pairs. See also <a href="#oop">OO Concepts</a>, <code><a
  9805. href="#new">new</a></code>, <code><a
  9806. href="#type">type</a></code> and <code><a
  9807. href="#isa">isa</a></code>.
  9808.  
  9809. <pre><code>
  9810. : (object 'Obj '(+A +B +C) 'a 1 'b 2 'c 3)
  9811. -> Obj
  9812. : (show 'Obj)
  9813. Obj (+A +B +C)
  9814. c 3
  9815. b 2
  9816. a 1
  9817. -> Obj
  9818. </code></pre>
  9819.  
  9820. <dt><a name="oct"><code>(oct 'num ['num]) -> sym</code></a>
  9821. <dt><code>(oct 'sym) -> num</code>
  9822. <dd>Converts a number <code>num</code> to an octal string, or an octal string
  9823. <code>sym</code> to a number. In the first case, if the second argument is
  9824. given, the result is separated by spaces into groups of such many digits. See
  9825. also <code><a href="#bin">bin</a></code>, <code><a
  9826. href="#hex">hex</a></code>, <code><a
  9827. href="#fmt64">fmt64</a></code>, <code><a
  9828. href="#hax">hax</a></code> and <code><a
  9829. href="#format">format</a></code>.
  9830.  
  9831. <pre><code>
  9832. : (oct 73)
  9833. -> "111"
  9834. : (oct "111")
  9835. -> 73
  9836. : (oct 1234567 3)
  9837. -> "4 553 207"
  9838. </code></pre>
  9839.  
  9840. <dt><a name="off"><code>(off var ..) -> NIL</code></a>
  9841. <dd>Stores <code>NIL</code> in all <code>var</code> arguments. See also <code><a
  9842. href="#on">on</a></code>, <code><a
  9843. href="#onOff">onOff</a></code>, <code><a
  9844. href="#zero">zero</a></code> and <code><a
  9845. href="#one">one</a></code>.
  9846.  
  9847. <pre><code>
  9848. : (off A B)
  9849. -> NIL
  9850. : A
  9851. -> NIL
  9852. : B
  9853. -> NIL
  9854. </code></pre>
  9855.  
  9856. <dt><a name="offset"><code>(offset 'lst1 'lst2) -> cnt | NIL</code></a>
  9857. <dd>Returns the <code>cnt</code> position of the tail list <code>lst1</code> in
  9858. <code>lst2</code>, or <code>NIL</code> if it is not found. See also <code><a
  9859. href="#index">index</a></code>, <code><a
  9860. href="#sub?">sub?</a></code> and <code><a
  9861. href="#tail">tail</a></code>.
  9862.  
  9863. <pre><code>
  9864. : (offset '(c d e f) '(a b c d e f))
  9865. -> 3
  9866. : (offset '(c d e) '(a b c d e f))
  9867. -> NIL
  9868. </code></pre>
  9869.  
  9870. <dt><a name="on"><code>(on var ..) -> T</code></a>
  9871. <dd>Stores <code>T</code> in all <code>var</code> arguments. See also <code><a
  9872. href="#off">off</a></code>, <code><a
  9873. href="#onOff">onOff</a></code>, <code><a
  9874. href="#zero">zero</a></code> and <code><a
  9875. href="#one">one</a></code>.
  9876.  
  9877. <pre><code>
  9878. : (on A B)
  9879. -> T
  9880. : A
  9881. -> T
  9882. : B
  9883. -> T
  9884. </code></pre>
  9885.  
  9886. <dt><a name="once"><code>(once . prg) -> any</code></a>
  9887. <dd>Executes <code>prg</code> once, when the current file is <code><a
  9888. href="#load">load</a></code>ed the first time. Subsequent loads at a
  9889. later time will not execute <code>prg</code>, and <code>once</code> returns
  9890. <code>NIL</code>. See also <code><a href="#*Once">*Once</a></code>.
  9891.  
  9892. <pre><code>
  9893. (once
  9894. (zero *Cnt1 *Cnt2) # Init counters
  9895. (load "file1.l" "file2.l") ) # Load other files
  9896.  
  9897. `(once T) # Ignore next time the rest of this file
  9898. </code></pre>
  9899.  
  9900. <dt><a name="one"><code>(one var ..) -> 1</code></a>
  9901. <dd>Stores <code>1</code> in all <code>var</code> arguments. See also <code><a
  9902. href="#zero">zero</a></code>, <code><a
  9903. href="#on">on</a></code>, <code><a href="refO.html#off">off</a></code>
  9904. and <code><a href="#onOff">onOff</a></code>.
  9905.  
  9906. <pre><code>
  9907. : (one A B)
  9908. -> 1
  9909. : A
  9910. -> 1
  9911. : B
  9912. -> 1
  9913. </code></pre>
  9914.  
  9915. <dt><a name="onOff"><code>(onOff var ..) -> flg</code></a>
  9916. <dd>Logically negates the values of all <code>var</code> arguments. Returns the
  9917. new value of the last symbol. See also <code><a
  9918. href="#on">on</a></code>, <code><a href="refO.html#off">off</a></code>,
  9919. <code><a href="#zero">zero</a></code> and <code><a
  9920. href="#one">one</a></code>.
  9921.  
  9922. <pre><code>
  9923. : (onOff A B)
  9924. -> T
  9925. : A
  9926. -> T
  9927. : B
  9928. -> T
  9929. : (onOff A B)
  9930. -> NIL
  9931. : A
  9932. -> NIL
  9933. : B
  9934. -> NIL
  9935. </code></pre>
  9936.  
  9937. <dt><a name="open"><code>(open 'any ['flg]) -> cnt | NIL</code></a>
  9938. <dd>Opens the file with the name <code>any</code> in read/write mode (or
  9939. read-only if <code>flg</code> is non-<code>NIL</code>), and returns a file
  9940. descriptor <code>cnt</code> (or <code>NIL</code> on error). A leading
  9941. "<code>@</code>" character in <code>any</code> is substituted with the
  9942. <u>PicoLisp Home Directory</u>, as it was remembered during interpreter startup.
  9943. If <code>flg</code> is <code>NIL</code> and the file does not exist, it is
  9944. created. The file descriptor can be used in subsequent calls to <code><a
  9945. href="#in">in</a></code> and <code><a
  9946. href="#out">out</a></code>. See also <code><a
  9947. href="#close">close</a></code> and <code><a
  9948. href="#poll">poll</a></code>.
  9949.  
  9950. <pre><code>
  9951. : (open "x")
  9952. -> 3
  9953. </code></pre>
  9954.  
  9955. <dt><a name="opid"><code>(opid) -> pid | NIL</code></a>
  9956. <dd>Returns the corresponding process ID when the current output channel is
  9957. writing to a pipe, otherwise <code>NIL</code>. See also <code><a
  9958. href="#ipid">ipid</a></code> and <code><a
  9959. href="#out">out</a></code>.
  9960.  
  9961. <pre><code>
  9962. : (out '(cat) (call 'ps "-p" (opid)))
  9963. PID TTY TIME CMD
  9964. 7127 pts/3 00:00:00 cat
  9965. -> T
  9966. </code></pre>
  9967.  
  9968. <dt><a name="opt"><code>(opt) -> sym</code></a>
  9969. <dd>Return the next command line argument ("option", as would be processed by
  9970. <code><a href="#load">load</a></code>) as a string, and remove it from
  9971. the remaining command line arguments. See also <a
  9972. href="#invoc">Invocation</a> and <code><a
  9973. href="#argv">argv</a></code>.
  9974.  
  9975. <pre><code>
  9976. $ pil -"de f () (println 'opt (opt))" -f abc -bye
  9977. opt "abc"
  9978. </code></pre>
  9979.  
  9980. <dt><a name="or"><code>(or 'any ..) -> any</code></a>
  9981. <dd>Logical OR. The expressions <code>any</code> are evaluated from left to
  9982. right. If a non-<code>NIL</code> value is encountered, it is returned
  9983. immediately. Else the result of the last expression is returned.
  9984.  
  9985. <pre><code>
  9986. : (or (= 3 3) (read))
  9987. -> T
  9988. : (or (= 3 4) (read))
  9989. abc
  9990. -> abc
  9991. </code></pre>
  9992.  
  9993. <dt><a name="or/2"><code>or/2</code></a>
  9994. <dd><a href="#pilog">Pilog</a> predicate that takes an arbitrary number
  9995. of clauses, and succeeds if one of them can be proven. See also <code><a
  9996. href="#not/1">not/1</a></code>.
  9997.  
  9998. <pre><code>
  9999. : (?
  10000. (or
  10001. ((equal 3 @X) (equal @X 4))
  10002. ((equal 7 @X) (equal @X 7)) ) )
  10003. @X=7
  10004. -> NIL</code></pre>
  10005.  
  10006. <dt><a name="out"><code>(out 'any . prg) -> any</code></a>
  10007. <dd>Opens <code>any</code> as output channel during the execution of
  10008. <code>prg</code>. The current output channel will be saved and restored
  10009. appropriately. If the argument is <code>NIL</code>, standard output is used. If
  10010. the argument is a symbol, it is used as a file name (opened in "append" mode if
  10011. the first character is "<code>+</code>"). If it is a positive number, it is used
  10012. as the descriptor of an open file. If it is a negative number, the saved output
  10013. channel such many levels above the current one is used. Otherwise (if it is a
  10014. list), it is taken as a command with arguments, and a pipe is opened for output.
  10015. See also <code><a href="#opid">opid</a></code>, <code> <a
  10016. href="#call">call</a></code>, <code><a
  10017. href="#in">in</a></code>, <code> <a
  10018. href="#err">err</a></code>, <code> <a
  10019. href="#ctl">ctl</a></code>, <code><a
  10020. href="#pipe">pipe</a></code>, <code> <a
  10021. href="#poll">poll</a></code>, <code> <a
  10022. href="#close">close</a></code> and <code><a
  10023. href="#load">load</a></code>.
  10024.  
  10025. <pre><code>
  10026. : (out "a" (println 123 '(a b c) 'def)) # Write one line to file "a"
  10027. -> def
  10028. </code></pre>
  10029.  
  10030. </dl>
  10031.  
  10032. <h1><a name="P">P</a></h1>
  10033.  
  10034. <dl>
  10035.  
  10036. <dt><a name="*PPid"><code>*PPid</code></a>
  10037. <dd>A global constant holding the process-id of the parent picolisp process, or
  10038. <code>NIL</code> if the current process is a top level process.
  10039.  
  10040. <pre><code>
  10041. : (println *PPid *Pid)
  10042. NIL 5286
  10043.  
  10044. : (unless (fork) (println *PPid *Pid) (bye))
  10045. 5286 5522
  10046. </code></pre>
  10047.  
  10048. <dt><a name="*Pid"><code>*Pid</code></a>
  10049. <dd>A global constant holding the current process-id.
  10050.  
  10051. <pre><code>
  10052. : *Pid
  10053. -> 6386
  10054. : (call "ps") # Show processes
  10055. PID TTY TIME CMD
  10056. .... ... ........ .....
  10057. 6386 pts/1 00:00:00 pil # <- current process
  10058. 6388 pts/1 00:00:00 ps
  10059. -> T
  10060. </code></pre>
  10061.  
  10062. <dt><a name="*Prompt"><code>*Prompt</code></a>
  10063. <dd>Global variable holding a (possibly empty) <code>prg</code> body, which is
  10064. executed - and the result <code><a href="#prin">prin</a></code>ted -
  10065. every time before a prompt is output to the console in the
  10066. "read-eval-print-loop" (REPL).
  10067.  
  10068. <pre><code>
  10069. : (de *Prompt (pack "[" (stamp) "]"))
  10070. # *Prompt redefined
  10071. -> *Prompt
  10072. [2011-10-11 16:50:05]: (+ 1 2 3)
  10073. -> 6
  10074. [2011-10-11 16:50:11]:
  10075. </code></pre>
  10076.  
  10077. <dt><a name="pack"><code>(pack 'any ..) -> sym</code></a>
  10078. <dd>Returns a transient symbol whose name is concatenated from all arguments
  10079. <code>any</code>. A <code>NIL</code> arguments contributes nothing to the result
  10080. string, a number is converted to a digit string, a symbol supplies the
  10081. characters of its name, and for a list its elements are taken. See also <code><a
  10082. href="#text">text</a></code> and <code><a
  10083. href="#glue">glue</a></code>.
  10084.  
  10085. <pre><code>
  10086. : (pack 'car " is " 1 '(" symbol " name))
  10087. -> "car is 1 symbol name"
  10088. </code></pre>
  10089.  
  10090. <dt><a name="pad"><code>(pad 'cnt 'any) -> sym</code></a>
  10091. <dd>Returns a transient symbol with <code>any</code> <code><a
  10092. href="#pack">pack</a></code>ed with leading '0' characters, up to a
  10093. field width of <code>cnt</code>. See also <code><a
  10094. href="#format">format</a></code> and <code><a
  10095. href="#align">align</a></code>.
  10096.  
  10097. <pre><code>
  10098. : (pad 5 1)
  10099. -> "00001"
  10100. : (pad 5 123456789)
  10101. -> "123456789"
  10102. </code></pre>
  10103.  
  10104. <dt><a name="pair"><code>(pair 'any) -> any</code></a>
  10105. <dd>Returns <code>any</code> when the argument is a cons pair. See also <code><a
  10106. href="#atom">atom</a></code>, <code><a
  10107. href="#num?">num?</a></code>, <code><a
  10108. href="#sym?">sym?</a></code> and <code><a
  10109. href="#lst?">lst?</a></code>.
  10110.  
  10111. <pre><code>
  10112. : (pair NIL)
  10113. -> NIL
  10114. : (pair (1 . 2))
  10115. -> (1 . 2)
  10116. : (pair (1 2 3))
  10117. -> (1 2 3)
  10118. </code></pre>
  10119.  
  10120. <dt><a name="part/3"><code>part/3</code></a>
  10121. <dd><a href="#pilog">Pilog</a> predicate that succeeds if the first
  10122. argument, after <code><a href="#fold">fold</a></code>ing it to a
  10123. canonical form, is a <i>substring</i> of the folded string representation of the
  10124. result of applying the <code><a href="#get">get</a></code> algorithm to
  10125. the following arguments. Typically used as filter predicate in <code><a
  10126. href="#select/3">select/3</a></code> database queries. See also
  10127. <code><a href="#sub?">sub?</a></code>, <code><a
  10128. href="#isa/2">isa/2</a></code>, <code><a
  10129. href="#same/3">same/3</a></code>, <code><a
  10130. href="#bool/3">bool/3</a></code>, <code><a
  10131. href="#range/3">range/3</a></code>, <code><a
  10132. href="#head/3">head/3</a></code>, <code><a
  10133. href="#fold/3">fold/3</a></code> and <code><a
  10134. href="#tolr/3">tolr/3</a></code>.
  10135.  
  10136. <pre><code>
  10137. : (?
  10138. @Nr (1 . 5)
  10139. @Nm "part"
  10140. (select (@Item)
  10141. ((nr +Item @Nr) (nm +Item @Nm))
  10142. (range @Nr @Item nr)
  10143. (part @Nm @Item nm) ) )
  10144. @Nr=(1 . 5) @Nm="part" @Item={3-1}
  10145. @Nr=(1 . 5) @Nm="part" @Item={3-2}
  10146. -> NIL
  10147. </code></pre>
  10148.  
  10149. <dt><a name="pass"><code>(pass 'fun ['any ..]) -> any</code></a>
  10150. <dd>Passes to <code>fun</code> all arguments <code>any</code>, and all remaining
  10151. variable arguments (<code>@</code>) as they would be returned by <code><a
  10152. href="#rest">rest</a></code>. <code>(pass 'fun 'any)</code> is
  10153. equivalent to <code>(apply 'fun (rest) 'any)</code>. See also <code><a
  10154. href="#apply">apply</a></code>.
  10155.  
  10156. <pre><code>
  10157. : (de bar (A B . @)
  10158. (println 'bar A B (rest)) )
  10159. -> bar
  10160. : (de foo (A B . @)
  10161. (println 'foo A B)
  10162. (pass bar 1)
  10163. (pass bar 2) )
  10164. -> foo
  10165. : (foo 'a 'b 'c 'd 'e 'f)
  10166. foo a b
  10167. bar 1 c (d e f)
  10168. bar 2 c (d e f)
  10169. -> (d e f)
  10170. </code></pre>
  10171.  
  10172. <dt><a name="pat?"><code>(pat? 'any) -> pat | NIL</code></a>
  10173. <dd>Returns <code>any</code> when the argument <code>any</code> is a symbol
  10174. whose name starts with an at-mark "<code>@</code>", otherwise <code>NIL</code>.
  10175.  
  10176. <pre><code>
  10177. : (pat? '@)
  10178. -> @
  10179. : (pat? "@Abc")
  10180. -> "@Abc"
  10181. : (pat? "ABC")
  10182. -> NIL
  10183. : (pat? 123)
  10184. -> NIL
  10185. </code></pre>
  10186.  
  10187. <dt><a name="patch"><code>(patch 'lst 'any . prg) -> any</code></a>
  10188. <dd>Destructively replaces all sub-expressions of <code>lst</code>, that
  10189. <code><a href="#match">match</a></code> the pattern <code>any</code>,
  10190. by the result of the execution of <code>prg</code>. See also <code><a
  10191. href="#daemon">daemon</a></code> and <code><a
  10192. href="#redef">redef</a></code>.
  10193.  
  10194. <pre><code>
  10195. : (pp 'hello)
  10196. (de hello NIL
  10197. (prinl "Hello world!") )
  10198. -> hello
  10199.  
  10200. : (patch hello 'prinl 'println)
  10201. -> NIL
  10202. : (pp 'hello)
  10203. (de hello NIL
  10204. (println "Hello world!") )
  10205. -> hello
  10206.  
  10207. : (patch hello '(prinl @S) (fill '(println "We said: " . @S)))
  10208. -> NIL
  10209. : (hello)
  10210. We said: Hello world!
  10211. -> "Hello world!"
  10212. </code></pre>
  10213.  
  10214. <dt><a name="path"><code>(path 'any) -> sym</code></a>
  10215. <dd>Substitutes any leading "<code>@</code>" character in the <code>any</code>
  10216. argument with the <u>PicoLisp Home Directory</u>, as it was remembered during
  10217. interpreter startup. Optionally, the name may be preceded by a "<code>+</code>"
  10218. character (as used by <code><a href="#in">in</a></code> and <code><a
  10219. href="#out">out</a></code>). This mechanism is used internally by all
  10220. I/O functions. See also <a href="#invoc">Invocation</a>, <code><a
  10221. href="#basename">basename</a></code> and <code><a
  10222. href="#dirname">dirname</a></code>.
  10223.  
  10224. <pre><code>
  10225. $ /usr/bin/picolisp /usr/lib/picolisp/lib.l
  10226. : (path "a/b/c")
  10227. -> "a/b/c"
  10228. : (path "@a/b/c")
  10229. -> "/usr/lib/picolisp/a/b/c"
  10230. : (path "+@a/b/c")
  10231. -> "+/usr/lib/picolisp/a/b/c"
  10232. </code></pre>
  10233.  
  10234. <dt><a name="peek"><code>(peek) -> sym</code></a>
  10235. <dd>Single character look-ahead: Returns the same character as the next call to
  10236. <code><a href="#char">char</a></code> would return. See also <code><a
  10237. href="#skip">skip</a></code>.
  10238.  
  10239. <pre><code>
  10240. $ cat a
  10241. # Comment
  10242. abcd
  10243. $ pil +
  10244. : (in "a" (list (peek) (char)))
  10245. -> ("#" "#")
  10246. </code></pre>
  10247.  
  10248. <dt><a name="permute/2"><code>permute/2</code></a>
  10249. <dd><a href="#pilog">Pilog</a> predicate that succeeds if the second
  10250. argument is a permutation of the list in the second argument. See also <code><a
  10251. href="#append/3">append/3</a></code>.
  10252.  
  10253. <pre><code>
  10254. : (? (permute (a b c) @X))
  10255. @X=(a b c)
  10256. @X=(a c b)
  10257. @X=(b a c)
  10258. @X=(b c a)
  10259. @X=(c a b)
  10260. @X=(c b a)
  10261. -> NIL
  10262. </code></pre>
  10263.  
  10264. <dt><a name="pick"><code>(pick 'fun 'lst ..) -> any</code></a>
  10265. <dd>Applies <code>fun</code> to successive elements of <code>lst</code> until
  10266. non-<code>NIL</code> is returned. Returns that value, or <code>NIL</code> if
  10267. <code>fun</code> did not return non-<code>NIL</code> for any element of
  10268. <code>lst</code>. When additional <code>lst</code> arguments are given, their
  10269. elements are also passed to <code>fun</code>. <code>(pick 'fun 'lst)</code> is
  10270. equivalent to <code>(fun (find 'fun 'lst))</code>. See also <code><a
  10271. href="#seek">seek</a></code>, <code><a
  10272. href="#find">find</a></code> and <code><a
  10273. href="#extract">extract</a></code>.
  10274.  
  10275. <pre><code>
  10276. : (setq A NIL B 1 C NIL D 2 E NIL F 3)
  10277. -> 3
  10278. : (find val '(A B C D E))
  10279. -> B
  10280. : (pick val '(A B C D E))
  10281. -> 1
  10282. </code></pre>
  10283.  
  10284. <dt><a name="pico"><code>pico</code></a>
  10285. <dd>(64-bit version only) A global constant holding the initial (default)
  10286. namespace of internal symbols. Its value is a cons pair of two '<code><a
  10287. href="#idx">idx</a></code>' trees, one for symbols with short names and
  10288. one for symbols with long names (more than 7 bytes in the name). See also
  10289. <code><a href="#symbols">symbols</a></code>, <code><a
  10290. href="#import">import</a></code> and <code><a
  10291. href="#intern">intern</a></code>.
  10292.  
  10293. <pre><code>
  10294. : (symbols)
  10295. -> pico
  10296. : (cdr pico)
  10297. -> (rollback (*NoTrace (*CtryCode (+IdxFold) genStrKey) basename ...
  10298. </code></pre>
  10299.  
  10300. <dt><a name="pil"><code>(pil ['any ..]) -> sym</code></a>
  10301. <dd>Returns the path name to the <code><a
  10302. href="#pack">pack</a></code>ed <code>any</code> arguments in
  10303. the directory ".pil/" in the user's home directory.
  10304. See also <code><a href="#tmp">tmp</a></code>.
  10305.  
  10306. <pre><code>
  10307. : (pil "history") # Path to the line editor's history file
  10308. -> "/home/app/.pil/history"
  10309. </code></pre>
  10310.  
  10311. <dt><a name="pilog"><code>(pilog 'lst . prg) -> any</code></a>
  10312. <dd>Evaluates a <a href="#pilog">Pilog</a> query, and executes
  10313. <code>prg</code> for each result set with all Pilog variables bound to their
  10314. matching values. See also <code><a href="#solve">solve</a></code>,
  10315. <code><a href="#?">?</a></code>, <code><a
  10316. href="#goal">goal</a></code> and <code><a
  10317. href="#prove">prove</a></code>.
  10318.  
  10319. <pre><code>
  10320. : (pilog '((append @X @Y (a b c))) (println @X '- @Y))
  10321. NIL - (a b c)
  10322. (a) - (b c)
  10323. (a b) - (c)
  10324. (a b c) - NIL
  10325. -> NIL
  10326. </code></pre>
  10327.  
  10328. <dt><a name="pipe"><code>(pipe exe) -> cnt</code></a>
  10329. <dt><code>(pipe exe . prg) -> any</code>
  10330. <dd>Executes <code>exe</code> in a <code><a
  10331. href="#fork">fork</a></code>'ed child process (which terminates
  10332. thereafter). In the first form, <code>pipe</code> just returns a file descriptor
  10333. to write to the standard input and read from the standard output of that
  10334. process. In the second form, it opens the standard output of that process as
  10335. input channel during the execution of <code>prg</code>. The current input
  10336. channel will be saved and restored appropriately. See also <code><a
  10337. href="#later">later</a></code>, <code><a
  10338. href="#ipid">ipid</a></code>, <code><a
  10339. href="#in">in</a></code> and <code><a
  10340. href="#out">out</a></code>.
  10341.  
  10342. <pre><code>
  10343. : (pipe # equivalent to 'any'
  10344. (prinl "(a b # Comment^Jc d)") # Child
  10345. (read) ) # Parent
  10346. -> (a b c d)
  10347.  
  10348. : (pipe # pipe through an external program
  10349. (out '(tr "[a-z]" "[A-Z]") # Child
  10350. (prinl "abc def ghi") )
  10351. (line T) ) # Parent
  10352. -> "ABC DEF GHI"
  10353.  
  10354. : (setq P
  10355. (pipe
  10356. (in NIL # Child: Read stdin
  10357. (while (line T)
  10358. (prinl (uppc @)) # and write to stdout
  10359. (flush) ) ) ) )
  10360. -> 3
  10361. : (out P (prinl "abc def")) # Parent: Send line to child
  10362. -> "abc def"
  10363. : (in P (line)) # Parent: Read reply
  10364. -> ("A" "B" "C" " " "D" "E" "F")
  10365. </code></pre>
  10366.  
  10367. <dt><a name="place"><code>(place 'cnt 'lst 'any) -> lst</code></a>
  10368. <dd>Places <code>any</code> into <code>lst</code> at position <code>cnt</code>.
  10369. This is a non-destructive operation. See also <code><a
  10370. href="#insert">insert</a></code>, <code><a
  10371. href="#remove">remove</a></code>, <code><a
  10372. href="#append">append</a></code>, <code><a
  10373. href="#delete">delete</a></code> and <code><a
  10374. href="#replace">replace</a></code>.
  10375.  
  10376. <pre><code>
  10377. : (place 3 '(a b c d e) 777)
  10378. -> (a b 777 d e)
  10379. : (place 1 '(a b c d e) 777)
  10380. -> (777 b c d e)
  10381. : (place 9 '(a b c d e) 777)
  10382. -> (a b c d e 777)
  10383. </code></pre>
  10384.  
  10385. <dt><a name="poll"><code>(poll 'cnt) -> cnt | NIL</code></a>
  10386. <dd>Checks for the availability of data for reading on the file descriptor
  10387. <code>cnt</code>. See also <code><a href="#open">open</a></code>,
  10388. <code><a href="#in">in</a></code> and <code><a
  10389. href="#close">close</a></code>.
  10390.  
  10391. <pre><code>
  10392. : (and (poll *Fd) (in @ (read))) # Prevent blocking
  10393. </code></pre>
  10394.  
  10395. <dt><a name="pool"><code>(pool ['sym1 ['lst] ['sym2] ['sym3]]) -> T</code></a>
  10396. <dd>Opens the file <code>sym1</code> as a database file in read/write mode. If
  10397. the file does not exist, it is created. A currently open database is closed.
  10398. <code>lst</code> is a list of block size scale factors (i.e. numbers),
  10399. defaulting to (2) (for a single file with a 256 byte block size). If
  10400. <code>lst</code> is given, an individual database file is opened for each item.
  10401. If <code>sym2</code> is non-<code>NIL</code>, it is opened in append-mode as an
  10402. asynchronous replication journal. If <code>sym3</code> is non-<code>NIL</code>,
  10403. it is opened for reading and appending, to be used as a synchronous transaction
  10404. log during <code><a href="#commit">commit</a></code>s. See also
  10405. <code><a href="#dbs">dbs</a></code>, <code><a
  10406. href="#*Dbs">*Dbs</a></code> and <code><a
  10407. href="#journal">journal</a></code>.
  10408.  
  10409. <pre><code>
  10410. : (pool "/dev/hda2")
  10411. -> T
  10412.  
  10413. : *Dbs
  10414. -> (1 2 2 4)
  10415. : (pool "dbFile" *Dbs)
  10416. -> T
  10417. :
  10418. abu:~/pico ls -l dbFile*
  10419. -rw-r--r-- 1 abu abu 256 2007-06-11 07:57 dbFile1
  10420. -rw-r--r-- 1 abu abu 13 2007-06-11 07:57 dbFile2
  10421. -rw-r--r-- 1 abu abu 13 2007-06-11 07:57 dbFile3
  10422. -rw-r--r-- 1 abu abu 13 2007-06-11 07:57 dbFile4
  10423. </code></pre>
  10424.  
  10425. <dt><a name="pop"><code>(pop 'var) -> any</code></a>
  10426. <dd>Pops the first element (CAR) from the stack in <code>var</code>. See also
  10427. <code><a href="#push">push</a></code>, <code><a
  10428. href="#queue">queue</a></code>, <code><a
  10429. href="#cut">cut</a></code>, <code><a
  10430. href="#del">del</a></code> and <code><a
  10431. href="#fifo">fifo</a></code>.
  10432.  
  10433. <pre><code>
  10434. : (setq S '((a b c) (1 2 3)))
  10435. -> ((a b c) (1 2 3))
  10436. : (pop S)
  10437. -> a
  10438. : (pop (cdr S))
  10439. -> 1
  10440. : (pop 'S)
  10441. -> (b c)
  10442. : S
  10443. -> ((2 3))
  10444. </code></pre>
  10445.  
  10446. <dt><a name="port"><code>(port ['T] 'cnt|(cnt . cnt) ['var]) -> cnt</code></a>
  10447. <dd>Opens a TCP-Port <code>cnt</code> (or a UDP-Port if the first argument is
  10448. <code>T</code>), and returns a socket descriptor suitable as an argument for
  10449. <code><a href="#listen">listen</a></code> or <code><a
  10450. href="#accept">accept</a></code> (or <code><a
  10451. href="#udp">udp</a></code>, respectively). If <code>cnt</code> is zero,
  10452. some free port number is allocated. If a pair of <code>cnt</code>s is given
  10453. instead, it should be a range of numbers which are tried in turn. When
  10454. <code>var</code> is given, it is bound to the port number.
  10455.  
  10456. <pre><code>
  10457. : (port 0 'A) # Allocate free port
  10458. -> 4
  10459. : A
  10460. -> 1034 # Got 1034
  10461. : (port (4000 . 4008) 'A) # Try one of these ports
  10462. -> 5
  10463. : A
  10464. -> 4002
  10465. </code></pre>
  10466.  
  10467. <dt><a name="pp"><code>(pp 'sym) -> sym</code></a>
  10468. <dt><code>(pp 'sym 'cls) -> sym</code>
  10469. <dt><code>(pp '(sym . cls)) -> sym</code>
  10470. <dd>Pretty-prints the function or method definition of <code>sym</code>. The
  10471. output format would regenerate that same definition when read and executed. See
  10472. also <code><a href="#pretty">pretty</a></code>, <code><a
  10473. href="#debug">debug</a></code> and <code><a
  10474. href="#vi">vi</a></code>.
  10475.  
  10476. <pre><code>
  10477. : (pp 'tab)
  10478. (de tab (Lst . @)
  10479. (for N Lst
  10480. (let V (next)
  10481. (and (gt0 N) (space (- N (length V))))
  10482. (prin V)
  10483. (and
  10484. (lt0 N)
  10485. (space (- 0 N (length V))) ) ) )
  10486. (prinl) )
  10487. -> tab
  10488.  
  10489. : (pp 'has> '+Entity)
  10490. (dm has> (Var Val)
  10491. (or
  10492. (nor Val (get This Var))
  10493. (has> (meta This Var) Val (get This Var)) ) )
  10494. -> has>
  10495.  
  10496. : (more (can 'has>) pp)
  10497. (dm (has> . +relation) (Val X)
  10498. (and (= Val X) X) )
  10499.  
  10500. (dm (has> . +Fold) (Val X)
  10501. (extra
  10502. Val
  10503. (if (= Val (fold Val)) (fold X) X) ) )
  10504.  
  10505. (dm (has> . +Entity) (Var Val)
  10506. (or
  10507. (nor Val (get This Var))
  10508. (has> (meta This Var) Val (get This Var)) ) )
  10509.  
  10510. (dm (has> . +List) (Val X)
  10511. (and
  10512. Val
  10513. (or
  10514. (extra Val X)
  10515. (find '((X) (extra Val X)) X) ) ) )
  10516.  
  10517. (dm (has> . +Bag) (Val X)
  10518. (and
  10519. Val
  10520. (or (super Val X) (car (member Val X))) ) )
  10521. </code></pre>
  10522.  
  10523. <dt><a name="pr"><code>(pr 'any ..) -> any</code></a>
  10524. <dd>Binary print: Prints all <code>any</code> arguments to the current output
  10525. channel in encoded binary format. See also <code><a
  10526. href="#rd">rd</a></code>, <code><a
  10527. href="#bytes">bytes</a></code>, <code><a
  10528. href="#tell">tell</a></code>, <code><a
  10529. href="#hear">hear</a></code> and <code><a
  10530. href="#wr">wr</a></code>.
  10531.  
  10532. <pre><code>
  10533. : (out "x" (pr 7 "abc" (1 2 3) 'a)) # Print to "x"
  10534. -> a
  10535. : (hd "x")
  10536. 00000000 04 0E 0E 61 62 63 01 04 02 04 04 04 06 03 05 61 ...abc.........a
  10537. -> NIL
  10538. </code></pre>
  10539.  
  10540. <dt><a name="prEval"><code>(prEval 'prg ['cnt]) -> any</code></a>
  10541. <dd>Executes <code>prg</code>, similar to <code><a
  10542. href="#run">run</a></code>, by evaluating all expressions in
  10543. <code>prg</code> (within the binding environment given by <code>cnt-1</code>).
  10544. As a side effect, all atomic expressions will be printed with <code><a
  10545. href="#prinl">prinl</a></code>. See also <code><a
  10546. href="#eval">eval</a></code>.
  10547.  
  10548. <pre><code>
  10549. : (let Prg 567
  10550. (prEval
  10551. '("abc" (prinl (+ 1 2 3)) Prg 987) ) )
  10552. abc
  10553. 6
  10554. 567
  10555. 987
  10556. -> 987
  10557. </code></pre>
  10558.  
  10559. <dt><a name="pre?"><code>(pre? 'any1 'any2) -> any2 | NIL</code></a>
  10560. <dd>Returns <code>any2</code> when the string representation of
  10561. <code>any1</code> is a prefix of the string representation of <code>any2</code>.
  10562. See also <code><a href="#sub?">sub?</a></code> and <code><a
  10563. href="#head">head</a></code>.
  10564.  
  10565. <pre><code>
  10566. : (pre? "abc" "abcdefg")
  10567. -> "abcdef"
  10568. : (pre? "def" "abcdefg")
  10569. -> NIL
  10570. : (pre? (+ 3 4) "7fach")
  10571. -> "7fach"
  10572. : (pre? NIL "abcdefg")
  10573. -> "abcdefg"
  10574.  
  10575. : (pre? "abc" '(a b c d e f g))
  10576. -> "abcdefg"
  10577. : (pre? '(a b c) "abcdefg")
  10578. -> "abcdefg"
  10579. </code></pre>
  10580.  
  10581. <dt><a name="pretty"><code>(pretty 'any 'cnt)</code></a>
  10582. <dd>Pretty-prints <code>any</code>. If <code>any</code> is an atom, or a list
  10583. with a <code><a href="#size">size</a></code> not greater than 12, it is
  10584. <code><a href="#print">print</a></code>ed as is. Otherwise, only the
  10585. opening parenthesis and the CAR of the list is printed, all other elementes are
  10586. pretty-printed recursively indented by three spaces, followed by a space and the
  10587. corresponding closing parenthesis. The initial indentation level
  10588. <code>cnt</code> defaults to zero. See also <code><a
  10589. href="#pp">pp</a></code>.
  10590.  
  10591. <pre><code>
  10592. : (pretty '(a (b c d) (e (f (g) (h) (i)) (j (k) (l) (m))) (n o p) q))
  10593. (a
  10594. (b c d)
  10595. (e
  10596. (f (g) (h) (i))
  10597. (j (k) (l) (m)) )
  10598. (n o p)
  10599. q )-> ")"
  10600. </code></pre>
  10601.  
  10602. <dt><a name="prin"><code>(prin 'any ..) -> any</code></a>
  10603. <dd>Prints the string representation of all <code>any</code> arguments to the
  10604. current output channel. No space or newline is printed between individual items,
  10605. or after the last item. For lists, all elements are <code>prin</code>'ted
  10606. recursively. See also <code><a href="#prinl">prinl</a></code>.
  10607.  
  10608. <pre><code>
  10609. : (prin 'abc 123 '(a 1 b 2))
  10610. abc123a1b2-> (a 1 b 2)
  10611. </code></pre>
  10612.  
  10613. <dt><a name="prinl"><code>(prinl 'any ..) -> any</code></a>
  10614. <dd>Prints the string representation of all <code>any</code> arguments to the
  10615. current output channel, followed by a newline. No space or newline is printed
  10616. between individual items. For lists, all elements are <code>prin</code>'ted
  10617. recursively. See also <code><a href="#prin">prin</a></code>.
  10618.  
  10619. <pre><code>
  10620. : (prinl 'abc 123 '(a 1 b 2))
  10621. abc123a1b2
  10622. -> (a 1 b 2)
  10623. </code></pre>
  10624.  
  10625. <dt><a name="print"><code>(print 'any ..) -> any</code></a>
  10626. <dd>Prints all <code>any</code> arguments to the current output channel. If
  10627. there is more than one argument, a space is printed between successive
  10628. arguments. No space or newline is printed after the last item. See also <code><a
  10629. href="#println">println</a></code>, <code><a
  10630. href="#printsp">printsp</a></code>, <code><a
  10631. href="#sym">sym</a></code> and <code><a
  10632. href="#str">str</a></code>
  10633.  
  10634. <pre><code>
  10635. : (print 123)
  10636. 123-> 123
  10637. : (print 1 2 3)
  10638. 1 2 3-> 3
  10639. : (print '(a b c) 'def)
  10640. (a b c) def-> def
  10641. </code></pre>
  10642.  
  10643. <dt><a name="println"><code>(println 'any ..) -> any</code></a>
  10644. <dd>Prints all <code>any</code> arguments to the current output channel,
  10645. followed by a newline. If there is more than one argument, a space is printed
  10646. between successive arguments. See also <code><a
  10647. href="#print">print</a></code>, <code><a
  10648. href="#printsp">printsp</a></code>.
  10649.  
  10650. <pre><code>
  10651. : (println '(a b c) 'def)
  10652. (a b c) def
  10653. -> def
  10654. </code></pre>
  10655.  
  10656. <dt><a name="printsp"><code>(printsp 'any ..) -> any</code></a>
  10657. <dd>Prints all <code>any</code> arguments to the current output channel,
  10658. followed by a space. If there is more than one argument, a space is printed
  10659. between successive arguments. See also <code><a
  10660. href="#print">print</a></code>, <code><a
  10661. href="#println">println</a></code>.
  10662.  
  10663. <pre><code>
  10664. : (printsp '(a b c) 'def)
  10665. (a b c) def -> def
  10666. </code></pre>
  10667.  
  10668. <dt><a name="prior"><code>(prior 'lst1 'lst2) -> lst | NIL</code></a>
  10669. <dd>Returns the cell in <code>lst2</code> which immediately precedes the cell
  10670. <code>lst1</code>, or <code>NIL</code> if <code>lst1</code> is not found in
  10671. <code>lst2</code> or is the very first cell. <code><a
  10672. href="#==">==</a></code> is used for comparison (pointer equality). See
  10673. also <code><a href="#offset">offset</a></code> and <code><a
  10674. href="#memq">memq</a></code>.
  10675.  
  10676. <pre><code>
  10677. : (setq L (1 2 3 4 5 6))
  10678. -> (1 2 3 4 5 6)
  10679. : (setq X (cdddr L))
  10680. -> (4 5 6)
  10681. : (prior X L)
  10682. -> (3 4 5 6)
  10683. </code></pre>
  10684.  
  10685. <dt><a name="proc"><code>(proc 'sym ..) -> T</code></a>
  10686. <dd>(Debug mode on Linux only) Shows a list of processes with command names
  10687. given by the <code>sym</code> arguments, using the system <code>ps</code>
  10688. utility. See also <code><a href="#kids">kids</a></code>, <code><a
  10689. href="#kill">kill</a></code> and <code><a
  10690. href="#hd">hd</a></code>.
  10691.  
  10692. <pre><code>
  10693. : (proc 'pil)
  10694. PID PPID STARTED SIZE %CPU WCHAN CMD
  10695. 16993 3267 12:38:21 1516 0.5 - /usr/bin/picolisp /usr/lib/picolisp/lib.l /usr/bin/pil +
  10696. 15731 1834 12:36:35 2544 0.1 - /usr/bin/picolisp /usr/lib/picolisp/lib.l /usr/bin/pil app/main.l -main -go +
  10697. 15823 15731 12:36:44 2548 0.0 - /usr/bin/picolisp /usr/lib/picolisp/lib.l /usr/bin/pil app/main.l -main -go +
  10698. -> T
  10699. </code></pre>
  10700.  
  10701. <dt><a name="prog"><code>(prog . prg) -> any</code></a>
  10702. <dd>Executes <code>prg</code>, and returns the result of the last expression.
  10703. See also <code><a href="#nil">nil</a></code>, <code><a
  10704. href="#t">t</a></code>, <code><a
  10705. href="#prog1">prog1</a></code> and <code><a
  10706. href="#prog2">prog2</a></code>.
  10707.  
  10708. <pre><code>
  10709. : (prog (print 1) (print 2) (print 3))
  10710. 123-> 3
  10711. </code></pre>
  10712.  
  10713. <dt><a name="prog1"><code>(prog1 'any1 . prg) -> any1</code></a>
  10714. <dd>Executes all arguments, and returns the result of the first expression
  10715. <code>any1</code>. See also <code><a href="#nil">nil</a></code>,
  10716. <code><a href="#t">t</a></code>, <code><a
  10717. href="#prog">prog</a></code> and <code><a
  10718. href="#prog2">prog2</a></code>.
  10719.  
  10720. <pre><code>
  10721. : (prog1 (print 1) (print 2) (print 3))
  10722. 123-> 1
  10723. </code></pre>
  10724.  
  10725. <dt><a name="prog2"><code>(prog2 'any1 'any2 . prg) -> any2</code></a>
  10726. <dd>Executes all arguments, and returns the result of the second expression
  10727. <code>any2</code>. See also <code><a href="#nil">nil</a></code>,
  10728. <code><a href="#t">t</a></code>, <code><a
  10729. href="#prog">prog</a></code> and <code><a
  10730. href="#prog1">prog1</a></code>.
  10731.  
  10732. <pre><code>
  10733. : (prog2 (print 1) (print 2) (print 3))
  10734. 123-> 2
  10735. </code></pre>
  10736.  
  10737. <dt><a name="prop"><code>(prop 'sym1|lst ['sym2|cnt ..] 'sym) -> var</code></a>
  10738. <dd>Fetches a property for a property key <code>sym</code> from a symbol. That
  10739. symbol is <code>sym1</code> (if no other arguments are given), or a symbol found
  10740. by applying the <code><a href="#get">get</a></code> algorithm to
  10741. <code>sym1|lst</code> and the following arguments. The property (the cons pair,
  10742. not just its value) is returned, suitable for direct (destructive) manipulations
  10743. with functions expecting a <code>var</code> argument. See also <code><a
  10744. href="#::">::</a></code>.
  10745.  
  10746. <pre><code>
  10747. : (put 'X 'cnt 0)
  10748. -> 0
  10749. : (prop 'X 'cnt)
  10750. -> (0 . cnt)
  10751. : (inc (prop 'X 'cnt)) # Directly manipulate the property value
  10752. -> 1
  10753. : (get 'X 'cnt)
  10754. -> 1
  10755. </code></pre>
  10756.  
  10757. <dt><a name="protect"><code>(protect . prg) -> any</code></a>
  10758. <dd>Executes <code>prg</code>, and returns the result of the last expression. If
  10759. a signal is received during that time, its handling will be delayed until the
  10760. execution of <code>prg</code> is completed. See also <code><a
  10761. href="#alarm">alarm</a></code>, <a href="refH.html#*Hup">*Hup</a>, <a
  10762. href="#*Sig1">*Sig[12]</a> and <code><a
  10763. href="#kill">kill</a></code>.
  10764.  
  10765. <pre><code>
  10766. : (protect (journal "db1.log" "db2.log"))
  10767. -> T
  10768. </code></pre>
  10769.  
  10770. <dt><a name="prove"><code>(prove 'lst ['lst]) -> lst</code></a>
  10771. <dd>The <a href="#pilog">Pilog</a> interpreter. Tries to prove the query
  10772. list in the first argument, and returns an association list of symbol-value
  10773. pairs, or <code>NIL</code> if not successful. The query list is modified as a
  10774. side effect, allowing subsequent calls to <code>prove</code> for further
  10775. results. The optional second argument may contain a list of symbols; in that
  10776. case the successful matches of rules defined for these symbols will be traced.
  10777. See also <code><a href="#goal">goal</a></code>, <code><a
  10778. href="#->">-&gt</a></code> and <code><a
  10779. href="#unify">unify</a></code>.
  10780.  
  10781. <pre><code>
  10782. : (prove (goal '((equal 3 3))))
  10783. -> T
  10784. : (prove (goal '((equal 3 @X))))
  10785. -> ((@X . 3))
  10786. : (prove (goal '((equal 3 4))))
  10787. -> NIL
  10788. </code></pre>
  10789.  
  10790. <dt><a name="prune"><code>(prune ['cnt])</code></a>
  10791. <dd>Optimizes memory usage by pruning in-memory nodes of database trees.
  10792. Typically called repeatedly during bulk data imports. If <code>cnt</code> is
  10793. <code>NIL</code>, further pruning will be disabled. Otherwise, all nodes which
  10794. have not been accessed (with <code><a href="#fetch">fetch</a></code> or
  10795. <code><a href="#store">store</a></code>) for <code>cnt</code> calls to
  10796. <code>prune</code> will be <code><a href="#wipe">wipe</a></code>d. See
  10797. also <code><a href="#lieu">lieu</a></code>.
  10798.  
  10799. <pre><code>
  10800. (in File1
  10801. (while (someData)
  10802. (new T '(+Cls1) ..)
  10803. (at (0 . 10000) (commit) (prune 100)) ) )
  10804. (in File2
  10805. (while (moreData)
  10806. (new T '(+Cls2) ..)
  10807. (at (0 . 10000) (commit) (prune 100)) ) )
  10808. (commit)
  10809. (prune)
  10810. </code></pre>
  10811.  
  10812. <dt><a name="push"><code>(push 'var 'any ..) -> any</code></a>
  10813. <dd>Implements a stack using a list in <code>var</code>. The <code>any</code>
  10814. arguments are cons'ed in front of the value list. See also <code><a
  10815. href="#push1">push1</a></code>, <code><a
  10816. href="#push1q">push1q</a></code>, <code><a
  10817. href="#pop">pop</a></code>, <code><a
  10818. href="#queue">queue</a></code> and <code><a
  10819. href="#fifo">fifo</a></code>.
  10820.  
  10821. <pre><code>
  10822. : (push 'S 3) # Use the VAL of 'S' as a stack
  10823. -> 3
  10824. : S
  10825. -> (3)
  10826. : (push 'S 2)
  10827. -> 2
  10828. : (push 'S 1)
  10829. -> 1
  10830. : S
  10831. -> (1 2 3)
  10832. : (push S 999) # Now use the CAR of the list in 'S'
  10833. -> 999
  10834. : (push S 888 777)
  10835. -> 777
  10836. : S
  10837. -> ((777 888 999 . 1) 2 3)
  10838. </code></pre>
  10839.  
  10840. <dt><a name="push1"><code>(push1 'var 'any ..) -> any</code></a>
  10841. <dd>Maintains a unique list in <code>var</code>. Each <code>any</code> argument
  10842. is cons'ed in front of the value list only if it is not already a <code><a
  10843. href="#member">member</a></code> of that list. See also <code><a
  10844. href="#push">push</a></code>, <code><a
  10845. href="#push1q">push1q</a></code>, <code><a
  10846. href="#pop">pop</a></code> and <code><a
  10847. href="#queue">queue</a></code>.
  10848.  
  10849. <pre><code>
  10850. : (push1 'S 1 2 3)
  10851. -> 3
  10852. : S
  10853. -> (3 2 1)
  10854. : (push1 'S 2 4)
  10855. -> 4
  10856. : S
  10857. -> (4 3 2 1)
  10858. </code></pre>
  10859.  
  10860. <dt><a name="push1q"><code>(push1q 'var 'any ..) -> any</code></a>
  10861. <dd>Maintains a unique list in <code>var</code>. Each <code>any</code> argument
  10862. is cons'ed in front of the value list only if it is not already <code><a
  10863. href="#memq">memq</a></code> of that list (pointer equality). See also
  10864. <code><a href="#push">push</a></code>, <code><a
  10865. href="#push1">push1</a></code>, <code><a
  10866. href="#pop">pop</a></code> and <code><a
  10867. href="#queue">queue</a></code>.
  10868.  
  10869. <pre><code>
  10870. : (push1q 'S 'a (1) 'b (2) 'c)
  10871. -> c
  10872. : S
  10873. -> (c (2) b (1) a)
  10874. : (push1q 'S 'b (1) 'd) # (1) is not pointer equal to the previous one
  10875. -> d
  10876. : S
  10877. -> (d (1) c (2) b (1) a) # (1) is twice in the list
  10878. </code></pre>
  10879.  
  10880. <dt><a name="put"><code>(put 'sym1|lst ['sym2|cnt ..] 'sym|0 'any) ->
  10881. any</code></a> <dd>Stores a new value <code>any</code> for a property key
  10882. <code>sym</code> (or in the symbol value for zero) in a symbol. That symbol is
  10883. <code>sym1</code> (if no other arguments are given), or a symbol found by
  10884. applying the <code><a href="#get">get</a></code> algorithm to
  10885. <code>sym1|lst</code> and the following arguments. See also <code><a
  10886. href="#=:">=:</a></code>.
  10887.  
  10888. <pre><code>
  10889. : (put 'X 'a 1)
  10890. -> 1
  10891. : (get 'X 'a)
  10892. -> 1
  10893. : (prop 'X 'a)
  10894. -> (1 . a)
  10895.  
  10896. : (setq L '(A B C))
  10897. -> (A B C)
  10898. : (setq B 'D)
  10899. -> D
  10900. : (put L 2 0 'p 5) # Store '5' under the 'p' property of the value of 'B'
  10901. -> 5
  10902. : (getl 'D)
  10903. -> ((5 . p))
  10904. </code></pre>
  10905.  
  10906. <dt><a name="put!"><code>(put! 'obj 'sym 'any) -> any</code></a>
  10907. <dd><a href="#trans">Transaction</a> wrapper function for <code><a
  10908. href="#put">put</a></code>. Note that for setting property values of
  10909. entities typically the <code><a
  10910. href="#entityMesssages">put!></a></code> message is used. See also
  10911. <code><a href="#new!">new!</a></code>, <code><a
  10912. href="#set!">set!</a></code> and <code><a
  10913. href="#inc!">inc!</a></code>.
  10914.  
  10915. <pre><code>
  10916. (put! Obj 'cnt 0) # Setting a property of a non-entity object
  10917. </code></pre>
  10918.  
  10919. <dt><a name="putl"><code>(putl 'sym1|lst1 ['sym2|cnt ..] 'lst) -> lst</code></a>
  10920. <dd>Stores a complete new property list <code>lst</code> in a symbol. That
  10921. symbol is <code>sym1</code> (if no other arguments are given), or a symbol found
  10922. by applying the <code><a href="#get">get</a></code> algorithm to
  10923. <code>sym1|lst1</code> and the following arguments. All previously defined
  10924. properties for that symbol are lost. See also <code><a
  10925. href="#getl">getl</a></code> and <code><a
  10926. href="#maps">maps</a></code>.
  10927.  
  10928. <pre><code>
  10929. : (putl 'X '((123 . a) flg ("Hello" . b)))
  10930. -> ((123 . a) flg ("Hello" . b))
  10931. : (get 'X 'a)
  10932. -> 123
  10933. : (get 'X 'b)
  10934. -> "Hello"
  10935. : (get 'X 'flg)
  10936. -> T
  10937. </code></pre>
  10938.  
  10939. <dt><a name="pwd"><code>(pwd) -> sym</code></a>
  10940. <dd>Returns the path to the current working directory. See also <code><a
  10941. href="#dir">dir</a></code> and <code><a
  10942. href="#cd">cd</a></code>.
  10943.  
  10944. <pre><code>
  10945. : (pwd)
  10946. -> "/home/app"
  10947. </code></pre>
  10948.  
  10949. </dl>
  10950.  
  10951. <h1><a name="Q">Q</a></h1>
  10952.  
  10953. <dl>
  10954.  
  10955. <dt><a name="qsym"><code>(qsym . sym) -> lst</code></a>
  10956. <dd>Returns a cons pair of the value and property list of <code>sym</code>. See
  10957. also <code><a href="#quote">quote</a></code>, <code><a
  10958. href="#val">val</a></code> and <code><a
  10959. href="#getl">getl</a></code>.
  10960.  
  10961. <pre><code>
  10962. : (setq A 1234)
  10963. -> 1234
  10964. : (put 'A 'a 1)
  10965. -> 1
  10966. : (put 'A 'b 2)
  10967. -> 2
  10968. : (put 'A 'f T)
  10969. -> T
  10970. : (qsym . A)
  10971. -> (1234 f (2 . b) (1 . a))
  10972. </code></pre>
  10973.  
  10974. <dt><a name="quote"><code>(quote . any) -> any</code></a>
  10975. <dd>Returns <code>any</code> unevaluated. The reader recognizes the single quote
  10976. char <code>'</code> as a macro for this function. See also <code><a
  10977. href="#lit">lit</a></code>.
  10978.  
  10979. <pre><code>
  10980. : 'a
  10981. -> a
  10982. : '(foo a b c)
  10983. -> (foo a b c)
  10984. : (quote (quote (quote a)))
  10985. -> ('('(a)))
  10986. </code></pre>
  10987.  
  10988. <dt><a name="query"><code>(query 'lst ['lst]) -> flg</code></a>
  10989. <dd>Handles an interactive <a href="#pilog">Pilog</a> query. The two
  10990. <code>lst</code> arguments are passed to <code><a
  10991. href="#prove">prove</a></code>. <code>query</code> displays each
  10992. result, waits for console input, and terminates when a non-empty line is
  10993. entered. See also <code><a href="#?">?</a></code>, <code><a
  10994. href="#pilog">pilog</a></code> and <code><a
  10995. href="#solve">solve</a></code>.
  10996.  
  10997. <pre><code>
  10998. : (query (goal '((append @X @Y (a b c)))))
  10999. @X=NIL @Y=(a b c)
  11000. @X=(a) @Y=(b c). # Stop
  11001. -> NIL
  11002. </code></pre>
  11003.  
  11004. <dt><a name="queue"><code>(queue 'var 'any) -> any</code></a>
  11005. <dd>Implements a queue using a list in <code>var</code>. The <code>any</code>
  11006. argument is (destructively) concatenated to the end of the value list. See also
  11007. <code><a href="#push">push</a></code>, <code><a
  11008. href="#pop">pop</a></code> and <code><a
  11009. href="#fifo">fifo</a></code>.
  11010.  
  11011. <pre><code>
  11012. : (queue 'A 1)
  11013. -> 1
  11014. : (queue 'A 2)
  11015. -> 2
  11016. : (queue 'A 3)
  11017. -> 3
  11018. : A
  11019. -> (1 2 3)
  11020. : (pop 'A)
  11021. -> 1
  11022. : A
  11023. -> (2 3)
  11024. </code></pre>
  11025.  
  11026. <dt><a name="quit"><code>(quit ['any ['any]])</code></a>
  11027. <dd>Stops current execution. If no arguments are given, all pending <code><a
  11028. href="#finally">finally</a></code> expressions are executed and control
  11029. is returned to the top level read-eval-print loop. Otherwise, an error handler
  11030. is entered. The first argument can be some error message, and the second might
  11031. be the reason for the error. See also <code><a href="#errors">Error
  11032. Handling</a></code>.
  11033.  
  11034. <pre><code>
  11035. : (de foo (X) (quit "Sorry, my error" X))
  11036. -> foo
  11037. : (foo 123) # 'X' is bound to '123'
  11038. 123 -- Sorry, my error # Error entered
  11039. ? X # Inspect 'X'
  11040. -> 123
  11041. ? # Empty line: Exit
  11042. :
  11043. </code></pre>
  11044.  
  11045. </dl>
  11046.  
  11047. <h1><a name="R">R</a></h1>
  11048.  
  11049. <dl>
  11050.  
  11051. <dt><a name="*Run"><code>*Run</code></a>
  11052. <dd>This global variable can hold a list of <code>prg</code> expressions which
  11053. are used during <code><a href="#key">key</a></code>, <code><a
  11054. href="#sync">sync</a></code>, <code><a
  11055. href="#wait">wait</a></code> and <code><a
  11056. href="#listen">listen</a></code>. The first element of each expression
  11057. must either be a positive number (thus denoting a file descriptor to wait for)
  11058. or a negative number (denoting a timeout value in milliseconds (in that case
  11059. another number must follow to hold the remaining time)). A <code>select</code>
  11060. system call is performed with these values, and the corresponding
  11061. <code>prg</code> body is executed when input data are available or when a
  11062. timeout occurred. See also <code><a href="#task">task</a></code>.
  11063.  
  11064. <pre><code>
  11065. : (de *Run (-2000 0 (println '2sec))) # Install 2-sec-timer
  11066. -> *Run
  11067. : 2sec # Prints "2sec" every 2 seconds
  11068. 2sec
  11069. 2sec
  11070. # (Ctrl-D) Exit
  11071. $
  11072. </code></pre>
  11073.  
  11074. <dt><a name="+Ref"><code>+Ref</code></a>
  11075. <dd>Prefix class for maintaining non-unique indexes to <code><a
  11076. href="#+relation">+relation</a></code>s, a subclass of <code><a
  11077. href="#+index">+index</a></code>. Accepts an optional argument for a
  11078. <code><a href="#+Hook">+Hook</a></code> attribute. See also <a
  11079. href="#dbase">Database</a>.
  11080.  
  11081. <pre><code>
  11082. (rel tel (+Fold +Ref +String)) # Phone number with folded, non-unique index
  11083. </code></pre>
  11084.  
  11085. <dt><a name="+Ref2"><code>+Ref2</code></a>
  11086. <dd>Prefix class for maintaining a secondary ("backing") index to <code><a
  11087. href="#+relation">+relation</a></code>s. Can only be used as a prefix
  11088. class to <code><a href="#+Key">+Key</a></code> or <code><a
  11089. href="#+Ref">+Ref</a></code>. It maintains an index in the current
  11090. (sub)class, in addition to that in one of the superclasses, to allow
  11091. (sub)class-specific queries. See also <a
  11092. href="#dbase">Database</a>.
  11093.  
  11094. <pre><code>
  11095. (class +Ord +Entity) # Order class
  11096. (rel nr (+Need +Key +Number)) # Order number
  11097. ...
  11098. (class +EuOrd +Ord) # EU-specific order subclass
  11099. (rel nr (+Ref2 +Key +Number)) # Order number with backing index
  11100. </code></pre>
  11101.  
  11102. <dt><a name="+relation"><code>+relation</code></a>
  11103. <dd>Abstract base class of all database relations. Relation objects are usually
  11104. defined with <code><a href="#rel">rel</a></code>. The class hierarchy
  11105. includes the classes <code><a href="#+Any">+Any</a></code>, <code><a
  11106. href="#+Bag">+Bag</a></code>, <code><a
  11107. href="#+Bool">+Bool</a></code>, <code><a
  11108. href="#+Number">+Number</a></code>, <code><a
  11109. href="#+Date">+Date</a></code>, <code><a
  11110. href="#+Time">+Time</a></code>, <code><a
  11111. href="#+Symbol">+Symbol</a></code>, <code><a
  11112. href="#+String">+String</a></code>, <code><a
  11113. href="#+Link">+Link</a></code>, <code><a
  11114. href="#+Joint">+Joint</a></code> and <code><a
  11115. href="#+Blob">+Blob</a></code>, and the prefix classes <code><a
  11116. href="#+Hook">+Hook</a></code>, <code><a
  11117. href="#+Hook2">+Hook2</a></code>, <code><a
  11118. href="#+index">+index</a></code>, <code><a
  11119. href="#+Key">+Key</a></code>, <code><a
  11120. href="#+Ref">+Ref</a></code>, <code><a
  11121. href="#+Ref2">+Ref2</a></code>, <code><a
  11122. href="#+Idx">+Idx</a></code>, <code><a
  11123. href="#+IdxFold">+IdxFold</a></code>, <code><a
  11124. href="#+Sn">+Sn</a></code>, <code><a
  11125. href="#+Fold">+Fold</a></code>, <code><a
  11126. href="#+Aux">+Aux</a></code>, <code><a
  11127. href="#+UB">+UB</a></code>, <code><a
  11128. href="#+Dep">+Dep</a></code>, <code><a
  11129. href="#+List">+List</a></code>, <code><a
  11130. href="#+Need">+Need</a></code>, <code><a
  11131. href="#+Mis">+Mis</a></code> and <code><a
  11132. href="#+Alt">+Alt</a></code>. See also <a
  11133. href="#dbase">Database</a> and <code><a
  11134. href="#+Entity">+Entity</a></code>.
  11135.  
  11136. <p><a name="relationMesssages">Messages</a> to relation objects include
  11137.  
  11138. <pre><code>
  11139. mis> (Val Obj) # Return error if mismatching type or value
  11140. has> (Val X) # Check if the value is present
  11141. put> (Obj Old New) # Put new value
  11142. rel> (Obj Old New) # Maintain relational structures
  11143. lose> (Obj Val) # Delete relational structures
  11144. keep> (Obj Val) # Restore deleted relational structures
  11145. zap> (Obj Val) # Clean up relational structures
  11146. </code></pre>
  11147.  
  11148. <dt><a name="rand"><code>(rand ['cnt1 'cnt2] | ['T]) -> cnt | flg</code></a>
  11149. <dd>Returns a pseudo random number in the range cnt1 .. cnt2 (or -2147483648 ..
  11150. +2147483647 if no arguments are given). If the argument is <code>T</code>, a
  11151. boolean value <code>flg</code> is returned. See also <code><a
  11152. href="#seed">seed</a></code>.
  11153.  
  11154. <pre><code>
  11155. : (rand 3 9)
  11156. -> 3
  11157. : (rand 3 9)
  11158. -> 7
  11159. </code></pre>
  11160.  
  11161. <dt><a name="range"><code>(range 'num1 'num2 ['num3]) -> lst</code></a>
  11162. <dd>Produces a list of numbers in the range <code>num1</code> through
  11163. <code>num2</code>. When <code>num3</code> is non-<code>NIL</code>), it is used
  11164. to increment <code>num1</code> (if it is smaller than <code>num2</code>) or to
  11165. decrement <code>num1</code> (if it is greater than <code>num2</code>). See also
  11166. <code><a href="#need">need</a></code>.
  11167.  
  11168. <pre><code>
  11169. : (range 1 6)
  11170. -> (1 2 3 4 5 6)
  11171. : (range 6 1)
  11172. -> (6 5 4 3 2 1)
  11173. : (range -3 3)
  11174. -> (-3 -2 -1 0 1 2 3)
  11175. : (range 3 -3 2)
  11176. -> (3 1 -1 -3)
  11177. </code></pre>
  11178.  
  11179. <dt><a name="range/3"><code>range/3</code></a>
  11180. <dd><a href="#pilog">Pilog</a> predicate that succeeds if the first
  11181. argument is in the range of the result of applying the <code><a
  11182. href="#get">get</a></code> algorithm to the following arguments.
  11183. Typically used as filter predicate in <code><a
  11184. href="#select/3">select/3</a></code> database queries. See also
  11185. <code><a href="#cmp">Comparing</a></code>, <code><a
  11186. href="#isa/2">isa/2</a></code>, <code><a
  11187. href="#same/3">same/3</a></code>, <code><a
  11188. href="#bool/3">bool/3</a></code>, <code><a
  11189. href="#head/3">head/3</a></code>, <code><a
  11190. href="#fold/3">fold/3</a></code>, <code><a
  11191. href="#part/3">part/3</a></code> and <code><a
  11192. href="#tolr/3">tolr/3</a></code>.
  11193.  
  11194. <pre><code>
  11195. : (?
  11196. @Nr (1 . 5) # Numbers between 1 and 5
  11197. @Nm "part"
  11198. (select (@Item)
  11199. ((nr +Item @Nr) (nm +Item @Nm))
  11200. (range @Nr @Item nr)
  11201. (part @Nm @Item nm) ) )
  11202. @Nr=(1 . 5) @Nm="part" @Item={3-1}
  11203. @Nr=(1 . 5) @Nm="part" @Item={3-2}
  11204. -> NIL
  11205. </code></pre>
  11206.  
  11207. <dt><a name="rank"><code>(rank 'any 'lst ['flg]) -> lst</code></a>
  11208. <dd>Searches a ranking list. <code>lst</code> should be sorted. Returns the
  11209. element from <code>lst</code> with a maximal CAR less or equal to
  11210. <code>any</code> (if <code>flg</code> is <code>NIL</code>), or with a minimal
  11211. CAR greater or equal to <code>any</code> (if <code>flg</code> is
  11212. non-<code>NIL</code>), or <code>NIL</code> if no match is found. See also
  11213. <code><a href="#assoc">assoc</a></code> and <a
  11214. href="#cmp">Comparing</a>.
  11215.  
  11216. <pre><code>
  11217. : (rank 0 '((1 . a) (100 . b) (1000 . c)))
  11218. -> NIL
  11219. : (rank 50 '((1 . a) (100 . b) (1000 . c)))
  11220. -> (1 . a)
  11221. : (rank 100 '((1 . a) (100 . b) (1000 . c)))
  11222. -> (100 . b)
  11223. : (rank 300 '((1 . a) (100 . b) (1000 . c)))
  11224. -> (100 . b)
  11225. : (rank 9999 '((1 . a) (100 . b) (1000 . c)))
  11226. -> (1000 . c)
  11227. : (rank 50 '((1000 . a) (100 . b) (1 . c)) T)
  11228. -> (100 . b)
  11229. </code></pre>
  11230.  
  11231. <dt><a name="rassoc"><code>(rassoc 'any 'lst) -> lst</code></a>
  11232. <dd>Reverse <code><a href="#assoc">assoc</a></code>. Returns the first
  11233. element from <code>lst</code> with its CDR equal to <code>any</code>, or
  11234. <code>NIL</code> if no match is found. See also <code><a
  11235. href="#assoc">assoc</a></code> and <code><a
  11236. href="#asoq">asoq</a></code>.
  11237.  
  11238. <pre><code>
  11239. : (rassoc 7 '((999 1 2 3) ("b" . 7) ("ok" "Hello")))
  11240. -> ("b" . 7)
  11241. : (rassoc (1 2 3) '((999 1 2 3) ("b" . 7) ("ok" "Hello")))
  11242. -> (999 1 2 3)
  11243. : (rassoc 'u '((999 1 2 3) ("b" . 7) ("ok" "Hello")))
  11244. -> NIL
  11245. </code></pre>
  11246.  
  11247. <dt><a name="raw"><code>(raw ['flg]) -> flg</code></a>
  11248. <dd>Console mode control function. When called without arguments, it returns the
  11249. current console mode (<code>NIL</code> for "cooked mode"). Otherwise, the
  11250. console is set to the new state. See also <code><a
  11251. href="#key">key</a></code>.
  11252.  
  11253. <pre><code>
  11254. $ pil
  11255. : (raw)
  11256. -> NIL
  11257. $ pil +
  11258. : (raw)
  11259. -> T
  11260. </code></pre>
  11261.  
  11262. <dt><a name="rc"><code>(rc 'sym 'any1 ['any2]) -> any</code></a>
  11263. <dd>Fetches a value from a resource file <code>sym</code>, or stores a value
  11264. <code>any2</code> in that file, using a key <code>any1</code>. All values are
  11265. stored in a list in the file, using <code><a
  11266. href="#assoc">assoc</a></code>. During the whole operation, the file is
  11267. exclusively locked with <code><a href="#ctl">ctl</a></code>.
  11268.  
  11269. <pre><code>
  11270. : (info "a.rc") # File exists?
  11271. -> NIL # No
  11272. : (rc "a.rc" 'a 1) # Store 1 for 'a'
  11273. -> 1
  11274. : (rc "a.rc" 'b (2 3 4)) # Store (2 3 4) for 'b'
  11275. -> (2 3 4)
  11276. : (rc "a.rc" 'c 'b) # Store 'b' for 'c'
  11277. -> b
  11278. : (info "a.rc") # Check file
  11279. -> (28 733124 . 61673)
  11280. : (in "a.rc" (echo)) # Display it
  11281. ((c . b) (b 2 3 4) (a . 1))
  11282. -> T
  11283. : (rc "a.rc" 'c) # Fetch value for 'c'
  11284. -> b
  11285. : (rc "a.rc" @) # Fetch value for 'b'
  11286. -> (2 3 4)
  11287. </code></pre>
  11288.  
  11289. <dt><a name="rd"><code>(rd ['sym]) -> any</code></a>
  11290. <dt><code>(rd 'cnt) -> num | NIL</code>
  11291. <dd>Binary read: Reads one item from the current input channel in encoded binary
  11292. format. When called with a <code>cnt</code> argument (second form), that number
  11293. of raw bytes (in big endian format if <code>cnt</code> is positive, otherwise
  11294. little endian) is read as a single number. Upon end of file, if the
  11295. <code>sym</code> argument is given, it is returned, otherwise <code>NIL</code>.
  11296. See also <code><a href="#pr">pr</a></code>, <code><a
  11297. href="#tell">tell</a></code>, <code><a
  11298. href="#hear">hear</a></code> and <code><a
  11299. href="#wr">wr</a></code>.
  11300.  
  11301. <pre><code>
  11302. : (out "x" (pr 'abc "EOF" 123 "def"))
  11303. -> "def"
  11304. : (in "x" (rd))
  11305. -> abc
  11306. : (in "x"
  11307. (make
  11308. (use X
  11309. (until (== "EOF" (setq X (rd "EOF"))) # '==' detects end of file
  11310. (link X) ) ) ) )
  11311. -> (abc "EOF" 123 "def") # as opposed to reading a symbol "EOF"
  11312.  
  11313. : (in "/dev/urandom" (rd 20))
  11314. -> 396737673456823753584720194864200246115286686486
  11315. </code></pre>
  11316.  
  11317. <dt><a name="read"><code>(read ['sym1 ['sym2]]) -> any</code></a>
  11318. <dd>Reads one item from the current input channel. <code>NIL</code> is returned
  11319. upon end of file. When called without arguments, an arbitrary Lisp expression is
  11320. read. Otherwise, a token (a number, an internal symbol, a transient symbol (for
  11321. punctuation), or a list of symbols (for a string)) is read. In that case,
  11322. <code>sym1</code> specifies which set of characters to accept for continuous
  11323. symbol names (in addition to the standard alphanumerical characters), and
  11324. <code>sym2</code> an optional comment character. See also <code><a
  11325. href="#any">any</a></code>, <code><a
  11326. href="#str">str</a></code>, <code><a
  11327. href="#line">line</a></code>, <code><a
  11328. href="#skip">skip</a></code> and <code><a
  11329. href="#eof">eof</a></code>.
  11330.  
  11331. <pre><code>
  11332. : (list (read) (read) (read)) # Read three things from console
  11333. 123 # a number
  11334. abcd # a symbol
  11335. (def # and a list
  11336. ghi
  11337. jkl
  11338. )
  11339. -> (123 abcd (def ghi jkl))
  11340. : (make (while (read "_" "#") (link @)))
  11341. abc = def_ghi("xyz"+-123) # Comment
  11342. NIL
  11343. -> (abc "=" def_ghi "(" ("x" "y" "z") "+" "-" 123 ")")
  11344. </code></pre>
  11345.  
  11346. <dt><a name="recur"><code>(recur fun) -> any</code></a>
  11347. <dt><a name="recurse"><code>(recurse ..) -> any</code></a>
  11348. <dd>Implements anonymous recursion, by defining the function
  11349. <code>recurse</code> on the fly. During the execution of <code>fun</code>, the
  11350. symbol <code>recurse</code> is bound to the function definition
  11351. <code>fun</code>. See also <code><a href="#let">let</a></code> and
  11352. <code><a href="#lambda">lambda</a></code>.
  11353.  
  11354. <pre><code>
  11355. : (de fibonacci (N)
  11356. (when (lt0 N)
  11357. (quit "Bad fibonacci" N) )
  11358. (recur (N)
  11359. (if (>= 2 N)
  11360. 1
  11361. (+
  11362. (recurse (dec N))
  11363. (recurse (- N 2)) ) ) ) )
  11364. -> fibonacci
  11365. : (fibonacci 22)
  11366. -> 17711
  11367. : (fibonacci -7)
  11368. -7 -- Bad fibonacci
  11369. </code></pre>
  11370.  
  11371. <dt><a name="redef"><code>(redef sym . fun) -> sym</code></a>
  11372. <dd>Redefines <code>sym</code> in terms of itself. The current definition is
  11373. saved in a new symbol, which is substituted for each occurrence of
  11374. <code>sym</code> in <code>fun</code>, and which is also returned. See also
  11375. <code><a href="#de">de</a></code>, <code><a
  11376. href="#undef">undef</a></code>, <code><a
  11377. href="#daemon">daemon</a></code> and <code><a
  11378. href="#patch">patch</a></code>.
  11379.  
  11380. <pre><code>
  11381. : (de hello () (prinl "Hello world!"))
  11382. -> hello
  11383. : (pp 'hello)
  11384. (de hello NIL
  11385. (prinl "Hello world!") )
  11386. -> hello
  11387.  
  11388. : (redef hello (A B)
  11389. (println 'Before A)
  11390. (prog1 (hello) (println 'After B)) )
  11391. -> "hello"
  11392. : (pp 'hello)
  11393. (de hello (A B)
  11394. (println 'Before A)
  11395. (prog1 ("hello") (println 'After B)) )
  11396. -> hello
  11397. : (hello 1 2)
  11398. Before 1
  11399. Hello world!
  11400. After 2
  11401. -> "Hello world!"
  11402.  
  11403. : (redef * @
  11404. (msg (rest))
  11405. (pass *) )
  11406. -> "*"
  11407. : (* 1 2 3)
  11408. (1 2 3)
  11409. -> 6
  11410.  
  11411. : (redef + @
  11412. (pass (ifn (num? (next)) pack +) (arg)) )
  11413. -> "+"
  11414. : (+ 1 2 3)
  11415. -> 6
  11416. : (+ "a" 'b '(c d e))
  11417. -> "abcde"
  11418.  
  11419. </code></pre>
  11420.  
  11421. <dt><a name="rel"><code>(rel sym lst [any ..]) -> any</code></a>
  11422. <dd>Defines a relation for <code>sym</code> in the current class <code><a
  11423. href="#*Class">*Class</a></code>, using <code>lst</code> as the list of
  11424. classes for that relation, and possibly additional arguments <code>any</code>
  11425. for its initialization. See also <a href="#dbase">Database</a>, <code><a
  11426. href="#class">class</a></code>, <code><a
  11427. href="#extend">extend</a></code>, <code><a
  11428. href="#dm">dm</a></code> and <code><a
  11429. href="#var">var</a></code>.
  11430.  
  11431. <pre><code>
  11432. (class +Person +Entity)
  11433. (rel nm (+List +Ref +String)) # Names
  11434. (rel tel (+Ref +String)) # Telephone
  11435. (rel adr (+Joint) prs (+Address)) # Address
  11436.  
  11437. (class +Address +Entity)
  11438. (rel cit (+Need +Hook +Link) (+City)) # City
  11439. (rel str (+List +Ref +String) cit) # Street
  11440. (rel prs (+List +Joint) adr (+Person)) # Inhabitants
  11441.  
  11442. (class +City +Entity)
  11443. (rel nm (+List +Ref +String)) # Zip / Names
  11444. </code></pre>
  11445.  
  11446. <dt><a name="release"><code>(release 'sym) -> NIL</code></a>
  11447. <dd>Releases the mutex represented by the file 'sym'. This is the reverse
  11448. operation of <code><a href="#acquire">acquire</a></code>.
  11449.  
  11450. <pre><code>
  11451. : (release "sema1")
  11452. -> NIL
  11453. </code></pre>
  11454.  
  11455. <dt><a name="remote/2"><code>remote/2</code></a>
  11456. <dd><a href="#pilog">Pilog</a> predicate for remote database queries. It
  11457. takes a list and an arbitrary number of clauses. The list should contain a Pilog
  11458. variable for the result in the CAR, and a list of resources in the CDR. The
  11459. clauses will be evaluated on remote machines according to these resources. Each
  11460. resource must be a cons pair of two functions, an "out" function in the CAR, and
  11461. an "in" function in the CDR. See also <code><a
  11462. href="#*Ext">*Ext</a></code>, <code><a
  11463. href="#select/3">select/3</a></code> and <code><a
  11464. href="#db/3">db/3</a></code>.
  11465.  
  11466. <pre><code>
  11467. (setq *Ext # Set up external offsets
  11468. (mapcar
  11469. '((@Host @Ext)
  11470. (cons @Ext
  11471. (curry (@Host @Ext (Sock)) (Obj)
  11472. (when (or Sock (setq Sock (connect @Host 4040)))
  11473. (ext @Ext
  11474. (out Sock (pr (cons 'qsym Obj)))
  11475. (prog1
  11476. (in Sock (rd))
  11477. (unless @
  11478. (close Sock)
  11479. (off Sock) ) ) ) ) ) ) )
  11480. '("localhost")
  11481. '(20) ) )
  11482.  
  11483. (de rsrc () # Simple resource handler, ignoring errors or EOFs
  11484. (extract
  11485. '((@Ext Host)
  11486. (let? @Sock (connect Host 4040)
  11487. (cons
  11488. (curry (@Ext @Sock) (X) # out
  11489. (ext @Ext (out @Sock (pr X))) )
  11490. (curry (@Ext @Sock) () # in
  11491. (ext @Ext (in @Sock (rd))) ) ) ) )
  11492. '(20)
  11493. '("localhost") ) )
  11494.  
  11495. : (?
  11496. @Nr (1 . 3)
  11497. @Sup 2
  11498. @Rsrc (rsrc)
  11499. (remote (@Item . @Rsrc)
  11500. (db nr +Item @Nr @Item)
  11501. (val @Sup @Item sup nr) )
  11502. (show @Item) )
  11503. {L-2} (+Item)
  11504. pr 1250
  11505. inv 100
  11506. sup {K-2}
  11507. nm Spare Part
  11508. nr 2
  11509. @Nr=(1 . 3) @Sup=2 @Rsrc=((((X) (ext 20 (out 16 (pr X)))) NIL (ext 20 (in 16 (rd))))) @Item={L-2}
  11510. -> NIL
  11511. </code></pre>
  11512.  
  11513. <dt><a name="remove"><code>(remove 'cnt 'lst) -> lst</code></a>
  11514. <dd>Removes the element at position <code>cnt</code> from <code>lst</code>. This
  11515. is a non-destructive operation. See also <code><a
  11516. href="#insert">insert</a></code>, <code><a
  11517. href="#place">place</a></code>, <code><a
  11518. href="#append">append</a></code>, <code><a
  11519. href="#delete">delete</a></code> and <code><a
  11520. href="#replace">replace</a></code>.
  11521.  
  11522. <pre><code>
  11523. : (remove 3 '(a b c d e))
  11524. -> (a b d e)
  11525. : (remove 1 '(a b c d e))
  11526. -> (b c d e)
  11527. : (remove 9 '(a b c d e))
  11528. -> (a b c d e)
  11529. </code></pre>
  11530.  
  11531. <dt><a name="repeat"><code>(repeat) -> lst</code></a>
  11532. <dd>Makes the current <a href="#pilog">Pilog</a> definition "tail
  11533. recursive", by closing the previously defined rules in the definition's T
  11534. property to a circular list. See also <code><a
  11535. href="#repeat/0">repeat/0</a></code> and <code><a
  11536. href="#be">be</a></code>.
  11537.  
  11538. <pre><code>
  11539. (be a (1)) # Define three facts
  11540. (be a (2))
  11541. (be a (3))
  11542. (repeat) # Unlimited supply
  11543.  
  11544. : (? (a @N))
  11545. @N=1
  11546. @N=2
  11547. @N=3
  11548. @N=1
  11549. @N=2
  11550. @N=3. # Stop
  11551. -> NIL
  11552. </code></pre>
  11553.  
  11554. <dt><a name="repeat/0"><code>repeat/0</code></a>
  11555. <dd><a href="#pilog">Pilog</a> predicate that always succeeds, also on
  11556. backtracking. See also <code><a href="#repeat">repeat</a></code> and
  11557. <code><a href="#true/0">true/0</a></code>.
  11558.  
  11559. <pre><code>
  11560. : (be integer (@I) # Generate unlimited supply of integers
  11561. (^ @C (box 0)) # Init to zero
  11562. (repeat) # Repeat from here
  11563. (^ @I (inc (-> @C))) )
  11564. -> integer
  11565.  
  11566. : (? (integer @X))
  11567. @X=1
  11568. @X=2
  11569. @X=3
  11570. @X=4. # Stop
  11571. -> NIL
  11572. </code></pre>
  11573.  
  11574. <dt><a name="replace"><code>(replace 'lst 'any1 'any2 ..) -> lst</code></a>
  11575. <dd>Replaces in <code>lst</code> all occurrences of <code>any1</code> with
  11576. <code>any2</code>. For optional additional argument pairs, this process is
  11577. repeated. This is a non-destructive operation. See also <code><a
  11578. href="#append">append</a></code>, <code><a
  11579. href="#delete">delete</a></code>, <code><a
  11580. href="#insert">insert</a></code>, <code><a
  11581. href="#remove">remove</a></code> and <code><a
  11582. href="#place">place</a></code>.
  11583.  
  11584. <pre><code>
  11585. : (replace '(a b b a) 'a 'A)
  11586. -> (A b b A)
  11587. : (replace '(a b b a) 'b 'B)
  11588. -> (a B B a)
  11589. : (replace '(a b b a) 'a 'B 'b 'A)
  11590. -> (B A A B)
  11591. </code></pre>
  11592.  
  11593. <dt><a name="request"><code>(request 'typ 'sym ['hook] 'val ..) -> obj</code></a>
  11594. <dd>Returns a database object. If a matching object cannot be found (using
  11595. <code><a href="#db">db</a></code>), a new object of the given type is
  11596. created (using <code><a href="#new">new</a></code>). See also <code><a
  11597. href="#obj">obj</a></code>.
  11598.  
  11599. <pre><code>
  11600. : (request '(+Item) 'nr 2)
  11601. -> {3-2}
  11602. </code></pre>
  11603.  
  11604. <dt><a name="rest"><code>(rest) -> lst</code></a>
  11605. <dd>Can only be used inside functions with a variable number of arguments (with
  11606. <code>@</code>). Returns the list of all remaining arguments from the internal
  11607. list. See also <code><a href="#args">args</a></code>, <code><a
  11608. href="#next">next</a></code>, <code><a
  11609. href="#arg">arg</a></code> and <code><a
  11610. href="#pass">pass</a></code>.
  11611.  
  11612. <pre><code>
  11613. : (de foo @ (println (rest)))
  11614. -> foo
  11615. : (foo 1 2 3)
  11616. (1 2 3)
  11617. -> (1 2 3)
  11618. </code></pre>
  11619.  
  11620. <dt><a name="retract"><code>(retract) -> lst</code></a>
  11621. <dd>Removes a <a href="#pilog">Pilog</a> fact or rule. See also <code><a
  11622. href="#be">be</a></code>, <code><a
  11623. href="#clause">clause</a></code>, <code><a
  11624. href="#asserta">asserta</a></code> and <code><a
  11625. href="#assertz">assertz</a></code>.
  11626.  
  11627. <pre><code>
  11628. : (be a (1))
  11629. -> a
  11630. : (be a (2))
  11631. -> a
  11632. : (be a (3))
  11633. -> a
  11634.  
  11635. : (retract '(a (2)))
  11636. -> (((1)) ((3)))
  11637.  
  11638. : (? (a @N))
  11639. @N=1
  11640. @N=3
  11641. -> NIL
  11642. </code></pre>
  11643.  
  11644. <dt><a name="retract/1"><code>retract/1</code></a>
  11645. <dd><a href="#pilog">Pilog</a> predicate that removes a fact or rule.
  11646. See also <code><a href="#retract">retract</a></code>, <code><a
  11647. href="#asserta/1">asserta/1</a></code> and <code><a
  11648. href="#assertz/1">assertz/1</a></code>.
  11649.  
  11650. <pre><code>
  11651. : (be a (1))
  11652. -> a
  11653. : (be a (2))
  11654. -> a
  11655. : (be a (3))
  11656. -> a
  11657.  
  11658. : (? (retract (a 2)))
  11659. -> T
  11660. : (rules 'a)
  11661. 1 (be a (1))
  11662. 2 (be a (3))
  11663. -> a
  11664. </code></pre>
  11665.  
  11666. <dt><a name="reverse"><code>(reverse 'lst) -> lst</code></a>
  11667. <dd>Returns a reversed copy of <code>lst</code>. See also <code><a
  11668. href="#flip">flip</a></code>.
  11669.  
  11670. <pre><code>
  11671. : (reverse (1 2 3 4))
  11672. -> (4 3 2 1)
  11673. </code></pre>
  11674.  
  11675. <dt><a name="rewind"><code>(rewind) -> flg</code></a>
  11676. <dd>Sets the file position indicator for the current output stream to the
  11677. beginning of the file, and truncates the file length to zero. Returns
  11678. <code>T</code> when successful. See also <code><a
  11679. href="#flush">flush</a></code>.
  11680.  
  11681. <pre><code>
  11682. : (out "a" (prinl "Hello world"))
  11683. -> "Hello world"
  11684. : (in "a" (echo))
  11685. Hello world
  11686. -> T
  11687. : (info "a")
  11688. -> (12 733216 . 53888)
  11689. : (out "a" (rewind))
  11690. -> T
  11691. : (info "a")
  11692. -> (0 733216 . 53922)
  11693. </code></pre>
  11694.  
  11695. <dt><a name="rollback"><code>(rollback) -> flg</code></a>
  11696. <dd>Cancels a transaction, by discarding all modifications of external symbols.
  11697. See also <code><a href="#commit">commit</a></code>.
  11698.  
  11699. <pre><code>
  11700. : (pool "db")
  11701. -> T
  11702. # .. Modify external objects ..
  11703. : (rollback) # Rollback
  11704. -> T
  11705. </code></pre>
  11706.  
  11707. <dt><a name="root"><code>(root 'tree) -> (num . sym)</code></a>
  11708. <dd>Returns the root of a database index tree, with the number of entries in
  11709. <code>num</code>, and the base node in <code>sym</code>. See also <code><a
  11710. href="#tree">tree</a></code>.
  11711.  
  11712. <pre><code>
  11713. : (root (tree 'nr '+Item))
  11714. -> (7 . {7-1})
  11715. </code></pre>
  11716.  
  11717. <dt><a name="rot"><code>(rot 'lst ['cnt]) -> lst</code></a>
  11718. <dd>Rotate: The contents of the cells of <code>lst</code> are (destructively)
  11719. shifted right, and the value from the last cell is stored in the first cell.
  11720. Without the optional <code>cnt</code> argument, the whole list is rotated,
  11721. otherwise only the first <code>cnt</code> elements. See also <code><a
  11722. href="#flip">flip</a></code> .
  11723.  
  11724. <pre><code>
  11725. : (rot (1 2 3 4)) # Rotate all four elements
  11726. -> (4 1 2 3)
  11727. : (rot (1 2 3 4 5 6) 3) # Rotate only the first three elements
  11728. -> (3 1 2 4 5 6)
  11729. </code></pre>
  11730.  
  11731. <dt><a name="round"><code>(round 'num1 'num2) -> sym</code></a>
  11732. <dd>Formats a number <code>num1</code> with <code>num2</code> decimal places,
  11733. according to the current scale <code><a href="#*Scl">*Scl</a></code>.
  11734. <code>num2</code> defaults to 3. See also <a href="#num-io">Numbers</a>
  11735. and <code><a href="#format">format</a></code>.
  11736.  
  11737. <pre><code>
  11738. : (scl 4) # Set scale to 4
  11739. -> 4
  11740. : (round 123456) # Format with three decimal places
  11741. -> "12.346"
  11742. : (round 123456 2) # Format with two decimal places
  11743. -> "12.35"
  11744. : (format 123456 *Scl) # Format with full precision
  11745. -> "12.3456"
  11746. </code></pre>
  11747.  
  11748. <dt><a name="rules"><code>(rules 'sym ..) -> sym</code></a>
  11749. <dd>Prints all rules defined for the <code>sym</code> arguments. See also <a
  11750. href="#pilog">Pilog</a> and <code><a href="ref.html#be">be</a></code>.
  11751.  
  11752. <pre><code>
  11753. : (rules 'member 'append)
  11754. 1 (be member (@X (@X . @)))
  11755. 2 (be member (@X (@ . @Y)) (member @X @Y))
  11756. 1 (be append (NIL @X @X))
  11757. 2 (be append ((@A . @X) @Y (@A . @Z)) (append @X @Y @Z))
  11758. -> append
  11759. </code></pre>
  11760.  
  11761. <dt><a name="run"><code>(run 'any ['cnt ['lst]]) -> any</code></a>
  11762. <dd>If <code>any</code> is an atom, <code>run</code> behaves like <code><a
  11763. href="#eval">eval</a></code>. Otherwise <code>any</code> is a list,
  11764. which is evaluated in sequence. The last result is returned. If a binding
  11765. environment offset <code>cnt</code> is given, that evaluation takes place in the
  11766. corresponding environment, and an optional <code>lst</code> of excluded symbols
  11767. can be supplied. See also <code><a href="#up">up</a></code>.
  11768.  
  11769. <pre><code>
  11770. : (run '((println (+ 1 2 3)) (println 'OK)))
  11771. 6
  11772. OK
  11773. -> OK
  11774.  
  11775. : (de f Prg
  11776. (let A 12
  11777. (println (cons 'Prg Prg) (cons 'A A))
  11778. (run Prg 1) ) )
  11779. -> f
  11780. : (let (Prg 77 A 99)
  11781. (f
  11782. (println (cons 'Prg Prg) (cons 'A A)) ) )
  11783. (Prg (println (cons 'Prg Prg) (cons 'A A))) (A . 12)
  11784. (Prg . 77) (A . 99)
  11785. -> (A . 99)
  11786. </code></pre>
  11787.  
  11788. </dl>
  11789.  
  11790. <h1><a name="S">S</a></h1>
  11791.  
  11792. <dl>
  11793.  
  11794. <dt><a name="*Scl"><code>*Scl</code></a>
  11795. <dd>A global variable holding the current fixpoint input scale. See also <a
  11796. href="#num-io">Numbers</a> and <code><a
  11797. href="#scl">scl</a></code>.
  11798.  
  11799. <pre><code>
  11800. : (str "123.45") # Default value of '*Scl' is 0
  11801. -> (123)
  11802. : (setq *Scl 3)
  11803. -> 3
  11804. : (str "123.45")
  11805. -> (123450)
  11806.  
  11807. : 123.4567
  11808. -> 123457
  11809. : 12.3456
  11810. -> 12346
  11811. </code></pre>
  11812.  
  11813. <dt><a name="*Sig1"><code>*Sig1</code></a>
  11814. <dt><a name="*Sig2"><code>*Sig2</code></a>
  11815. <dd>Global variables holding (possibly empty) <code>prg</code> bodies, which
  11816. will be executed when a SIGUSR1 signal (or a SIGUSR2 signal, respectively) is
  11817. sent to the current process. See also <code><a
  11818. href="#alarm">alarm</a></code>, <code><a
  11819. href="#sigio">sigio</a></code> and <code><a
  11820. href="#*Hup">*Hup</a></code>.
  11821.  
  11822. <pre><code>
  11823. : (de *Sig1 (msg 'SIGUSR1))
  11824. -> *Sig1
  11825. </code></pre>
  11826.  
  11827. <dt><a name="*Solo"><code>*Solo</code></a>
  11828. <dd>A global variable indicating exclusive database access. Its value is
  11829. <code>0</code> initially, set to <code>T</code> (or <code>NIL</code>) during
  11830. cooperative database locks when <code><a href="#lock">lock</a></code>
  11831. is successfully called with a <code>NIL</code> (or non-<code>NIL</code>)
  11832. argument. See also <code><a href="#*Zap">*Zap</a></code>.
  11833.  
  11834. <pre><code>
  11835. : *Solo
  11836. -> 0
  11837. : (lock *DB)
  11838. -> NIL
  11839. : *Solo
  11840. -> NIL
  11841. : (rollback)
  11842. -> T
  11843. : *Solo
  11844. -> 0
  11845. : (lock)
  11846. -> NIL
  11847. : *Solo
  11848. -> T
  11849. : (rollback)
  11850. -> T
  11851. : *Solo
  11852. -> T
  11853. </code></pre>
  11854.  
  11855. <dt><a name="+Sn"><code>+Sn</code></a>
  11856. <dd>Prefix class for maintaining indexes according to a modified soundex
  11857. algorithm, for tolerant name searches, to <code><a
  11858. href="#+String">+String</a></code> relations. Typically used in
  11859. combination with the <code><a href="#+Idx">+Idx</a></code> prefix
  11860. class. See also <a href="#dbase">Database</a>.
  11861.  
  11862. <pre><code>
  11863. (rel nm (+Sn +Idx +String)) # Name
  11864. </code></pre>
  11865.  
  11866. <dt><a name="+String"><code>+String</code></a>
  11867. <dd>Class for string (transient symbol) relations, a subclass of <code><a
  11868. href="#+Symbol">+Symbol</a></code>. Accepts an optional argument for
  11869. the string length (currently not used). See also <a
  11870. href="#dbase">Database</a>.
  11871.  
  11872. <pre><code>
  11873. (rel nm (+Sn +Idx +String)) # Name, indexed by soundex and substrings
  11874. </code></pre>
  11875.  
  11876. <dt><a name="+Swap"><code>+Swap</code></a>
  11877. <dd>Prefix class for <code><a href="#+relation">+relation</a></code>s
  11878. where the data are to be stored in the value of a separate external symbol
  11879. instead of the relation's object. Typically used for data which are relatively
  11880. large and/or rarely accessed. Doesn't work with bidirectional relations
  11881. (<code><a href="#+Joint">+Joint</a></code> or <code><a
  11882. href="#+index">+index</a></code>). See also <a
  11883. href="#dbase">Database</a>.
  11884.  
  11885. <pre><code>
  11886. (rel pw (+Swap +String)) # Password
  11887. (rel nr (+Swap +List +Number)) # List of bignums
  11888. </code></pre>
  11889.  
  11890. <dt><a name="+Symbol"><code>+Symbol</code></a>
  11891. <dd>Class for symbolic relations, a subclass of <code><a
  11892. href="#+relation">+relation</a></code>. Objects of that class typically
  11893. maintain internal symbols, as opposed to the more often-used <code><a
  11894. href="#+String">+String</a></code> for transient symbols. See also <a
  11895. href="#dbase">Database</a>.
  11896.  
  11897. <pre><code>
  11898. (rel perm (+List +Symbol)) # Permission list
  11899. </code></pre>
  11900.  
  11901. <dt><a name="same/3"><code>same/3</code></a>
  11902. <dd><a href="#pilog">Pilog</a> predicate that succeeds if the first
  11903. argument matches the result of applying the <code><a
  11904. href="#get">get</a></code> algorithm to the following arguments.
  11905. Typically used as filter predicate in <code><a
  11906. href="#select/3">select/3</a></code> database queries. See also
  11907. <code><a href="#isa/2">isa/2</a></code>, <code><a
  11908. href="#bool/3">bool/3</a></code>, <code><a
  11909. href="#range/3">range/3</a></code>, <code><a
  11910. href="#head/3">head/3</a></code>, <code><a
  11911. href="#fold/3">fold/3</a></code>, <code><a
  11912. href="#part/3">part/3</a></code> and <code><a
  11913. href="#tolr/3">tolr/3</a></code>.
  11914.  
  11915. <pre><code>
  11916. : (?
  11917. @Nr 2
  11918. @Nm "Spare"
  11919. (select (@Item)
  11920. ((nr +Item @Nr) (nm +Item @Nm))
  11921. (same @Nr @Item nr)
  11922. (head @Nm @Item nm) ) )
  11923. @Nr=2 @Nm="Spare" @Item={3-2}
  11924. </code></pre>
  11925.  
  11926. <dt><a name="scan"><code>(scan 'tree ['fun] ['any1] ['any2] ['flg])</code></a>
  11927. <dd>Scans through a database tree by applying <code>fun</code> to all key-value
  11928. pairs. <code>fun</code> should be a function accepting two arguments for key and
  11929. value. It defaults to <code><a href="#println">println</a></code>.
  11930. <code>any1</code> and <code>any2</code> may specify a range of keys. If
  11931. <code>any2</code> is greater than <code>any1</code>, the traversal will be in
  11932. opposite direction. Note that the keys need not to be atomic, depending on the
  11933. application's index structure. If <code>flg</code> is non-<code>NIL</code>,
  11934. partial keys are skipped. See also <code><a
  11935. href="#tree">tree</a></code>, <code><a
  11936. href="#iter">iter</a></code>, <code><a
  11937. href="#init">init</a></code> and <code><a
  11938. href="#step">step</a></code>.
  11939.  
  11940. <pre><code>
  11941. : (scan (tree 'nm '+Item))
  11942. ("ASLRSNSTRSTN" {3-3} . T) {3-3}
  11943. ("Additive" {3-4}) {3-4}
  11944. ("Appliance" {3-6}) {3-6}
  11945. ("Auxiliary Construction" . {3-3}) {3-3}
  11946. ("Construction" {3-3}) {3-3}
  11947. ("ENNSNNTTTF" {3-4} . T) {3-4}
  11948. ("Enhancement Additive" . {3-4}) {3-4}
  11949. ("Fittings" {3-5}) {3-5}
  11950. ("GTSTFLNS" {3-6} . T) {3-6}
  11951. ("Gadget Appliance" . {3-6}) {3-6}
  11952. ...
  11953.  
  11954. : (scan (tree 'nm '+Item) println NIL T T) # 'flg' is non-NIL
  11955. ("Auxiliary Construction" . {3-3}) {3-3}
  11956. ("Enhancement Additive" . {3-4}) {3-4}
  11957. ("Gadget Appliance" . {3-6}) {3-6}
  11958. ("Main Part" . {3-1}) {3-1}
  11959. ("Metal Fittings" . {3-5}) {3-5}
  11960. ("Spare Part" . {3-2}) {3-2}
  11961. ("Testartikel" . {3-8}) {3-8}
  11962. -> {7-6}
  11963. </code></pre>
  11964.  
  11965. <dt><a name="scl"><code>(scl 'num [. prg]) -> num</code></a>
  11966. <dd>If <code>prg</code> is given, it binds <code><a
  11967. href="#*Scl">*Scl</a></code> dynamically to <code>num</code> during the
  11968. execution of <code>prg</code>. Otherwise, it sets <code><a
  11969. href="#*Scl">*Scl</a></code> globally to <code>num</code>. See also <a
  11970. href="#num-io">Numbers</a>.
  11971.  
  11972. <pre><code>
  11973. : (scl 0)
  11974. -> 0
  11975. : (str "123.45")
  11976. -> (123)
  11977. : (scl 1)
  11978. -> 1
  11979. : (read)
  11980. 123.45
  11981. -> 1235
  11982. : (scl 3)
  11983. -> 3
  11984. : (str "123.45")
  11985. -> (123450)
  11986. : (scl 1 (str "123.45"))
  11987. -> (1235)
  11988. : *Scl
  11989. -> 3
  11990. </code></pre>
  11991.  
  11992. <dt><a name="script"><code>(script 'any ..) -> any</code></a>
  11993. <dd>The first <code>any</code> argument is <code><a
  11994. href="#load">load</a></code>ed, with the remaining arguments <code><a
  11995. href="#pass">pass</a></code>ed as variable arguments. They can be
  11996. accessed with <code><a href="#next">next</a></code>, <code><a
  11997. href="#arg">arg</a></code>, <code><a
  11998. href="#args">args</a></code> and <code><a
  11999. href="#rest">rest</a></code>. With that, the syntax in the script is
  12000. the same as that in the body of a function with variable arguments (see <a
  12001. href="#lambda">lambda expression</a>s, "when the CAR is the symbol @").
  12002.  
  12003. <pre><code>
  12004. $ cat x
  12005. (* (next) (next))
  12006.  
  12007. $ pil +
  12008. : (script "x" 3 4)
  12009. -> 12
  12010. </code></pre>
  12011.  
  12012. <dt><a name="sect"><code>(sect 'lst 'lst) -> lst</code></a>
  12013. <dd>Returns the intersection of the <code>lst</code> arguments. See also
  12014. <code><a href="#diff">diff</a></code>.
  12015.  
  12016. <pre><code>
  12017. : (sect (1 2 3 4) (3 4 5 6))
  12018. -> (3 4)
  12019. : (sect (1 2 3) (4 5 6))
  12020. -> NIL
  12021. </code></pre>
  12022.  
  12023. <dt><a name="seed"><code>(seed 'any) -> cnt</code></a>
  12024. <dd>Initializes the random generator's seed, and returns a pseudo random number
  12025. in the range -2147483648 .. +2147483647. See also <code><a
  12026. href="#rand">rand</a></code> and <code><a
  12027. href="#hash">hash</a></code>.
  12028.  
  12029. <pre><code>
  12030. : (seed "init string")
  12031. -> 2015582081
  12032. : (rand)
  12033. -> -706917003
  12034. : (rand)
  12035. -> 1224196082
  12036.  
  12037. : (seed (time))
  12038. -> 128285383
  12039. </code></pre>
  12040.  
  12041. <dt><a name="seek"><code>(seek 'fun 'lst ..) -> lst</code></a>
  12042. <dd>Applies <code>fun</code> to <code>lst</code> and all successive CDRs, until
  12043. non-<code>NIL</code> is returned. Returns the tail of <code>lst</code> starting
  12044. with that element (and stores the non-<code>NIL</code> value in the global
  12045. variable <code><a href="#@@">@@</a></code>), or <code>NIL</code> if
  12046. <code>fun</code> did not return non-<code>NIL</code> for any element of
  12047. <code>lst</code>. When additional <code>lst</code> arguments are given, they are
  12048. passed to <code>fun</code> in the same way. See also <code><a
  12049. href="#find">find</a></code>, <code><a
  12050. href="#pick">pick</a></code>.
  12051.  
  12052. <pre><code>
  12053. : (seek '((X) (> (car X) 9)) (1 5 8 12 19 22))
  12054. -> (12 19 22)
  12055. </code></pre>
  12056.  
  12057. <dt><a name="select"><code>(select [var ..] cls [hook|T] [var val ..]) -> obj | NIL</code></a>
  12058. <dd>(Debug mode only) Interactive database function, loosely modelled after the
  12059. SQL '<code>SELECT</code>' command. A (limited) front-end to the Pilog <code><a
  12060. href="#select/3">select/3</a></code> predicate. When called with only a
  12061. <code>cls</code> argument, <code>select</code> steps through all objects of that
  12062. class, and <code><a href="#show">show</a></code>s their complete
  12063. contents (this is analog to 'SELECT * from CLS'). If <code>cls</code> is
  12064. followed by attribute/value specifications, the search is limited to these
  12065. values (this is analog to 'SELECT * from CLS where VAR = VAL'). If between the
  12066. <code>select</code> function and <code>cls</code> one or several attribute names
  12067. are supplied, only these attribute (instead of the full <code>show</code>) are
  12068. printed. These attribute specifications may also be lists, then the <code><a
  12069. href="#get">get</a></code> algorithm will be used to retrieve related
  12070. data. See also <code><a href="#update">update</a></code>, <a
  12071. href="#dbase">Database</a> and <a href="ref.html#pilog">Pilog</a>.
  12072.  
  12073. <pre><code>
  12074. : (select +Item) # Show all items
  12075. {3-1} (+Item)
  12076. nr 1
  12077. pr 29900
  12078. inv 100
  12079. sup {2-1}
  12080. nm "Main Part"
  12081.  
  12082. {3-2} (+Item)
  12083. nr 2
  12084. pr 1250
  12085. inv 100
  12086. sup {2-2}
  12087. nm "Spare Part"
  12088. . # Stop
  12089. -> {3-2}
  12090.  
  12091. : (select +Item nr 3) # Show only item 3
  12092. {3-3} (+Item)
  12093. nr 3
  12094. sup {2-1}
  12095. pr 15700
  12096. nm "Auxiliary Construction"
  12097. inv 100
  12098. . # Stop
  12099. -> {3-3}
  12100.  
  12101. # Show selected attributes for items 3 through 3
  12102. : (select nr nm pr (sup nm) +Item nr (3 . 5))
  12103. 3 "Auxiliary Construction" 157.00 "Active Parts Inc." {3-3}
  12104. 4 "Enhancement Additive" 9.99 "Seven Oaks Ltd." {3-4}
  12105. 5 "Metal Fittings" 79.80 "Active Parts Inc." {3-5}
  12106. -> NIL
  12107. </code></pre>
  12108.  
  12109. <dt><a name="select/3"><code>select/3</code></a>
  12110. <dd><a href="#pilog">Pilog</a> database predicate that allows combined
  12111. searches over <code><a href="#+index">+index</a></code> and other
  12112. relations. It takes a list of Pilog variables, a list of generator clauses, and
  12113. an arbitrary number of filter clauses. The functionality is described in detail
  12114. in <a href="select.html">The 'select' Predicate</a>. See also <code><a
  12115. href="#db/3">db/3</a></code>, <code><a
  12116. href="#isa/2">isa/2</a></code>, <code><a
  12117. href="#same/3">same/3</a></code>, <code><a
  12118. href="#bool/3">bool/3</a></code>, <code><a
  12119. href="#range/3">range/3</a></code>, <code><a
  12120. href="#head/3">head/3</a></code>, <code><a
  12121. href="#fold/3">fold/3</a></code>, <code><a
  12122. href="#part/3">part/3</a></code>, <code><a
  12123. href="#tolr/3">tolr/3</a></code> and <code><a
  12124. href="#remote/2">remote/2</a></code>.
  12125.  
  12126. <pre><code>
  12127. : (?
  12128. @Nr (2 . 5) # Select all items with numbers between 2 and 5
  12129. @Sup "Active" # and suppliers matching "Active"
  12130. (select (@Item) # Bind results to '@Item'
  12131. ((nr +Item @Nr) (nm +CuSu @Sup (sup +Item))) # Generator clauses
  12132. (range @Nr @Item nr) # Filter clauses
  12133. (part @Sup @Item sup nm) ) )
  12134. @Nr=(2 . 5) @Sup="Active" @Item={3-3}
  12135. @Nr=(2 . 5) @Sup="Active" @Item={3-5}
  12136. -> NIL
  12137. </code></pre>
  12138.  
  12139. <dt><a name="send"><code>(send 'msg 'obj ['any ..]) -> any</code></a>
  12140. <dd>Sends the message <code>msg</code> to the object <code>obj</code>,
  12141. optionally with arguments <code>any</code>. If the message cannot be located in
  12142. <code>obj</code>, its classes and superclasses, an error <code>"Bad
  12143. message"</code> is issued. See also <a href="#oop">OO Concepts</a>,
  12144. <code><a href="#try">try</a></code>, <code><a
  12145. href="#method">method</a></code>, <code><a
  12146. href="#meth">meth</a></code>, <code><a
  12147. href="#super">super</a></code> and <code><a
  12148. href="#extra">extra</a></code>.
  12149.  
  12150. <pre><code>
  12151. : (send 'stop> Dlg) # Equivalent to (stop> Dlg)
  12152. -> NIL
  12153. </code></pre>
  12154.  
  12155. <dt><a name="seq"><code>(seq 'cnt|sym1) -> sym | NIL</code></a>
  12156. <dd>Sequential single step: Returns the <i>first</i> external symbol in the
  12157. <code>cnt</code>'th database file, or the <i>next</i> external symbol following
  12158. <code>sym1</code> in the database, or <code>NIL</code> when the end of the
  12159. database is reached. See also <code><a href="#free">free</a></code>.
  12160.  
  12161. <pre><code>
  12162. : (pool "db")
  12163. -> T
  12164. : (seq *DB)
  12165. -> {2}
  12166. : (seq @)
  12167. -> {3}
  12168. </code></pre>
  12169.  
  12170. <dt><a name="set"><code>(set 'var 'any ..) -> any</code></a>
  12171. <dd>Stores new values <code>any</code> in the <code>var</code> arguments. See
  12172. also <code><a href="#setq">setq</a></code>, <code><a
  12173. href="#val">val</a></code>, <code><a
  12174. href="#con">con</a></code> and <code><a
  12175. href="#def">def</a></code>.
  12176.  
  12177. <pre><code>
  12178. : (set 'L '(a b c) (cdr L) '999)
  12179. -> 999
  12180. : L
  12181. -> (a 999 c)
  12182. </code></pre>
  12183.  
  12184. <dt><a name="set!"><code>(set! 'obj 'any) -> any</code></a>
  12185. <dd><a href="#trans">Transaction</a> wrapper function for <code><a
  12186. href="#set">set</a></code>. Note that for setting the value of entities
  12187. typically the <code><a href="#entityMesssages">set!></a></code> message
  12188. is used. See also <code><a href="#new!">new!</a></code>, <code><a
  12189. href="#put!">put!</a></code> and <code><a
  12190. href="#inc!">inc!</a></code>.
  12191.  
  12192. <pre><code>
  12193. (set! Obj (* Count Size)) # Setting a non-entity object to a numeric value
  12194. </code></pre>
  12195.  
  12196. <dt><a name="setq"><code>(setq var 'any ..) -> any</code></a>
  12197. <dd>Stores new values <code>any</code> in the <code>var</code> arguments. See
  12198. also <code><a href="#set">set</a></code>, <code><a
  12199. href="#val">val</a></code> and <code><a
  12200. href="#def">def</a></code>.
  12201.  
  12202. <pre><code>
  12203. : (setq A 123 B (list A A)) # Set 'A' to 123, then 'B' to (123 123)
  12204. -> (123 123)
  12205. </code></pre>
  12206.  
  12207. <dt><a name="show"><code>(show 'any ['sym|cnt ..]) -> any</code></a>
  12208. <dd>Shows the name, value and property list of a symbol found by applying the
  12209. <code><a href="#get">get</a></code> algorithm to <code>any</code> and
  12210. the following arguments. See also <code><a href="#edit">edit</a></code>
  12211. and <code><a href="#view">view</a></code>.
  12212.  
  12213. <pre><code>
  12214. : (setq A 123456)
  12215. -> 123456
  12216. : (put 'A 'x 1)
  12217. -> 1
  12218. : (put 'A 'lst (9 8 7))
  12219. -> (9 8 7)
  12220. : (put 'A 'flg T)
  12221. -> T
  12222.  
  12223. : (show 'A)
  12224. A 123456
  12225. flg
  12226. lst (9 8 7)
  12227. x 1
  12228. -> A
  12229.  
  12230. : (show 'A 'lst 2)
  12231. -> 8
  12232. </code></pre>
  12233.  
  12234. <dt><a name="show/1"><code>show/1</code></a>
  12235. <dd><a href="#pilog">Pilog</a> predicate that always succeeds, and shows
  12236. the name, value and property list of the argument symbol. See also <code><a
  12237. href="#show">show</a></code>.
  12238.  
  12239. <pre><code>
  12240. : (? (db nr +Item 2 @Item) (show @Item))
  12241. {3-2} (+Item)
  12242. nm "Spare Part"
  12243. nr 2
  12244. pr 1250
  12245. inv 100
  12246. sup {2-2}
  12247. @Item={3-2}
  12248. -> NIL
  12249. </code></pre>
  12250.  
  12251. <dt><a name="sigio"><code>(sigio 'cnt . prg) -> cnt</code></a>
  12252. <dd>Sets a signal handler <code>prg</code> for SIGIO on the file descriptor
  12253. <code>cnt</code>. Returns the file descriptor. See also <code><a
  12254. href="#alarm">alarm</a></code>, <code><a
  12255. href="#*Hup">*Hup</a></code> and <code><a
  12256. href="#*Sig1">*Sig[12]</a></code>.
  12257.  
  12258. <pre><code>
  12259. # First session
  12260. : (sigio (setq *SigSock (port T 4444)) # Register signal handler at UDP port
  12261. (while (udp *SigSock) # Queue all received data
  12262. (fifo '*SigQueue @) ) )
  12263. -> 3
  12264.  
  12265. # Second session
  12266. : (for I 7 (udp "localhost" 4444 I)) # Send numbers to first session
  12267.  
  12268. # First session
  12269. : (fifo '*SigQueue)
  12270. -> 1
  12271. : (fifo '*SigQueue)
  12272. -> 2
  12273. </code></pre>
  12274.  
  12275. <dt><a name="size"><code>(size 'any) -> cnt</code></a>
  12276. <dd>Returns the "size" of <code>any</code>. For numbers this is the number of
  12277. bytes needed for the value, for external symbols it is the number of bytes it
  12278. would occupy in the database, for other symbols it is the number of bytes
  12279. occupied by the UTF-8 representation of the name, and for lists it is the total
  12280. number of cells in this list and all its sublists. See also <code><a
  12281. href="#length">length</a></code> and <code><a
  12282. href="#bytes">bytes</a></code>.
  12283.  
  12284. <pre><code>
  12285. : (size "abc")
  12286. -> 3
  12287. : (size "äbc")
  12288. -> 4
  12289. : (size 127) # One byte
  12290. -> 1
  12291. : (size 128) # Two bytes (eight bits plus sign bit!)
  12292. -> 2
  12293. : (size (1 (2) 3))
  12294. -> 4
  12295. : (size (1 2 3 .))
  12296. -> 3
  12297. </code></pre>
  12298.  
  12299. <dt><a name="skip"><code>(skip ['any]) -> sym</code></a>
  12300. <dd>Skips all whitespace (and comments if <code>any</code> is given) in the
  12301. input stream. Returns the next available character, or <code>NIL</code> upon end
  12302. of file. See also <code><a href="#peek">peek</a></code> and <code><a
  12303. href="#eof">eof</a></code>.
  12304.  
  12305. <pre><code>
  12306. $ cat a
  12307. # Comment
  12308. abcd
  12309. $ pil +
  12310. : (in "a" (skip "#"))
  12311. -> "a"
  12312. </code></pre>
  12313.  
  12314. <dt><a name="solve"><code>(solve 'lst [. prg]) -> lst</code></a>
  12315. <dd>Evaluates a <a href="#pilog">Pilog</a> query and, returns the list
  12316. of result sets. If <code>prg</code> is given, it is executed for each result
  12317. set, with all Pilog variables bound to their matching values, and returns a list
  12318. of the results. See also <code><a href="#pilog">pilog</a></code>,
  12319. <code><a href="#?">?</a></code>, <code><a
  12320. href="#goal">goal</a></code> and <code><a
  12321. href="#prove">prove</a></code>.
  12322.  
  12323. <pre><code>
  12324. : (solve '((append @X @Y (a b c))))
  12325. -> (((@X) (@Y a b c)) ((@X a) (@Y b c)) ((@X a b) (@Y c)) ((@X a b c) (@Y)))
  12326.  
  12327. : (solve '((append @X @Y (a b c))) @X)
  12328. -> (NIL (a) (a b) (a b c))
  12329. </code></pre>
  12330.  
  12331. <dt><a name="sort"><code>(sort 'lst ['fun]) -> lst</code></a>
  12332. <dd>Sorts <code>lst</code> by destructively exchanging its elements. If
  12333. <code>fun</code> is given, it is used as a "less than" predicate for
  12334. comparisons. Typically, <code>sort</code> is used in combination with <a
  12335. href="#by">by</a>, giving shorter and often more efficient solutions
  12336. than with the predicate function. See also <a href="#cmp">Comparing</a>,
  12337. <code><a href="#group">group</a></code>, <code><a
  12338. href="#maxi">maxi</a></code>, <code><a
  12339. href="#mini">mini</a></code> and <code><a
  12340. href="#uniq">uniq</a></code>.
  12341.  
  12342. <pre><code>
  12343. : (sort '(a 3 1 (1 2 3) d b 4 T NIL (a b c) (x y z) c 2))
  12344. -> (NIL 1 2 3 4 a b c d (1 2 3) (a b c) (x y z) T)
  12345. : (sort '(a 3 1 (1 2 3) d b 4 T NIL (a b c) (x y z) c 2) >)
  12346. -> (T (x y z) (a b c) (1 2 3) d c b a 4 3 2 1 NIL)
  12347. : (by cadr sort '((1 4 3) (5 1 3) (1 2 4) (3 8 5) (6 4 5)))
  12348. -> ((5 1 3) (1 2 4) (1 4 3) (6 4 5) (3 8 5))
  12349. </code></pre>
  12350.  
  12351. <dt><a name="space"><code>(space ['cnt]) -> cnt</code></a>
  12352. <dd>Prints <code>cnt</code> spaces, or a single space when <code>cnt</code> is
  12353. not given. See also <code><a href="#beep">beep</a></code>, <code><a
  12354. href="#prin">prin</a></code> and <code><a
  12355. href="#char">char</a></code>.
  12356.  
  12357. <pre><code>
  12358. : (space)
  12359. -> 1
  12360. : (space 1)
  12361. -> 1
  12362. : (space 2)
  12363. -> 2
  12364. </code></pre>
  12365.  
  12366. <dt><a name="sp?"><code>(sp? 'any) -> flg</code></a>
  12367. <dd>Returns <code>T</code> when the argument <code>any</code> is
  12368. <code>NIL</code>, or if it is a string (symbol) that consists only of whitespace
  12369. characters.
  12370.  
  12371. <pre><code>
  12372. : (sp? " ")
  12373. -> T
  12374. : (sp? "ABC")
  12375. -> NIL
  12376. : (sp? 123)
  12377. -> NIL
  12378. </code></pre>
  12379.  
  12380. <dt><a name="split"><code>(split 'lst 'any ..) -> lst</code></a>
  12381. <dd>Splits <code>lst</code> at all places containing an element <code>any</code>
  12382. and returns the resulting list of sublists. See also <code><a
  12383. href="#stem">stem</a></code>.
  12384.  
  12385. <pre><code>
  12386. : (split (1 a 2 b 3 c 4 d 5 e 6) 'e 3 'a)
  12387. -> ((1) (2 b) (c 4 d 5) (6))
  12388. : (mapcar pack (split (chop "The quick brown fox") " "))
  12389. -> ("The" "quick" "brown" "fox")
  12390. </code></pre>
  12391.  
  12392. <dt><a name="sqrt"><code>(sqrt 'num ['flg|num]) -> num</code></a>
  12393. <dd>Returns the square root of the <code>num</code> argument. If
  12394. <code>flg</code> is given and non-<code>NIL</code>, the result will be rounded.
  12395. If in addition to that <code>flg</code> is a number, the first argument will be
  12396. multiplied with it before doing the square root calculation. See also <code><a
  12397. href="#*/">*/</a></code>.
  12398.  
  12399. <pre><code>
  12400. : (sqrt 64)
  12401. -> 8
  12402. : (sqrt 1000)
  12403. -> 31
  12404. : (sqrt 1000 T)
  12405. -> 32
  12406. : (sqrt 10000000000000000000000000000000000000000)
  12407. -> 100000000000000000000
  12408.  
  12409. : (scl 6)
  12410. -> 6
  12411. : (sqrt 2.0 1.0)
  12412. -> 1414214
  12413. </code></pre>
  12414.  
  12415. <dt><a name="stack"><code>(stack ['cnt]) -> cnt | (.. sym . cnt)</code></a>
  12416. <dd>(64-bit version only) Maintains the stack segment size for <a
  12417. href="#coroutines">coroutines</a> (the main stack segment is limited -
  12418. while at least one coroutine is running - to four times that size). If called
  12419. without a <code>cnt</code> argument, or if already one or more coroutines are
  12420. running, the current size in kilobytes is returned. Otherwise, the stack segment
  12421. size is set to the new value (default 64 kB). If there are running coroutines,
  12422. their tags will be <code><a href="#cons">cons</a></code>ed in front of
  12423. the size. See also <code><a href="#heap">heap</a></code>.
  12424.  
  12425. <pre><code>
  12426. $ ulimit -s unlimited && pil + # Guarantee stack space
  12427. : (stack) # Current size
  12428. -> 64 # 64 kB
  12429. : (stack 200) # Set to 200 kB
  12430. -> 200
  12431. : (co 'inc (let N 0 (loop (yield (inc 'N))))) # Create two coroutines
  12432. -> 1
  12433. : (co 'dec (let N 0 (loop (yield (dec 'N)))))
  12434. -> -1
  12435. : (stack)
  12436. -> (dec inc . 200)
  12437. </code></pre>
  12438.  
  12439. <dt><a name="stamp"><code>(stamp ['dat 'tim]|['T]) -> sym</code></a>
  12440. <dd>Returns a date-time string in the form "YYYY-MM-DD HH:MM:SS". If
  12441. <code>dat</code> and <code>tim</code> is missing, the current date and time is
  12442. used. If <code>T</code> is passed, the current Coordinated Universal Time (UTC)
  12443. is used instead. See also <code><a href="#date">date</a></code> and
  12444. <code><a href="#time">time</a></code>.
  12445.  
  12446. <pre><code>
  12447. : (stamp)
  12448. -> "2000-09-12 07:48:04"
  12449. : (stamp (date) 0)
  12450. -> "2000-09-12 00:00:00"
  12451. : (stamp (date 2000 1 1) (time 12 0 0))
  12452. -> "2000-01-01 12:00:00"
  12453. </code></pre>
  12454.  
  12455. <dt><a name="state"><code>(state 'var (sym|lst exe [. prg]) ..) -> any</code></a>
  12456. <dd>Implements a finite state machine. The variable <code>var</code> holds the
  12457. current state as a symbolic value. When a clause is found that contains the
  12458. current state in its CAR <code>sym|lst</code> value, and where the
  12459. <code>exe</code> in its CADR evaluates to non-<code>NIL</code>, the current
  12460. state will be set to that value, the body <code>prg</code> in the CDDR will be
  12461. executed, and the result returned. <code>T</code> is a catch-all for any state.
  12462. If no state-condition matches, <code>NIL</code> is returned. See also <code><a
  12463. href="#case">case</a></code>, <code><a
  12464. href="#cond">cond</a></code> and <code><a
  12465. href="#job">job</a></code>.
  12466.  
  12467. <pre><code>
  12468. : (de tst ()
  12469. (job '((Cnt . 4))
  12470. (state '(start)
  12471. (start 'run
  12472. (printsp 'start) )
  12473. (run (and (gt0 (dec 'Cnt)) 'run)
  12474. (printsp 'run) )
  12475. (run 'stop
  12476. (printsp 'run) )
  12477. (stop 'start
  12478. (setq Cnt 4)
  12479. (println 'stop) ) ) ) )
  12480. -> tst
  12481. : (do 12 (tst))
  12482. start run run run run stop
  12483. start run run run run stop
  12484. -> stop
  12485. : (pp 'tst)
  12486. (de tst NIL
  12487. (job '((Cnt . 4))
  12488. (state '(start)
  12489. ...
  12490. -> tst
  12491. : (do 3 (tst))
  12492. start run run -> run
  12493. : (pp 'tst)
  12494. (de tst NIL
  12495. (job '((Cnt . 2))
  12496. (state '(run)
  12497. ...
  12498. -> tst
  12499. </code></pre>
  12500.  
  12501. <dt><a name="stem"><code>(stem 'lst 'any ..) -> lst</code></a>
  12502. <dd>Returns the tail of <code>lst</code> that does not contain any of the
  12503. <code>any</code> arguments. <code>(stem 'lst 'any ..)</code> is equivalent to
  12504. <code>(last (split 'lst 'any ..))</code>. See also <code><a
  12505. href="#tail">tail</a></code> and <code><a
  12506. href="#split">split</a></code>.
  12507.  
  12508. <pre><code>
  12509. : (stem (chop "abc/def\\ghi") "/" "\\")
  12510. -> ("g" "h" "i")
  12511. </code></pre>
  12512.  
  12513. <dt><a name="step"><code>(step 'lst ['flg]) -> any</code></a>
  12514. <dd>Single-steps iteratively through a database tree. <code>lst</code> is a
  12515. structure as received from <code><a href="#init">init</a></code>. If
  12516. <code>flg</code> is non-<code>NIL</code>, partial keys are skipped. See also
  12517. <code><a href="#tree">tree</a></code>, <code><a
  12518. href="#scan">scan</a></code>, <code><a
  12519. href="#iter">iter</a></code>, <code><a
  12520. href="#leaf">leaf</a></code> and <code><a
  12521. href="#fetch">fetch</a></code>.
  12522.  
  12523. <pre><code>
  12524. : (setq Q (init (tree 'nr '+Item) 3 5))
  12525. -> (((3 . 5) ((3 NIL . {3-3}) (4 NIL . {3-4}) (5 NIL . {3-5}) (6 NIL . {3-6}) (7 NIL . {3-8}))))
  12526. : (get (step Q) 'nr)
  12527. -> 3
  12528. : (get (step Q) 'nr)
  12529. -> 4
  12530. : (get (step Q) 'nr)
  12531. -> 5
  12532. : (get (step Q) 'nr)
  12533. -> NIL
  12534. </code></pre>
  12535.  
  12536. <dt><a name="store"><code>(store 'tree 'any1 'any2 ['(num1 . num2)])</code></a>
  12537. <dd>Stores a value <code>any2</code> for the key <code>any1</code> in a database
  12538. tree. <code>num1</code> is a database file number, as used in <code><a
  12539. href="#new">new</a></code> (defaulting to 1), and <code>num2</code> a
  12540. database block size (defaulting to 256). When <code>any2</code> is
  12541. <code>NIL</code>, the corresponding entry is deleted from the tree. See also
  12542. <code><a href="#tree">tree</a></code> and <code><a
  12543. href="#fetch">fetch</a></code>.
  12544.  
  12545. <pre><code>
  12546. : (store (tree 'nr '+Item) 2 '{3-2})
  12547. </code></pre>
  12548.  
  12549. <dt><a name="str"><code>(str 'sym ['sym1]) -> lst</code></a>
  12550. <dt><code>(str 'lst) -> sym</code>
  12551. <dd>In the first form, the string <code>sym</code> is parsed into a list. This
  12552. mechanism is also used by <code><a href="#load">load</a></code>. If
  12553. <code>sym1</code> is given, it should specify a set of characters, and
  12554. <code>str</code> will then return a list of tokens analog to <code><a
  12555. href="#read">read</a></code>. The second form does the reverse
  12556. operation by building a string from a list. See also <code><a
  12557. href="#any">any</a></code>, <code><a
  12558. href="#name">name</a></code> and <code><a
  12559. href="#sym">sym</a></code>.
  12560.  
  12561. <pre><code>
  12562. : (str "a (1 2) b")
  12563. -> (a (1 2) b)
  12564. : (str '(a "Hello" DEF))
  12565. -> "a \"Hello\" DEF"
  12566. : (str "a*3+b*4" "_")
  12567. -> (a "*" 3 "+" b "*" 4)
  12568. </code></pre>
  12569.  
  12570. <dt><a name="str?"><code>(str? 'any) -> sym | NIL</code></a>
  12571. <dd>Returns the argument <code>any</code> when it is a transient symbol
  12572. (string), otherwise <code>NIL</code>. See also <code><a
  12573. href="#sym?">sym?</a></code>, <code><a
  12574. href="#box?">box?</a></code> and <code><a
  12575. href="#ext?">ext?</a></code>.
  12576.  
  12577. <pre><code>
  12578. : (str? 123)
  12579. -> NIL
  12580. : (str? '{ABC})
  12581. -> NIL
  12582. : (str? 'abc)
  12583. -> NIL
  12584. : (str? "abc")
  12585. -> "abc"
  12586. </code></pre>
  12587.  
  12588. <dt><a name="strDat"><code>(strDat 'sym) -> dat</code></a>
  12589. <dd>Converts a string <code>sym</code> in the date format of the current
  12590. <code><a href="#locale">locale</a></code> to a <code><a
  12591. href="#date">date</a></code>. See also <code><a
  12592. href="#expDat">expDat</a></code>, <code><a
  12593. href="#$dat">$dat</a></code> and <code><a
  12594. href="#datStr">datStr</a></code>.
  12595.  
  12596. <pre><code>
  12597. : (strDat "2007-06-01")
  12598. -> 733134
  12599. : (strDat "01.06.2007")
  12600. -> NIL
  12601. : (locale "DE" "de")
  12602. -> NIL
  12603. : (strDat "01.06.2007")
  12604. -> 733134
  12605. : (strDat "1.6.2007")
  12606. -> 733134
  12607. </code></pre>
  12608.  
  12609. <dt><a name="strip"><code>(strip 'any) -> any</code></a>
  12610. <dd>Strips all leading <code>quote</code> symbols from <code>any</code>.
  12611.  
  12612. <pre><code>
  12613. : (strip 123)
  12614. -> 123
  12615. : (strip '''(a))
  12616. -> (a)
  12617. : (strip (quote quote a b c))
  12618. -> (a b c)
  12619. </code></pre>
  12620.  
  12621. <dt><a name="struct"><code>(struct 'num 'any 'any ..) -> any</code></a>
  12622. <dd>Creates or extracts data structures, suitable to be passed to or returned
  12623. from <code><a href="#native">native</a></code> C functions. The first
  12624. <code>num</code> argument should be a native value, either a scalar, or a
  12625. pointer obtained by calling functions like <code>malloc()</code>. The second
  12626. argument <code>any</code> is a <a href="#natResult">result
  12627. specification</a>, while all following <a
  12628. href="#natItem">initialization items</a> are stored in the structure
  12629. pointed to by the first argument. See also <a href="native.html">Native C
  12630. Calls</a>.
  12631.  
  12632. <pre><code>
  12633. : (scl 2)
  12634. -> 2
  12635.  
  12636. ## /* We assume the following C structure */
  12637. ## typedef struct value {
  12638. ## int x, y;
  12639. ## double a, b, c;
  12640. ## long z;
  12641. ## char nm[4];
  12642. ## } value;
  12643.  
  12644. # Allocate structure
  12645. : (setq P (native "@" "malloc" 'N 44))
  12646. -> 9204032
  12647.  
  12648. # Store two integers, three doubles, one long, and four characters
  12649. : (struct P 'N -7 -4 (1.0 0.11 0.22 0.33) (7 . 8) 65 66 67 0)
  12650. -> 9204032
  12651.  
  12652. # Extract the structure
  12653. : (struct P '((I . 2) (1.0 . 3) N (C . 4)))
  12654. -> ((7 4) (11 22 33) 7 ("A" "B" "C" NIL))
  12655.  
  12656. # Do both in a single call (allowing conversions of data types)
  12657. : (struct P
  12658. '((I . 2) (1.0 . 3) N (C . 4))
  12659. -7 -4 (1.0 0.11 0.22 0.33) (7 . 8) 65 66 67 0 )
  12660. -> ((7 4) (11 22 33) 7 ("A" "B" "C" NIL))
  12661.  
  12662. # De-allocate structure
  12663. : (native "@" "free" NIL P)
  12664. -> NIL
  12665. </code></pre>
  12666.  
  12667. <dt><a name="sub?"><code>(sub? 'any1 'any2) -> any2 | NIL</code></a>
  12668. <dd>Returns <code>any2</code> when the string representation of
  12669. <code>any1</code> is a substring of the string representation of
  12670. <code>any2</code>. See also <code><a href="#pre?">pre?</a></code>,
  12671. <code><a href="#offset">offset</a></code> and <code><a
  12672. href="#index">index</a></code>.
  12673.  
  12674. <pre><code>
  12675. : (sub? "def" "abcdefg")
  12676. -> "abcdefg"
  12677. : (sub? "abb" "abcdefg")
  12678. -> NIL
  12679. : (sub? NIL "abcdefg")
  12680. -> "abcdefg"
  12681.  
  12682. : (sub? "def" '(a b c d e f g))
  12683. -> "abcdefg"
  12684. : (sub? '(d e f) "abcdefg")
  12685. -> "abcdefg"
  12686. </code></pre>
  12687.  
  12688. <dt><a name="subr"><code>(subr 'sym) -> num</code></a>
  12689. <dd>Converts a Lisp-function that was previously converted with <code><a
  12690. href="#expr">expr</a></code> back to a C-function.
  12691.  
  12692. <pre><code>
  12693. : car
  12694. -> 67313448
  12695. : (expr 'car)
  12696. -> (@ (pass $385260187))
  12697. : (subr 'car)
  12698. -> 67313448
  12699. : car
  12700. -> 67313448
  12701. </code></pre>
  12702.  
  12703. <dt><a name="sum"><code>(sum 'fun 'lst ..) -> num</code></a>
  12704. <dd>Applies <code>fun</code> to each element of <code>lst</code>. When
  12705. additional <code>lst</code> arguments are given, their elements are also passed
  12706. to <code>fun</code>. Returns the sum of all numeric values returned from
  12707. <code>fun</code>.
  12708.  
  12709. <pre><code>
  12710. : (setq A 1 B 2 C 3)
  12711. -> 3
  12712. : (sum val '(A B C))
  12713. -> 6
  12714. : (sum * (3 4 5) (5 6 7)) # Vector dot product
  12715. -> 74
  12716. : (sum # Total size of symbol list values
  12717. '((X)
  12718. (and (pair (val X)) (size @)) )
  12719. (what) )
  12720. -> 32021
  12721. </code></pre>
  12722.  
  12723. <dt><a name="super"><code>(super ['any ..]) -> any</code></a>
  12724. <dd>Can only be used inside methods. Sends the current message to the current
  12725. object <code>This</code>, this time starting the search for a method at the
  12726. superclass(es) of the class where the current method was found. See also <a
  12727. href="#oop">OO Concepts</a>, <code><a
  12728. href="#extra">extra</a></code>, <code><a
  12729. href="#method">method</a></code>, <code><a
  12730. href="#meth">meth</a></code>, <code><a
  12731. href="#send">send</a></code> and <code><a
  12732. href="#try">try</a></code>.
  12733.  
  12734. <pre><code>
  12735. (dm stop> () # 'stop>' method of current class
  12736. (super) # Call the 'stop>' method of the superclass
  12737. ... ) # other things
  12738. </code></pre>
  12739.  
  12740. <dt><a name="swap"><code>(swap 'var 'any) -> any</code></a>
  12741. <dd>Set the value of <code>var</code> to <code>any</code>, and return the
  12742. previous value. See also <code><a href="#xchg">xchg</a></code> and
  12743. <code><a href="#set">set</a></code>.
  12744.  
  12745. <pre><code>
  12746. : (setq A 7 L (1 2 3))
  12747. -> (1 2 3)
  12748. : (swap (cdr L) (swap 'A 'xyz))
  12749. -> 2
  12750. : A
  12751. -> xyz
  12752. : L
  12753. -> (1 7 3)
  12754. </code></pre>
  12755.  
  12756. <dt><a name="sym"><code>(sym 'any) -> sym</code></a>
  12757. <dd>Generate the printed representation of <code>any</code> into the name of a
  12758. new symbol <code>sym</code>. This is the reverse operation of <code><a
  12759. href="#any">any</a></code>. See also <code><a
  12760. href="#name">name</a></code> and <code><a
  12761. href="#str">str</a></code>.
  12762.  
  12763. <pre><code>
  12764. : (sym '(abc "Hello" 123))
  12765. -> "(abc \"Hello\" 123)"
  12766. </code></pre>
  12767.  
  12768. <dt><a name="sym?"><code>(sym? 'any) -> flg</code></a>
  12769. <dd>Returns <code>T</code> when the argument <code>any</code> is a symbol. See
  12770. also <code><a href="#num?">num?</a></code>, <code><a
  12771. href="#atom">atom</a></code>, <code><a
  12772. href="#pair">pair</a></code>, <code><a
  12773. href="#str?">str?</a></code>, <code><a
  12774. href="#box?">box?</a></code> and <code><a
  12775. href="#ext?">ext?</a></code>.
  12776.  
  12777. <pre><code>
  12778. : (sym? 'a)
  12779. -> T
  12780. : (sym? NIL)
  12781. -> T
  12782. : (sym? 123)
  12783. -> NIL
  12784. : (sym? '(a b))
  12785. -> NIL
  12786. </code></pre>
  12787.  
  12788. <dt><a name="symbols"><code>(symbols) -> sym</code></a>
  12789. <dt><code>(symbols 'sym1) -> sym2</code>
  12790. <dt><code>(symbols 'sym1 'sym ..) -> sym2</code>
  12791. <dd>(64-bit version only) Creates and manages namespaces of internal symbols: In
  12792. the first form, the current namespace is returned. In the second form, the
  12793. current namespace is set to <code>sym1</code>, and the previous namespace
  12794. <code>sym2</code> is returned. In the third form, <code>sym1</code> is assigned
  12795. a <code><a href="#balance">balance</a></code>d copy of the existing
  12796. namespace(s) <code>sym</code>, and becomes the new current namespace, returning
  12797. the previous namespace <code>sym2</code>. If in the third form more than one
  12798. <code>sym</code> argument is given, possibly conflicting symbols in later
  12799. namespaces are not interned into <code>sym2</code>. See also <code><a
  12800. href="#pico">pico</a></code>, <code><a
  12801. href="#local">local</a></code>, <code><a
  12802. href="#import">import</a></code>, <code><a
  12803. href="#intern">intern</a></code> and <code><a
  12804. href="#load">load</a></code>.
  12805.  
  12806. <pre><code>
  12807. : (symbols 'myLib 'pico)
  12808. -> pico
  12809. myLib: (de foo (X)
  12810. (bar (inc X)) )
  12811. -> foo
  12812. myLib: (symbols 'pico)
  12813. -> myLib
  12814. : (pp 'foo)
  12815. (de foo . NIL)
  12816. -> foo
  12817. : (pp 'myLib~foo)
  12818. (de "foo" (X)
  12819. ("bar" (inc X)) )
  12820. -> "foo"
  12821. : (symbols 'myLib)
  12822. -> pico
  12823. myLib: (pp 'foo)
  12824. (de foo (X)
  12825. (bar (inc X)) )
  12826. -> foo
  12827. myLib:
  12828. </code></pre>
  12829.  
  12830. <dt><a name="sync"><code>(sync) -> flg</code></a>
  12831. <dd>Waits for pending data from all family processes. While other processes are
  12832. still sending data (via the <code><a href="#tell">tell</a></code>
  12833. mechanism), a <code>select</code> system call is executed for all file
  12834. descriptors and timers in the <code>VAL</code> of the global variable <code><a
  12835. href="#*Run">*Run</a></code>. When used in a non-database context,
  12836. <code>(tell)</code> should be called in the end to inform the parent process
  12837. that it may grant synchronization to other processes waiting for
  12838. <code>sync</code>. In a database context, where <code>sync</code> is usually
  12839. called by <code><a href="#dbSync">dbSync</a></code>, this is not
  12840. necessary because it is done internally by <code><a
  12841. href="#commit">commit</a></code> or <code><a
  12842. href="#rollback">rollback</a></code>.
  12843.  
  12844. See also <code><a
  12845. href="#key">key</a></code> and <code><a
  12846. href="#wait">wait</a></code>.
  12847.  
  12848. <pre><code>
  12849. : (or (lock) (sync)) # Ensure database consistency
  12850. -> T # (numeric process-id if lock failed)
  12851. </code></pre>
  12852.  
  12853. <dt><a name="sys"><code>(sys 'any ['any]) -> sym</code></a>
  12854. <dd>Returns or sets a system environment variable.
  12855.  
  12856. <pre><code>
  12857. : (sys "TERM") # Get current value
  12858. -> "xterm"
  12859. : (sys "TERM" "vt100") # Set new value
  12860. -> "vt100"
  12861. : (sys "TERM")
  12862. -> "vt100"
  12863. </code></pre>
  12864.  
  12865. </dl>
  12866.  
  12867. <h1><a name="T">T</a></h1>
  12868.  
  12869. <dl>
  12870.  
  12871. <dt><a name="*Tmp"><code>*Tmp</code></a>
  12872. <dd>A global variable holding the temporary directory name created with <code><a
  12873. href="#tmp">tmp</a></code>. See also <code><a
  12874. href="#*Bye">*Bye</a></code>.
  12875.  
  12876. <pre><code>
  12877. : *Bye
  12878. -> ((saveHistory) (and *Tmp (call 'rm "-r" *Tmp)))
  12879. : (tmp "foo" 123)
  12880. -> "/home/app/.pil/tmp/27140/foo123"
  12881. : *Tmp
  12882. -> "/home/app/.pil/tmp/27140/"
  12883. </code></pre>
  12884.  
  12885. <p><dt><a name="*Tsm"><code>*Tsm</code></a>
  12886. <dd>A global variable which may hold a cons pair of two strings with escape
  12887. sequences, to switch on and off an alternative transient symbol markup. If set,
  12888. <code><a href="#print">print</a></code> will output these sequences to
  12889. the console instead of the standard double quote markup characters. An easy way
  12890. to switch on transient symbol markup is loading "@lib/tsm.l".
  12891.  
  12892. <pre><code>
  12893. : (de *Tsm "^[[4m" . "^[[24m") # vt100 escape sequences for underline
  12894. -> *Tsm
  12895. : <u>Hello world</u>
  12896. -> <u>Hello world</u>
  12897. : (off *Tsm)
  12898. -> NIL
  12899. : "Hello world" # No underlining
  12900. -> "Hello world"
  12901. </code></pre>
  12902.  
  12903. <dt><a name="+Time"><code>+Time</code></a>
  12904. <dd>Class for clock time values (as calculated by <code><a
  12905. href="#time">time</a></code>), a subclass of <code><a
  12906. href="#+Number">+Number</a></code>. See also <a
  12907. href="#dbase">Database</a>.
  12908.  
  12909. <pre><code>
  12910. (rel tim (+Time)) # Time of the day
  12911. </code></pre>
  12912.  
  12913. <dt><a name="T"><code>T</code></a>
  12914. <dd>A global constant, evaluating to itself. <code>T</code> is commonly returned
  12915. as the boolean value "true" (though any non-<code>NIL</code> values could be
  12916. used). It represents the absolute maximum, as it is larger than any other
  12917. object. As a property key, it is used to store <a
  12918. href="#pilog">Pilog</a> clauses, and inside Pilog clauses it is the
  12919. <i>cut</i> operator. See also <code><a href="#nilSym">NIL</a></code> and
  12920. and <a href="#cmp">Comparing</a>.
  12921.  
  12922. <pre><code>
  12923. : T
  12924. -> T
  12925. : (= 123 123)
  12926. -> T
  12927. : (get 'not T)
  12928. -> ((@P (1 (-> @P)) T (fail)) (@P))
  12929. </code></pre>
  12930.  
  12931. <dt><a name="This"><code>This</code></a>
  12932. <dd>Holds the current object during method execution (see <a
  12933. href="#oop">OO Concepts</a>), or inside the body of a <code><a
  12934. href="#with">with</a></code> statement. As it is a normal symbol,
  12935. however, it can be used in normal bindings anywhere. See also <code><a
  12936. href="#isa">isa</a></code>, <code><a href="ref_.html#:">:</a></code>,
  12937. <code><a href="#=:">=:</a></code>, <code><a
  12938. href="#::">::</a></code> and <code><a
  12939. href="#var:">var:</a></code>.
  12940.  
  12941. <pre><code>
  12942. : (with 'X (println 'This 'is This))
  12943. This is X
  12944. -> X
  12945. : (put 'X 'a 1)
  12946. -> 1
  12947. : (put 'X 'b 2)
  12948. -> 2
  12949. : (put 'Y 'a 111)
  12950. -> 111
  12951. : (put 'Y 'b 222)
  12952. -> 222
  12953. : (mapcar '((This) (cons (: a) (: b))) '(X Y))
  12954. -> ((1 . 2) (111 . 222))
  12955. </code></pre>
  12956.  
  12957. <dt><a name="t"><code>(t . prg) -> T</code></a>
  12958. <dd>Executes <code>prg</code>, and returns <code>T</code>. See also <code><a
  12959. href="#nil">nil</a></code>, <code><a
  12960. href="#prog">prog</a></code>, <code><a
  12961. href="#prog1">prog1</a></code> and <code><a
  12962. href="#prog2">prog2</a></code>.
  12963.  
  12964. <pre><code>
  12965. : (t (println 'OK))
  12966. OK
  12967. -> T
  12968. </code></pre>
  12969.  
  12970. <dt><a name="tab"><code>(tab 'lst 'any ..) -> NIL</code></a>
  12971. <dd>Print all <code>any</code> arguments in a tabular format. <code>lst</code>
  12972. should be a list of numbers, specifying the field width for each argument. All
  12973. items in a column will be left-aligned for negative numbers, otherwise
  12974. right-aligned. See also <code><a href="#align">align</a></code>,
  12975. <code><a href="#center">center</a></code> and <code><a
  12976. href="#wrap">wrap</a></code>.
  12977.  
  12978. <pre><code>
  12979. : (let Fmt (-3 14 14)
  12980. (tab Fmt "Key" "Rand 1" "Rand 2")
  12981. (tab Fmt "---" "------" "------")
  12982. (for C '(A B C D E F)
  12983. (tab Fmt C (rand) (rand)) ) )
  12984. Key Rand 1 Rand 2
  12985. --- ------ ------
  12986. A 0 1481765933
  12987. B -1062105905 -877267386
  12988. C -956092119 812669700
  12989. D 553475508 -1702133896
  12990. E 1344887256 -1417066392
  12991. F 1812158119 -1999783937
  12992. -> NIL
  12993. </code></pre>
  12994.  
  12995. <dt><a name="tail"><code>(tail 'cnt|lst 'lst) -> lst</code></a>
  12996. <dd>Returns the last <code>cnt</code> elements of <code>lst</code>. If
  12997. <code>cnt</code> is negative, it is added to the length of <code>lst</code>. If
  12998. the first argument is a <code>lst</code>, <code>tail</code> is a predicate
  12999. function returning that argument list if it is <code>equal</code> to the tail of
  13000. the second argument, and <code>NIL</code> otherwise. <code>(tail -2 Lst)</code>
  13001. is equivalent to <code>(nth Lst 3)</code>. See also <code><a
  13002. href="#offset">offset</a></code>, <code><a
  13003. href="#head">head</a></code>, <code><a
  13004. href="#last">last</a></code> and <code><a
  13005. href="#stem">stem</a></code>.
  13006.  
  13007. <pre><code>
  13008. : (tail 3 '(a b c d e f))
  13009. -> (d e f)
  13010. : (tail -2 '(a b c d e f))
  13011. -> (c d e f)
  13012. : (tail 0 '(a b c d e f))
  13013. -> NIL
  13014. : (tail 10 '(a b c d e f))
  13015. -> (a b c d e f)
  13016. : (tail '(d e f) '(a b c d e f))
  13017. -> (d e f)
  13018. </code></pre>
  13019.  
  13020. <dt><a name="task"><code>(task 'num ['num] [sym 'any ..] [. prg]) -> lst</code></a>
  13021. <dd>A front-end to the <code><a href="#*Run">*Run</a></code> global. If
  13022. called with only a single <code>num</code> argument, the corresponding entry is
  13023. removed from the value of <code>*Run</code>. Otherwise, a new entry is created.
  13024. If an entry with that key already exists, an error is issued. For negative
  13025. numbers, a second number must be supplied. If <code>sym</code>/<code>any</code>
  13026. arguments are given, a <code><a href="#job">job</a></code> environment
  13027. is built for thie <code>*Run</code> entry. See also <code><a
  13028. href="#forked">forked</a></code> and <code><a
  13029. href="#timeout">timeout</a></code>.
  13030.  
  13031. <pre><code>
  13032. : (task -10000 5000 N 0 (msg (inc 'N))) # Install task
  13033. -> (-10000 5000 (job '((N . 0)) (msg (inc 'N)))) # for every 10 seconds
  13034. : 1 # ... after 5 seconds
  13035. 2 # ... after 10 seconds
  13036. 3 # ... after 10 seconds
  13037. (task -10000) # remove again
  13038. -> NIL
  13039.  
  13040. : (task (port T 4444) (eval (udp @))) # Receive RPC via UDP
  13041. -> (3 (eval (udp @)))
  13042.  
  13043. # Another session (on the same machine)
  13044. : (udp "localhost" 4444 '(println *Pid)) # Send RPC message
  13045. -> (println *Pid)
  13046. </code></pre>
  13047.  
  13048. <dt><a name="telStr"><code>(telStr 'sym) -> sym</code></a>
  13049. <dd>Formats a telephone number according to the current <code><a
  13050. href="#locale">locale</a></code>. If the string head matches the local
  13051. country code, it is replaced with <code>0</code>, otherwise <code>+</code> is
  13052. prepended. See also <code><a href="#expTel">expTel</a></code>, <code><a
  13053. href="#datStr">datStr</a></code>, <code><a
  13054. href="#money">money</a></code> and <code><a
  13055. href="#format">format</a></code>.
  13056.  
  13057. <pre><code>
  13058. : (telStr "49 1234 5678-0")
  13059. -> "+49 1234 5678-0"
  13060. : (locale "DE" "de")
  13061. -> NIL
  13062. : (telStr "49 1234 5678-0")
  13063. -> "01234 5678-0"
  13064. </code></pre>
  13065.  
  13066. <dt><a name="tell"><code>(tell ['cnt] 'sym ['any ..]) -> any</code></a>
  13067. <dd>Family IPC: Send an executable list <code>(sym any ..)</code> to all family
  13068. members (i.e. all children of the current process, and all other children of the
  13069. parent process, see <code><a href="#fork">fork</a></code>) for
  13070. automatic execution. When the <code>cnt</code> argument is given and non-zero,
  13071. it should be the PID of such a process, and the list will be sent only to that
  13072. process. When called without arguments, no message is actually sent, and the
  13073. parent process may grant <code><a href="#sync">sync</a></code> to the
  13074. next waiting process. <code>tell</code> is also used internally by <code><a
  13075. href="#commit">commit</a></code> to notify about database changes. When
  13076. called explicitly, the size of the message is limited to the POSIX constant
  13077. PIPE_BUF. See also <code><a href="#kids">kids</a></code> and <code><a
  13078. href="#hear">hear</a></code>.
  13079.  
  13080. <pre><code>
  13081. : (call 'ps "x") # Show processes
  13082. PID TTY STAT TIME COMMAND
  13083. ..
  13084. 1321 pts/0 S 0:00 /usr/bin/picolisp .. # Parent process
  13085. 1324 pts/0 S 0:01 /usr/bin/picolisp .. # First child
  13086. 1325 pts/0 S 0:01 /usr/bin/picolisp .. # Second child
  13087. 1326 pts/0 R 0:00 ps x
  13088. -> T
  13089. : *Pid # We are the second child
  13090. -> 1325
  13091. : (tell 'println '*Pid) # Ask all others to print their Pid's
  13092. 1324
  13093. -> *Pid
  13094. </code></pre>
  13095.  
  13096. <dt><a name="test"><code>(test 'any . prg)</code></a>
  13097. <dd>Executes <code>prg</code>, and issues an <code><a
  13098. href="#errors">error</a></code> if the result does not <code><a
  13099. href="#match">match</a></code> the <code>any</code> argument. See also
  13100. <code><a href="#assert">assert</a></code>.
  13101.  
  13102. <pre><code>
  13103. : (test 12 (* 3 4))
  13104. -> NIL
  13105. : (test 12 (+ 3 4))
  13106. ((+ 3 4))
  13107. 12 -- 'test' failed
  13108. ?
  13109. </code></pre>
  13110.  
  13111. <dt><a name="text"><code>(text 'any1 'any ..) -> sym</code></a>
  13112. <dd>Builds a new transient symbol (string) from the string representation of
  13113. <code>any1</code>, by replacing all occurrences of an at-mark "<code>@</code>",
  13114. followed by one of the letters "<code>1</code>" through "<code>9</code>", and
  13115. "<code>A</code>" through "<code>Z</code>", with the corresponding
  13116. <code>any</code> argument. In this context "<code>@A</code>" refers to the 10th
  13117. argument. A literal at-mark in the text can be represented by two successive
  13118. at-marks. See also <code><a href="#pack">pack</a></code> and <code><a
  13119. href="#glue">glue</a></code>.
  13120.  
  13121. <pre><code>
  13122. : (text "abc @1 def @2" 'XYZ 123)
  13123. -> "abc XYZ def 123"
  13124. : (text "a@@bc.@1" "de")
  13125. -> "a@bc.de"
  13126. </code></pre>
  13127.  
  13128. <dt><a name="throw"><code>(throw 'sym 'any)</code></a>
  13129. <dd>Non-local jump into a previous <code><a
  13130. href="#catch">catch</a></code> environment with the jump label
  13131. <code>sym</code> (or <code>T</code> as a catch-all). Any pending <code><a
  13132. href="#finally">finally</a></code> expressions are executed, local
  13133. symbol bindings are restored, open files are closed and internal data structures
  13134. are reset appropriately, as the environment was at the time when the
  13135. corresponding <code>catch</code> was called. Then <code>any</code> is returned
  13136. from that <code>catch</code>. See also <code><a
  13137. href="#quit">quit</a></code>.
  13138.  
  13139. <pre><code>
  13140. : (de foo (N)
  13141. (println N)
  13142. (throw 'OK) )
  13143. -> foo
  13144. : (let N 1 (catch 'OK (foo 7)) (println N))
  13145. 7
  13146. 1
  13147. -> 1
  13148. </code></pre>
  13149.  
  13150. <dt><a name="tick"><code>(tick (cnt1 . cnt2) . prg) -> any</code></a>
  13151. <dd>Executes <code>prg</code>, then (destructively) adds the number of elapsed
  13152. user ticks to the <code>cnt1</code> parameter, and the number of elapsed system
  13153. ticks to the <code>cnt2</code> parameter. Thus, <code>cnt1</code> and
  13154. <code>cnt2</code> will finally contain the total number of user and system time
  13155. ticks spent in <code>prg</code> and all functions called (this works also for
  13156. recursive functions). For execution profiling, <code>tick</code> is usually
  13157. inserted into words with <code>prof</code>, and removed with
  13158. <code>unprof</code>. See also <code><a href="#usec">usec</a></code>.
  13159.  
  13160. <pre><code>
  13161. : (de foo () # Define function with empty loop
  13162. (tick (0 . 0) (do 100000000)) )
  13163. -> foo
  13164. : (foo) # Execute it
  13165. -> NIL
  13166. : (pp 'foo)
  13167. (de foo NIL
  13168. (tick (97 . 0) (do 100000000)) ) # 'tick' incremented 'cnt1' by 97
  13169. -> foo
  13170. </code></pre>
  13171.  
  13172. <dt><a name="till"><code>(till 'any ['flg]) -> lst|sym</code></a>
  13173. <dd>Reads from the current input channel till a character contained in
  13174. <code>any</code> is found (or until end of file if <code>any</code> is
  13175. <code>NIL</code>). If <code>flg</code> is <code>NIL</code>, a list of
  13176. single-character transient symbols is returned. Otherwise, a single string is
  13177. returned. See also <code><a href="#from">from</a></code> and <code><a
  13178. href="#line">line</a></code>.
  13179.  
  13180. <pre><code>
  13181. : (till ":")
  13182. abc:def
  13183. -> ("a" "b" "c")
  13184. : (till ":" T)
  13185. abc:def
  13186. -> "abc"
  13187. </code></pre>
  13188.  
  13189. <dt><a name="tim$"><code>(tim$ 'tim ['flg]) -> sym</code></a>
  13190. <dd>Formats a <code><a href="#time">time</a></code> <code>tim</code>.
  13191. If <code>flg</code> is <code>NIL</code>, the format is HH:MM, otherwise it is
  13192. HH:MM:SS. See also <code><a href="#$tim">$tim</a></code> and <code><a
  13193. href="#dat$">dat$</a></code>.
  13194.  
  13195. <pre><code>
  13196. : (tim$ (time))
  13197. -> "10:57"
  13198. : (tim$ (time) T)
  13199. -> "10:57:56"
  13200. </code></pre>
  13201.  
  13202. <dt><a name="time"><code>(time ['T]) -> tim</code></a>
  13203. <dt><code>(time 'tim) -> (h m s)</code>
  13204. <dt><code>(time 'h 'm ['s]) -> tim | NIL</code>
  13205. <dt><code>(time '(h m [s])) -> tim | NIL</code>
  13206. <dd>Calculates the time of day, represented as the number of seconds since
  13207. midnight. When called without arguments, the current local time is returned.
  13208. When called with a <code>T</code> argument, the time of the last call to
  13209. <code><a href="#date">date</a></code> is returned. When called with a
  13210. single number <code>tim</code>, it is taken as a time value and a list with the
  13211. corresponding hour, minute and second is returned. When called with two or three
  13212. numbers (or a list of two or three numbers) for the hour, minute (and optionally
  13213. the second), the corresponding time value is returned (or <code>NIL</code> if
  13214. they do not represent a legal time). See also <code><a
  13215. href="#date">date</a></code>, <code><a
  13216. href="#stamp">stamp</a></code>, <code><a
  13217. href="#usec">usec</a></code>, <code><a
  13218. href="#tim$">tim$</a></code> and <code><a
  13219. href="#$tim">$tim</a></code>.
  13220.  
  13221. <pre><code>
  13222. : (time) # Now
  13223. -> 32334
  13224. : (time 32334) # Now
  13225. -> (8 58 54)
  13226. : (time 12 70) # Illegal time
  13227. -> NIL
  13228. </code></pre>
  13229.  
  13230. <dt><a name="timeout"><code>(timeout ['num])</code></a>
  13231. <dd>Sets or refreshes a timeout value in the <code><a
  13232. href="#*Run">*Run</a></code> global, so that the current process
  13233. executes <code><a href="#bye">bye</a></code> after the given period. If
  13234. called without arguments, the timeout is removed. See also <code><a
  13235. href="#task">task</a></code>.
  13236.  
  13237. <pre><code>
  13238. : (timeout 3600000) # Timeout after one hour
  13239. -> (-1 3600000 (bye))
  13240. : *Run # Look after a few seconds
  13241. -> ((-1 3574516 (bye)))
  13242. </code></pre>
  13243.  
  13244. <dt><a name="tmp"><code>(tmp ['any ..]) -> sym</code></a>
  13245. <dd>Returns the path name to the <code><a
  13246. href="#pack">pack</a></code>ed <code>any</code> arguments in a
  13247. process-local temporary directory. The directory name consists of the path to
  13248. ".pil/tmp/" in the user's home directory, followed by the current process ID
  13249. <code><a href="#*Pid">*Pid</a></code>. This directory is automatically
  13250. created if necessary, and removed upon termination of the process (<code><a
  13251. href="#bye">bye</a></code>). See also <code><a
  13252. href="#pil">pil</a></code>, <code><a
  13253. href="#*Tmp">*Tmp</a></code> and <code><a
  13254. href="#*Bye">*Bye</a></code> .
  13255.  
  13256. <pre><code>
  13257. : *Pid
  13258. -> 27140
  13259. : (tmp "foo" 123)
  13260. -> "/home/app/.pil/tmp/27140/foo123"
  13261. : (out (tmp "foo" 123) (println 'OK))
  13262. -> OK
  13263. : (dir (tmp))
  13264. -> ("foo123")
  13265. : (in (tmp "foo" 123) (read))
  13266. -> OK
  13267. </code></pre>
  13268.  
  13269. <dt><a name="tolr/3"><code>tolr/3</code></a>
  13270. <dd><a href="#pilog">Pilog</a> predicate that succeeds if the first
  13271. argument, after <code><a href="#fold">fold</a></code>ing it to a
  13272. canonical form, is either a <i>substring</i> or a <code><a
  13273. href="#+Sn">+Sn</a></code> <i>soundex</i> match of the result of
  13274. applying the <code><a href="#get">get</a></code> algorithm to the
  13275. following arguments. Typically used as filter predicate in <code><a
  13276. href="#select/3">select/3</a></code> database queries. See also
  13277. <code><a href="#isa/2">isa/2</a></code>, <code><a
  13278. href="#same/3">same/3</a></code>, <code><a
  13279. href="#bool/3">bool/3</a></code>, <code><a
  13280. href="#range/3">range/3</a></code>, <code><a
  13281. href="#head/3">head/3</a></code>, <code><a
  13282. href="#fold/3">fold/3</a></code> and <code><a
  13283. href="#part/3">part/3</a></code>.
  13284.  
  13285. <pre><code>
  13286. : (?
  13287. @Nr (1 . 5)
  13288. @Nm "Sven"
  13289. (select (@CuSu)
  13290. ((nr +CuSu @Nr) (nm +CuSu @Nm))
  13291. (range @Nr @CuSu nr)
  13292. (tolr @Nm @CuSu nm) )
  13293. (val @Name @CuSu nm) )
  13294. @Nr=(1 . 5) @Nm="Sven" @CuSu={2-2} @Name="Seven Oaks Ltd."
  13295. </code></pre>
  13296.  
  13297. <dt><a name="touch"><code>(touch 'sym) -> sym</code></a>
  13298. <dd>When <code>sym</code> is an external symbol, it is marked as "modified" so
  13299. that upon a later <code><a href="#commit">commit</a></code> it will be
  13300. written to the database file. An explicit call of <code>touch</code> is only
  13301. necessary when the value or properties of <code>sym</code> are indirectly
  13302. modified.
  13303.  
  13304. <pre><code>
  13305. : (get '{2} 'lst)
  13306. -> (1 2 3 4 5)
  13307. : (set (cdr (get (touch '{2}) 'lst)) 999) # Only read-access, need 'touch'
  13308. -> 999
  13309. : (get '{2} 'lst) # Modified second list element
  13310. -> (1 999 3 4 5)
  13311. </code></pre>
  13312.  
  13313. <dt><a name="trace"><code>(trace 'sym) -> sym</code></a>
  13314. <dt><code>(trace 'sym 'cls) -> sym</code>
  13315. <dt><code>(trace '(sym . cls)) -> sym</code>
  13316. <dd>(Debug mode only) Inserts a <code><a href="#$">$</a></code> trace
  13317. function call at the beginning of the function or method body of
  13318. <code>sym</code>, so that trace information will be printed before and after
  13319. execution. Built-in functions (C-function pointer) are automatically converted
  13320. to Lisp expressions (see <code><a href="#expr">expr</a></code>). See
  13321. also <code><a href="#*Dbg">*Dbg</a></code>, <code><a
  13322. href="#traceAll">traceAll</a></code> and <code><a
  13323. href="#untrace">untrace</a></code>, <code><a
  13324. href="#debug">debug</a></code> and <code><a
  13325. href="#lint">lint</a></code>.
  13326.  
  13327. <pre><code>
  13328. : (trace '+)
  13329. -> +
  13330. : (+ 3 4)
  13331. + : 3 4
  13332. + = 7
  13333. -> 7
  13334. </code></pre>
  13335.  
  13336. <dt><a name="traceAll"><code>(traceAll ['lst]) -> sym</code></a>
  13337. <dd>(Debug mode only) Traces all Lisp level functions by inserting a <code><a
  13338. href="#$">$</a></code> function call at the beginning. <code>lst</code>
  13339. may contain symbols which are to be excluded from that process. In addition, all
  13340. symbols in the global variable <code>*NoTrace</code> are excluded. See also
  13341. <code><a href="#trace">trace</a></code>, <code><a
  13342. href="#untrace">untrace</a></code> and <code><a
  13343. href="#*Dbg">*Dbg</a></code>.
  13344.  
  13345. <pre><code>
  13346. : (traceAll) # Trace all Lisp level functions
  13347. -> balance
  13348. </code></pre>
  13349.  
  13350. <dt><a name="trail"><code>(trail ['flg]) -> lst</code></a>
  13351. <dd>(64-bit version only) Returns a stack backtrace for the current point of
  13352. program execution. The list elements are either list expressions (denoting
  13353. function or method calls), or symbols followed by their corresponding values. If
  13354. <code>flg</code> is <code>NIL</code>, the symbols and their values are omitted,
  13355. and only the expressions are returned. See also <code><a
  13356. href="#bt">bt</a></code>, <code><a
  13357. href="#up">up</a></code> and <code><a
  13358. href="#env">env</a></code>.
  13359.  
  13360. <pre><code>
  13361. : (de f (A B)
  13362. (g (inc A) (dec B)) )
  13363. -> f
  13364. : (de g (X Y)
  13365. (trail T) )
  13366. -> g
  13367. : (f 3 4)
  13368. -> ((f 3 4) A 3 B 4 (g (inc A) (dec B)) X 4 Y 3)
  13369. </code></pre>
  13370.  
  13371. <dt><a name="tree"><code>(tree 'sym 'cls ['hook]) -> tree</code></a>
  13372. <dd>Returns a data structure specifying a database index tree. <code>sym</code>
  13373. and <code>cls</code> determine the relation, with an optional <code>hook</code>
  13374. object. See also <code><a href="#root">root</a></code>, <code><a
  13375. href="#fetch">fetch</a></code>, <code><a
  13376. href="#store">store</a></code>, <code><a
  13377. href="#count">count</a></code>, <code><a
  13378. href="#leaf">leaf</a></code>, <code><a
  13379. href="#minKey">minKey</a></code>, <code><a
  13380. href="#maxKey">maxKey</a></code>, <code><a
  13381. href="#init">init</a></code>, <code><a
  13382. href="#step">step</a></code>, <code><a
  13383. href="#scan">scan</a></code>, <code><a
  13384. href="#iter">iter</a></code>, <code><a
  13385. href="#prune">prune</a></code>, <code><a
  13386. href="#zapTree">zapTree</a></code> and <code><a
  13387. href="#chkTree">chkTree</a></code>.
  13388.  
  13389. <pre><code>
  13390. : (tree 'nm '+Item)
  13391. -> (nm . +Item)
  13392. </code></pre>
  13393.  
  13394. <dt><a name="trim"><code>(trim 'lst) -> lst</code></a>
  13395. <dd>Returns a copy of <code>lst</code> with all trailing whitespace characters
  13396. or <code>NIL</code> elements removed. See also <code><a
  13397. href="#clip">clip</a></code>.
  13398.  
  13399. <pre><code>
  13400. : (trim (1 NIL 2 NIL NIL))
  13401. -> (1 NIL 2)
  13402. : (trim '(a b " " " "))
  13403. -> (a b)
  13404. </code></pre>
  13405.  
  13406. <dt><a name="true/0"><code>true/0</code></a>
  13407. <dd><a href="#pilog">Pilog</a> predicate that always succeeds. See also
  13408. <code><a href="#fail/0">fail/0</a></code> and <code><a
  13409. href="#repeat/0">repeat/0</a></code>.
  13410.  
  13411. <pre><code>
  13412. : (? (true))
  13413. -> T
  13414. </code></pre>
  13415.  
  13416. <dt><a name="try"><code>(try 'msg 'obj ['any ..]) -> any</code></a>
  13417. <dd>Tries to send the message <code>msg</code> to the object <code>obj</code>,
  13418. optionally with arguments <code>any</code>. If <code>obj</code> is not an
  13419. object, or if the message cannot be located in <code>obj</code>, in its classes
  13420. or superclasses, <code>NIL</code> is returned. See also <a
  13421. href="#oop">OO Concepts</a>, <code><a
  13422. href="#send">send</a></code>, <code><a
  13423. href="#method">method</a></code>, <code><a
  13424. href="#meth">meth</a></code>, <code><a
  13425. href="#super">super</a></code> and <code><a
  13426. href="#extra">extra</a></code>.
  13427.  
  13428. <pre><code>
  13429. : (try 'msg> 123)
  13430. -> NIL
  13431. : (try 'html> 'a)
  13432. -> NIL
  13433. </code></pre>
  13434.  
  13435. <dt><a name="type"><code>(type 'any) -> lst</code></a>
  13436. <dd>Return the type (list of classes) of the object <code>sym</code>. See also
  13437. <a href="#oop">OO Concepts</a>, <code><a
  13438. href="#isa">isa</a></code>, <code><a
  13439. href="#class">class</a></code>, <code><a
  13440. href="#new">new</a></code> and <code><a
  13441. href="#object">object</a></code>.
  13442.  
  13443. <pre><code>
  13444. : (type '{1A;3})
  13445. (+Address)
  13446. : (type '+DnButton)
  13447. -> (+Tiny +Rid +JS +Able +Button)
  13448. </code></pre>
  13449.  
  13450. </dl>
  13451.  
  13452. <h1><a name="U">U</a></h1>
  13453.  
  13454. <dl>
  13455.  
  13456. <dt><a name="*Uni"><code>*Uni</code></a>
  13457. <dd>A global variable holding an <code><a href="#idx">idx</a></code>
  13458. tree, with all unique data that were collected with the comma (<code>,</code>)
  13459. read-macro. Typically used for localization. See also <code><a
  13460. href="#macro-io">Read-Macros</a></code> and <code><a
  13461. href="#locale">locale</a></code>.
  13462.  
  13463. <pre><code>
  13464. : (off *Uni) # Clear
  13465. -> NIL
  13466. : ,"abc" # Collect a transient symbol
  13467. -> "abc"
  13468. : ,(1 2 3) # Collect a list
  13469. -> (1 2 3)
  13470. : *Uni
  13471. -> ("abc" NIL (1 2 3))
  13472. </code></pre>
  13473.  
  13474. <dt><a name="+UB"><code>+UB</code></a>
  13475. <dd>Prefix class for <code><a href="#+Aux">+Aux</a></code> to maintain
  13476. an UB-Tree index instead of the direct values. This allows efficient range
  13477. access to multi-dimensional data. Only positive numeric keys are supported. See
  13478. also <code><a href="#ubIter">ubIter</a></code> and <a
  13479. href="#dbase">Database</a>.
  13480.  
  13481. <pre><code>
  13482. (class +Pos +Entity)
  13483. (rel x (+UB +Aux +Ref +Number) (y z))
  13484. (rel y (+Number))
  13485. (rel z (+Number))
  13486.  
  13487. : (scan (tree 'x '+Pos))
  13488. (288362200753438306 . {13}) {13}
  13489. (348187139486943716 . {16}) {16}
  13490. (605261596962573238 . {11}) {11}
  13491. (638523558602802506 . {7}) {7} # UBKEY of (453062 450921 613956)
  13492. (654697989157410399 . {12}) {12}
  13493. ...
  13494.  
  13495. : (show '{7})
  13496. {7} (+Pos)
  13497. x 453062
  13498. y 450921
  13499. z 613956
  13500. -> {7}
  13501.  
  13502. # Discrete queries work the same way as without the +UB prefix
  13503. : (db 'x '+Pos 453062 'y 450921 'z 613956)
  13504. -> {7}
  13505. : (aux 'x '+Pos 453062 450921 613956)
  13506. -> {7}
  13507. : (? (db x +Pos (453062 450921 613956) @Pos))
  13508. @Pos={7}
  13509. -> NIL
  13510.  
  13511. # Range queries work efficiently with 'collect'. Note that though also Pilog
  13512. queries can handle UB-trees, they may do so sub-optimally for certain ranges.
  13513. : (collect 'x '+Pos (200000 200000 200000) (899999 899999 899999))
  13514. -> ({7} {14} {17} {15})
  13515. </code></pre>
  13516.  
  13517. <dt><a name="u"><code>(u) -> T</code></a>
  13518. <dd>(Debug mode only) Removes <code><a href="#!">!</a></code> all
  13519. breakpoints in all subexpressions of the current breakpoint. Typically used when
  13520. single-stepping a function or method with <code><a
  13521. href="#debug">debug</a></code>. See also <code><a
  13522. href="#d">d</a></code> and <code><a
  13523. href="#unbug">unbug</a></code>.
  13524.  
  13525. <pre><code>
  13526. ! (u) # Unbug subexpression(s) at breakpoint
  13527. -> T
  13528. </code></pre>
  13529.  
  13530. <dt><a name="ubIter"><code>(ubIter 'tree 'dim 'fun 'lst1 'lst2)</code></a>
  13531. <dd>Efficiently iterates through a database <code><a
  13532. href="#+UB">+UB</a></code> tree, by applying <code>fun</code> to all
  13533. values. <code>dim</code> is the number of the key dimensions, <code>lst1</code>
  13534. and <code>lst2</code> specify a range of keys. <code><a
  13535. href="#collect">collect</a></code> uses <code>ubIter</code> internally
  13536. for UB-tree queries. See also <code><a href="#iter">iter</a></code>.
  13537.  
  13538. <pre><code>
  13539. : (ubIter (tree 'x '+Pos) 3 show (200000 200000 200000) (899999 899999 899999))
  13540. {7} (+Pos)
  13541. z 613956
  13542. y 450921
  13543. x 453062
  13544. {14} (+Pos)
  13545. z 771372
  13546. y 262217
  13547. x 862358
  13548. {17} (+Pos)
  13549. z 676836
  13550. y 529576
  13551. x 398229
  13552. {15} (+Pos)
  13553. z 889332
  13554. y 691799
  13555. x 265381
  13556. -> NIL
  13557. </code></pre>
  13558.  
  13559. <dt><a name="udp"><code>(udp 'any1 'any2 'any3) -> any</code></a>
  13560. <dt><code>(udp 'cnt) -> any</code>
  13561. <dd>Simple unidirectional sending/receiving of UDP packets. In the first form,
  13562. <code>any3</code> is sent to a UDP server listening at host <code>any1</code>,
  13563. port <code>any2</code>. In the second form, one item is received from a UDP
  13564. socket <code>cnt</code>, established with <code><a
  13565. href="#port">port</a></code>. See also <code><a
  13566. href="#listen">listen</a></code> and <code><a
  13567. href="#connect">connect</a></code>.
  13568.  
  13569. <pre><code>
  13570. # First session
  13571. : (port T 6666)
  13572. -> 3
  13573. : (udp 3) # Receive a datagram
  13574.  
  13575. # Second session (on the same machine)
  13576. : (udp "localhost" 6666 '(a b c))
  13577. -> (a b c)
  13578.  
  13579. # First session
  13580. -> (a b c)
  13581. </code></pre>
  13582.  
  13583. <dt><a name="ultimo"><code>(ultimo 'y 'm) -> cnt</code></a>
  13584. <dd>Returns the <code><a href="#date">date</a></code> of the last day
  13585. of the month <code>m</code> in the year <code>y</code>. See also <code><a
  13586. href="#day">day</a></code> and <code><a
  13587. href="#week">week</a></code>.
  13588.  
  13589. <pre><code>
  13590. : (date (ultimo 2007 1))
  13591. -> (2007 1 31)
  13592. : (date (ultimo 2007 2))
  13593. -> (2007 2 28)
  13594. : (date (ultimo 2004 2))
  13595. -> (2004 2 29)
  13596. : (date (ultimo 2000 2))
  13597. -> (2000 2 29)
  13598. : (date (ultimo 1900 2))
  13599. -> (1900 2 28)
  13600. </code></pre>
  13601.  
  13602. <dt><a name="unbug"><code>(unbug 'sym) -> T</code></a>
  13603. <dt><code>(unbug 'sym 'cls) -> T</code>
  13604. <dt><code>(unbug '(sym . cls)) -> T</code>
  13605. <dd>(Debug mode only) Removes all <code><a href="#!">!</a></code>
  13606. breakpoints in the function or method body of sym, as inserted with <code><a
  13607. href="#debug">debug</a></code> or <code><a
  13608. href="#d">d</a></code>, or directly with <code><a
  13609. href="#edit">edit</a></code>. See also <code><a
  13610. href="#u">u</a></code>.
  13611.  
  13612. <pre><code>
  13613. : (pp 'tst)
  13614. (de tst (N)
  13615. (! println (+ 3 N)) ) # 'tst' has a breakpoint '!'
  13616. -> tst
  13617. : (unbug 'tst) # Unbug it
  13618. -> T
  13619. : (pp 'tst) # Restore
  13620. (de tst (N)
  13621. (println (+ 3 N)) )
  13622. </code></pre>
  13623.  
  13624. <dt><a name="undef"><code>(undef 'sym) -> fun</code></a>
  13625. <dt><code>(undef 'sym 'cls) -> fun</code>
  13626. <dt><code>(undef '(sym . cls)) -> fun</code>
  13627. <dd>Undefines the function or method <code>sym</code>. Returns the previous
  13628. definition. See also <code><a href="#de">de</a></code>, <code><a
  13629. href="#dm">dm</a></code>, <code><a href="refD.html#def">def</a></code>
  13630. and <code><a href="#redef">redef</a></code>.
  13631.  
  13632. <pre><code>
  13633. : (de hello () "Hello world!")
  13634. -> hello
  13635. : hello
  13636. -> (NIL "Hello world!")
  13637. : (undef 'hello)
  13638. -> (NIL "Hello world!")
  13639. : hello
  13640. -> NIL
  13641. </code></pre>
  13642.  
  13643. <dt><a name="unify"><code>(unify 'any) -> lst</code></a>
  13644. <dd>Unifies <code>any</code> with the current <a href="#pilog">Pilog</a>
  13645. environment at the current level and with a value of <code>NIL</code>, and
  13646. returns the new environment or <code>NIL</code> if not successful. See also
  13647. <code><a href="#prove">prove</a></code> and <code><a
  13648. href="#->">-&gt</a></code>.
  13649.  
  13650. <pre><code>
  13651. : (? (^ @A (unify '(@B @C))))
  13652. @A=(((NIL . @C) 0 . @C) ((NIL . @B) 0 . @B) T)
  13653. </code></pre>
  13654.  
  13655. <dt><a name="uniq"><code>(uniq 'lst) -> lst</code></a>
  13656. <dd>Returns a unique list, by eliminating all duplicate elements from
  13657. <code>lst</code>. See also <a href="#cmp">Comparing</a>, <code><a
  13658. href="#sort">sort</a></code> and <code><a
  13659. href="#group">group</a></code>.
  13660.  
  13661. <pre><code>
  13662. : (uniq (2 4 6 1 2 3 4 5 6 1 3 5))
  13663. -> (2 4 6 1 3 5)
  13664. </code></pre>
  13665.  
  13666. <dt><a name="uniq/2"><code>uniq/2</code></a>
  13667. <dd><a href="#pilog">Pilog</a> predicate that succeeds if the second
  13668. argument is not yet stored in the first argument's index structure. <code><a
  13669. href="#idx">idx</a></code> is used internally storing for the values
  13670. and checking for uniqueness. See also <code><a
  13671. href="#member/2">member/2</a></code>.
  13672.  
  13673. <pre><code>
  13674. : (let U NIL
  13675. (? (lst @X (a b c b c d)) (uniq U @X)) )
  13676. @X=a
  13677. @X=b
  13678. @X=c
  13679. @X=d
  13680. -> NIL
  13681. : (solve '((^ @B (box)) (lst @X (a b c b c d)) (uniq @B @X)) @X)
  13682. -> (a b c d)
  13683. </code></pre>
  13684.  
  13685. <dt><a name="unless"><code>(unless 'any . prg) -> any</code></a>
  13686. <dd>Conditional execution: When the condition <code>any</code> evaluates to
  13687. non-<code>NIL</code>, <code>NIL</code> is returned. Otherwise <code>prg</code>
  13688. is executed and the result returned. See also <code><a
  13689. href="#when">when</a></code>.
  13690.  
  13691. <pre><code>
  13692. : (unless (= 3 3) (println 'Strange 'result))
  13693. -> NIL
  13694. : (unless (= 3 4) (println 'Strange 'result))
  13695. Strange result
  13696. -> result
  13697. </code></pre>
  13698.  
  13699. <dt><a name="until"><code>(until 'any . prg) -> any</code></a>
  13700. <dd>Conditional loop: While the condition <code>any</code> evaluates to
  13701. <code>NIL</code>, <code>prg</code> is repeatedly executed. If <code>prg</code>
  13702. is never executed, <code>NIL</code> is returned. Otherwise the result of
  13703. <code>prg</code> is returned. See also <code><a
  13704. href="#while">while</a></code>.
  13705.  
  13706. <pre><code>
  13707. : (until (=T (setq N (read)))
  13708. (println 'square (* N N)) )
  13709. 4
  13710. square 16
  13711. 9
  13712. square 81
  13713. T
  13714. -> 81
  13715. </code></pre>
  13716.  
  13717. <dt><a name="untrace"><code>(untrace 'sym) -> sym</code></a>
  13718. <dt><code>(untrace 'sym 'cls) -> sym</code>
  13719. <dt><code>(untrace '(sym . cls)) -> sym</code>
  13720. <dd>(Debug mode only) Removes the <code><a href="#$">$</a></code> trace
  13721. function call at the beginning of the function or method body of
  13722. <code>sym</code>, so that no more trace information will be printed before and
  13723. after execution. Built-in functions (C-function pointer) are automatically
  13724. converted to their original form (see <code><a
  13725. href="#subr">subr</a></code>). See also <code><a
  13726. href="#trace">trace</a></code> and <code><a
  13727. href="#traceAll">traceAll</a></code>.
  13728.  
  13729. <pre><code>
  13730. : (trace '+) # Trace the '+' function
  13731. -> +
  13732. : +
  13733. -> (@ ($ + @ (pass $385455126))) # Modified for tracing
  13734. : (untrace '+) # Untrace '+'
  13735. -> +
  13736. : +
  13737. -> 67319120 # Back to original form
  13738. </code></pre>
  13739.  
  13740. <dt><a name="up"><code>(up [cnt] sym ['val]) -> any</code></a>
  13741. <dd>Looks up (or modifies) the <code>cnt</code>'th previously saved value of
  13742. <code>sym</code> in the corresponding enclosing environment. If <code>cnt</code>
  13743. is not given, 1 is used. The 64-bit version also allows to omit the
  13744. <code>sym</code> argument, then the corresponding expression (function or method
  13745. call) is returned. See also <code><a href="#eval">eval</a></code>,
  13746. <code><a href="#run">run</a></code>, <code><a
  13747. href="#trail">trail</a></code> and <code><a
  13748. href="#env">env</a></code>.
  13749.  
  13750. <pre><code>
  13751. : (let N 1 ((quote (N) (println N (up N))) 2))
  13752. 2 1
  13753. -> 1
  13754. : (let N 1 ((quote (N) (println N (up N) (up N 7))) 2) N)
  13755. 2 1 7
  13756. -> 7
  13757.  
  13758. : (de foo (N)
  13759. (println (up)) # 64-bits only
  13760. (inc N) )
  13761. -> foo
  13762. : (foo 7)
  13763. (foo 7)
  13764. -> 8
  13765. </code></pre>
  13766.  
  13767. <dt><a name="upd"><code>(upd sym ..) -> lst</code></a>
  13768. <dd>Synchronizes the internal state of all passed (external) symbols by passing
  13769. them to <code><a href="#wipe">wipe</a></code>. <code>upd</code> is the
  13770. standard function passed to <code><a href="#commit">commit</a></code>
  13771. during database <code><a href="#trans">transactions</a></code>.
  13772.  
  13773. <pre><code>
  13774. (commit 'upd) # Commit changes, informing all sister processes
  13775. </code></pre>
  13776.  
  13777. <dt><a name="update"><code>(update 'obj ['var]) -> obj</code></a>
  13778. <dd>(Debug mode only) Interactive database function for modifying external
  13779. symbols. When called only with an <code>obj</code> argument, <code>update</code>
  13780. steps through the value and all properties of that object (and recursively also
  13781. through substructures) and allows to edit them with the console line editor.
  13782. When the <code>var</code> argument is given, only that single property is handed
  13783. to the editor. To delete a property, <code>NIL</code> must be explicitly
  13784. entered. <code>update</code> will correctly handle all <a
  13785. href="#er">entity/relation</a> mechanisms. See also <code><a
  13786. href="#select">select</a></code>, <code><a
  13787. href="#edit">edit</a></code> and <a href="ref.html#dbase">Database</a>.
  13788.  
  13789. <pre><code>
  13790. : (show '{3-1}) # Show item 1
  13791. {3-1} (+Item)
  13792. nr 1
  13793. pr 29900
  13794. inv 100
  13795. sup {2-1}
  13796. nm "Main Part"
  13797. -> {3-1}
  13798.  
  13799. : (update '{3-1} 'pr) # Update the prices of that item
  13800. {3-1} pr 299.00 # The cursor is right behind "299.00"
  13801. -> {3-1}
  13802. </code></pre>
  13803.  
  13804. <dt><a name="upp?"><code>(upp? 'any) -> sym | NIL</code></a> <dd>Returns
  13805. <code>any</code> when the argument is a string (symbol) that starts with an
  13806. uppercase character. See also <code><a href="#uppc">uppc</a></code> and
  13807. <code><a href="#low?">low?</a></code>
  13808.  
  13809. <pre><code>
  13810. : (upp? "A")
  13811. -> "A"
  13812. : (upp? "a")
  13813. -> NIL
  13814. : (upp? 123)
  13815. -> NIL
  13816. : (upp? ".")
  13817. -> NIL
  13818. </code></pre>
  13819.  
  13820. <dt><a name="uppc"><code>(uppc 'any) -> any</code></a>
  13821. <dd>Upper case conversion: If <code>any</code> is not a symbol, it is returned
  13822. as it is. Otherwise, a new transient symbol with all characters of
  13823. <code>any</code>, converted to upper case, is returned. See also <code><a
  13824. href="#lowc">lowc</a></code>, <code><a
  13825. href="#fold">fold</a></code> and <code><a
  13826. href="#upp?">upp?</a></code>.
  13827.  
  13828. <pre><code>
  13829. : (uppc 123)
  13830. -> 123
  13831. : (uppc "abc")
  13832. -> "ABC"
  13833. : (uppc 'car)
  13834. -> "CAR"
  13835. </code></pre>
  13836.  
  13837. <dt><a name="use"><code>(use sym . prg) -> any</code></a>
  13838. <dt><code>(use (sym ..) . prg) -> any</code>
  13839. <dd>Defines local variables. The value of the symbol <code>sym</code> - or the
  13840. values of the symbols <code>sym</code> in the list of the second form - are
  13841. saved, <code>prg</code> is executed, then the symbols are restored to their
  13842. original values. During execution of <code>prg</code>, the values of the symbols
  13843. can be temporarily modified. The return value is the result of <code>prg</code>.
  13844. See also <code><a href="#bind">bind</a></code>, <code><a
  13845. href="#job">job</a></code> and <code><a
  13846. href="#let">let</a></code>.
  13847.  
  13848. <pre><code>
  13849. : (setq X 123 Y 456)
  13850. -> 456
  13851. : (use (X Y) (setq X 3 Y 4) (* X Y))
  13852. -> 12
  13853. : X
  13854. -> 123
  13855. : Y
  13856. -> 456
  13857. </code></pre>
  13858.  
  13859. <dt><a name="useKey"><code>(useKey 'sym 'cls ['hook]) -> num</code></a>
  13860. <dd>Generates or reuses a key for a database tree, by randomly trying to locate
  13861. a free number. See also <code><a href="#genKey">genKey</a></code>.
  13862.  
  13863. <pre><code>
  13864. : (maxKey (tree 'nr '+Item))
  13865. -> 8
  13866. : (useKey 'nr '+Item)
  13867. -> 12
  13868. </code></pre>
  13869.  
  13870. <dt><a name="usec"><code>(usec ['flg]) -> num</code></a>
  13871. <dd>Returns a number of microseconds. If <code>flg</code> is
  13872. non-<code>NIL</code>, the microsecond fraction of the last call to <code><a
  13873. href="#time">time</a></code> is returned, otherwise the number of
  13874. microseconds since interpreter startup. See also <code><a
  13875. href="#date">date</a></code> and <code><a
  13876. href="#tick">tick</a></code>.
  13877.  
  13878. <pre><code>
  13879. : (usec)
  13880. -> 1154702479219050
  13881. : (list (date (date)) (time (time T)) (usec T))
  13882. -> ((2013 1 4) (10 12 39) 483321)
  13883. </code></pre>
  13884.  
  13885. </dl>
  13886.  
  13887. <h1><a name="V">V</a></h1>
  13888.  
  13889. <dl>
  13890.  
  13891. <dt><a name="val"><code>(val 'var) -> any</code></a>
  13892. <dd>Returns the current value of <code>var</code>. See also <code><a
  13893. href="#setq">setq</a></code>, <code><a
  13894. href="#set">set</a></code> and <code><a
  13895. href="#def">def</a></code>.
  13896.  
  13897. <pre><code>
  13898. : (setq L '(a b c))
  13899. -> (a b c)
  13900. : (val 'L)
  13901. -> (a b c)
  13902. : (val (cdr L))
  13903. -> b
  13904. </code></pre>
  13905.  
  13906. <dt><a name="val/3"><code>val/3</code></a>
  13907. <dd><a href="#pilog">Pilog</a> predicate that returns the value of an
  13908. object's attribute. Typically used in database queries. The first argument is a
  13909. Pilog variable to bind the value, the second is the object, and the third and
  13910. following arguments are used to apply the <code><a
  13911. href="#get">get</a></code> algorithm to that object. See also <code><a
  13912. href="#db/3">db/3</a></code> and <code><a
  13913. href="#select/3">select/3</a></code>.
  13914.  
  13915. <pre><code>
  13916. : (?
  13917. (db nr +Item (2 . 5) @Item) # Fetch articles 2 through 5
  13918. (val @Nm @Item nm) # Get item description
  13919. (val @Sup @Item sup nm) ) # and supplier's name
  13920. @Item={3-2} @Nm="Spare Part" @Sup="Seven Oaks Ltd."
  13921. @Item={3-3} @Nm="Auxiliary Construction" @Sup="Active Parts Inc."
  13922. @Item={3-4} @Nm="Enhancement Additive" @Sup="Seven Oaks Ltd."
  13923. @Item={3-5} @Nm="Metal Fittings" @Sup="Active Parts Inc."
  13924. -> NIL
  13925. </code></pre>
  13926.  
  13927. <dt><a name="var"><code>(var sym . any) -> any</code></a>
  13928. <dt><code>(var (sym . cls) . any) -> any</code>
  13929. <dd>Defines a class variable <code>sym</code> with the initial value
  13930. <code>any</code> for the current class, implicitly given by the value of the
  13931. global variable <code><a href="#*Class">*Class</a></code>, or - in the
  13932. second form - for the explicitly given class cls. See also <a
  13933. href="#oop">OO Concepts</a>, <code><a
  13934. href="#rel">rel</a></code> and <code><a
  13935. href="#var:">var:</a></code>.
  13936.  
  13937. <pre><code>
  13938. : (class +A)
  13939. -> +A
  13940. : (var a . 1)
  13941. -> 1
  13942. : (var b . 2)
  13943. -> 2
  13944. : (show '+A)
  13945. +A NIL
  13946. b 2
  13947. a 1
  13948. -> +A
  13949. </code></pre>
  13950.  
  13951. <dt><a name="var:"><code>(var: sym) -> any</code></a>
  13952. <dd>Fetches the value of a class variable <code>sym</code> for the current
  13953. object <code><a href="#This">This</a></code>, by searching the property
  13954. lists of its class(es) and supperclasses. See also <a href="#oop">OO
  13955. Concepts</a>, <code><a href="#var">var</a></code>, <code><a
  13956. href="#with">with</a></code>, <code><a
  13957. href="#meta">meta</a></code>, <code><a href="ref_.html#:">:</a></code>,
  13958. <code><a href="#=:">=:</a></code> and <code><a
  13959. href="#::">::</a></code>.
  13960.  
  13961. <pre><code>
  13962. : (class +A)
  13963. -> +A
  13964. : (var a . 1)
  13965. -> 1
  13966. : (var b . 2)
  13967. -> 2
  13968. : (object 'O '(+A) 'a 9 'b 8)
  13969. -> O
  13970. : (with 'O (list (: a) (: b) (var: a) (var: b)))
  13971. -> (9 8 1 2)
  13972. </code></pre>
  13973.  
  13974. <dt><a name="version"><code>(version ['flg]) -> lst</code></a>
  13975. <dd>Prints the current version as a string of dot-separated numbers, and returns
  13976. the current version as a list of numbers. The JVM- and C-versions print an
  13977. additional "JVM" or "C", respectively, separated by a space. When
  13978. <code>flg</code> is non-NIL, printing is suppressed. See also <code><a
  13979. href="#*CPU">*CPU</a></code> and <code><a
  13980. href="#*OS">*OS</a></code>.
  13981.  
  13982. <pre><code>
  13983. $ pil -version
  13984. 3.0.1.22
  13985. : (version T)
  13986. -> (3 0 1 22)
  13987. </code></pre>
  13988.  
  13989. <dt><a name="vi"><code>(vi 'sym) -> sym</code></a>
  13990. <dt><code>(vi 'sym 'cls) -> sym</code>
  13991. <dt><code>(vi '(sym . cls)) -> sym</code>
  13992. <dt><code>(vi) -> NIL</code>
  13993. <dd>(Debug mode only) Opens the "vi" editor on the function or method definition
  13994. of <code>sym</code>. A call to <code><a href="#ld">ld</a></code>
  13995. thereafter will <code><a href="#load">load</a></code> the modified
  13996. file. A call without arguments permanently switches the REPL line editor and the
  13997. <code><a href="#edit">edit</a></code> function to "vi" mode. See also
  13998. <code><a href="#doc">doc</a></code>, <code><a
  13999. href="#edit">edit</a></code>, <code><a
  14000. href="#em">em</a></code>, <code><a
  14001. href="#*Dbg">*Dbg</a></code>, <code><a
  14002. href="#debug">debug</a></code> and <code><a
  14003. href="#pp">pp</a></code>.
  14004.  
  14005. <pre><code>
  14006. : (vi 'url> '+CuSu) # Edit the method's source code, then exit from 'vi'
  14007. -> T
  14008. </code></pre>
  14009.  
  14010. <dt><a name="view"><code>(view 'lst ['T]) -> any</code></a>
  14011. <dd>Views <code>lst</code> as tree-structured ASCII graphics. When the
  14012. <code>T</code> argument is given, <code>lst</code> should be a binary tree
  14013. structure (as generated by <code><a href="#idx">idx</a></code>), which
  14014. is then shown as a left-rotated tree. See also <code><a
  14015. href="#pretty">pretty</a></code> and <code><a
  14016. href="#show">show</a></code>.
  14017.  
  14018. <pre><code>
  14019. : (balance 'I '(a b c d e f g h i j k l m n o))
  14020. -> NIL
  14021. : I
  14022. -> (h (d (b (a) c) f (e) g) l (j (i) k) n (m) o)
  14023.  
  14024. : (view I)
  14025. +-- h
  14026. |
  14027. +---+-- d
  14028. | |
  14029. | +---+-- b
  14030. | | |
  14031. | | +---+-- a
  14032. | | |
  14033. | | +-- c
  14034. | |
  14035. | +-- f
  14036. | |
  14037. | +---+-- e
  14038. | |
  14039. | +-- g
  14040. |
  14041. +-- l
  14042. |
  14043. +---+-- j
  14044. | |
  14045. | +---+-- i
  14046. | |
  14047. | +-- k
  14048. |
  14049. +-- n
  14050. |
  14051. +---+-- m
  14052. |
  14053. +-- o
  14054. -> NIL
  14055.  
  14056. : (view I T)
  14057. o
  14058. n
  14059. m
  14060. l
  14061. k
  14062. j
  14063. i
  14064. h
  14065. g
  14066. f
  14067. e
  14068. d
  14069. c
  14070. b
  14071. a
  14072. -> NIL
  14073. </code></pre>
  14074.  
  14075. </dl>
  14076.  
  14077. <h1><a name="W">W</a></h1>
  14078.  
  14079. <dl>
  14080.  
  14081. <dt><a name="wait"><code>(wait ['cnt] . prg) -> any</code></a>
  14082. <dd>Waits for a condition. While the result of the execution of <code>prg</code>
  14083. is <code>NIL</code>, a <code>select</code> system call is executed for all file
  14084. descriptors and timers in the <code>VAL</code> of the global variable <code><a
  14085. href="#*Run">*Run</a></code>. When <code>cnt</code> is
  14086. non-<code>NIL</code>, the waiting time is limited to <code>cnt</code>
  14087. milliseconds. Returns the result of <code>prg</code>. See also <code><a
  14088. href="#key">key</a></code> and <code><a
  14089. href="#sync">sync</a></code>.
  14090.  
  14091. <pre><code>
  14092. : (wait 2000) # Wait 2 seconds
  14093. -> NIL
  14094. : (prog
  14095. (zero *Cnt)
  14096. (setq *Run # Install background loop
  14097. '((-2000 0 (println (inc '*Cnt)))) ) # Increment '*Cnt' every 2 sec
  14098. (wait NIL (> *Cnt 6)) # Wait until > 6
  14099. (off *Run) )
  14100. 1 # Waiting ..
  14101. 2
  14102. 3
  14103. 4
  14104. 5
  14105. 6
  14106. 7
  14107. -> NIL
  14108. </code></pre>
  14109.  
  14110. <dt><a name="week"><code>(week 'dat) -> num</code></a>
  14111. <dd>Returns the number of the week for a given <code><a
  14112. href="#date">date</a></code> <code>dat</code>. See also <code><a
  14113. href="#day">day</a></code>, <code><a
  14114. href="#ultimo">ultimo</a></code>, <code><a
  14115. href="#datStr">datStr</a></code> and <code><a
  14116. href="#strDat">strDat</a></code>.
  14117.  
  14118. <pre><code>
  14119. : (datStr (date))
  14120. -> "2007-06-01"
  14121. : (week (date))
  14122. -> 22
  14123. </code></pre>
  14124.  
  14125. <dt><a name="when"><code>(when 'any . prg) -> any</code></a>
  14126. <dd>Conditional execution: When the condition <code>any</code> evaluates to
  14127. non-<code>NIL</code>, <code>prg</code> is executed and the result is returned.
  14128. Otherwise <code>NIL</code> is returned. See also <code><a
  14129. href="#unless">unless</a></code>.
  14130.  
  14131. <pre><code>
  14132. : (when (> 4 3) (println 'OK) (println 'Good))
  14133. OK
  14134. Good
  14135. -> Good
  14136. </code></pre>
  14137.  
  14138. <dt><a name="while"><code>(while 'any . prg) -> any</code></a>
  14139. <dd>Conditional loop: While the condition <code>any</code> evaluates to
  14140. non-<code>NIL</code>, <code>prg</code> is repeatedly executed. If
  14141. <code>prg</code> is never executed, <code>NIL</code> is returned. Otherwise the
  14142. result of <code>prg</code> is returned. See also <code><a
  14143. href="#until">until</a></code>.
  14144.  
  14145. <pre><code>
  14146. : (while (read)
  14147. (println 'got: @) )
  14148. abc
  14149. got: abc
  14150. 1234
  14151. got: 1234
  14152. NIL
  14153. -> 1234
  14154. </code></pre>
  14155.  
  14156. <dt><a name="what"><code>(what 'sym) -> lst</code></a>
  14157. <dd>(Debug mode only) Returns a list of all internal symbols that match the
  14158. pattern string <code>sym</code>. See also <code><a
  14159. href="#match">match</a></code>, <code><a
  14160. href="#who">who</a></code>, <code><a
  14161. href="#has">has</a></code> and <code><a
  14162. href="#can">can</a></code>.
  14163.  
  14164. <pre><code>
  14165. : (what "cd@dr")
  14166. -> (cdaddr cdaadr cddr cddddr cdddr cddadr cdadr)
  14167. </code></pre>
  14168.  
  14169. <dt><a name="who"><code>(who 'any) -> lst</code></a>
  14170. <dd>(Debug mode only) Returns a list of all functions or method definitions that
  14171. contain the atom or pattern <code>any</code>. See also <code><a
  14172. href="#match">match</a></code>, <code><a
  14173. href="#what">what</a></code>, <code><a
  14174. href="#has">has</a></code> and <code><a
  14175. href="#can">can</a></code>.
  14176.  
  14177. <pre><code>
  14178. : (who 'caddr) # Who is using 'caddr'?
  14179. -> ($dat lint1 expDat datStr $tim tim$ mail _gen dat$ datSym)
  14180.  
  14181. : (who "Type error")
  14182. -> ((mis> . +Link) *Uni (mis> . +Joint))
  14183.  
  14184. : (more (who "Type error") pp) # Pretty print all results
  14185. (dm (mis> . +Link) (Val Obj)
  14186. (and
  14187. Val
  14188. (nor (isa (: type) Val) (canQuery Val))
  14189. "Type error" ) )
  14190. . # Stop
  14191. -> T
  14192. </code></pre>
  14193.  
  14194. <dt><a name="wipe"><code>(wipe 'sym|lst) -> sym|lst</code></a>
  14195. <dd>Clears the <code>VAL</code> and the property list of <code>sym</code>, or of
  14196. all symbols in the list <code>lst</code>. When a symbol is an external symbol,
  14197. its state is also set to "not loaded". Does nothing when <code>sym</code> is an
  14198. external symbol that has been modified or deleted ("dirty").
  14199.  
  14200. <pre><code>
  14201. : (setq A (1 2 3 4))
  14202. -> (1 2 3 4)
  14203. : (put 'A 'a 1)
  14204. -> 1
  14205. : (put 'A 'b 2)
  14206. -> 2
  14207. : (show 'A)
  14208. A (1 2 3 4)
  14209. b 2
  14210. a 1
  14211. -> A
  14212. : (wipe 'A)
  14213. -> A
  14214. : (show 'A)
  14215. A NIL
  14216. -> A
  14217. </code></pre>
  14218.  
  14219. <dt><a name="with"><code>(with 'sym . prg) -> any</code></a>
  14220. <dd>Saves the current object <code>This</code> and sets it to the new value
  14221. <code>sym</code>. Then <code>prg</code> is executed, and <code>This</code> is
  14222. restored to its previous value. The return value is the result of
  14223. <code>prg</code>. Used typically to access the local data of <code>sym</code> in
  14224. the same manner as inside a method body. <code>prg</code> is not executed (and
  14225. <code>NIL</code> is returned) when <code>sym</code> is <code>NIL</code>.
  14226. <code>(with 'X . prg)</code> is equivalent to <code>(let? This 'X . prg)</code>.
  14227.  
  14228. <pre><code>
  14229. : (put 'X 'a 1)
  14230. -> 1
  14231. : (put 'X 'b 2)
  14232. -> 2
  14233. : (with 'X (list (: a) (: b)))
  14234. -> (1 2)
  14235. </code></pre>
  14236.  
  14237. <dt><a name="wr"><code>(wr 'cnt ..) -> cnt</code></a>
  14238. <dd>Writes all <code>cnt</code> arguments as raw bytes to the current output
  14239. channel. See also <code><a href="#rd">rd</a></code> and <code><a
  14240. href="#pr">pr</a></code>.
  14241.  
  14242. <pre><code>
  14243. : (out "x" (wr 1 255 257)) # Write to "x"
  14244. -> 257
  14245. : (hd "x")
  14246. 00000000 01 FF 01 ...
  14247. -> NIL
  14248. </code></pre>
  14249.  
  14250. <dt><a name="wrap"><code>(wrap 'cnt 'lst) -> sym</code></a>
  14251. <dd>Returns a transient symbol with all characters in <code>lst</code> <code><a
  14252. href="#pack">pack</a></code>ed in lines with a maximal length of
  14253. <code>cnt</code>. See also <code><a href="#tab">tab</a></code>,
  14254. <code><a href="#align">align</a></code> and <code><a
  14255. href="#center">center</a></code>.
  14256.  
  14257. <pre><code>
  14258. : (wrap 20 (chop "The quick brown fox jumps over the lazy dog"))
  14259. -> "The quick brown fox^Jjumps over the lazy^Jdog"
  14260. : (wrap 8 (chop "The quick brown fox jumps over the lazy dog"))
  14261. -> "The^Jquick^Jbrown^Jfox^Jjumps^Jover the^Jlazy dog"
  14262. </code></pre>
  14263.  
  14264. </dl>
  14265.  
  14266. <h1><a name="X">X</a></h1>
  14267.  
  14268. <dl>
  14269.  
  14270. <dt><a name="xchg"><code>(xchg 'var 'var ..) -> any</code></a>
  14271. <dd>Exchange the values of successive <code>var</code> argument pairs. See also
  14272. <code><a href="#swap">swap</a></code> and <code><a
  14273. href="#set">set</a></code>.
  14274.  
  14275. <pre><code>
  14276. : (setq A 1 B 2 C '(a b c))
  14277. -> (a b c)
  14278. : (xchg 'A C 'B (cdr C))
  14279. -> 2
  14280. : A
  14281. -> a
  14282. : B
  14283. -> b
  14284. : C
  14285. -> (1 2 c)
  14286. </code></pre>
  14287.  
  14288. <dt><a name="xor"><code>(xor 'any 'any) -> flg</code></a>
  14289. <dd>Returns T if exactly one of the arguments evaluates to non-<code>NIL</code>.
  14290.  
  14291. <pre><code>
  14292. : (xor T NIL)
  14293. -> T
  14294. : (xor T T)
  14295. -> NIL
  14296. </code></pre>
  14297.  
  14298. <dt><a name="x|"><code>(x| 'num ..) -> num</code></a>
  14299. <dd>Returns the bitwise <code>XOR</code> of all <code>num</code> arguments. When
  14300. one of the arguments evaluates to <code>NIL</code>, it is returned immediately.
  14301. See also <code><a href="#&">&</a></code>, <code><a
  14302. href="#|">|</a></code> and <code><a
  14303. href="#bit?">bit?</a></code>.
  14304.  
  14305. <pre><code>
  14306. : (x| 2 7)
  14307. -> 5
  14308. : (x| 2 7 1)
  14309. -> 4
  14310. </code></pre>
  14311.  
  14312. </dl>
  14313.  
  14314. <h1><a name="Y">Y</a></h1>
  14315.  
  14316. <dl>
  14317.  
  14318. <dt><a name="yield"><code>(yield 'any ['sym]) -> any</code></a>
  14319. <dd>(64-bit version only) Transfers control from the current <a
  14320. href="#coroutines">coroutine</a> back to the caller (when the
  14321. <code>sym</code> tag is not given), or to some other coroutine (specified by
  14322. <code>sym</code>) to continue execution at the point where that coroutine had
  14323. called <code>yield</code> before. In the first case, the value <code>any</code>
  14324. will be returned from the corresponding <code><a
  14325. href="#co">co</a></code> call, in the second case it will be the return
  14326. value of that <code>yield</code> call. See also <code><a
  14327. href="#stack">stack</a></code>, <code><a
  14328. href="#catch">catch</a></code> and <code><a
  14329. href="#throw">throw</a></code>.
  14330.  
  14331. <pre><code>
  14332. : (co "rt1" # Start first routine
  14333. (msg (yield 1) " in rt1 from rt2") # Return '1', wait for value from "rt2"
  14334. 7 ) # Then return '7'
  14335. -> 1
  14336.  
  14337. : (co "rt2" # Start second routine
  14338. (yield 2 "rt1") ) # Send '2' to "rt1"
  14339. 2 in rt1 from rt2
  14340. -> 7
  14341. </code></pre>
  14342.  
  14343. <dt><a name="yoke"><code>(yoke 'any ..) -> any</code></a>
  14344. <dd>Inserts one or several new elements <code>any</code> in front of the list in
  14345. the current <code><a href="#make">make</a></code> environment.
  14346. <code>yoke</code> returns the last inserted argument. See also <code><a
  14347. href="#link">link</a></code>, <code><a
  14348. href="#chain">chain</a></code> and <code><a
  14349. href="#made">made</a></code>.
  14350.  
  14351. <pre><code>
  14352. : (make (link 2 3) (yoke 1) (link 4))
  14353. -> (1 2 3 4)
  14354. </code></pre>
  14355.  
  14356. </dl>
  14357.  
  14358. <h1><a name="Z">Z</a></h1>
  14359.  
  14360. <dl>
  14361.  
  14362. <dt><a name="*Zap"><code>*Zap</code></a>
  14363. <dd>A global variable holding a list and a pathname. If given, and the value of
  14364. <code><a href="#*Solo">*Solo</a></code> is <code>NIL</code>, external
  14365. symbols which are no longer accessible can be collected in the CAR, e.g. during
  14366. DB tree processing, and written to the file in the CDR at the next <code><a
  14367. href="#commit">commit</a></code>. A (typically periodic) call to
  14368. <code><a href="#zap_">zap_</a></code> will clean them up later.
  14369.  
  14370. <pre><code>
  14371. : (setq *Zap '(NIL . "db/app/_zap"))
  14372. -> "db/app/_zap"
  14373. </code></pre>
  14374.  
  14375. <dt><a name="zap"><code>(zap 'sym) -> sym</code></a>
  14376. <dd>"Delete" the symbol <code>sym</code>. For internal symbols, that means to
  14377. remove it from the internal index, effectively transforming it to a transient
  14378. symbol. For external symbols, it means to mark it as "deleted", so that upon a
  14379. later <code><a href="#commit">commit</a></code> it will be removed from
  14380. the database file. See also <code><a href="#intern">intern</a></code>.
  14381.  
  14382. <pre><code>
  14383. : (de foo (Lst) (car Lst)) # 'foo' calls 'car'
  14384. -> foo
  14385. : (zap 'car) # Delete the symbol 'car'
  14386. -> "car"
  14387. : (pp 'foo)
  14388. (de foo (Lst)
  14389. ("car" Lst) ) # 'car' is now a transient symbol
  14390. -> foo
  14391. : (foo (1 2 3)) # 'foo' still works
  14392. -> 1
  14393. : (car (1 2 3)) # Reader returns a new 'car' symbol
  14394. !? (car (1 2 3))
  14395. car -- Undefined
  14396. ?
  14397. </code></pre>
  14398.  
  14399. <dt><a name="zapTree"><code>(zapTree 'sym)</code></a>
  14400. <dd>Recursively deletes a tree structure from the database. See also <code><a
  14401. href="#tree">tree</a></code>, <code><a
  14402. href="#chkTree">chkTree</a></code> and <code><a
  14403. href="#prune">prune</a></code>.
  14404.  
  14405. <pre><code>
  14406. : (zapTree (cdr (root (tree 'nm '+Item))))
  14407. </code></pre>
  14408.  
  14409. <dt><a name="zap_"><code>(zap_)</code></a>
  14410. <dd>Delayed deletion (with <code><a href="#zap">zap</a></code>) of
  14411. external symbols which were collected e.g. during DB tree processing. An
  14412. auxiliary file (with the name taken from the CDR of the value of <code><a
  14413. href="#*Zap">*Zap</a></code>, concatenated with a "<code>_</code>"
  14414. character) is used as an intermediary file.
  14415.  
  14416. <pre><code>
  14417. : *Zap
  14418. -> (NIL . "db/app/Z")
  14419. : (call 'ls "-l" "db/app")
  14420. ...
  14421. -rw-r--r-- 1 abu abu 1536 2007-06-23 12:34 Z
  14422. -rw-r--r-- 1 abu abu 1280 2007-05-23 12:15 Z_
  14423. ...
  14424. : (zap_)
  14425. ...
  14426. : (call 'ls "-l" "db/app")
  14427. ...
  14428. -rw-r--r-- 1 abu abu 1536 2007-06-23 12:34 Z_
  14429. ...
  14430. </code></pre>
  14431.  
  14432. <dt><a name="zero"><code>(zero var ..) -> 0</code></a>
  14433. <dd>Stores <code>0</code> in all <code>var</code> arguments. See also <code><a
  14434. href="#one">one</a></code>, <code><a href="refO.html#on">on</a></code>,
  14435. <code><a href="#off">off</a></code> and <code><a
  14436. href="#onOff">onOff</a></code>.
  14437.  
  14438. <pre><code>
  14439. : (zero A B)
  14440. -> 0
  14441. : A
  14442. -> 0
  14443. : B
  14444. -> 0
  14445. </code></pre>
  14446.  
  14447. </dl>
Add Comment
Please, Sign In to add comment
Public Pastes
We use cookies for various purposes including analytics. By continuing to use Pastebin, you agree to our use of cookies as described in the Cookies Policy.  OK, I Understand
Not a member of Pastebin yet?
Sign Up, it unlocks many cool features!