doc/newlisp_manual.html

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
   2 <html>
   3 <head>
   4    <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
   5    <meta name="author" content="Lutz Mueller">
   6    <meta name="keywords" content="newLISP LISP SCHEME programming language manual reference Artificial Intelligence AI NUEVATEC">
   7    <meta name="description" content="newLISP Users Manual and Reference">
   8    <title>newLISP v.9.3.3 Manual and Reference</title>
   9
  10 <style type="text/css" media="screen">
  11
  12
  13 .divider {
  14         margin-top: 2em;
  15         margin-bottom: 1em;
  16         font-family: Times New Roman, Times, serif;
  17         color: #ffAA28;
  18         }
  19
  20 .title {
  21         font-family:Optima, Georgia, Times New Roman, Times, serif;
  22         font-size:456%;
  23         }
  24
  25 .trade {
  26         font-family:Optima, Georgia, Times New Roman, Times, serif;
  27         font-size:100%;
  28         padding-top:16px;
  29         }
  30
  31 span.arw {
  32         color:#303030;
  33         font-size: 100%;
  34         font-weight: bold;
  35         }
  36
  37 span.err {
  38         color:#cc0000;
  39         }
  40
  41 span.comment {
  42         color:#555555;
  43         }
  44
  45 span.operator {
  46         color:#aa0000;
  47         }
  48
  49 span.keyword {
  50         color:#0000aa;
  51         }
  52
  53 span.number {
  54         color:#665500;
  55         }
  56
  57 span.string {
  58         color:#008800;
  59         }
  60
  61 span.function {
  62         color:#dd0000;
  63         }
  64 <!--
  65 span.plus1 {
  66         font-size:"+1";
  67         }
  68 -->
  69
  70 body, h1, h2, h3, h4, p {
  71         font-family: Georgia, Times New Roman, Times, serif;
  72         line-height: 120%;
  73         }
  74
  75 b {
  76     color: #303030;
  77     }
  78
  79 table.list {
  80         border-width: 0px;
  81         padding: 3px;
  82         }
  83
  84 th.list {
  85         font-family:Georgia, Times New Roman, Times, serif;
  86         font-size:0.8em;
  87         font-weight: 700;
  88         }
  89
  90 td.left {
  91         font-family: Andale Mono, Bitstream Vera Sans Mono, Monaco, Courier New;
  92         font-size: 100%;
  93         }
  94
  95 td.right {
  96         font-family:Georgia, Times New Roman, Times, serif;
  97         font-size: 100%;
  98         font-style: italic;
  99         }
 100
 101 pre {
 102         font-family: Andale Mono, "Bitstream Vera Sans Mono", Monaco, "Courier New";
 103         font-size: 100%;
 104         }
 105
 106 tt {
 107         font-family: Andale Mono, "Bitstream Vera Sans Mono", Monaco, "Courier New";
 108         font-size: 100%;
 109         }
 110
 111 -->
 112 </style>
 113
 114 </head>
 115 <body text="#000000" bgcolor="#FFFFFF" link="#376590" vlink="#551A8B" alink="#ffAA28">
 116
 117 <br /><br /><br /><br /><br /><br /><br /><br /><br />
 118
 119
 120 <table align="center"><tr>
 121 <td  class="title">newLISP</td>
 122 <td valign="top" class="trade">&trade;</td>
 123 </tr></table>
 124
 125 <br />
 126
 127 <center>
 128 <b>For BSDs, Linux, Mac OS X, Solaris and Win32</b>
 129 </center>
 130
 131 <center>
 132 <h2>Users Manual and Reference v.9.3.3</h2>
 133 </center>
 134
 135 <br /><br /><br /><br />
 136 <center>
 137 <span style="line-height:80%;">
 138 <font size=-2>
 139 <br />Copyright &copy; 2008 Lutz Mueller.&nbsp; <a href="http://www.nuevatec.com">www.nuevatec.com</a>. All rights reserved.<br /><br />
 140 Permission is granted to copy, distribute and/or modify this document
 141 under the terms of the GNU Free Documentation License,<br /> Version 1.2 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts,<br /> and no Back-Cover Texts. A copy of the license is included in the section entitled
 142 <a href="#GNUFDL">GNU Free Documentation License</a>.<br /><br />
 143
 144 The accompanying software is protected by the <a href="#GNUGPL">GNU General Public License</a> V.3, June 2008.<br /><br />
 145 newLISP is a registered trademark of Lutz Mueller.
 146
 147 </font>
 148 </span>
 149 </center>
 150 <br /><br /><br />
 151
 152 <center><h1>Contents</h1></center>
 153
 154 <h3>Users Manual</h3>
 155
 156 <ol>
 157 <li><a href="#introduction">Introduction</a></li>
 158 <li><a href="#deprecated">Deprecated functions and future changes</a></li>
 159 <li><a href="#options">Command line options, startup and directories</a>
 160   <ul>
 161   <li><a href="#url_files">Specifying files as URLs</a></li>
 162   <li><a href="#stack_size">Stack size</a></li>
 163   <li><a href="#max_mem">Maximum memory usage</a></li>
 164   <li><a href="#working_dir">Specifiying the working directory</a></li>
 165   <li><a href="#prompt">Suppressing the prompt and HTTP processing</a></li>
 166   <li><a href="#http_mode">HTTP only server mode</a></li>
 167   <li><a href="#tcpip_server">newLISP as a TCP/IP server</a></li>
 168   <li><a href="#daemon">TCP/IP daemon mode</a></li>
 169   <li><a href="#local_domain_server">Local domain UNIX socket server</a></li>
 170   <li><a href="#inetd_daemon"><tt>inetd</tt> daemon mode</a></li>
 171   <li><a href="#direct_exec">Direct execution mode</a></li>
 172   <li><a href="#logging">Logging I/O</a></li>
 173   <li><a href="#cmd_help">Command line help summary</a></li>
 174   <li><a href="#initialization">The initialization file <tt>init.lsp</tt></a></li>
 175   <li><a href="#directories_unix">Directories on Linux, BSD, Mac OS X</a></li>
 176   <li><a href="#directories_win32">Directories on Win32</a></li>
 177   <li><a href="#environment">Environment variable NEWLISPDIR</a></li>
 178   </ul>
 179
 180 </li>
 181 <li><a href="#shared-lib">Shared library module for Linux/BSD</a></li>
 182 <li><a href="#dll">DLL module for Win32 versions</a></li>
 183 <li><a href="#expressions">Evaluating newLISP expressions</a>
 184   <ul>
 185   <li><a href="#int_float">Integer and floating point data types and operators</a></li>
 186   <li><a href="#eval_rules">Evaluation rules and data types</a></li>
 187   </ul>
 188
 189 </li>
 190 <li><a href="#lambda_expressions">Lambda expressions in newLISP</a></li>
 191 <li><a href="#nil_and_true"><tt>nil</tt>, <tt>true</tt>, <tt>cons</tt> and <tt>()</tt> in newLISP</a></li>
 192 <li><a href="#arrays">Arrays</a></li>
 193 <li><a href="#hash">Dictionaries or Hash tables</a></li>
 194 <li><a href="#indexing">Indexing elements of strings, lists and arrays</a>
 195   <ul>
 196
 197   <li><a href="#implicit_indexing">Implicit indexing for <tt>nth</tt></a></li>
 198   <li><a href="#implicit_default">Implicit indexing and the default function</a>
 199   <li><a href="#implicit_rest_slice">Implicit indexing for <tt>rest</tt> and <tt>slice</tt></a>
 200   <li><a href="#implicit_nth-set">Implicit indexing for <tt>nth-set</tt> and <tt>set-nth</tt></a>
 201
 202   </ul>
 203 </li>
 204 <li><a href="#destructive">Destructive versus non-destructive functions</a></li>
 205 <ul>
 206         <li><a href="#make_nondestructive">Make a destructive function non-destructive</a></li>
 207 </ul>
 208 <li><a href="#scoping">Dynamic and lexical scoping</a></li>
 209 <li><a href="#return">Early return from functions, loops, blocks</a>
 210
 211   <ul>
 212   <li><a href="#flow_catch_throw">Using <tt>catch</tt> and <tt>throw</tt></a></li>
 213   <li><a href="#flow_and_or">Using <tt>and</tt> and <tt>or</tt></a></li>
 214   </ul>
 215
 216 </li>
 217 <li><a href="#contexts">Contexts</a>
 218   <ul>
 219   <li><a href="#context_rules">Symbol creation in contexts</a></li>
 220   <li><a href="#scope_context">Scoping rules for contexts</a></li>
 221   <li><a href="#scope_change">Changing scoping</a></li>
 222   <li><a href="#protection">Symbol protection</a></li>
 223   <li><a href="#overwrite">Overwriting global symbols and built-ins</a></li>
 224   <li><a href="#context_vars">Variables holding contexts</a></li>
 225   <li><a href="#loading_contexts">Sequence of creating or loading contexts</a></li>
 226   </ul>
 227 </li>
 228 <li><a href="#context_objects">Programming with contexts</a>
 229   <ul>
 230   <li><a href="#context_modules">Contexts as programming modules</a></li>
 231   <li><a href="#context_data">Contexts as data containers</a></li>
 232   <li><a href="#loading_contexts">Loading and declaring contexts</a></li>
 233   <li><a href="#default_function">The context default functor</a></li>
 234   <li><a href="#pass_big">Passing data by reference</a></li>
 235   <li><a href="#serializing">Serializing context objects</a></li>
 236   </ul>
 237 <li><a href="#oo_programming">Object-Oriented Programming in newLISP</a>
 238   <ul>
 239   <li><a href="#newlisp_classes">Classes and constructors</a></li>
 240   <li><a href="#newlisp_objects">Objects</a></li>
 241   <li><a href="#colon_operator">The colon <tt>:</tt> operator and polymorphism</a></li>
 242   </ul>
 243 </li>
 244
 245
 246 </li>
 247 <li><a href="#XML">XML, SXML and XML-RPC</a></li>
 248 <li><a href="#internationalization">Customization, localization and UTF-8</a>
 249   <ul>
 250   <li><a href="#switching">Switching the locale</a></li>
 251   <li><a href="#decimal_point">Decimal point and decimal comma</a></li>
 252   <li><a href="#unicode_utf8">Unicode and UTF-8 encoding</a></li>
 253   </ul>
 254
 255 </li>
 256 <li><a href="#commas">Commas in parameter lists</a></li>
 257 <li><a href="#linking">Linking newLISP source and executable</a></li>
 258 </ol>
 259
 260 <h3>Function Reference</h3>
 261 <ol>
 262 <li><a href="#symbol_names">Syntax of symbol variables and numbers</a></li>
 263 <li><a href="#type_ids">Data types and names in the reference</a></li>
 264 <li><a href="#functions">Functions in groups</a>
 265   <ul>
 266   <li><a href="#list_processing">List processing, flow control and integer arithmetic</a></li>
 267   <li><a href="#string_operators">String and conversion functions</a></li>
 268   <li><a href="#floating_point">Floating point math and special functions</a></li>
 269   <li><a href="#matrices">Matrix functions</a></li>
 270   <li><a href="#array-funcs">Array functions</a></li>
 271   <li><a href="#bit_operators">Bit operators</a></li>
 272   <li><a href="#predicates">Predicates</a></li>
 273   <li><a href="#timedate">Time and date functions</a></li>
 274   <li><a href="#montecarlo">Simulation and modeling math functions</a></li>
 275   <li><a href="#pattern">Pattern matching</a></li>
 276   <li><a href="#financial">Financial math functions</a></li>
 277   <li><a href="#input_output">File and I/O operations</a></li>
 278   <li><a href="#process_threads">Processes, pipes and threads</a></li>
 279   <li><a href="#directory_management">File and directory management</a></li>
 280   <li><a href="#http_api">HTTP networking API</a></li>
 281   <li><a href="#socket_tcpip">Socket TCP/IP and UDP network API</a></li>
 282   <li><a href="#system_functions">System functions</a></li>
 283   <li><a href="#importing_libraries">Importing libraries</a></li>
 284   <li><a href="#internals">newLISP internals API</a></li>
 285   </ul>
 286
 287 </li>
 288 </ol>
 289
 290 <h3><a href="#functions_alphabetical">Functions in alphabetical order</a></h3>
 291
 292
 293 <b>
 294 <a href="#shell">!</a>&nbsp;
 295 <a href="#arithmetic">+-*/%</a>&nbsp;
 296 <a href="#colon">:</a>&nbsp;
 297 <a href="#abs">Ab</a>&nbsp;
 298 <a href="#append">Ap</a>&nbsp;
 299 <a href="#base64-dec">B</a>&nbsp;
 300
 301 <a href="#callback">Ca</a>&nbsp;
 302 <a href="#command-line">Co</a>&nbsp;
 303 <a href="#date">Da</a>&nbsp;
 304 <a href="#difference">Di</a>&nbsp;
 305 <a href="#emptyp">Em</a>&nbsp;
 306 <a href="#eval">Ev</a>&nbsp;
 307 <a href="#factor">Fa</a>&nbsp;
 308 <a href="#fn">Fn</a>&nbsp;
 309 <a href="#gammai">G</a>&nbsp;
 310
 311 <a href="#if">I</a>&nbsp;
 312 <a href="#join">J</a>&nbsp;
 313 <a href="#lambda">La</a>&nbsp;
 314 <a href="#list">Li</a>&nbsp;
 315 <br />
 316 <a href="#macrop">Ma</a>&nbsp;
 317 <a href="#member">Me</a>&nbsp;
 318 <a href="#name">Na</a> &nbsp;
 319 <a href="#net-accept">Ne</a>&nbsp;
 320
 321 <a href="#not">No</a>&nbsp;
 322 <a href="#open">O</a>&nbsp;
 323 <a href="#pack">Pa</a>&nbsp;
 324 <a href="#pretty-print">Pr</a>&nbsp;
 325 <a href="#quote">Q</a>&nbsp;
 326 <a href="#rand">Ra</a>&nbsp;
 327 <a href="#regex">Reg</a>&nbsp;
 328 <a href="#save">Sa</a>&nbsp;
 329 <a href="#share">Sh</a>&nbsp;
 330
 331 <a href="#starts-with">St</a>&nbsp;
 332 <a href="#tan">T</a>&nbsp;
 333 <a href="#unicode">U</a>&nbsp;
 334 <a href="#wait-pid">W</a>&nbsp;
 335 <a href="#xml-error">X</a>&nbsp;
 336 </b>
 337
 338 <h3>Appendix</h3>
 339
 340 <ul>
 341 <li><a href="#error_codes">Error Codes</a></li>
 342 <li><a href="#GNUFDL">GNU Free Documentation License</a></li>
 343 <li><a href="#GNUGPL">GNU General Public License</a></li>
 344 </ul>
 345 <br />
 346 <br />
 347
 348
 349 <a NAME="introduction"></a>
 350
 351 <center style="font-size: 150%">
 352 <span class="divider">(&nbsp;<font color="#7ba9d4">&part;</font>&nbsp;)</span>
 353 </center>
 354
 355 <CENTER><H1>newLISP Users Manual</H1></CENTER>
 356
 357
 358 <h2>1. Introduction</h2>
 359
 360                 <p>
 361                         newLISP focuses on the core components of LISP:
 362                         <em>lists</em>, <em>symbols</em>, and <em>lambda expressions</em>.
 363                         To these, newLISP adds <em>arrays</em>,
 364                         <em>implicit indexing</em> on lists and arrays,
 365                         and <em>dynamic</em> and <em>lexical scoping</em>.
 366                         Lexical scoping is implemented using separate namespaces called <em>contexts</em>.
 367                 </p>
 368                 <p>
 369                         The result is an easier-to-learn LISP
 370                         that is even smaller than most Scheme implementations,
 371                         but which still has about 350 built-in functions.
 372                         Approximately 200k in size,
 373                         newLISP is built for high portability
 374                         using only the most common UNIX system C-libraries.
 375                         It loads quickly and has a small memory footprint.
 376                         newLISP is as fast or faster than other popular scripting languages
 377                         and uses very few resources.
 378                 </p>
 379                 <p>
 380                         newLISP is dynamically scoped inside lexically separated contexts (namespaces).
 381                         Contexts can be used to create isolated protected expansion packages
 382                         and to write <em>prototype</em>-based <em>object-oriented</em> programs.
 383                 </p>
 384                 <p>
 385                         Both built-in and user-defined functions, along with variables,
 386                         share the same namespace and are manipulated by the same functions.
 387                         Lambda expressions and user-defined functions can be handled
 388                         like any other list expression.
 389                 </p>
 390                 <p>
 391                 Contexts in newLISP facilitate the development
 392                 of larger applications comprising independently developed modules
 393                 with their own separate namespaces.
 394                 They can be copied,
 395                 dynamically assigned to variables,
 396                 and passed by reference to functions as arguments.
 397                 In this way, contexts can serve as dynamically created objects
 398                 packaging symbols and methods.
 399                 Lexical separation of namespaces
 400                 also enables the definition of statically scoped functions.
 401                 </p>
 402                 <p>
 403                         newLISP's efficient <em>red-black tree</em> implementation
 404                         can handle millions of symbols without degrading performance.
 405                         Contexts can hold symbol-value pairs,
 406                         allowing them to be used as hash-tables.
 407                         Functions are also available
 408                         to iteratively access symbols inside contexts.
 409                 </p>
 410                 <p>
 411                         newLISP allocates and reclaims memory automatically,
 412                         without using traditional asynchronous garbage collection
 413                         (except under error conditions).
 414                         All objects &mdash; except for contexts, built-in primitives, and symbols &mdash;
 415                         are passed by value and are referenced only once.
 416                         When objects are no longer referenced,
 417                         their memory is automatically deallocated.
 418                         This results in predictable processing times,
 419                         without the pauses found in traditional garbage collection.
 420                         newLISP's unique automatic memory management
 421                         makes it the fastest interactive LISP available.
 422                 </p>
 423                 <p>
 424                         Many of newLISP's built-in functions are polymorphic
 425                         and accept a variety of data types and optional parameters.
 426                         This greatly reduces the number of functions
 427                         and syntactic forms it is necessary to learn and implement.
 428                         High-level functions are available for distributed computing,
 429                         financial math, statistics, and AI.
 430                 </p>
 431                 <p>
 432                         newLISP has functions to modify, insert, or delete elements inside
 433             complex <em>nested</em> lists or <em>multidimensional</em> array structures.
 434                 </p>
 435                 <p>
 436                         Since strings can contain null characters in newLISP,
 437                         they can be used to process binary data.
 438                 </p>
 439                 <p>
 440                         newLISP can also be extended with a shared library interface
 441                         to import functions that access data in foreign binary data structures.
 442                         The distribution contains a module for importing popular database APIs.
 443                 </p>
 444                 <p>
 445                         newLISP's HTTP, TCP/IP, and UDP socket interfaces
 446                         make it easy to write distributed networked applications.
 447                         Its built-in XML interface,
 448                         along with its text-processing features
 449                         &mdash; Perl Compatible Regular Expressions (PCRE) and text-parsing functions &mdash;
 450                         make newLISP a useful tool for CGI processing.
 451                         The source distribution includes examples of HTML forms processing.
 452                         newLISP can be run a as a CGI capable web server using its built-in http mode option.
 453                 </p>
 454                 <p>
 455                         The source distribution can be compiled for Linux, BSDs, Mac OS X/Darwin, Solaris, and Win32.
 456             On 64-bit Linux, SUN Solaris and True64Unix newLISP can be compiled as a 64-bit LP64 application
 457             for full 64-bit memory addressing.
 458                 </p>
 459                 <br />
 460                 <h3>
 461                         newLISP-GS
 462                 </h3>
 463                 <p>
 464                         newLISP-GS is a graphical user interface front-end
 465                         written in newLISP and a Java based library server
 466                         using the standard Java runtime environment
 467                         installed on all Windows and Mac OS X platforms.
 468                         Applications built with newLISP-GS can have the host operating system's
 469                         native look and feel.
 470                         Interfaces to GTK, Tcl/Tk and OpenGL graphics libraries
 471                         are also available.
 472                 </p>
 473                 <p>
 474                         newLISP and Java are available for most operating systems.
 475             This makes newLISP-GS is a platform-independent solution
 476                         for writing GUI applications.
 477                 </p>
 478                 <p>
 479                         For more information on newLISP-GS,
 480                         see <a HREF="http://newlisp.org/guiserver">newLISP-GS</a>.
 481                 </p>
 482                 <br />
 483                 <h3>
 484                         Licensing
 485                 </h3>
 486                 <p>
 487                         newLISP and newLISP-GS are licensed under version 3
 488                         of the <a HREF="#GNUGPL">GPL (General Public License)</a>.
 489                         Both the newLISP and other documentation packaged with newLISP
 490                         are licensed under the <a href="#GNUFDL">GNU Free Documentation License</a>.
 491                 </p>
 492
 493 <br />
 494
 495 <center>
 496 <span class="divider">(&nbsp;<font color="#7ba9d4">&sect;</font>&nbsp;)</span>
 497 </center>
 498
 499 <a NAME="deprecated"></a>
 500 <h2>2. Deprecated functions and future changes</h2>
 501
 502 <p>The new <a href="#set-assoc">set-assoc</a>  or <a href="#pop-assoc">pop-assoc</a> should
 503 be used instead of <a href="#replace-assoc">replace-assoc</a>, to replace or remove an association
 504 in an association list. The new <tt>set-assoc</tt> and <tt>pop-assoc</tt>  handle multiple key
 505 expressions for nested association lists. The old <tt>replace-assoc</tt> will be removed in
 506 a future version.</p>
 507
 508 <br /><br />
 509
 510 <center>
 511 <span class="divider">(&nbsp;<font color="#7ba9d4">&sect;</font>&nbsp;)</span>
 512 </center>
 513
 514 <a NAME="options"></a>
 515 <h2>3. Command-line options startup and directories</h2>
 516
 517 <p>When starting newLISP from the command line several switches and options and source files
 518 can be specified. The options and source files are executed. For options such as <tt>-p</tt> and <tt>-d</tt>,
 519 it makes sense to load source files <em>first</em>; other options, like <tt>-m</tt> and <tt>-s</tt>,
 520 should be specified <em>before</em> the source files. The <tt>-e</tt> switch is used to evaluate
 521 the program text and then exit; otherwise, evaluation continues interactively
 522 (unless an exit occurs while the files are loading).</p>
 523
 524 <br />
 525
 526 <a name="url_files"></a>
 527 <h3>Specifying files as URLs</h3>
 528
 529 <p>newLISP will load and execute files specified on the command line. Files are specified with either their
 530 pathname on the local filesystem or with a <tt>http://</tt> or <tt>file://</tt> URL:</p>
 531
 532 <blockquote><pre>
 533 newlisp aprog.lsp bprog.lsp prog.lsp
 534 newlisp http://newlisp.org/example.lsp
 535 newlisp file:///usr/home/newlisp/demo.lsp
 536 </pre></blockquote>
 537
 538                 <br />
 539                 <a name="stack_size"></a>
 540                 <h3>
 541                         Stack size
 542                 </h3>
 543 <blockquote><pre>
 544 newlisp -s 4000
 545 newlisp -s 100000 aprog bprog
 546 newlisp -s 6000 myprog
 547 newlisp -s 6000 http://asite.com/example.lsp
 548 </pre></blockquote>
 549                 <p>
 550                         The above examples show starting newLISP with different stack sizes using
 551                         the <tt>-s</tt> option, as well as loading one or more newLISP source files
 552                         and loading files specified by an URL. When no stack size is specified,
 553                         the stack defaults to 2048.
 554                 </p>
 555                 <br />
 556                 <a name="max_mem"></a>
 557                 <h3>
 558                         Maximum memory usage
 559                 </h3>
 560 <blockquote><pre>
 561 newlisp -m 128
 562 </pre></blockquote>
 563                 <p>
 564                         This example limits LISP cell memory to 128 megabytes. In 32-bit newLISP, each LISP cell consumes 16 bytes, so the argument <tt>128</tt> would represent a maximum of 8,388,608 LISP cells. This information is returned by <a href="#sys-info">sys-info</a> as the list's second element. Although LISP cell memory is not the only memory consumed by newLISP, it is a good estimate of overall memory usage.
 565                 </p>
 566                 <br />
 567
 568 <a name="working_dir"></a>
 569 <h3>
 570 Specifiying the working directory
 571 </h3>
 572
 573 <p>The <tt>-w</tt> option specifies the initial working directory for newLISP after startup:
 574 </p>
 575
 576 <blockquote><pre>
 577 newlisp -w /usr/home/newlisp
 578 </pre></blockquote>
 579
 580 <p>All file requests without a directory path will now be directed to the path specified with the <tt>-w</tt> option.</p>
 581
 582 <br />
 583
 584                 <a name="prompt"></a>
 585                 <h3>
 586                         Suppressing the prompt and HTTP processing
 587                 </h3>
 588                 <p>
 589                         The command-line prompt
 590                         and initial copyright banner
 591                         can be suppressed:
 592                 </p>
 593 <blockquote><pre>
 594 newlisp -c
 595 </pre></blockquote>
 596 <p>
 597         Listen and connection messages
 598         are suppressed if logging is not enabled.
 599         The <tt>-c</tt> option is useful
 600         when controlling newLISP
 601         from other programs;
 602         it is mandatory when setting it up
 603         as a <a href="#net-eval">net-eval</a> server.
 604 </p>
 605 <p>
 606         The <tt>-c</tt> option also enables newLISP server nodes to answer
 607         <tt>HTTP GET</tt>, <tt>PUT</tt>, <tt>POST</tt> and <tt>DELETE</tt> requests, as well as
 608         perform CGI processing. Using the <tt>-c</tt> option,
 609         together with the <tt>-w</tt> and <tt>-d</tt> options,
 610         newLISP can serve as a standalone <tt>httpd</tt> webserver:
 611 </p>
 612 <blockquote><pre>
 613 newlisp -c -d 8080 -w /usr/home/www
 614 </pre></blockquote>
 615
 616 <p>
 617 When running newLISP as a <tt>inetd</tt> or <tt>xinetd</tt> enabled
 618 server on UNIX machines, use:
 619 </p>
 620
 621 <blockquote><pre>
 622 newlisp -c -w /usr/home/www
 623 </pre></blockquote>
 624
 625 <p>
 626    In <tt>-c</tt> mode, newLISP processes command-line requests as well as
 627    HTTP and <a href="#net-eval">net-eval</a> requests. Running
 628    newLISP in this mode is only recommended on a machine behind
 629    a firewall. This mode should not be run on machines open and accessible
 630    through the Internet.
 631    To suppress the processing of <a href="#net-eval">net-eval</a> and command-line&ndash;like requests,
 632    use the safer <tt>-http</tt> option.
 633 </p>
 634 <br />
 635
 636 <a name="http_mode"></a>
 637
 638         <h3>
 639         HTTP-only server mode
 640         </h3>
 641 <p>
 642    newLISP can be limited to HTTP processing using the <tt>-http</tt> option.
 643    With this mode, a secure <tt>httpd</tt> web server daemon can be configured:
 644 </p>
 645 <blockquote><pre>
 646 newlisp -http -d 8080 -w /usr/home/www
 647 </pre></blockquote>
 648 <p>
 649 When running newLISP as an <tt>inetd</tt> or <tt>xinetd</tt>-enabled
 650 server on UNIX machines, use:
 651 </p>
 652 <blockquote><pre>
 653 newlisp -http -w /usr/home/www
 654 </pre></blockquote>
 655
 656 <p>To further enhance security and HTTP processing, load a program during startup when using this mode:
 657 </p>
 658 <blockquote><pre>
 659 newlisp http-conf.lsp -http -w /usr/home/www
 660 </pre></blockquote>
 661
 662 <p>Defining a function named <tt>httpd-conf</tt>
 663 in a source file called <tt>httpd-conf.lsp</tt>
 664 can be used to customize HTTP request processing.
 665 The newLISP distribution contains an example
 666 <tt>httpd-conf.lsp</tt> file.
 667 This file shows how to configure redirects
 668 and filter unauthorized requests.</p>
 669
 670 <p>In the HTTP modes enabled by either <tt>-c</tt> or <tt>-http</tt>, the following file types are
 671 recognized, and a correctly formatted <tt>Content-Type:</tt> header is sent back:</p>
 672
 673 <br />
 674 <blockquote>
 675 <table class="list" width="50%">
 676 <tr align="left"><th>file extension</th><th>media type</th></tr>
 677 <tr><td class="left">.jpg</td><td class="left">image/jpg</td></tr>
 678 <tr><td class="left">.pgn</td><td class="left">image/png</td></tr>
 679 <tr><td class="left">.gif</td><td class="left">image/gif</td></tr>
 680 <tr><td class="left">.pdf</td><td class="left">application/pdf</td></tr>
 681 <tr><td class="left">.mp3</td><td class="left">image/mpeg</td></tr>
 682 <tr><td class="left">.mov</td><td class="left">image/quicktime</td></tr>
 683 <tr><td class="left">.mpg</td><td class="left">image/mpeg</td></tr>
 684 <tr><td><em>any other</em></td><td class="left">text/html</td></tr>
 685 </table>
 686 </blockquote>
 687
 688 <br />
 689 <h3>Forcing prompts in pipe I/O mode</h3>
 690
 691 <p>
 692         A capital <tt>C</tt> forces prompts when running newLISP in pipe I/O mode
 693     inside the Emacs editor:
 694 </p>
 695
 696 <blockquote><pre>
 697 newlisp -C
 698 </pre></blockquote>
 699
 700 <p>
 701         To suppress return values from evaluations,
 702         use <a href="#silent">silent</a>.
 703 </p>
 704 <br />
 705
 706                 <a name="tcpip_server"></a>
 707                 <h3>
 708                         newLISP as a TCP/IP server
 709                 </h3>
 710 <blockquote><pre>
 711 newlisp some.lsp -p 9090
 712 </pre></blockquote>
 713
 714 <p>
 715 This example shows how newLISP can listen for commands on a TCP/IP socket connection.
 716 In this case, standard I/O is redirected to the port specified with the <tt>-p</tt>
 717 option. <tt>some.lsp</tt> is an optional file loaded during startup, before listening
 718 for a connection begins.
 719 </p>
 720
 721 <p>
 722 The <tt>-p</tt> option is also used to control newLISP from another application,
 723 such as a newLISP GUI front-end or a program written in another language.
 724 </p>
 725
 726 <p>
 727 A telnet application can be used to test running newLISP as a server. First enter:
 728 </p>
 729
 730 <blockquote><pre>
 731 newlisp -p 4711 &amp;
 732 </pre></blockquote>
 733
 734 <p>
 735 The <tt>&amp;</tt> indicates to a UNIX shell to run the process in the background.
 736 Now connect with a telnet application:
 737 </p>
 738
 739 <blockquote><pre>
 740 telnet localhost 4711
 741 </pre></blockquote>
 742
 743 <p>
 744 If connected, the newLISP sign-on banner and prompt appear. Instead of <tt>4711</tt>,
 745 any other port number could be used.
 746 </p>
 747
 748 <p>
 749 When the client application closes the connection, newLISP will exit, too.
 750 </p>
 751
 752         <br />
 753                 <a NAME="daemon"></a>
 754                 <h3>
 755                         TCP/IP daemon mode
 756                 </h3>
 757
 758 <p>When the connection to the client is closed in <tt>-p</tt> mode, newLISP exits.
 759 To avoid this, use the <tt>-d</tt> option instead of the <tt>-p</tt> option:
 760 </p>
 761
 762 <blockquote><pre>
 763 newlisp -d 4711 &amp;
 764 </pre></blockquote>
 765
 766 <p>
 767 This works like the <tt>-p</tt> option, but newLISP does not exit after a
 768 connection closes. Instead, it stays in memory, listening for a new connection
 769 and preserving its state. An <a HREF="#exit">exit</a> issued from a client
 770 application closes the network connection, and the newLISP daemon remains resident,
 771 waiting for a new connection. Any port number could be used in place of <tt>4711</tt>.
 772 </p>
 773
 774 <p>
 775 When running in <tt>-p</tt> or <tt>-d</tt> mode, the opening and closing tags
 776 <tt>[cmd]</tt> and <tt>[/cmd]</tt> must be used to enclose multiline statements.
 777 They must each appear on separate lines. This makes it possible to transfer larger
 778 portions of code from controlling applications.
 779 </p>
 780
 781 <p>
 782 The following variant of the <tt>-d</tt> mode is frequently used in a distributed
 783 computing environment, together with <a href="#net-eval">net-eval</a> on the client side:
 784 </p>
 785
 786 <blockquote><pre>
 787 newlisp -c -d 4711 &amp;
 788 </pre></blockquote>
 789
 790 <p>
 791 The <tt>-c</tt> spec suppresses prompts, making this mode suitable
 792 for receiving requests from the <a href="#net-eval">net-eval</a> function.
 793 </p>
 794
 795 <p>
 796         newLISP server nodes running on UNIX like operating systems,
 797         will also answer <tt>HTTP GET</tt>, <tt>PUT</tt> and <tt>DELETE</tt> requests.
 798         This can be used to retrieve and store files
 799         with <a href="#get-url">get-url</a>, <a href="#put-url">put-url</a>,
 800     <a href="#delete-url">delet-url</a>,
 801         <a href="#read-file">read-file</a>, <a href="#write-file">write-file</a>
 802         and <a href="#append-file">append-file</a>,
 803         or to load and save programs using <a href="#load">load</a>
 804         and <a href="#save">save</a> from and to remote server nodes.
 805     See the chapters for the <tt>-c</tt> and <tt>-http</tt> options
 806     for more details.
 807 </p>
 808
 809
 810 <br />
 811
 812 <a name="local_domain_server"></a>
 813 <h3>Local domain UNIX socket server</h3>
 814
 815 <p>Instead of a port a local domain UNIX socket path can be specified in
 816 the <tt>-d</tt> or <tt>-p</tt> server modes.</p>
 817
 818 <blockquote><pre>
 819 newlisp -c -d /tmp/mysocket &amp;
 820 </pre></blockquote>
 821
 822 <p>This mode will work together with local domain socket modes of
 823 <a href="#net-connect">net-connect</a>, <a href="#net-listen">net-listen</a>,
 824 and <a href="#net-eval">net-eval</a>. Local domain sockets opened with
 825 with <tt>net-connect</tt> and <tt>net-listen</tt> can be served using
 826 <a href="#net-accept">net-accept</a>, <a href="#net-receive">net-receive</a>,
 827 and <a href="#net-send">net-send</a>. Local domain socket connections
 828 can be monitored using <a href="#net-peek">net-peek</a> and
 829 <a href="#net-select">net-select</a>.</p>
 830
 831 <p>Local domain socket connections are much faster than normal Tcp/Ip network
 832 connections and preferred for communications between processes on
 833 the same local file system in distributed applications. This mode is not
 834 available on Win32.</p>
 835
 836 <br />
 837
 838                 <a name="inetd_daemon"></a>
 839                 <h3><tt>inetd</tt>       daemon mode</h3>
 840 <p>
 841 The <tt>inetd</tt> server running on virtually all Linux/UNIX OSes can function
 842 as a proxy for newLISP. The server accepts TCP/IP or UDP connections and passes
 843 on requests via standard I/O to newLISP. <tt>inetd</tt> starts a newLISP process
 844 for each client connection. When a client disconnects, the connection is closed
 845 and the newLISP process exits.
 846 </p>
 847
 848 <p>
 849 <tt>inetd</tt> and newLISP together can handle multiple connections efficiently
 850 because of newLISP's small memory footprint, fast executable, and short program load
 851 times. When working with <a href="#net-eval">net-eval</a>, this mode is preferred
 852 for efficiently handling multiple requests in a distributed computing environment.
 853 </p>
 854
 855 <p>
 856 Two files must be configured: <tt>services</tt> and <tt>inetd.conf</tt>.
 857 Both are ASCII-editable and can usually be found at <tt>/etc/services</tt> and
 858 <tt>/etc/inetd.conf</tt>.
 859 </p>
 860
 861 <p>
 862 Put one of the following lines into <tt>inetd.conf:</tt>
 863 </p>
 864
 865 <blockquote><pre>
 866 net-eval  stream  tcp  nowait  root  /usr/bin/newlisp -c
 867
 868 # as an alternative, a program can also be preloaded
 869
 870 net-eval  stream  tcp  nowait  root  /usr/bin/newlisp -c myprog.lsp
 871 </pre></blockquote>
 872
 873 <p>
 874 Instead of <tt>root</tt>, another user and optional group can be specified.
 875 For details, see the UNIX man page for <tt>inetd</tt>.
 876 </p>
 877
 878 <p>
 879 The following line is put into the <tt>services</tt> file:
 880 </p>
 881
 882 <blockquote><pre>
 883 net-eval        4711/tcp     # newLISP net-eval requests
 884 </pre></blockquote>
 885
 886 <p>
 887 On Mac OS X and some UNIX systems, <tt>xinetd</tt> can be used instead of
 888 <tt>inetd</tt>. Save the following to a file named <tt>net-eval</tt> in the
 889 <tt>/etc/xinetd.d/</tt> directory:
 890 </p>
 891
 892 <blockquote><pre>
 893 service net-eval
 894 {
 895     socket_type = stream
 896     wait = no
 897     user = root
 898     server = /usr/bin/newlisp
 899     port = 4711
 900     server_args = -c
 901     only_from = localhost
 902 }
 903 </pre></blockquote>
 904 <p>
 905 For security reasons, <tt>root</tt> should be changed to a different user,
 906 when traffic is accepted from other places than <tt>localhost</tt>.
 907 The <tt>only_from</tt> spec can be left out to permit remote access.
 908 </p>
 909
 910 <p>
 911 See the man pages for <tt>xinetd</tt> and <tt>xinetd.conf</tt>
 912 for other configuration options.
 913 </p>
 914
 915 <p>
 916 After configuring the daemon, <tt>inetd</tt> or
 917 <tt>xinetd</tt> must be restarted to
 918 allow the new or changed configuration files to be read:
 919 </p>
 920
 921 <blockquote><pre>
 922 kill -HUP &lt;pid&gt;
 923 </pre></blockquote>
 924 <p>
 925 Replace <tt>&lt;pid&gt;</tt> with the process ID of the
 926 running <tt>xinetd</tt> process.
 927 </p>
 928
 929 <p>
 930 A number or network protocol other than 4711 or TCP can be specified.
 931 </p>
 932
 933 <p>
 934 newLISP handles everything as if the input were being entered
 935 on a newLISP command line without a prompt. To test the
 936 <tt>inetd</tt> setup, the <tt>telnet</tt> program can be used:
 937 </p>
 938
 939 <blockquote><pre>
 940 telnet localhost 4711
 941 </pre></blockquote>
 942
 943 <p>
 944 newLISP expressions can now be entered, and <tt>inetd</tt> will
 945 automatically handle the startup and communications of a newLISP
 946 process. Multiline expressions can be entered by bracketing them
 947 with <tt>[cmd]</tt> and <tt>[/cmd]</tt> tags, each on separate lines.
 948 </p>
 949
 950 <p>
 951 <p>
 952         newLISP server nodes running on UNIX like operating systems,
 953         will also answer simple <tt>HTTP GET</tt> and <tt>PUT</tt> requests.
 954         This can be used to retrieve and store files
 955         with <a href="#get-url">get-url</a>, <a href="#put-url">put-url</a>,
 956         <a href="#read-file">read-file</a>, <a href="#write-file">write-file</a>
 957         and <a href="#append-file">append-file</a>,
 958         or to load and save programs using <a href="#load">load</a>
 959         and <a href="#save">save</a> from and to remote server nodes.
 960         On Win32 newLISP server nodes do not
 961         answer HTTP requests.
 962 </p>
 963
 964                 <br />
 965                 <a name="direct_exec"></a>
 966                 <h3>
 967                         Direct execution mode
 968                 </h3>
 969                 Small pieces of newLISP code can be executed directly from the command line:
 970 <blockquote><pre>
 971 newlisp -e "(+ 3 4)"&nbsp;&nbsp;<span class="arw">&rarr;</span> 7
 972 </pre></blockquote>             <p>
 973                         The expression enclosed in quotation marks is evaluated, and the result is printed to standard out (STDOUT). In most UNIX system shells, single quotes can also be used as command-line delimiters. Note that there is a space between <tt>-e</tt> and the quoted command string.
 974                 </p>
 975                 <br />
 976
 977 <a name="logging"></a>
 978 <h3>Logging I/O</h3>
 979
 980 <p>
 981 In any mode newLISP can write a log when started with the <tt>-l</tt> or <tt>-L</tt> option.
 982 Depending on the mode newLISP is running, different output is written to the logfile. Both options always must
 983 specify the  path of a log-file. The path may be a relative path and can be either attached or detached to the
 984 <tt>-l</tt> or <tt>-L</tt> option.
 985 </p>
 986
 987 <blockquote><pre>
 988 newlisp -l./logfile.txt -c
 989
 990 newlisp -L /usr/home/www/log.txt -http -w /usr/home/www/htpdocs
 991 </pre></blockquote>
 992
 993 <center>
 994 <table class="list" width="95%" summary="logging formats">
 995 <tr align="left"><th>logging mode</th><th>command line and net-eval with <tt>-c</tt></th><th>HTTP server with <tt>-http</tt></th></tr>
 996 <tr><td><tt>newlisp -l</tt></td>
 997     <td>log only input and network connections</td>
 998     <td>log only net-work connections</td></tr>
 999 <tr><td><tt>newlisp -L</tt></td>
1000     <td>log also newLISP output (w/o prompts)</td>
1001     <td>log also HTTP requests</td></tr>
1002 </table>
1003 </center>
1004 <br />
1005                 <p>
1006                         All logging output is written to the file specified after the <tt>-l</tt> or <tt>-L</tt> option.
1007                 </p>
1008                 <br />
1009                 <a name="cmd_help"></a>
1010                 <h3>
1011                         Command line help summary
1012                 </h3>
1013                 <p>The <tt>-h</tt> command-line switch prints a copyright notice and summary of options:
1014                 </p>
1015 <blockquote><pre>
1016 newlisp -h
1017 </pre></blockquote>             <p>
1018                         On Linux and other UNIX systems, a <tt>newlisp</tt> <em>man page</em> can be found:
1019                 </p>
1020 <blockquote><pre>
1021 man newlisp
1022 </pre></blockquote>             <p>
1023                         This will display a man page in the Linux/UNIX shell.
1024                 </p>
1025 <br />
1026
1027 <a name="initialization"></a>
1028 <h3> The initialization file <tt>init.lsp</tt></h3>
1029 <p> On Linux, BSDs, Mac OS X and other UNIXs the initialization file is installed and expected in <tt>/usr/share/newlisp/init.lsp</tt>. newLISP on Win32 compiled with MinGW looks for <tt>init.lsp</tt> in the same directory where <tt>newlisp.exe</tt> is installed. Along with any files specified on the command line, <tt>init.lsp</tt> is loaded before the banner and prompt are shown. When newLISP is executed or launched by a program or process other than a shell, the banner and prompt are not shown, and newLISP  communicates by standard I/O. <tt>init.lsp</tt>, however, is still loaded and evaluated if present.
1030 </p>
1031
1032 <p> While newLISP does not require <tt>init.lsp</tt> to run, it is convenient for defining functions and systemwide variables.</p>
1033 <p>
1034 The last part of <tt>init.lsp</tt> contains OS-specific code, which loads a  second <tt>.init.lsp</tt> (starting with a dot). On Linux/UNIX, this file is expected in the directory specified by the <tt>HOME</tt> environment variable. On Win32, this file is expected in the directory specified by the <tt>USERPROFILE</tt> or <tt>DOCUMENT_ROOT</tt> environment variable.
1035 </p>
1036
1037 <br />
1038
1039 <a name="directories_unix"></a>
1040 <h3> Directories on Linux, BSD, Mac OS X and other UNIX </h3>
1041 <p>
1042 The directory <tt>/usr/share/newlisp/modules</tt> contains modules with useful functions
1043 for a variety of tasks, such as database management with MySQL, procedures for statistics,
1044 POP3 mail, etc. The directory <tt>/usr/share/newlisp/guiserver</tt> contains sample programs
1045 for writing GUI aplications with newLISP-GS.
1046 The directory <tt>/usr/share/doc/newlisp/</tt> contains documentation in HTML format.
1047                 </p>
1048                 <br />
1049                 <a name="directories_win32"></a>
1050                 <h3>
1051                         Directories on Win32
1052                 </h3>
1053                 <p>
1054 On Win32 systems, all files are installed in the default directory <tt>$PROGRAMFILES\newlisp</tt>.
1055 <tt>$PROGRAMFILES</tt> is a Win32 environment variable that resolves to
1056 <tt>C:\Program files\newlisp\</tt> in English language installations. The subdirectories
1057 <tt>$PROGRAMFILES\newlisp\modules</tt> and <tt>$PROGRAMFILES\newlisp\guiserver</tt>
1058 contain modules for interfacing to external libraries and sample programs written for
1059 newLISP-GS.</p>
1060 <br />
1061
1062 <a name="environment"></a>
1063 <h3>Environment variable NEWLISPDIR</h3>
1064 <p>During startup newLISP sets the environment variable NEWLISPDIR, if it is not set already. On Linux, BSDs, Mac OS X and other UNIXs the variable is set to <tt>/usr/share/newlisp</tt>. On Win32 the variable is set to <tt>%PROGRAMFILES%/newlisp</tt>.</p>
1065
1066 <p>The environment variable <tt>NEWLISPDIR</tt> is useful when loading files installed with
1067 newLISP:</p>
1068
1069 <blockquote><pre>
1070 (load (append (env "NEWLISPDIR") "/guiserver.lsp"))
1071
1072 (load (append (env "NEWLISPDIR") "/modules/mysql51.lsp"))
1073 </pre></blockquote>
1074
1075 <center>
1076 <span class="divider">(&nbsp;<font color="#7ba9d4">&sect;</font>&nbsp;)</span>
1077 </center>
1078
1079                 <a NAME="shared-lib"></a>
1080                 <h2>
1081                         4. Shared library module for Linux/BSD versions
1082                 </h2>
1083                 <p>
1084                         newLISP can be compiled as a UNIX shared library called <tt>newlisp.dylib</tt> on Mac OS X and as <tt>newlisp.so</tt> on Linux and BSDs. A newLISP shared library can be used like any other UNIX shared library.
1085                 </p>
1086                 <p>
1087                         To use <tt>newlisp.so</tt> or <tt>newlisp.dylib</tt>, import the function <tt>newlispEvalStr</tt>. Like <a href="#eval-string">eval-string</a>, this function takes a string containing a newLISP expression and stores the result in a string address. The result can be converted using <a href="#get-string">get-string</a>. The returned string is formatted like output from a command-line session. It contains terminating line-feed characters, but without the prompt strings.
1088                 </p>
1089                 <p>
1090                         The first example shows how <tt>newlisp.so</tt> is imported from newLISP itself.
1091                 </p>
1092 <blockquote><pre>
1093 (import "/usr/lib/newlisp.so" "newlispEvalStr")
1094 (get-string (newlispEvalStr "(+ 3 4)"))&nbsp;&nbsp;<span class=arw>&rarr;</span> "7\n"
1095 </pre></blockquote>             <p>
1096                         The second example shows how to import <tt>newlisp.so</tt> into a program written in C:
1097                 </p>
1098 <blockquote><pre>
1099 /* libdemo.c - demo for importing newlisp.so
1100  *
1101  * compile using:
1102  *    gcc -ldl libdemo.c -o libdemo
1103  *
1104  * use:
1105  *
1106  *    ./libdemo '(+ 3 4)'
1107  *    ./libdemo '(symbols)'
1108  *
1109  */
1110 #include &lt;stdio.h&gt;
1111 #include &lt;dlfcn.h&gt;
1112
1113 int main(int argc, char * argv[])
1114 {
1115 void * hLibrary;
1116 char * result;
1117 char * (*func)(char *);
1118 char * error;
1119
1120 if((hLibrary = dlopen("/usr/lib/newlisp.so",
1121                        RTLD_GLOBAL | RTLD_LAZY)) == 0)
1122     {
1123     printf("cannot import library\n");
1124     exit(-1);
1125     }
1126
1127 func = dlsym(hLibrary, "newlispEvalStr");
1128 if((error = dlerror()) != NULL)
1129     {
1130     printf("error: %s\n", error);
1131     exit(-1);
1132     }
1133
1134 printf("%s\n", (*func)(argv[1]));
1135
1136 return(0);
1137 }
1138
1139 /* eof */
1140 </pre></blockquote>             <p>
1141                         This program will accept quoted newLISP expressions and print the evaluated results.
1142                 </p>
1143                 <p>
1144                         When calling <tt>newlisp.so</tt>'s  function <tt>newlispEvalStr</tt>, output normally directed to the console (e.g., return values or <a href="#print">print</a> statements) is returned in the form of an integer string pointer. The output can be accessed by passing this pointer to the <tt>get-string</tt> function. To silence the output from return values, use the <a href="#silent">silent</a> function.
1145                 </p>
1146
1147 <center>
1148 <span class="divider">(&nbsp;<font color="#7ba9d4">&sect;</font>&nbsp;)</span>
1149 </center>
1150
1151                 <a NAME="dll"></a>
1152                 <h2>
1153                         5. DLL module for Win32 versions
1154                 </h2>
1155                 <p>
1156                         On the Win32 platforms, newLISP can be compiled as a DLL (Dynamic Link Library). In this way, newLISP functions can be made available to other programs (e.g., MS Excel, Visual Basic, Borland Delphi, or even newLISP itself).
1157                 </p>
1158                 <p>
1159                         When the DLL is loaded, it looks for the file <tt>init.lsp</tt> in the current directory of the calling process.
1160                 </p>
1161                 <p>
1162                         To access the functionality of the DLL, use <tt>newlispEvalStr</tt>, which takes a string containing a valid newLISP expression and returns a string of the result:
1163                 </p>
1164 <blockquote><pre>
1165 (import "newlisp.dll" "newlispEvalStr")
1166 (get-string (newlispEvalStr "(+ 3 4)"))  <span class=arw>&rarr;</span> "7"
1167 </pre></blockquote>             <p>
1168                         The above example shows the loading of a DLL using newLISP. The <a href="#get-string">get-string</a> function is necessary to access the string being returned. Other applications running on Win32 allow the returned data type to be declared when importing the function.
1169                 </p>
1170                 <p>
1171                         When using <tt>newlisp.so</tt>, output normally directed to the console &mdash; like <a href="#print">print</a> statements or return values &mdash; will be returned in a string pointed to by the call to <tt>newlispEvalStr</tt>. To silence the output from return values, use the <a href="#silent">silent</a> directive.
1172                 </p>
1173
1174 <center>
1175 <span class="divider">(&nbsp;<font color="#7ba9d4">&sect;</font>&nbsp;)</span>
1176 </center>
1177
1178                 <a NAME="expressions"></a>
1179                 <h2>
1180                         6. Evaluating newLISP expressions
1181                 </h2>
1182                 <p>
1183                         The following is a short introduction to LISP statement evaluation and the role of integer and floating point arithmetic in newLISP.
1184                 </p>
1185                 <p>
1186                         Top-level expressions are evaluated when using the <a href="#load"> load</a> function or when entering expressions in console mode on the command line. As shown in the following snippet from an interactive session, multiline expressions can be entered by enclosing them between <tt>[cmd]</tt> and <tt>[/cmd]</tt> tags:
1187                 </p>
1188 <blockquote><pre>
1189 &gt; [cmd]
1190 (define (foo x y)
1191 (+ x y))
1192 [/cmd]
1193 <strong>(lambda (x y) (+ x y))</strong>
1194 &gt; (foo 3 4)
1195 <strong>7</strong>
1196 &gt; _
1197 </pre></blockquote>             <p>
1198                         Each <tt>[cmd]</tt> and <tt>[/cmd]</tt> tag is entered on a separate line. This mode is useful for pasting multiline code into the interactive console.
1199                 </p>
1200                 <br />
1201                 <a name="int_float"></a>
1202                 <h3>
1203                         Integer data, floating point data, and operators
1204                 </h3>
1205                 <p>
1206                         newLISP functions and operators accept integer and floating point numbers, converting them into the needed format. For example, a bit-manipulating operator converts a floating point number into an integer by omitting the fractional part. In the same fashion, a trigonometric function will internally convert an integer into a floating point number before performing its calculation.
1207                 </p>
1208                 <p>
1209                         The symbol operators (<tt>+</tt> <tt>-</tt> <tt>*</tt> <tt>/</tt> <tt>%</tt> <tt>$</tt> <tt>~</tt> <tt>|</tt> <tt>^</tt> <tt>&lt;&lt;</tt> <tt>&gt;&gt;</tt>) return values of type integer. Functions and operators named with a word instead of a symbol (e.g., <tt>add</tt> rather than <tt>+</tt>) return floating point numbers. Integer operators truncate floating point numbers to integers, discarding the fractional parts.
1210                 </p>
1211                 <p>
1212                         newLISP has two types of basic arithmetic operators: integer (<tt>+</tt> <tt>-</tt> <tt>*</tt> <tt>/</tt>) and floating point (<tt>add</tt> <tt>sub</tt> <tt>mul</tt> <tt>div</tt>). The arithmetic functions convert their arguments into types compatible with the function's own type: integer function arguments into integers, floating point function arguments into floating points. To make newLISP behave more like other scripting languages, the integer operators <tt>+</tt>, <tt>-</tt>, <tt>*</tt>, and <tt>/</tt> can be redefined to perform the floating point operators <tt>add</tt>, <tt>sub</tt>, <tt>mul</tt>, and <tt>div</tt>:
1213                 </p>
1214 <blockquote><pre>
1215 (constant '+ add)
1216 (constant '- sub)
1217 (constant '* mul)
1218 (constant '/ div)
1219
1220 ;; or all 4 operators at once
1221 (constant '+ add '- sub '* mul '/ div)
1222 </pre></blockquote>             <p>
1223                         Now the common arithmetic operators <tt>+</tt>, <tt>-</tt>, <tt>*</tt>, and <tt>/</tt> accept both integer and floating point numbers and return floating point results.
1224                 </p>
1225                 <p>
1226                         Note that the looping variables in <a href="#dotimes">dotimes</a> and <a href="#for">for</a>, as well as the result of <a href="#sequence">sequence</a>, use floating point numbers for their values.
1227                 </p>
1228                 <p>
1229                         Care must be taken when importing from libraries that use functions expecting integers. After redefining <tt>+, -, *</tt>, and <tt>/</tt>, a double floating point number may be unintentionally passed to an imported function instead of an integer. In this case, floating point numbers can be converted into integers by using the function <a href="#int">int</a>. Likewise, integers can be transformed into floating point numbers using the <a href="#float">float</a> function:
1230                 </p>
1231 <blockquote><pre>
1232 (import "mylib.dll" "foo")  ; importing int foo(int x) from C
1233 (foo (int x))               ; passed argument as integer
1234 (import "mylib.dll" "bar")  ; importing C int bar(double y)
1235 (bar (float y))             ; force double float
1236 </pre></blockquote>             <p>
1237                         Some of the modules shipping with newLISP are written assuming the default implementations of <tt>+</tt>, <tt>-</tt>, <tt>*</tt>, and <tt>/</tt>. This gives imported library functions maximum speed when performing address calculations.
1238                 </p>
1239                 <p>
1240                         The newLISP preference is to leave <tt>+</tt>, <tt>-</tt>, <tt>*</tt>, and <tt>/</tt> defined as integer operators and use <tt>add</tt>, <tt>sub</tt>, <tt>mul</tt>, and <tt>div</tt> when explicitly required.
1241 Since version 8.9.7 integer operations in newLISP are 64 bit operations, while 64 bit double floating
1242 point numbers only offer 52 bits of resolution in the integer part of the number.
1243                 </p>
1244
1245
1246
1247
1248
1249                 <br />
1250                 <a name="eval_rules"></a>
1251                 <h3>
1252                         Evaluation rules and data types
1253                 </h3>
1254                 <p>
1255                         Evaluate expressions by entering and editing them on the command line. More complicated programs can be entered using editors like Emacs and VI, which have modes to show matching parentheses while typing. Load a saved file back into a console session by using the <a href="#load">load</a> function.
1256                 </p>
1257                 <p>
1258                         A line comment begins with a <tt>;</tt> (semicolon) or a <tt>#</tt> (number sign) and extends to the end of the line. newLISP ignores this line during evaluation. The <tt>#</tt> is useful when using newLISP as a scripting language in Linux/UNIX environments, where the <tt>#</tt> is commonly used as a line comment in scripts and shells.
1259                 </p>
1260                 <p>
1261                         When evaluation occurs from the command line, the result is printed to the console window.
1262                 </p>
1263                 <p>
1264                         The following examples can be entered on the command line by typing the code to the left of the &nbsp;&nbsp;<span class=arw>&rarr;</span> symbol. The result that appears on the next line should match the code to the right of the &nbsp;&nbsp;<span class=arw>&rarr;</span> symbol.
1265                 </p>
1266                 <p>
1267                         <strong>nil</strong> and <strong>true</strong> are boolean data types that evaluate to themselves:
1268                 </p>
1269 <blockquote><pre>
1270 nil    <span class=arw>&rarr;</span> nil
1271 true   <span class=arw>&rarr;</span> true
1272 </pre></blockquote>             <p>
1273                         <strong>Integers</strong> and <strong>floating point</strong> numbers evaluate to themselves:
1274                 </p>
1275 <blockquote><pre>
1276 123    <span class=arw>&rarr;</span> 123
1277 0xE8   <span class=arw>&rarr;</span> 232    ; hexadecimal prefixed by 0x
1278 055    <span class=arw>&rarr;</span> 45     ; octal prefixed by 0 (zero)
1279 1.23   <span class=arw>&rarr;</span> 1.23
1280 123e-3 <span class=arw>&rarr;</span> 0.123  ; scientific notation
1281 </pre></blockquote>
1282          <p>
1283                         Integers are 64-bit numbers (including the sign bit, 32-bit before version 8.9.7).
1284             Valid integers are numbers between -9,223,372,036,854,775,808 and
1285             +9,223,372,036,854,775,807.
1286             Larger numbers converted from floating point numbers are truncated
1287             to one of the two limits. Integers internal to newLISP, which
1288             are limited to 32-bit numbers overflow to either +2,147,483,647 or
1289             -2,147,483,648. Floating point numbers are IEEE 754 64-bit doubles.
1290             Unsigned numbers up to 18,446,744,073,709,551,615 can be displayed
1291             using special formatting characters for <a href="#format">format</a>.
1292                 </p>
1293
1294                 <p>
1295                         <strong>Strings</strong> may contain null characters and can have different delimiters. They evaluate to themselves.
1296                 </p>
1297 <blockquote><pre>
1298 "hello"             <span class=arw>&rarr;</span>"hello"
1299 "\032\032\065\032"  <span class=arw>&rarr;</span>"  A "
1300 "\x20\x20\x41\x20"  <span class=arw>&rarr;</span>"  A "
1301 "\t\r\n"            <span class=arw>&rarr;</span>"\t\r\n"
1302 "\x09\x0d\x0a"      <span class=arw>&rarr;</span>"\t\r\n"
1303
1304 ;; null characters are legal in strings:
1305 "\000\001\002"       <span class=arw>&rarr;</span> "\000\001\002"
1306 {this "is" a string} <span class=arw>&rarr;</span> "this \"is\" a string"
1307
1308 ;; use [text] tags for text longer than 2048 bytes:
1309 [text]this is a string, too[/text]
1310 <span class=arw>&rarr;</span> "this is a string, too"
1311
1312 </pre></blockquote>             <p>
1313                         Strings delimited by <tt>"</tt> (double quotes) will also process the following characters escaped with a <tt>\</tt> (backslash):
1314                 </p>
1315 <br />
1316 <center>
1317 <table class="list" width="95%" summary="special characters in strings">
1318 <tr align="left"><th>escaped<br />character</th><th>description</th></tr>
1319 <tr><td class="left"><tt>\"</tt></td><td class="right">for a double quote inside a quoted string</td></tr>
1320 <tr><td class="left"><tt>\n</tt></td><td class="right">for a line-feed character (ASCII 10)</td></tr>
1321 <tr><td class="left"><tt>\r</tt></td><td class="right">for a return character (ASCII 13)</td></tr>
1322 <tr><td class="left"><tt>\t</tt></td><td class="right">for a TAB character (ASCII 9)</td></tr>
1323 <tr><td class="left"><tt>\nnn</tt></td><td class="right">for a three-digit ASCII number (nnn format between 000 and 255)</td></tr>
1324 <tr><td class="left"><tt>\xnn</tt></td><td class="right">for a two-hex-digit ASCII number (xnn format between x00 and xff)</td></tr>
1325 </table>
1326 </center>
1327 <br />
1328                 <p>
1329                         Quoted strings cannot exceed 2,048 characters. Longer strings should use the <tt>[text]</tt> and <tt>[/text]</tt> tag delimiters. newLISP automatically uses these tags for string output longer than 2,048 characters.
1330                 </p>
1331                 <p>
1332                         The <tt>{</tt> (left curly bracket), <tt>}</tt> (right curly bracket), and <tt>[text], [/text]</tt> delimiters do not perform escape character processing.
1333                 </p>
1334                 <p>
1335                         <strong>Lambda and lambda-macro expressions</strong> evaluate to themselves:
1336                 </p>
1337 <blockquote><pre>
1338 (lambda (x) (* x x))                   <span class=arw>&rarr;</span> (lambda (x) (* x x))
1339 (lambda-macro (a b) (set (eval a) b))  <span class=arw>&rarr;</span> (lambda (x) (* x x))
1340 (fn (x) (* x x))                       <span class=arw>&rarr;</span> (lambda (x) (* x x))  ; an alternative syntax
1341 </pre></blockquote>             <p>
1342                         <strong>Symbols</strong> evaluate to their contents:
1343                 </p>
1344 <blockquote><pre>
1345 (set 'something 123)  <span class=arw>&rarr;</span> 123
1346 something             <span class=arw>&rarr;</span> 123
1347 </pre></blockquote>             <p>
1348                         <strong>Contexts</strong> evaluate to themselves:
1349                 </p>
1350 <blockquote><pre>
1351 (context 'CTX)  <span class=arw>&rarr;</span> CTX
1352 CTX             <span class=arw>&rarr;</span> CTX
1353 </pre></blockquote>             <p>
1354                         <strong>Built-in functions</strong> also evaluate to themselves:
1355                 </p>
1356 <blockquote><pre>
1357 add                <span class=arw>&rarr;</span> add &lt;B845770D&gt;
1358 (eval (eval add))  <span class=arw>&rarr;</span> add &lt;B845770D&gt;
1359 (constant '+ add)  <span class=arw>&rarr;</span> add &lt;B845770D&gt;
1360 +                  <span class=arw>&rarr;</span> add &lt;B845770D&gt;
1361 </pre></blockquote>             <p>
1362                         In the above example, the number between the &lt; &gt; (angle brackets) is the hexadecimal memory address (machine-dependent) of the <tt>add</tt> function. It is displayed when printing a built-in primitive.
1363                 </p>
1364                 <p>
1365                         <strong>Quoted expressions</strong> lose one ' (single quote) when evaluated:
1366                 </p>
1367 <blockquote><pre>
1368 'something  <span class=arw>&rarr;</span> something
1369 ''''any     <span class=arw>&rarr;</span> '''any
1370 '(a b c d)  <span class=arw>&rarr;</span> (a b c d)
1371 </pre></blockquote>             <p>
1372                         A single quote is often used to <em>protect</em> an expression from evaluation (e.g., when referring to the symbol itself instead of its contents or to a list representing data instead of a function).
1373                 </p>
1374
1375 <p>In newLISP, a <strong>list</strong>'s first element is evaluated
1376 before the rest of the expression (as in Scheme). The result of the
1377 evaluation is applied to the remaining elements in the list and must
1378 be one of the following: a <em>lambda</em> expression, <em>lambda-macro</em>
1379 expression, or <em>primitive</em> (built-in) function.
1380 </p>
1381
1382 <blockquote><pre>
1383 (+ 1 2 3 4)                  <span class=arw>&rarr;</span> 10
1384 (define (double x) (+ x x))  <span class=arw>&rarr;</span> (lambda (x) (+ x x))
1385 </pre></blockquote>             <p>
1386                         or
1387                 </p>
1388 <blockquote><pre>
1389 (set 'double (lambda (x) (+ x x)))
1390 (double 20)               <span class=arw>&rarr;</span> 40
1391 ((lambda (x) (* x x)) 5)  <span class=arw>&rarr;</span> 25
1392 </pre></blockquote>             <p>
1393                         For a user-defined lambda expression, newLISP evaluates the arguments from left to right and binds the results to the parameters (also from left to right), before using the results in the body of the expression.
1394                 </p>
1395                 <p>
1396                         Like Scheme, newLISP evaluates the <em>functor</em> (function object) part of an expression before applying the result to its arguments. For example:
1397                 </p>
1398 <blockquote><pre>
1399 ((if (&gt; X 10) * +) X Y)
1400 </pre></blockquote>
1401
1402 <p>Depending on the value of X, this expression applies the <tt>*</tt>
1403 (product) or <tt>+</tt> (sum) function to X and Y.
1404 </p>
1405
1406 <p>Because their arguments are not evaluated, <strong>lambda-macro</strong>
1407 expressions are useful for extending the syntax of the language. Most
1408 built-in functions evaluate their arguments from left to right (as needed)
1409 when executed. Some exceptions to this rule are indicated in the reference
1410 section of this manual. LISP functions that do not evaluate all or some of
1411 their arguments are called <em>special forms</em>.
1412 </p>
1413
1414 <p><strong>Arrays</strong> evaluate to themselves:</p>
1415
1416 <blockquote><pre>
1417 (set 'A (array 2 2 '(1 2 3 4))) <span class=arw>&rarr;</span> ((1 2) (3 4))
1418 (eval A)                        <span class=arw>&rarr;</span> ((1 2) (3 4))
1419 </pre></blockquote></blockquote
1420
1421
1422 <p><strong>Shell commands</strong>: If an <tt>!</tt> (exclamation mark)
1423 is entered as the first character on the command line followed by a shell
1424 command, the command will be executed. For example, <tt>!ls</tt> on Unix or
1425 <tt>!dir</tt> on Win32 will display a listing of the present working directory.
1426 No spaces are permitted between the <tt>!</tt> and the shell command. Symbols
1427 beginning with an <tt>!</tt> are still allowed inside expressions or  on the
1428 command line when preceded by a space. Note: This mode only works when running
1429 in the shell and does not work when controlling newLISP from another
1430 application.
1431 </p>
1432
1433 <p>To exit the newLISP shell on Linux/UNIX, press <tt>Ctrl-D</tt>; on Win32,
1434 type <tt>(exit)</tt> or <tt>Ctrl-C</tt>, then the x key.
1435 </p>
1436
1437 <p>Use the <a href="#exec">exec</a> function to access shell commands from
1438 other applications or to pass results back to newLISP.
1439 </p>
1440
1441 <center>
1442 <span class="divider">(&nbsp;<font color="#7ba9d4">&sect;</font>&nbsp;)</span>
1443 </center>
1444
1445                 <a NAME="lambda_expressions"></a>
1446                 <h2>
1447                         7. Lambda expressions in newLISP
1448                 </h2>
1449                 <p>
1450                 Lambda expressions in newLISP evaluate to themselves and can be treated
1451                 just like regular lists:
1452 <blockquote><pre>
1453 (set 'double (lambda (x) (+ x x))
1454 (set 'double (fn (x) (+ x x))      ; alternative syntax
1455
1456 (last double)  <span class=arw>&rarr;</span> (+ x x)          ; treat lambda as a list
1457
1458 </pre></blockquote>             <p>
1459                         Note: No <tt>'</tt> is necessary before the lambda expression since lambda expressions evaluate to themselves in newLISP.
1460                 </p>
1461                 <p>
1462                         The second line uses the keyword <tt>fn</tt>, an alternative syntax first suggested by Paul Graham for his Arc language project.
1463                 </p>
1464                 <p>
1465                         A lambda expression is a <em>lambda list</em>, a subtype of <em>list</em>, and its arguments can associate from left to right or right to left. When using <a HREF="#append">append</a>, for example, the arguments associate from left to right:
1466                 </p>
1467 <blockquote><pre>
1468 (append (lambda (x)) '((+ x x)))  <span class=arw>&rarr;</span> (lambda (x) (+ x x))
1469 </pre></blockquote>             <p>
1470                         <a HREF="#cons">cons</a>, on the other hand, associates the arguments from right to left:
1471                 </p>
1472 <blockquote><pre>
1473 (cons '(x) (lambda (+ x x)))  <span class=arw>&rarr;</span> (lambda (x) (+ x x))
1474 </pre></blockquote>             <p>
1475                         Note that the <tt>lambda</tt> keyword is not a symbol in a list, but a
1476                         designator of a special <em>type</em> of list: the <em>lambda list</em>.
1477                 </p>
1478 <blockquote><pre>
1479 (length (lambda (x) (+ x x)))  <span class=arw>&rarr;</span> 2
1480 (first (lambda (x) (+ x x)))   <span class=arw>&rarr;</span> (x)
1481 </pre></blockquote>             <p>
1482                         Lambda expressions can be mapped or applied onto arguments to work as user-defined, anonymous functions:
1483                 </p>
1484 <blockquote><pre>
1485 ((lambda (x) (+ x x)) 123)           <span class=arw>&rarr;</span> 246
1486 (apply (lambda (x) (+ x x)) '(123))  <span class=arw>&rarr;</span> 246
1487 (map (lambda (x) (+ x x)) '(1 2 3))  <span class=arw>&rarr;</span> (2 4 6)
1488 </pre></blockquote>             <p>
1489                         A lambda expression can be assigned to a symbol, which in turn can be used as a function:
1490                 </p>
1491 <blockquote><pre>
1492 (set 'double (lambda (x) (+ x x)))  <span class=arw>&rarr;</span> 246
1493 (double 123)                        <span class=arw>&rarr;</span> (lambda (x) (+ x x))
1494 </pre></blockquote>             <p>
1495                         The <a href="#define">define</a> function is just a shorter way of
1496                         assigning a lambda expression to a symbol:
1497                 </p>
1498 <blockquote><pre>
1499 (define (double x) (+ x x)))  <span class=arw>&rarr;</span> (lambda (x) (+ x x))
1500 (double 123)                  <span class=arw>&rarr;</span> 246
1501 </pre></blockquote>             <p>
1502                         In the above example, the expressions inside the lambda list are still accessible within <tt>double</tt>:
1503                 </p>
1504 <blockquote><pre>
1505 (set 'double (lambda (x) (+ x x)))  <span class=arw>&rarr;</span> (lambda (x) (+ x x))
1506 (last double)                       <span class=arw>&rarr;</span> (+ x x)
1507 </pre></blockquote>             <p>
1508                         A lambda list can be manipulated as a first-class object using any function that operates on lists:
1509                 </p>
1510 <blockquote><pre>
1511 (set-nth (double 1) '(mul 2 x))  <span class=arw>&rarr;</span> (lambda (x) (mul 2 x))
1512 double                         <span class=arw>&rarr;</span> (lambda (x) (mul 2 x))
1513 (double 123)                   <span class=arw>&rarr;</span> 246
1514 </pre></blockquote>             <p>
1515                         All arguments are optional when applying lambda expressions and default to <tt>nil</tt> when not supplied by the user. This makes it possible to write functions with multiple parameter signatures.
1516                 </p>
1517
1518 <center>
1519 <span class="divider">(&nbsp;<font color="#7ba9d4">&sect;</font>&nbsp;)</span>
1520 </center>
1521
1522                 <a NAME="nil_and_true"></a>
1523                 <h2>
1524                         8. <tt>nil</tt>, <tt>true</tt>, <tt>cons</tt>, and <tt>()</tt>
1525                 </h2>
1526                 <p>
1527                         In newLISP, <tt>nil</tt> and <tt>true</tt> represent both the symbols and the boolean values <em>true</em> and <em>false</em>. Depending on their context, <tt>nil</tt> and <tt>true</tt> are treated differently. The following examples use <tt>nil</tt>, but they can be applied to <tt>true</tt> by simply reversing the logic.
1528                 </p>
1529                 <p>
1530                         Evaluation of <tt>nil</tt> yields a boolean false and is treated as such inside control flow expressions, such as <tt>if</tt>, <tt>unless</tt>, <tt>while</tt>, <tt>until</tt>, and <tt>not</tt>. Likewise, evaluating <tt>true</tt> yields true.
1531                 </p>
1532 <blockquote><pre>
1533 (set 'lst '(nil nil nil))  <span class=arw>&rarr;</span> (nil nil nil)
1534 (map symbol? lst)          <span class=arw>&rarr;</span> (true true true)
1535 </pre></blockquote>             <p>
1536                         In the above example, <tt>nil</tt> represents a symbol. In the following example, <tt>nil</tt> and <tt>true</tt> are evaluated and represent boolean values:
1537                 </p>
1538 <blockquote><pre>
1539 (if nil "no" "yes")  <span class=arw>&rarr;</span> "yes"
1540 (if true "yes" "no") <span class=arw>&rarr;</span> "yes"
1541 (map not lst)        <span class=arw>&rarr;</span> (true true true)
1542 </pre></blockquote>             <p>
1543                         In newLISP, <tt>nil</tt> and the empty list <tt>()</tt> are not the same as in some other LISPs. Only in conditional expressions are they treated as a boolean false, as in <tt>and</tt>, <tt>or</tt>, <tt>if</tt>, <tt>while</tt>, <tt>unless</tt>, <tt>until</tt>, and <tt>cond</tt>.
1544                 </p>
1545                 <p>
1546                         The expression <tt>(list? '())</tt> is true, but <tt>(list? nil)</tt> is not. This is because in newLISP, <tt>nil</tt> results in a boolean false when evaluated.
1547                 </p>
1548                 <p>
1549                         Evaluation of <tt>(cons x '())</tt> yields <tt>(x)</tt>, but <tt>(cons x nil)</tt> yields <tt>(x nil)</tt> because <tt>nil</tt> is treated as a boolean value when evaluated instead of as an empty list. The <tt>cons</tt> of two atoms in newLISP does not yield a dotted pair, but rather a two-element list. The predicate <tt>atom?</tt> is true for <tt>nil</tt>, but false for the empty list. The empty list in newLISP is only an empty list and not equal to <tt>nil</tt>.
1550                 </p>
1551                 <p>
1552                         A list in newLISP is a LISP cell of type list. It acts like a container for the linked list of elements making up the list cell's contents. There is no <em>dotted pair</em> in newLISP because the <em>cdr</em> (tail) part of a LISP cell always points to another LISP cell and never to a basic data type, such as a number or a symbol. Only the <em>car</em> (head) part may contain a basic data type. Early LISP implementations used car and cdr for the names <em>head</em> and <em>tail</em>.
1553                 </p>
1554
1555 <center>
1556 <span class="divider">(&nbsp;<font color="#7ba9d4">&sect;</font>&nbsp;)</span>
1557 </center>
1558
1559                 <a NAME="arrays"></a>
1560                 <h2>
1561                         9. Arrays
1562                 </h2>
1563                 <p>
1564                         newLISP's arrays enable fast element access within large lists. New arrays can be constructed and initialized with the contents of an existing list using the function <a href="#array">array</a>. Lists can be converted into arrays, and vice versa. Some of the same functions used for modifying and accessing lists can be applied to arrays, as well. Arrays can hold any type of data or combination thereof.
1565                 </p>
1566                 <p>
1567                         In particular, the following functions can be used for creating, accessing, and modifying arrays:
1568                 </p>
1569                 <br />
1570
1571 <center>
1572 <table class="list" width="95%" summary="functions using arrays">
1573 <tr align="left"><th>function</th><th>description</th></tr>
1574
1575 <tr>
1576 <td class="left"><a href="#append">append</a></td>
1577 <td class="right">appends arrays</td>
1578 </tr>
1579
1580 <tr>
1581 <td class="left"><a href="#array">array</a></td>
1582 <td class="right">creates and initializes an array with up to 16 dimensions</td>
1583 </tr>
1584
1585 <tr>
1586 <td class="left"><a href="#array-list">array-list</a></td>
1587 <td class="right">converts an array into a list</td>
1588 </tr>
1589
1590 <tr>
1591 <td class="left"><a href="#arrayp">array?</a></td>
1592 <td class="right">checks if expression is an array</td>
1593 </tr>
1594
1595 <tr>
1596 <td class="left"><a href="#det">det</a></td>
1597 <td class="right">returns the determinant of a matrix</td>
1598 </tr>
1599
1600 <tr>
1601 <td class="left"><a href="#first">first</a></td>
1602 <td class="right">returns the first row of an array</td>
1603 </tr>
1604
1605 <tr>
1606 <td class="left"><a href="#invert">invert</a></td>
1607 <td class="right">returns the inversion of a matrix</td>
1608 </tr>
1609
1610 <tr>
1611 <td class="left"><a href="#last">last</a></td>
1612 <td class="right">returns the last row of an array</td>
1613 </tr>
1614
1615 <tr>
1616 <td class="left"><a href="#multiply">multiply</a></td>
1617 <td class="right">multiplies two matrices</td>
1618 </tr>
1619
1620 <tr>
1621 <td class="left"><a href="#nth">nth</a></td>
1622 <td class="right">returns an element of and array</td>
1623 </tr>
1624
1625 <tr>
1626 <td class="left"><a href="#nth-set">nth-set</a></td>
1627 <td class="right">changes the element, returning the old; significantly faster than <tt>set-nth</tt></td>
1628 </tr>
1629
1630 <tr>
1631 <td class="left"><a href="#rest">rest</a></td>
1632 <td class="right">returns all but the first row of an array</td>
1633 </tr>
1634
1635 <tr>
1636 <td class="left"><a href="#set-nth">set-nth</a></td>
1637 <td class="right">changes the element and returns the changed array</td>
1638 </tr>
1639
1640 <tr>
1641 <td class="left"><a href="#slice">slice</a></td>
1642 <td class="right">returns a slice of an array</td>
1643 </tr>
1644
1645 <tr>
1646 <td class="left"><a href="#sort">sort</a></td>
1647 <td class="right">sort the elements in an array</td>
1648 </tr>
1649
1650 <tr>
1651 <td class="left"><a href="#transpose">transpose</a></td>
1652 <td class="right">transposes a matrix</td>
1653 </tr>
1654 </table>
1655 </center>
1656
1657                 <br />
1658                 <p>
1659                         newLISP represents multidimensional arrays with an array of arrays (i.e., the elements of the array are themselves arrays).
1660                 </p>
1661                 <p>
1662                         When used interactively, newLISP prints and displays arrays as lists, with no way of distinguishing between them.
1663                 </p>
1664                 <p>
1665                         Use the <a href="#source">source</a> or <a href="#save">save</a> functions to serialize arrays (or the variables containing them). The <a href="#array">array</a> statement is included as part of the definition when serializing arrays.
1666                 </p>
1667                 <p>
1668                         Like lists, negative indices can be used to enumerate the elements of an array, starting from the last element.
1669                 </p>
1670                 <p>
1671                         An out-of-bounds index will cause an error message on an array.  In contrast, lists pick the last or first element when an out-of-bounds occurs.
1672                 </p>
1673                 <p>
1674                         Arrays can be non-rectangular, but they are made rectangular during serialization when using <a href="#source">source</a> or <a href="#save">save</a>. The <a href="#array">array</a> function always constructs arrays in rectangular form.
1675                 </p>
1676                 <p>
1677                         The matrix functions <a href="#det">det</a>, <a href="#transpose">transpose</a>, <a href="#multiply">multiply</a>, and <a href="#invert">invert</a> can be used on matrices built with nested
1678 lists or arrays built with <a href="#array">array</a>.
1679                 </p>
1680                 <p>
1681                         For more details, see <a href="#array">array</a>, <a href="#arrayp">array?</a>, and <a href="#array-list">array-list</a> in the reference section of this manual.
1682                 </p>
1683
1684 <center>
1685 <span class="divider">(&nbsp;<font color="#7ba9d4">&sect;</font>&nbsp;)</span>
1686 </center>
1687
1688 <a NAME="hash"></a>
1689 <h2>
1690 10. Dictionaries (hash tables)
1691 </h2>
1692
1693 <p>newLISP has no built-in <em>hash table</em> data type. Instead, it uses symbols for associative memory access. Symbols in newLISP are implemented using an efficient <em>red-black tree</em> algorithm. This algorithm balances the binary symbol tree for faster symbol access. In newLISP, symbol trees are represented as namespaces called <em>contexts</em>, which are themselves part of the <tt>MAIN</tt> namespace.
1694 </p>
1695
1696 <p>For a more detailed introduction to <em>namespaces</em>, see the chapter on
1697 <a href="#contexts">Contexts</a>.
1698 </p>
1699
1700 <p>The <a href="#context">context</a> function can be used to make associations. It can also be used to create and switch contexts.
1701 </p>
1702
1703 <blockquote><pre>
1704 ;; create a symbol and store data into it
1705 (context 'MyHash "John Doe" 123)         <span class=arw>&rarr;</span> 123
1706 (context 'MyHash "@#$%^" "hello world")  <span class=arw>&rarr;</span> "hello world"
1707
1708 ;; retrieve contents from the symbol
1709 (context 'MyHash "John Doe")  <span class=arw>&rarr;</span> 123
1710 (context 'MyHash "@#$%^")     <span class=arw>&rarr;</span> "hello world"
1711 </pre></blockquote>
1712
1713 <p>The first two statements create the symbols <tt>"John Doe"</tt> and <tt>"@#$^"</tt>, storing the values <tt>123</tt> and <tt>"hello world"</tt> into them. The hash context named <tt>MyHash</tt> is created in the first statement, while the second merely adds the new association to the existing one.
1714 </p>
1715
1716 <p>
1717 Note that hash symbols can contain spaces or other special characters
1718 not typically allowed in variable names.
1719 </p>
1720
1721 <p>Internally, <a href="#context">context</a> is just a shorter
1722 and faster form of:
1723 </p>
1724
1725 <blockquote><pre>
1726 ;; create a symbol and store the data in it
1727 (set (sym "John Doe" 'MyHash) 123)  <span class=arw>&rarr;</span> 123
1728
1729 ;; retrieve contents from the symbol
1730 (eval (sym "John Doe" MyHash))  <span class=arw>&rarr;</span> 123
1731 </pre></blockquote>
1732
1733 <p>The context <a href="#default_function">default function</a> can be used for a
1734 very short definition of a hash function:
1735 </p>
1736
1737 <blockquote><pre>
1738 (define (myhash:myhash key value)
1739    (if value
1740        (context myhash key value)
1741        (context myhash key)))
1742
1743 ;; create a dictionary key value pair
1744 (myhash "hello" 123)    <span class=arw>&rarr;</span> 123
1745
1746 ;; retrieve the key value
1747 (myhash "hello")        <span class=arw>&rarr;</span> 123
1748 </pre></blockquote>
1749
1750
1751 <center>
1752 <span class="divider">(&nbsp;<font color="#7ba9d4">&sect;</font>&nbsp;)</span>
1753 </center>
1754
1755 <a NAME="indexing"></a>
1756 <h2>11. Indexing elements of strings, lists, and arrays</h2>
1757
1758 <p>Some functions take array, list, or string elements (characters) specified by one or more <em>int-index</em> (integer index). The positive indices run <tt>0, 1, &hellip;, N-2, N-1</tt>, where <tt>N</tt> is the number of elements in the list. If int-index is negative, the sequence is <tt>-N, -N+1, &hellip;, -2, -1</tt>. Adding <tt>N</tt> to the negative index of an element yields the positive index. Unless a function does otherwise, an index greater than <tt>N-1</tt> returns the last element in a list; it returns the first element for indices less than <tt>-N</tt>. An error message is produced for any indexing occurring outside an array's boundaries.</p>
1759
1760 <br />
1761 <a NAME="implicit_indexing"></a>
1762 <h3>Implicit indexing for <tt>nth</tt></h3>
1763
1764 <p>Implicit indexing can be used instead of <a href="#nth">nth</a> to retrieve the elements of a list or array or the characters of a string:</p>
1765
1766 <blockquote><pre>
1767 (set 'lst '(a b c (d e) (f g)))
1768
1769 (lst 0)    <span class=arw>&rarr;</span> a      ; same as (nth (lst 0))
1770 (lst 3)    <span class=arw>&rarr;</span> (d e)
1771 (lst 3 1)  <span class=arw>&rarr;</span> e      ; same as (nth (lst 3 1))
1772 (lst -1)   <span class=arw>&rarr;</span> (f g)
1773
1774 (set 'myarray (array 3 2 (sequence 1 6)))
1775
1776 (myarray 1)     <span class=arw>&rarr;</span> (3 4)
1777 (myarray 1 0)   <span class=arw>&rarr;</span> 3
1778 (myarray 0 -1)  <span class=arw>&rarr;</span> 2
1779
1780 ("newLISP" 3)   <span class=arw>&rarr;</span> "L"
1781 </pre></blockquote>
1782
1783 <p>Indices may also be supplied from a list. In this way, implicit indexing works together with functions that take or produce index vectors, such as <a href="#push">push</a>, <a href="#pop">pop</a>, <a href="#ref">ref</a>
1784 and <a href="#ref-all">ref-all</a>.</p>
1785
1786 <blockquote><pre>
1787 (lst '(3 1))             <span class=arw>&rarr;</span> e
1788 (set 'vec (ref 'e lst))  <span class=arw>&rarr;</span> (3 1)
1789 (lst vec)                <span class=arw>&rarr;</span> e
1790 </pre></blockquote>
1791
1792 <p>Note that implicit indexing is not breaking Lisp
1793 syntax rules but is merely an expansion of existing rules to
1794 other data types in the functor position of an s-expression.
1795 In original Lisp the first element in an s-expression list
1796 is applied as a function to the rest elements as arguments. In newLISP a list
1797 in the functor position of an s-expression assumes self-indexing functionality
1798 using the index arguments following it.</p>
1799
1800 <p>Implicit indexing is faster than the explicit forms, but the explicit forms
1801 may be more readable depending on context.</p>
1802
1803 <p>Note that in the UTF-8&ndash;enabled version of newLISP, implicit indexing of strings using the <a href="#nth">nth</a> function works on character rather than byte boundaries.</p>
1804
1805 <br />
1806
1807
1808 <a NAME="implicit_default"></a>
1809 <h3>Implicit indexing and the default functor</h3>
1810
1811 <p>The <em>default functor</em> is a functor inside a context with the same name as the context itself. See <a href="#default_function">The context default function</a> chapter. A default functor can be used together with implicit indexing to serve as a mechanism for referencing lists:</p>
1812
1813 <blockquote><pre>
1814 (set 'MyList:MyList '(a b c d e f g))
1815
1816 (MyList 0)   <span class=arw>&rarr;</span> a
1817 (MyList 3)   <span class=arw>&rarr;</span> d
1818 (MyList -1)  <span class=arw>&rarr;</span> g
1819
1820 (3 2 MyList) <span class=arw>&rarr;</span> (d e)
1821 (-3 MyList)  <span class=arw>&rarr;</span> (e f g)
1822
1823 (set 'aList MyList)
1824
1825 (aList 3)  <span class=arw>&rarr;</span> d
1826 </pre></blockquote>
1827
1828 <p>In this example, <tt>aList</tt> references <tt>MyList:MyList</tt>, not a copy of it. For more information about contexts, see <a href="#context_objects">Programming with contexts</a>.</p>
1829
1830 <p>The default functor can also be used with <a href="#nth-set">nht-set</a> as shown in the following
1831 example:</p>
1832
1833 <blockquote><pre>
1834 (set 'MyList:MyList '(a b c d e f g))
1835
1836 (nth-set (MyList 3) 999)   <span class=arw>&rarr;</span> d
1837 (MyList 3)                 <span class=arw>&rarr;</span> 999
1838 </pre></blockquote>
1839
1840 <br />
1841 <a NAME="implicit_rest_slice"></a>
1842 <h3>Implicit indexing for <tt>rest</tt> and <tt>slice</tt> </h3>
1843
1844 <p> Implicit forms of <a href="#rest">rest</a> and <a href="#slice">slice</a>
1845 can be created by prepending a list with one or two numbers for offset and length.
1846 If the length is negative it counts from the end of the list or string:</p>
1847
1848 <blockquote><pre>
1849 (set 'lst '(a b c d e f g))
1850 ; or as array
1851 (set 'lst (array 7 '(a b c d e f g)))
1852
1853 (1 lst)      <span class=arw>&rarr;</span> (b c d e f g)
1854 (2 lst)      <span class=arw>&rarr;</span> (c d e f g)
1855 (2 3 lst)    <span class=arw>&rarr;</span> (c d e)
1856 (-3 2 lst)   <span class=arw>&rarr;</span> (e f)
1857 (2 -2 lst)   <span class=arw>&rarr;</span> (d e)
1858
1859 (set 'str "abcdefg")
1860
1861 (1 str)      <span class=arw>&rarr;</span> "bcdefg"
1862 (2 str)      <span class=arw>&rarr;</span> "cdefg"
1863 (2 3 str)    <span class=arw>&rarr;</span> "cde"
1864 (-3 2 str)   <span class=arw>&rarr;</span> "ef"
1865 (2 -2 str)   <span class=arw>&rarr;</span> "de"
1866 </pre></blockquote>
1867
1868 <p>Implicit indexing for <a href="#rest">rest</a> works on
1869 character rather than byte boundaries when using the UTF-8&ndash;enabled version
1870 of newLISP, whereas implicit indexing for <a href="#slice">slice</a> will always
1871 work on byte boundaries and can be used for binary content.</p>
1872
1873 <br />
1874
1875 <a NAME="implicit_nth-set"></a>
1876
1877 <h3>Implicit indexing for <tt>nth-set</tt> and <tt>set-nth</tt></h3>
1878
1879 <blockquote>
1880 <pre>
1881
1882 (set 'aList '(a b c (d e (f g) h i) j k))
1883
1884 (nth-set (aList 0) 1) <span class=arw>&rarr;</span> a
1885
1886 (nth-set (aList 3 2) '(1 2 3 4)) <span class=arw>&rarr;</span> (f g)
1887
1888 (set 'i 3 'j 2 'k 2)
1889
1890 (nth-set (aList i j k) 99) <span class=arw>&rarr;</span> 3
1891
1892 aList
1893 <span class=arw>&rarr;</span> (1 b c (d e (1 2 99 4) h i) j k)
1894
1895 (set-nth (aList -3 -3 2) 999)
1896 <span class=arw>&rarr;</span> (1 b c (d e (1 2 999 4) h i) j k)
1897 </pre>
1898 </blockquote>
1899
1900 <p>As with <a href="#nth">nth</a>, indices can be supplied in a vector list to work together with
1901 functions handling index vectors such as <a href="#push">push</a>, <a href="#pop">pop</a>, <a href="#ref">ref</a>
1902 and <a href="#ref-all">ref-all</a>.<p>
1903
1904 <blockquote>
1905 <pre>
1906
1907 (set 'aList '(a b c (d e (f g) h i) j k))
1908
1909 (set 'vec (ref 'f aList))   <span class=arw>&rarr;</span> (3 2 0)
1910
1911 (set-nth (aList vec) 999)
1912
1913 (set-nth (aList vec) 999)   <span class=arw>&rarr;</span> (a b c (d e (999 g) h i) j k)
1914
1915 (nth-set (aList vec) 'Z)   <span class=arw>&rarr;</span> 999 ; old value
1916
1917 aList   <span class=arw>&rarr;</span> (a b c (d e (Z g) h i) j k)
1918 </pre>
1919 </blockquote>
1920
1921 <br />
1922
1923 <center>
1924 <span class="divider">(&nbsp;<font color="#7ba9d4">&sect;</font>&nbsp;)</span>
1925 </center>
1926
1927
1928                 <a NAME="destructive"></a>
1929                 <h2>
1930                         12. Destructive versus nondestructive functions
1931                 </h2>
1932                 <p>
1933                         Most of the primitives in newLISP are nondestructive (no <em>side effects</em>) and leave existing objects untouched, although they may create new ones. There are a few destructive functions, however, that <em>do</em> change the contents of a list, string, or variable:
1934                 </p>
1935 <br />
1936 <center>
1937 <table class="list" width="95%" summary="destructive functions">
1938 <tr align="left"><th>function</th><th>description</th></tr>
1939
1940 <tr>
1941 <td class="left"><a href="#bind">bind</a></td>
1942 <td class="right">binds variable associations in a list</td>
1943 </tr>
1944 <tr>
1945 <td class="left"><a href="#constant">constant</a></td>
1946 <td class="right">sets the contents of a variable and protects it</td>
1947 </tr>
1948 <tr>
1949 <td class="left"><a href="#dec">dec</a></td>
1950 <td class="right">decrements the value in a variable</td>
1951 </tr>
1952
1953 <tr>
1954 <td class="left"><a href="#inc">inc</a></td>
1955 <td class="right">increments the value in a variable</td>
1956 </tr>
1957
1958 <tr>
1959 <td class="left"><a href="#net-receive">net-receive</a></td>
1960 <td class="right">reads into a buffer variable</td>
1961 </tr>
1962
1963 <tr>
1964 <td class="left"><a href="#pop">pop</a></td>
1965 <td class="right">pops an element from a list or string</td>
1966 </tr>
1967
1968 <tr>
1969 <td class="left"><a href="#pop-assoc">pop-assoc</a></td>
1970 <td class="right">remove an association from an association list</td>
1971 </tr>
1972
1973 <tr>
1974 <td class="left"><a href="#push">push</a></td>
1975 <td class="right">pushes a new element onto a list or string</td>
1976 </tr>
1977
1978 <tr>
1979 <td class="left"><a href="#push-assoc">push-assoc</a></td>
1980 <td class="right">remove an association from an association list</td>
1981 </tr>
1982
1983 <tr>
1984 <td class="left"><a href="#read-buffer">read-buffer</a></td>
1985 <td class="right">reads into a buffer variable</td>
1986 </tr>
1987
1988 <tr>
1989 <td class="left"><a href="#replace">replace</a></td>
1990 <td class="right">replaces elements in a list or string</td>
1991 </tr>
1992
1993 <tr>
1994 <td class="left"><a href="#replace-assoc">replace-assoc</a></td>
1995 <td class="right">replace an element in an association list</td>
1996 </tr>
1997
1998 <tr>
1999 <td class="left"><a href="#reverse">reverse</a></td>
2000 <td class="right">reverses a list or string</td>
2001 </tr>
2002
2003 <tr>
2004 <td class="left"><a href="#rotate">rotate</a></td>
2005 <td class="right">rotates the elements of a list or characters of a string</td>
2006 </tr>
2007
2008 <tr>
2009 <td class="left"><a href="#set">set, setq</a></td>
2010 <td class="right">sets the contents of a variable</td>
2011 </tr>
2012
2013 <tr>
2014 <td class="left"><a href="#set-assoc">set-assoc</a>, <a href="#assoc-set">assoc-set</a></td>
2015 <td class="right">replaces an element in an association list</td>
2016 </tr>
2017
2018 <tr>
2019 <td class="left"><a href="#set-nth">set-nth</a>, <a href="#nth-set">nth-set</a></td>
2020 <td class="right">changes an element in a list or string</td>
2021 </tr>
2022
2023 <tr>
2024 <td class="left"><a href="#set-ref">set-ref</a>, <a href="#ref-set">ref-set</a></td>
2025 <td class="right">searches for an element in a nested list and replaces it</td>
2026 </tr>
2027
2028 <tr>
2029 <td class="left"><a href="#set-ref-all">set-ref-all</a></td>
2030 <td class="right">searches for an element in a nested list and replaces all instances</td>
2031 </tr>
2032
2033 <tr>
2034 <td class="left"><a href="#sort">sort</a></td>
2035 <td class="right">sorts the elements of a list or array</td>
2036 </tr>
2037
2038 <tr>
2039 <td class="left"><a href="#swap">swap</a></td>
2040 <td class="right">swaps two elements inside a list or string</td>
2041 </tr>
2042
2043 <tr>
2044 <td class="left"><a href="#write-buffer">write-buffer</a></td>
2045 <td class="right">writes to a string buffer or file</td>
2046 </tr>
2047
2048 <tr>
2049 <td class="left"><a href="#write-line">write-line</a></td>
2050 <td class="right">writes to a string buffer or file</td>
2051 </tr>
2052
2053 </table></center>
2054 <br />
2055
2056 <p>Note that the last two functions, <a href="#write-buffer">write-buffer</a> and <a href="#write-line"> write-line</a>, are only destructive in one of their syntactic forms: when taking a string buffer instead of a file handle.</p>
2057
2058 <br />
2059
2060 <a NAME="make_nondestructive"></a>
2061 <h3>Make a destructive function non-destructive</h3>
2062
2063 <p>Some destructive functions can be made non-destruvtive by wrapping the target object into a <a href="#begin">begin</a>
2064 block. A block returns a copy of the last evaluation in the block and the destructive function will work on the
2065 copy instead of the original.</p>
2066
2067 <blockquote><pre>
2068 (set 'aList '(a b c d e f))
2069
2070 (replace 'c (begin aList)) <span class=arw>&rarr;</span> (a b d e f)
2071
2072 aList <span class=arw>&rarr;</span> (a b c d e f)
2073
2074 (set 'str "newLISP") <span class=arw>&rarr;</span> "newLISP"
2075
2076 (rotate (begin str)) <span class=arw>&rarr;</span> "PnewLIS"
2077
2078 str <span class=arw>&rarr;</span> "newLISP"
2079 </pre></blockquote>
2080
2081 <br />
2082
2083 <center>
2084 <span class="divider">(&nbsp;<font color="#7ba9d4">&sect;</font>&nbsp;)</span>
2085 </center>
2086
2087                 <a NAME="scoping"></a>
2088                 <h2>
2089                         13. Dynamic and lexical scoping
2090                 </h2>
2091                 <p>
2092                         newLISP uses dynamic scoping <em>inside</em> contexts. A context is a lexically closed namespace. In this way, parts of a newLISP program can live in different namespaces taking advantage of <em>lexical scoping</em>.
2093                 </p>
2094                 <p>
2095                         When the parameter symbols of a lambda expression are bound to its arguments, the old bindings are pushed on a stack. newLISP automatically restores the original variable bindings when leaving the lambda function.
2096                 </p>
2097                 <p>
2098                         The following example illustrates the <em>dynamic scoping</em> mechanism. The text in bold is the output from newLISP:
2099                 </p>
2100 <blockquote><pre>
2101 &gt; (set 'x 1)
2102 <b>1</b>
2103 &gt; (define (f) x)
2104 <b>(lambda () x)</b>
2105 &gt; (f)
2106 <b>1</b>
2107 &gt; (define (g x) (f))
2108 <b>(lambda (x) (f))</b>
2109 &gt; (g 0)
2110 <b>0</b>
2111 &gt; (f)
2112 <b>1</b>
2113 &gt; _
2114 </pre></blockquote>
2115
2116 <p>The variable <tt>x</tt> is first set to <tt>1</tt>, but when <tt>(g 0)</tt> is called <tt>x</tt> is
2117 bound to <tt>0</tt> and <tt>x</tt> is reported by <tt>(f)</tt> as <tt>0</tt> during execution of <tt>(g 0)</tt>. After execution of <tt>(g 0)</tt> the call to <tt>(f)</tt> will report <tt>x</tt> as <tt>1</tt> again.</p>
2118
2119 <p>This is different from the <em>lexical scoping</em> mechanisms found in languages like C or Java, where the binding of local parameters occurs inside the function only. In lexically scoped languages like C, <tt>(f)</tt> would always print the global bindings of the symbol <tt>x</tt> with <tt>1</tt>.
2120                 </p>
2121                 <p>
2122                         Be aware that passing quoted symbols to a user-defined function causes a name clash if the same variable name is used as a function parameter:
2123                 </p>
2124 <blockquote><pre>
2125 (define (inc-symbol x y) (inc x y))
2126 (set 'y 200)
2127 (inc-symbol 'y 123)  <span class=arw>&rarr;</span> 246
2128 y                    <span class=arw>&rarr;</span> 200  ; y is still 200
2129 </pre></blockquote>             <p>
2130                         Since <tt>'y</tt> shares the same name as the function's second parameter, <tt>inc-symbol</tt> returns 246 (123 + 123), leaving <tt>'y</tt> unaffected. Dynamic scoping's <em>variable capture</em> can be a disadvantage when passing symbol references to user-defined functions.
2131                 </p>
2132                 <p>
2133                         The problem is avoided entirely by grouping related user-defined functions into a <a href="#contexts">context</a>. A symbol name clash cannot occur when accessing symbols and calling functions from <em>outside</em> of the defining context.
2134                 </p>
2135                 <p>
2136                         Contexts should be used to group related functions when creating interfaces or function libraries. This surrounds the functions with a lexical "fence," thus avoiding variable name clashes with the calling functions.
2137                 </p>
2138                 <p>
2139                         newLISP uses contexts for different forms of lexical scoping. See the chapters <a href="#contexts">Contexts</a> and <a href="#context_objects">Programming with contexts</a>, as well as the section <a href="#default_function">default functions</a> for more information.
2140                 </p>
2141
2142 <center>
2143 <span class="divider">(&nbsp;<font color="#7ba9d4">&sect;</font>&nbsp;)</span>
2144 </center>
2145
2146                 <a NAME="return"></a>
2147                 <h2>
2148                         14. Early return from functions, loops, and blocks
2149                 </h2>
2150                 <p>
2151                         What follows are methods of interrupting the control flow inside both loops and the <a href="#begin">begin</a> expression.
2152                 </p>
2153
2154                 <p>The looping functions <a href="#dolist">dolist</a> and <a href="#dotimes">
2155 dotimes</a> can take optional conditional expressions to leave the loop
2156 early. <a href="#catch">catch</a> and <a href="#throw">throw</a> are a more
2157 general form to break out of a loop body and are also applicable to other
2158 forms or statement blocks.
2159 </p>
2160
2161                 <br />
2162                 <a NAME="flow_catch_throw"></a>
2163                 <h3>
2164                         Using <tt>catch</tt> and <tt>throw</tt>
2165                 </h3>
2166                 <p>
2167                         Because newLISP is a functional language, it uses no <tt>break</tt> or <tt>return</tt> statements to exit functions or iterations. Instead, a block or function can be exited at any point using the functions <a href="#catch">catch</a> and <a href="#throw">throw</a>:
2168                 </p>
2169 <blockquote><pre>
2170 (define (foo x)
2171     (&hellip;)
2172     (if condition (throw 123))
2173     (&hellip;)
2174     456)
2175
2176 ;; if condition is true
2177
2178 (catch (foo p))  <span class=arw>&rarr;</span> 123
2179
2180 ;; if condition is not true
2181
2182 (catch (foo p))  <span class=arw>&rarr;</span> 456
2183 </pre></blockquote>             <p>
2184                         Breaking out of loops works in a similar way:
2185                 </p>
2186 <blockquote><pre>
2187 (catch
2188     (dotimes (i N)
2189         (if (= (foo i) 100) (throw i))))
2190 <span class=arw>&rarr;</span> value of i when foo(i) equals 100
2191 </pre></blockquote>             <p>
2192                         The example shows how an iteration can be exited before executing <tt>N</tt> times.
2193                 </p>
2194                 <p>
2195                         Multiple points of return can be coded using <a href="#throw">throw</a>:
2196                 </p>
2197 <blockquote><pre>
2198 (catch (begin
2199     (foo1)
2200     (foo2)
2201     (if condition-A (throw 'x))
2202     (foo3)
2203     (if condition-B (throw 'y))
2204     (foo4)
2205     (foo5)))
2206 </pre></blockquote>             <p>
2207                         If <tt>condition-A</tt> is true, <tt>x</tt> will be returned from the <tt>catch</tt> expression; if <tt>condition-B</tt> is true, the value returned is <tt>y</tt>. Otherwise, the result from <tt>foo5</tt> will be used as the return value.
2208                 </p>
2209                 <p>
2210                         As an alternative to <a href="#catch">catch</a>, the <a href="#throw-error">throw-error</a> function can be used
2211                         to catch errors caused by faulty code
2212                         or user-initiated exceptions.
2213                 </p>
2214                 <br />
2215                 <a name="flow_and_or"></a>
2216                 <h3>
2217                         Using <tt>and</tt> and <tt>or</tt>
2218                 </h3>
2219                 <p>
2220                         Using the logical functions <a href="#and">and</a> and <a href="#or">or</a>, blocks of statements can be built that are exited depending on the boolean result of the enclosed functions:
2221                 </p>
2222 <blockquote><pre>
2223 (and
2224     (func-a)
2225     (func-b)
2226     (func-c)
2227     (func-d))
2228 </pre></blockquote>             <p>
2229                         The <a href="#and">and</a> expression will return as soon as one of the block's functions returns <tt>nil</tt> or an <tt>()</tt> (empty list). If none of the preceding functions causes an exit from the block, the result of the last function is returned.
2230                 </p>
2231                 <p>
2232                         <a href="#or">or</a> can be used in a similar fashion:
2233                 </p>
2234 <blockquote><pre>
2235 (or
2236     (func-a)
2237     (func-b)
2238     (func-c)
2239     (func-d))
2240 </pre></blockquote>             <p>
2241                         The result of the <a href="#or">or</a> expression will be the first function that returns a value which is <em>not</em> <tt>nil</tt> or <tt>()</tt>.
2242                 </p>
2243
2244 <center>
2245 <span class="divider">(&nbsp;<font color="#7ba9d4">&sect;</font>&nbsp;)</span>
2246 </center>
2247
2248 <a name="contexts"></a>
2249 <h2>15. Contexts</h2>
2250
2251 <p>In newLISP, symbols can be separated into namespaces called <em>contexts</em>. Each context has a private symbol table lexically separate from all other contexts. Symbols known in one context are unknown in others, so the same name may be used in different contexts without conflict.</p>
2252
2253 <p>Contexts are used to build modules of isolated variable and function definitions. They can also be copied and dynamically assigned to variables or passed as arguments. Because contexts in newLISP have lexically separated namespaces, they allow programming with <em>lexical scoping</em> and software object styles of programming.</p>
2254
2255 <p>Contexts are identified by symbols that are part of the root or <tt>MAIN</tt> context. While context symbols are uppercased in this chapter, lowercase symbols may also be used.</p>
2256
2257 <p>In addition to context names, <tt>MAIN</tt> contains the symbols for built-in functions and special symbols such as <tt>true</tt> and <tt>nil</tt>. The <tt>MAIN</tt> context is created automatically each time newLISP is run. To see all the symbols in <tt>MAIN</tt>, enter the following expression after starting newLISP:</p>
2258
2259 <blockquote><pre>
2260 (symbols)
2261 </pre></blockquote>
2262
2263 <br />
2264
2265 <a name="context_rules"></a>
2266 <h3>Symbol creation in contexts</h3>
2267
2268 <p>The following rules should simplify the process of understanding contexts by
2269 identifying which ones the created symbols are being assigned to.</p>
2270
2271 <ol>
2272 <li>
2273 <p>newLISP first parses and translates each top level expression. The symbols
2274 are created during the parsing and translation phase. After the expression
2275 is translated it gets evaluated.</p>
2276 </li>
2277
2278 <li>
2279 <p>A symbol is created when newLISP first <em>sees</em> it, when calling the
2280 <a href="#load">load</a>, <a href="#sym">sym</a>,
2281 or <a href="#eval-string">eval-string</a> functions. When newLISP reads
2282 a source file, symbols are created <em>before</em> evaluation occurs.</p>
2283 </li>
2284
2285 <li>
2286 <p>When an unknown symbol is encountered during code translation,
2287 a search for its definition begins inside the current context.
2288 Failing that, the search continues inside <tt>MAIN</tt> for a
2289 built-in function, context, or global symbol. If no definition
2290 is found, the symbol is created locally inside the current context.</p>
2291 </li>
2292
2293 <li>
2294 <p>Once a symbol is created and assigned to a specific context,
2295 it will belong to that context permanently.</p>
2296 </li>
2297
2298 <li>
2299 <p>A user-defined function is evaluated in the context of the symbol it is called with.</p>
2300 </li>
2301
2302 </ol>
2303 <br />
2304 <a name="scope_context"></a>
2305 <h3>Scoping rules for contexts</h3>
2306 <p>
2307 Special symbols like <tt>nil</tt> and <tt>true</tt>, as well as context and built-in function symbols, are global (visible to all contexts). Any symbol in the <tt>MAIN</tt> context can be made global by using the <a href="#global">global</a> function.</p>
2308
2309 <p>The following simulates a command-line session in newLISP:</p>
2310
2311 <blockquote><pre>
2312 &gt; (context 'FOO)
2313 <strong>FOO</strong>
2314 FOO&gt; _
2315 </pre></blockquote>             <p>
2316                         If the <tt>FOO</tt> context already exists, newLISP switches to it. Otherwise, the context is created before the switch occurs. All symbols now read from the command line are created and known only within the context <tt>FOO</tt>. Note that the symbol used for the context name must be quoted (<tt>'FOO</tt> in this example) the first time a context is created. Subsequent uses of <tt>context</tt> do not require the quote. After the switch, the command-line prompt changes to <tt>FOO&gt;</tt> :
2317                 </p>
2318 <blockquote><pre>
2319 FOO&gt; (set 'x 123)
2320 <strong>123</strong>
2321 FOO&gt; (set 'y 456)
2322 <strong>456</strong>
2323 FOO&gt; (symbols)
2324 <strong>(x y)</strong>
2325 FOO&gt; _
2326 </pre></blockquote>             <p>
2327                         To switch back to the <tt>MAIN</tt> context, use:
2328                 </p>
2329 <blockquote><pre>
2330 FOO&gt; (context MAIN)
2331 MAIN
2332 &gt; _
2333 </pre></blockquote>             <p>
2334                         A symbol can be referenced from outside its defining context by prepending a context name and a colon to it:
2335                 </p>
2336 <blockquote><pre>
2337 &gt; FOO:x
2338 <strong>123</strong>
2339 &gt; _
2340 </pre></blockquote>             <p>
2341                         The same symbol may also be used in another context:
2342                 </p>
2343 <blockquote><pre>
2344 &gt; (context 'FOO-B)
2345 <strong>FOO-B</strong>
2346 FOO-B&gt; (set 'x 777)
2347 <strong>777</strong>
2348 FOO-B&gt; FOO:x
2349 <strong>123</strong>
2350 &gt; _
2351 </pre></blockquote>             <p>
2352                         When quoting a fully qualified symbol (<tt>context:symbol</tt>), the quote precedes the context name:
2353                 </p>
2354 <blockquote><pre>
2355 &gt; (set 'FOO-B:x 555)
2356 <strong>555</strong>
2357 &gt; _
2358 </pre></blockquote>             <p>
2359                         A context is implicitly created when referring to one that does not yet exist. Unlike the <tt>context</tt> function, the context is not switched. The following statements are all executed inside the <tt>MAIN</tt> context:
2360                 </p>
2361 <blockquote><pre>
2362 &gt; (set 'ACTX:var "hello")
2363 <strong>"hello"</strong>
2364 &gt; ACTX:var
2365 <strong>"hello"</strong>
2366 &gt; _
2367 </pre></blockquote>             <p>
2368                         The same symbol (<tt>x</tt> in this case) used in a context can also be used in MAIN. Now we have three versions of <tt>x</tt>, all in a different context:
2369                 </p>
2370 <blockquote><pre>
2371 &gt; (set 'x "I belong to MAIN")
2372 <strong>"I belong to MAIN"</strong>
2373 &gt; FOO:x
2374 <strong>123</strong>
2375 &gt; FOO-B:x
2376 <strong>555</strong>
2377 &gt; x
2378 <strong>"I belong to MAIN"</strong>
2379 &gt; _
2380 </pre></blockquote>             <p>
2381                         Symbols owned by a context (or <tt>MAIN</tt>) are <em>not</em> accessible unless prefixed by the context name:
2382                 </p>
2383 <blockquote><pre>
2384 FOO&gt; MAIN:x
2385 <strong>"I belong to MAIN"</strong>
2386 FOO&gt; FOO-B:x
2387 <strong>555</strong>
2388 FOO&gt; x
2389 <strong>123</strong>
2390 &gt; _
2391 </pre></blockquote>             <p>
2392                         When loading source files on the command line with <a href="#load">load</a>, or when executing the functions <a href="#eval-string">eval-string</a> or <a href="#sym">sym</a>, the <tt>context</tt> function tells newLISP where to put all of the symbols and definitions:
2393                 </p>
2394 <blockquote><pre>
2395 ;;; file MY_PROG.LSP
2396 ;;
2397 ;; everything from here on goes into GRAPH
2398 (context 'GRAPH)
2399
2400 (define (draw-triangle x y z)
2401     (&hellip;))
2402 (define (draw-circle)
2403     (&hellip;))
2404
2405 ;; show the runtime context, which is GRAPH
2406     (define (foo)
2407         (context))
2408
2409 ;; switch back to MAIN
2410 (context 'MAIN)
2411
2412 ;; end of file
2413 </pre></blockquote>             <p>
2414                         The <tt>draw-triangle</tt> and <tt>draw-circle</tt> functions &mdash; along with their <tt>x</tt>, <tt>y</tt>, and <tt>z</tt> parameters &mdash; are now part of the <tt>GRAPH</tt> context. These symbols are known only to <tt>GRAPH</tt>. To call these functions from another context, prefix them with
2415                         <tt>GRAPH:</tt>
2416                 </p>
2417 <blockquote><pre>
2418 (GRAPH:draw-triangle 1 2 3)
2419 (GRAPH:foo)  <span class=arw>&rarr;</span> GRAPH
2420 </pre></blockquote>             <p>
2421                         The last statement shows how the runtime context has changed to <tt>GRAPH</tt> (<tt>foo</tt>'s context).
2422                 </p>
2423                 <p>
2424                         A symbol's name and context are used when comparing symbols from different contexts. The <a
2425  href="#name">name</a> function can be used to extract the name part from a fully qualified symbol.
2426                 </p>
2427 <blockquote><pre>
2428 ;; same symbol name, but different context name
2429 (= 'A:val 'B:val)                <span class=arw>&rarr;</span> nil
2430 (= (name 'A:val) (name 'B:val))  <span class=arw>&rarr;</span> true
2431 </pre></blockquote>             <p>
2432                         Note: The symbols are quoted with a <tt>'</tt> (single quote) because we are interested in the symbol itself, not in the contents of the symbol.
2433                 </p>
2434                 <br />
2435                 <a name="scope_change"></a>
2436                 <h3>
2437                         Changing scoping
2438                 </h3>
2439                 <p>
2440                         By default, only built-in functions and symbols like <tt>nil</tt> and
2441                         <tt>true</tt> are visible inside contexts other than <tt>MAIN</tt>. To make a symbol visible to every context, use the <a href="#global">global</a> function:
2442                 </p>
2443 <blockquote><pre>
2444 (set 'aVar 123) <span class=arw>&rarr;</span> 123
2445 (global 'aVar)  <span class=arw>&rarr;</span> aVar
2446
2447 (context 'FOO)  <span class=arw>&rarr;</span> FOO
2448
2449 aVar            <span class=arw>&rarr;</span> 123
2450 </pre></blockquote>             <p>
2451                         Without the <tt>global</tt> statement, the second <tt>aVar</tt> would have returned <tt>nil</tt> instead of <tt>123</tt>. If <tt>FOO</tt> had a previously defined symbol (<tt>aVar</tt> in this example) <em>that</em> symbol's value &mdash; and not the global's &mdash; would be returned instead. Note that only symbols from the <tt>MAIN</tt> context can be made global.
2452                 </p>
2453                 <p>
2454                         Once it is made visible to contexts through the <a href="#global">global</a> function, a symbol cannot be hidden from them again.
2455                 </p>
2456                 <br />
2457                 <a name="protection"></a>
2458                 <h3>
2459                         Symbol protection
2460                 </h3>
2461                 <p>
2462                         By using the <a href="#constant">constant</a> function, symbols can be both set and protected from change at the same time:
2463                 </p>
2464 <blockquote><pre>
2465 &gt; (constant 'aVar 123)  <span class=arw>&rarr;</span> 123
2466 &gt; (set 'aVar 999)
2467 <span class=err>symbol is protected in function set : aVar</span>
2468 &gt;_
2469 </pre></blockquote>             <p>
2470                         A symbol needing to be both a constant and a global can be defined simultaneously:
2471                 </p>
2472 <blockquote><pre>
2473 (constant (global 'aVar) 123)
2474 </pre></blockquote>             <p>
2475                         In the current context, symbols protected by <tt>constant</tt> can be overwritten by using the <tt>constant</tt> function again. This protects the symbols from being overwritten by code in other contexts.
2476                 </p>
2477                 <br />
2478                 <a name="overwrite"></a>
2479                 <h3>
2480                         Overwriting global symbols and built-ins
2481                 </h3>
2482                 <p>
2483                         Global and built-in function symbols can be overwritten inside a
2484                         context by prefixing them with their <em>own</em> context symbol:
2485                 </p>
2486 <blockquote><pre>
2487 (context 'Account)
2488
2489 (define (Account:new &hellip;)
2490     (&hellip;))
2491 (context 'MAIN)
2492 </pre></blockquote>             <p>
2493                         In this example, the built-in function <a href="#new">new</a> is overwritten by <tt>Account:new</tt>, a different function that is private to the <tt>Account</tt> context.
2494                 </p>
2495                 <br />
2496                 <a name="context_vars"></a>
2497                 <h3>
2498                         Variables containing contexts
2499                 </h3>
2500                 <p>
2501                         Variables can be used to refer to contexts:
2502                 </p>
2503 <blockquote><pre>
2504 (set 'FOO:x 123)
2505
2506 (set 'ctx FOO)    <span class=arw>&rarr;</span> FOO
2507
2508 ctx:x             <span class=arw>&rarr;</span> 123
2509
2510 (set 'ctx:x 999)  <span class=arw>&rarr;</span> 999
2511
2512 FOO:x             <span class=arw>&rarr;</span> 999
2513 </pre></blockquote>             <p>
2514                         Context variables are used when creating contexts with the <a href="#new">new</a> function (<em>objects</em>), as well as when writing functions for uninstantiated contexts.
2515                 </p>
2516                 <p>
2517                         They also allow for <em>pass-by-reference</em> of large data objects when contained inside contexts and passed to functions as context variables.
2518                 </p>
2519                 <br />
2520                 <a name="loading_contexts"></a>
2521                 <h3>
2522                         Sequence of creating or loading contexts
2523                 </h3>
2524                 <p>
2525                         The sequence in which contexts are created or loaded can lead to unexpected results. Enter the following code into a file called <tt>demo</tt>:
2526                 </p>
2527 <blockquote><pre>
2528 ;; demo - file for loading contexts
2529 (context 'FOO)
2530     (set 'ABC 123)
2531 (context MAIN)
2532
2533 (context 'ABC)
2534     (set 'FOO 456)
2535 (context 'MAIN)
2536 </pre></blockquote>             <p>
2537                         Now load the file into the newlisp shell:
2538                 </p>
2539 <blockquote><pre>
2540 &gt; (load "demo")
2541 <span class=err>symbol is protected in function set : FOO</span
2542 >
2543 &gt; _
2544 </pre></blockquote>             <p>
2545                         Loading the file causes an error message for <tt>FOO</tt>, but not for <tt>ABC</tt>. When the first context <tt>FOO</tt> is loaded, the context <tt>ABC</tt> does not exist yet, so a local variable <tt>FOO:ABC</tt> gets created. When <tt>ABC</tt> loads, <tt>FOO</tt> already exists as a global protected symbol and will be correctly flagged as protected.
2546                 </p>
2547                 <p>
2548                         <tt>FOO</tt> could still be used as a local variable in the <tt>ABC</tt> context by explicitly prefixing it, as in <tt>ABC:FOO</tt>.
2549                 </p>
2550                 <p>
2551                         The following pattern can be applied to avoid unexpected behavior when loading contexts being used as modules to build larger applications:
2552                 </p>
2553 <blockquote><pre>
2554 ;; begin of file - MyModule.lsp
2555 (load "This.lsp")
2556 (load "That.lsp")
2557 (load "Other.lsp")
2558
2559 (context 'MyModule)
2560
2561  &hellip;
2562
2563 (define (func x y z) (&hellip;))
2564
2565  &hellip;
2566
2567 (context 'MAIN)
2568
2569 (MyModule:func 1 2 3)
2570
2571 (exit)
2572
2573 ;; end of file
2574 </pre></blockquote>
2575 <p>
2576 Always load the modules required by a context <em>before</em>
2577 the module's <tt>context</tt> statement. Always finish by switching
2578 back to the <tt>MAIN</tt> context, where the module's functions and
2579 values can be safely accessed.
2580 </p>
2581 <br />
2582
2583 <center>
2584 <span class="divider">(&nbsp;<font color="#7ba9d4">&sect;</font>&nbsp;)</span>
2585 </center>
2586
2587 <a NAME="context_objects"></a>
2588 <h2>16. Programming with contexts</h2>
2589
2590 <p>Contexts are used in newLISP in different ways. Most frequently they
2591 are used for partioning code into modules, but they also can be
2592 used for simple object-oriented programming when using the <a href="#colon">: (colon)</a>
2593 operator to handle <em>polymorphism</em> in function application.</p>
2594
2595 <a NAME="context_modules"></a>
2596 <h3>Contexts as programming modules</h3>
2597
2598 <p>Contexts in newLISP are mainly used for partitioning source into
2599 modules. Because each module lives in a different namespace, modules
2600 are lexically separated and the names of symbols cannot clash with
2601 identical names in other modules.</p>
2602
2603 <p>The <a href="http://newlisp.org/code/modules/">modules</a>, which are
2604 part of the newLISP distribution, are a good example how to put related
2605 functions into a module file, and how to document modules using
2606 the <a href="http://newlisp.org/newLISPdoc.html">newLISPdoc</a> utility.</p>
2607
2608 <p>For best programming practice a file should only contain one module and
2609 the filename should be similar if not identical to the context name used:</p>
2610
2611 <blockquote><pre>
2612 ;; file db.lsp, commonly used database functions
2613
2614 (context 'db)
2615
2616 ;; Variables used throughout this namespace
2617
2618 (define db:handle)
2619 (define db:host "http://loalhost)
2620
2621 ;; Constants
2622
2623 (constant 'Max_N 1000000)
2624 (constant 'Path "/usr/data/")
2625
2626 ;; Functions
2627
2628 (define (db:open ...)
2629 ...)
2630
2631 (define (db:close ...)
2632 ...)
2633
2634 (define (db:update ...)
2635 ...
2636 )
2637 </pre></blockquote>
2638
2639
2640 <p>The example shows a good practice of predefining variables, which are global
2641 inside the namespace and defining as constants variables, which will not change.</p>
2642
2643 <p>If a file contains more then one context, then the end of the context
2644 should be marked with a switch back to <tt>MAIN</tt>:</p>
2645
2646 <blockquote><pre>
2647 ;; Multi context file multi.lsp
2648
2649 (context 'A-ctx)
2650 ...
2651 (context MAIN)
2652
2653 (context 'B-ctx)
2654 ...
2655 (context MAIN)
2656
2657 (context 'C-ctx)
2658 ...
2659 (context MAIN)
2660 </pre></blockquote>
2661
2662 <br />
2663
2664 <a name="context_data"></a>
2665 <h3>Contexts as data containers</h3>
2666
2667 <p>Contexts are frequently uses as data containers, e.g. for hash-like dictionaries
2668 and configuration data:</p>
2669
2670 <blockquote><pre>
2671 ;; Config.lsp - configuration setup
2672
2673 (context 'Config)
2674
2675 (set 'user-name "admin")
2676 (set 'password "secret")
2677 (set 'db-name "/usr/data/db.lsp")
2678 ...
2679
2680 ;; eof
2681 </pre></blockquote>
2682
2683 <p>Loading the <tt>Config</tt> namespace will now load a whole variable set into
2684 memory at once:</p>
2685
2686 <blockquote><pre>
2687 (load "Config.lsp")
2688
2689 (set 'file (open Config:db-name "read"))
2690 ...
2691 ...
2692 </pre></blockquote>
2693
2694 <p>In a similar fashion a whole data set can be saved:</p>
2695
2696 <blockquote><pre>
2697 (save "Config.lsp" 'Config)
2698 </pre></blockquote>
2699
2700 <p>Read more about this in the section <a href="#serializing">Serializing contexts</a>.</p>
2701
2702 <br />
2703
2704 <a name="loading_contexts"></a>
2705 <h3>Loading and declaring contexts</h3>
2706
2707 <p>Module files are loaded using the <a href="#load">load</a> function.
2708 If a programming project contains numerous modules which are referring
2709 to each other, they should be pre-declared to avoid problems due to context forward
2710 references before loading of that context.</p>
2711
2712 <blockquote><pre>
2713 ;; predeclaring contexts
2714 (map context '(Utilities Config Aquisition Analysis SysLog))
2715
2716 ;; loading context module files
2717 (load "Utilities.lsp" "Aquisition.lsp")
2718 (load "http://192.168.1.34/Config.lsp") ; load module from remote location
2719 (load "Analysis.lsp" "SysLog.lsp")
2720
2721 (define (run)
2722 ...)
2723
2724 (run)
2725
2726 ;; end of file
2727 </pre></blockquote>
2728
2729 <p>When pre-declaring and loading modules as shown in the example, the sequence
2730 of declaration or loading can be neglected. All forward references to variables
2731 and definitions in modules not loaded yet will be translated correctly.</p>
2732
2733 <p>Modules not starting with a context switch are loaded always into <tt>MAIN</tt>
2734 except when the <a href="#load">load</a> statement specifies a target context
2735 as the last parameter. The <a href="#load">load</a> function can take <tt>URL</tt>s
2736 to load modules from remote locations, via <tt>HTTP</tt>.</p>
2737
2738
2739 <br />
2740 <a name="default_function"></a>
2741 <h3>The context default functor</h3>
2742                 <p>
2743                         A <em>default functor</em> or <em>default function</em>
2744                         is a symbol or user-defined function or macro
2745                         with the same name as its namespace.
2746                         When the context is used
2747                         as the name of a function or in the functor position of an s-expression,
2748                         newLISP executes the default function or refers to the contents of the
2749             default functor.
2750                 </p>
2751 <blockquote><pre>
2752 ;; the default function
2753
2754 (define (foo:foo a b c) (+ a b c))
2755
2756 (foo 1 2 3)  <span class=arw>&rarr;</span> 6
2757
2758 ;; the default functor
2759
2760 (define mylist:mylist '(a b c d e f g))
2761
2762 (mylist 3) <span class=arw>&rarr;</span> d
2763
2764 (nth-set (mylist 3) 'D) <span class=arw>&rarr;</span> d ; returns old contents
2765
2766 mylist:mylist <span class=arw>&rarr;</span> (a b c D e f g)
2767 </pre></blockquote>
2768
2769 <p>This allows the default function defined inside a context
2770 to be called whenever the context is applied as a function.
2771 A default function could update the lexically isolated static variables
2772 contained inside its context:</p>
2773
2774 <blockquote><pre>
2775 (define (gen:gen x)
2776     (if gen:acc
2777         (inc 'gen:acc x)
2778         (set 'gen:acc x)))
2779
2780 (gen 1)  <span class=arw>&rarr;</span> 1
2781 (gen 1)  <span class=arw>&rarr;</span> 2
2782 (gen 2)  <span class=arw>&rarr;</span> 4
2783 (gen 3)  <span class=arw>&rarr;</span> 7
2784
2785 gen:acc  <span class=arw>&rarr;</span> 7
2786 </pre></blockquote>
2787
2788 <p>The first time the <tt>gen</tt> function is called,
2789 its accumulator is set to the value of the argument.
2790 Each successive call increments <tt>gen</tt>'s accumulator
2791 by the argument's value.</p>
2792
2793 <p>If a default function is called
2794 from a context other than <tt>MAIN</tt>,
2795 the context must already exist
2796 or be declared with a <em>forward declaration</em>,
2797 which creates the context and the function symbol:</p>
2798
2799 <blockquote><pre>
2800 ;; forward declaration of a default function
2801 (define fubar:fubar)
2802
2803 (context 'foo)
2804 (define (foo:foo a b c)
2805      &hellip;
2806     (fubar a b)         ; forward reference
2807     (&hellip;))                ; to default function
2808
2809 (context MAIN)
2810
2811 ;; definition of previously declared default function
2812
2813 (context 'fubar)
2814 (define (fubar:fubar x y)
2815     (&hellip;))
2816
2817 (context MAIN)
2818 </pre></blockquote>
2819
2820 <p>Default functions work like global functions,
2821 but they are lexically separate from the context in which they are called.
2822 The arguments in a default function macro are safe from variable capture.</p>
2823
2824 <p>Like a lambda or lambda-macro function, default functions can be used
2825 with <a href="#map">map</a> or <a href="#apply">apply</a>.
2826 </p>
2827
2828
2829 <br />
2830
2831 <a name="pass_big"></a>
2832 <h3>Passing data by reference</h3>
2833 <p>
2834 In newLISP, all parameters are passed <em>by value</em>.
2835 This poses a potential problem when passing large lists or strings
2836 to user-defined functions or macros.
2837 Symbols and context objects can also be passed by reference.
2838 This allows memory-intensive objects to be passed
2839 without the overhead of copying the entire list or string.
2840 </p>
2841
2842 <p>Any data can be passed by reference by passing the symbol holding it:</p>
2843
2844 <blockquote><pre>
2845 (define (change-list aList) (push 999 (eval aList)))
2846
2847 (set 'data '(1 2 3 4 5))
2848
2849 ; note the quote ' in front of data
2850 (change-list 'data)  <span class=arw>&rarr;</span> (999 1 2 3 4 5)
2851
2852 data  <span class=arw>&rarr;</span>  (999 1 2 3 4 5)
2853 </pre></blockquote>
2854
2855 <p>Although this method is simple to understand and use, it poses the potential
2856 problem of <em>variable capture</em> when passing the same symbol as used in
2857 the function as a parameter:</p>
2858
2859 <blockquote><pre>
2860 ;; pass data by symbol reference
2861
2862 &gt; (set 'aList '(a b c d))
2863 (a b c d)
2864 &gt; (change-list 'aList)
2865
2866 <span class=err>list or string expected : (eval aList)
2867 called from user defined function change-list</span>
2868 &gt;
2869 </pre></blockquote>
2870
2871 <p>Because of the danger of variable capture, passing an object by its symbol
2872 should only be used in small scripts or programs where each function and its
2873 parameters are well-known. A safer method would be to package the object in
2874 a context (namespace) and pass the context ID:</p>
2875
2876 <blockquote><pre>
2877 ;; pass data by context reference
2878
2879 (set 'mydb:data (sequence 1 100000))
2880
2881 (define (change-db obj idx value)
2882     (nth-set (obj:data idx) value))
2883
2884 (change-db mydb 1234 "abcdefg")
2885
2886 (nth (mydb:data 1234))  <span class=arw>&rarr;</span> "abcdefg"
2887 </pre></blockquote>
2888
2889 <p>
2890 This example shows how objects can be passed <em>by reference</em>
2891 to a user-defined function using <a href="#context_vars">context variables</a>,
2892 without the overhead of passing them by value.
2893 String buffers or data objects enclosed in a context
2894 can also be passed using this technique.
2895 </p>
2896
2897 <p>
2898 As shown in the following variation, using <a href="#default_function">default
2899 functor</a> can further simplify the syntax:
2900 </p>
2901
2902 <blockquote><pre>
2903 ;; pass a context containing a default functor
2904
2905 (set 'mydb:mydb (sequence 1 100000))
2906
2907 (define (change-db obj idx value)
2908     (nth-set (obj idx) value))
2909
2910 (change-db mydb 1234 "abcdefg")
2911
2912 (mydb 1234)  <span class=arw>&rarr;</span> "abcdefg"
2913 </pre></blockquote>
2914 <p>
2915 The <tt>change-db</tt> function does not need to know
2916 the name of the variable inside the context.
2917 All functions which use a syntax <tt>(<em>functor</em> (L idx) ...)</tt> like:
2918 like
2919 <a href="#assoc-set">assoc-set</a>,
2920 <a href="#nth">nth</a>,
2921 <a href="#nth-set">nth-set</a>,
2922 <a href="#pop-assoc">pop-assoc</a>,
2923 <a href="#push">push</a>, and <a href="#pop">pop</a> and functions
2924 which use a syntax <tt>(<em>functor</em> (L key) ...)</tt> like:
2925 <a href="#ref">ref</a>,
2926 <a href="#ref-all">ref-all</a>,
2927 <a href="#ref-set">ref-set</a>,
2928 <a href="#set-assoc">set-assoc</a>,
2929 <a href="#set-nth">set-nth</a>,
2930 <a href="#set-ref">set-ref</a>,
2931 and <a href="#set-ref-all">set-ref-all</a>
2932 know how to extract the default functor from the context <tt>L</tt>.
2933 This technique works for arrays and strings, as well.
2934 </p>
2935
2936 <p>For destructive functions like <a href="#replace">replace</a>,
2937 <a href="#reverse">reverse</a>,
2938 <a href="#rotate">rotate</a>,
2939 <a href="#sort">sort</a>, and <a href="#swap">swap</a>,
2940 which refer to the un-indexed list, the function <a href="#default">default</a>
2941 can be used to extract the <a href="#default_function">default functor</a> symbol:</p>
2942
2943 <blockquote><pre>
2944 (set 'foo:foo '( 6 3 5 8 6 7 4 1))
2945
2946 (define (my-sort clist)
2947         (sort (eval (default clist))))
2948
2949 (my-sort foo)
2950
2951 foo:foo  <span class=arw>&rarr;</span> (1 3 4 5 6 6 7 8)
2952 </pre></blockquote>
2953
2954 <p>In this example,
2955 the list in foo:foo is passed by context reference.
2956 <a href="#default">default</a> is used to acces the
2957 <a href="#default_function">default functor</a> symbol,
2958 the contents of which is access by <a href="#eval">eval</a>.</p>
2959
2960 <br />
2961
2962 <a name="serializing"></a>
2963 <h3>Serializing contexts</h3>
2964
2965 <p>Serialization makes a software object <em>persistent</em>
2966 by converting it into a character stream,
2967 which is then saved to a file or string in memory.
2968 In newLISP, anything referenced by a symbol can be serialized to a file
2969 by using the <a href="#save">save</a> function.
2970 Like other symbols, contexts are saved just by using their names:
2971 </p>
2972
2973 <blockquote><pre>
2974 (save "mycontext.lsp" 'MyCtx)              ; save MyCtx to mycontext.lsp
2975
2976 (load "mycontext.lsp")                     ; loads MyCtx into memory
2977
2978 (save "mycontexts.lsp" 'Ctx1 'Ctx2 'Ctx3)  ; save multiple contexts at once
2979 </pre></blockquote>
2980
2981 <p>
2982 For details, see the functions <a href="#save">save</a> (mentioned above)
2983 and <a href="#source">source</a> (for serializing to a newLISP string).
2984 </p>
2985
2986 <center>
2987 <span class="divider">(&nbsp;<font color="#7ba9d4">&sect;</font>&nbsp;)</span>
2988 </center>
2989
2990
2991 <a name="oo_programming"></a>
2992 <h2>17. Object-Oriented Programming in newLISP</h2>
2993
2994 <p>Any object-oriented programming (OOP) system built in newLISP is based on the following
2995 three principles:</p>
2996
2997 <ul>
2998         <li>Class attributes and methods are stored in the namespace of the object class.</li><br />
2999
3000         <li>The namespace default functor is used to hold the object constructor method.</li><br />
3001
3002         <li>An object is constructed using a list, the first element of which is the
3003     context symbol describing the class of the object.</li><br />
3004
3005         <li>Polymorphism is implemented using the : (colon) operator, which selects the appropriate
3006      class from the object.</li>
3007 </ul>
3008
3009 <p>The following paragraphs are a short introduction to FOOP: Functional Object-Oriented Programming
3010 as designed by <em>Michael Michaels</em>. This description covers only very basic elements.
3011 For more details see the Michael Michaels's FOOP training videos on
3012 <a href="http://newlisp.org">newlisp.org</a> or <a href="http://neglook.com">neglook.com</a>.
3013 </p>
3014
3015
3016 <br />
3017
3018 <a name="newlisp_classes"></a>
3019 <h3>Classes and constructors</h3>
3020
3021 <p>Class attributes and methods are stored in the namespace of the object class.
3022 No object instance data is stored in this namespace/context. Data variables in
3023 the class namespace only desecribe the class of objects as a whole but don't contain
3024 any object specific information. A generic FOOP object constructor can be used
3025 as a template for specific object constructors when creating new object classes
3026 with <tt>new</tt>:</p>
3027
3028 <blockquote><pre>
3029 ; generic FOOP object constructor
3030 (define (Class:Class)
3031         (cons (context) (args)))
3032
3033 (new Class 'Rectangle)
3034 (new Class 'Circle)
3035 </pre></blockquote>
3036
3037 <p>Creating the namespace classes using <a href="#new">new</a>, reserves the class name as a context
3038 in newLISP and facilitates forward references. At the same time a simple
3039 constructor is defined for the new class for instantiating new objects. As a convention it is
3040 recommended to start class names in upper-case to signal that the name stands for a namespace.</p>
3041
3042 <p>In some cases it may be useful to overwrite the simple constructor, which was created during class creation
3043 with <tt>new</tt>:</p>
3044
3045 <blockquote><pre>
3046 ; overwrite simple constructor
3047 (define (Circle:Circle x y radius)
3048     (list Circle x y radius))
3049 </pre></blockquote>
3050
3051 <p>A constructor can also specify defaults:</p>
3052
3053 <blockquote><pre>
3054 ; constructor with defaults
3055 (define (Circle:Circle (x 10) (y 10) (radius 3))
3056     (list Circle x y radius))
3057 </pre></blockquote>
3058
3059 <p>In many cases the constructor as created when using <tt>new</tt> is sufficient and overwriting
3060 it is not necessary.</p>
3061
3062 <br />
3063 <a name="newlisp_objects"></a>
3064 <h3>Objects and associations</h3>
3065
3066 <p>FOOP represents objects as lists. The first element of the list indicates the object's kind or class, while the remaining elements contain the data. The following statements define two <em>objects</em> using any of the contructors defined previously:</p>
3067
3068 <blockquote><pre>
3069 (set 'myrect (Rectangle 5 5 10 20)) <span class=arw>&rarr;</span> (Rectangle 5 5 10 20)
3070 (set 'mycircle (Circle 1 2 10)) <span class=arw>&rarr;</span> (Circle 1 2 10)
3071 </pre></blockquote>
3072
3073 <p>An object created is identical to the function necessary to create it. Nested objects can be
3074 created in a similar manner:</p>
3075
3076 <blockquote><pre>
3077 ; create classes
3078 (new Class 'Person)
3079 (new Class 'Address)
3080 (new Class 'City)
3081 (new Class 'Street)
3082
3083 ; create an object containing other objects
3084 (set 'JohnDoe (Person (Address (City "Boston") (Street 123 "Main Street"))))
3085 <span class=arw>&rarr;</span> (Person (Address (City "Boston") (Street 123 "Main Street")))
3086 </pre></blockquote>
3087
3088 <p>Objects in FOOP not only resemble functions they also resemble associations. The
3089 <a href="#assoc">assoc</a> function can be used to acess object data by name:</p>
3090
3091 <blockquote><pre>
3092 (assoc (JohnDoe Address)) <span class=arw>&rarr;</span> (Address (City "Boston") (Street 123 "Main Street"))
3093
3094 (assoc (JohnDoe Address Street)) <span class=arw>&rarr;</span> (Street 123 "Main Street")
3095 </pre></blockquote>
3096
3097 <p>In a similar manner <a href="#set-assoc">set-assoc</a> could be used to modify object data:</p>
3098
3099 <blockquote><pre>
3100 (set-assoc (JohnDoe Address Street) (Street 456 "Main Street"))
3101 <span class=arw>&rarr;</span> (Person (Address (City "Boston") (Street 456 "Main Street")))
3102 </pre></blockquote>
3103
3104 <p>The street number has been changes from <tt>123</tt> to <tt>456</tt>.</p>
3105
3106 <br />
3107 <a name="colon_operator"></a>
3108 <h3>The colon <tt>:</tt> operator and polymorphism</h3>
3109
3110 <p>In newLISP, the colon character <tt>:</tt> is primarily used to
3111 connect the context symbol with the symbol it is qualifying.
3112 Secondly, the colon function is used in OOP to resolve a function's
3113 application <em>polymorphic</em>ally.</p>
3114
3115 <p>The following code defines two functions called <tt>area</tt>,
3116 each belonging to a different namespace. Both functions could
3117 have been defined in different modules, but in this case they are
3118 defined in the same file and without bracketing
3119 <a href="#context">context</a> statements. Here, only
3120 the symbols <tt>rectangle:area</tt> and <tt>circle:area</tt> belong
3121 to different namespaces. The local parameters <tt>p</tt>, <tt>c</tt>, <tt>dx</tt>, and <tt>dy</tt> are all part of <tt>MAIN</tt>,
3122 but this is of no concern.</p>
3123
3124 <blockquote><pre>
3125 ;; class methods for rectangles
3126
3127 (define (Rectangle:area p)
3128         (mul (p 3) (p 4)))
3129
3130 (define (Rectangle:move p dx dy)
3131         (list Rectangle (add (p 1) dx) (add (p 2) dy) (p 3) (p 4)))
3132
3133 ;; class methods for circles
3134
3135 (define (Circle:area c)
3136         (mul (pow (c 3) 2) (acos 0) 2))
3137
3138 (define (Circle:move p dx dy)
3139         (list Circle (add (p 1) dx) (add (p 2) dy) (p 3)))
3140 </pre></blockquote>
3141
3142 <p>By prefixing the <tt>area</tt> or <tt>move</tt> symbol with the <tt>:</tt> (colon), we can call these functions for each class of object. Although there is no space between the colon and the symbol following it, newLISP parses them as distinct entities. The colon works as a function that processes parameters:</p>
3143
3144 <blockquote><pre>
3145 (:area myrect) <span class=arw>&rarr;</span> 200 ; same as (Rectangle:area myrect)
3146 (:area mycircle) <span class=arw>&rarr;</span> 314.1592654 ; same as (Circle:area mycircle)
3147
3148 (set 'myrect (:move myrect 2 3))      <span class=arw>&rarr;</span> (Rectangle 7 8 10 20)
3149 (set 'mycircle (:move mycircle 4 5))  <span class=arw>&rarr;</span> (Circle 5 7 10)
3150 </pre></blockquote>
3151
3152 <p>In this example, the correct qualified symbol (<tt>rectangle:area</tt> or <tt>circle:area</tt>) is constructed and applied to the object data based on the symbol following the colon and the context name (the first element of the object list).</p>
3153
3154 <p>Note that moving the shapes is done in a <em>functional</em> manner.
3155 Rather than changing the <tt>x</tt> and <tt>y</tt> coordinates directly in <tt>myrect</tt> and <tt>mycircle</tt>, newLISP constructs and then reassigns the moved shapes.</p>
3156
3157
3158 <br />
3159 <a NAME="XML"></a>
3160 <h2>18. XML, S-XML, and XML-RPC</h2>
3161 <p>
3162 newLISP's built-in support for XML-encoded data or documents
3163 comprises three functions:
3164 <a href="#xml-parse">xml-parse</a>,
3165 <a href="#xml-type-tags">xml-type-tags</a>, and <a href="#xml-error">xml-error</a>.
3166 </p>
3167
3168 <p>
3169 Use the <a href="#xml-parse">xml-parse</a> function
3170 to parse XML-encoded strings.
3171 When <tt>xml-parse</tt> encounters an error,
3172 <tt>nil</tt> is returned.
3173 To diagnose syntax errors caused by incorrectly formatted XML,
3174 use the function <a href="#xml-error">xml-error</a>.
3175 The <a href="#xml-type-tags">xml-type-tags</a> function can be used
3176 to control or suppress the appearance of XML type tags.
3177 These tags classify XML into one of four categories:
3178 text, raw string data, comments, and element data.</p>
3179
3180
3181 <strong>XML source:</strong>
3182 <blockquote><pre>
3183 &lt;?xml version="1.0"?&gt;
3184 &lt;DATABASE name="example.xml"&gt;
3185 &lt;!--This is a database of fruits--&gt;
3186     &lt;FRUIT&gt;
3187         &lt;NAME&gt;apple&lt;/NAME&gt;
3188         &lt;COLOR&gt;red&lt;/COLOR&gt;
3189         &lt;PRICE&gt;0.80&lt;/PRICE&gt;
3190     &lt;/FRUIT&gt;
3191 &lt;/DATABASE&gt;
3192 </pre></blockquote>             <br />
3193                 <strong>Parsing without options:</strong>
3194 <blockquote><pre>
3195 (xml-parse (read-file "example.xml"))
3196 <span class=arw>&rarr;</span>  (("ELEMENT" "DATABASE" (("name" "example.xml")) (("TEXT" "\r\n")
3197         ("COMMENT" "This is a database of fruits")
3198         ("TEXT" "\r\n        ")
3199         ("ELEMENT" "FRUIT" () (
3200             ("TEXT" "\r\n\t        ")
3201             ("ELEMENT" "NAME" () (("TEXT" "apple")))
3202             ("TEXT" "\r\n\t\t")
3203             ("ELEMENT" "COLOR" () (("TEXT" "red")))
3204             ("TEXT" "\r\n\t\t")
3205             ("ELEMENT" "PRICE" () (("TEXT" "0.80")))
3206             ("TEXT" "\r\n\t")))
3207         ("TEXT" "\r\n"))))
3208 </pre></blockquote>             <p>
3209                         S-XML can be generated directly from XML
3210                         using <a href="#xml-type-tags">xml-type-tags</a>
3211                         and the special option parameters
3212                         of the <a href="#xml-parse">xml-parse</a> function:
3213                 </p>
3214                 <br />
3215                 <strong>S-XML generation using all options:</strong>
3216 <blockquote><pre>
3217 (xml-type-tags nil nil nil nil)
3218 (xml-parse (read-file "example.xml") (+ 1 2 4 8 16))
3219 <span class=arw>&rarr;</span>  ((DATABASE (@ (name "example.xml"))
3220           (FRUIT (NAME "apple")
3221               (COLOR "red")
3222               (PRICE "0.80"))))
3223
3224 </pre></blockquote>             <p>
3225                         S-XML is XML
3226                         reformatted as LISP <em>S-expressions</em>.
3227                         The <tt>@</tt> (at symbol) denotes
3228                         an XML attribute specification.
3229                 </p>
3230                 <p>
3231                         See <a href="#xml-parse">xml-parse</a> in
3232                         the reference section of the manual
3233                         for details on parsing and option numbers,
3234                         as well as for a longer example.
3235                 </p>
3236                 <br />
3237                 <strong>XML-RPC</strong>
3238                 <br />
3239                 <p>
3240                         The remote procedure calling protocol XML-RPC uses
3241                         HTTP post requests as a transport and
3242                         XML for the encoding of method names, parameters, and parameter types.
3243                         XML-RPC client libraries and servers have been implemented
3244                         for most popular compiled and scripting languages.
3245                 </p>
3246                 <p>
3247                         For more information about XML,
3248                         visit <a href="http://www.xmlrpc.com/">www.xmlrpc.com</a>.
3249                 </p>
3250                 <p>
3251                         XML-RPC clients and servers are easy to write
3252                         using newLISP's built-in network and XML support.
3253                         A stateless XML-RPC server implemented as a CGI service,
3254                         can be found in the file <tt>examples/xmlrpc.cgi</tt>. This
3255                         script can be used together with a web server, like Apache.
3256                         This XML-RPC service scripts implement
3257                         the following methods:
3258                 </p>
3259 <br />
3260 <center>
3261 <table class="list" width="98%" summary="XMPRPC methods for newLISP server">
3262 <tr align="left"><th>method</th><th>description</th></tr>
3263 <tr>
3264 <td class="left"><tt>system.listMethods</tt></td>
3265 <td class="right">Returns a list of all method names</td>
3266 </tr>
3267 <tr>
3268 <td class="left"><tt>system.methodHelp</tt></td>
3269 <td class="right">Returns help for a specific method</td>
3270 </tr>
3271 <tr>
3272 <td class="left"><tt>system.methodSignature</tt></td>
3273 <td class="right">Returns a list of return/calling signatures for a specific method </td>
3274 </tr>
3275 <tr>
3276 <td class="left"><tt>newLISP.evalString</tt></td>
3277 <td class="right">Evaluates a Base64 newLISP expression string</td></tr>
3278 </table>
3279 </center>
3280
3281                 <br />
3282                 <p>
3283                         The first three methods
3284                         are <em>discovery</em> methods
3285                         implemented by most XML-RPC servers.
3286                         The last one is specific
3287                         to the newLISP XML-RPC server script and
3288                         implements remote evaluation of
3289                         a Base64-encoded string of newLISP source code.
3290                         newLISP's <a href="#base64-enc">base64-enc</a>
3291                         and <a href="#base64-dec">base64-dec</a> functions
3292                         can be used to encode and decode
3293                         Base64-encoded information.
3294                 </p>
3295                 <p>
3296                         In the <tt>modules</tt> directory
3297                         of the source distribution,
3298                         the file <tt>xmlrpc-client.lsp</tt> implements
3299                         a specific client interface for
3300                         all of the above methods.
3301                 </p>
3302 <blockquote><pre>
3303 (load "xmlrpc-client.lsp")  ; load XML-RPC client routines
3304
3305 (XMLRPC:newLISP.evalString
3306     "http://localhost:8080"
3307     "(+ 3 4)")  <span class=arw>&rarr;</span> "7"
3308 </pre></blockquote>             <p>
3309                         In a similar fashion,
3310                         standard <tt>system.xxx</tt> calls can be issued.
3311                 </p>
3312                 <p>
3313                         All functions return either a result if successful,
3314                         or <tt>nil</tt> if a request fails.
3315                         In case of failure,
3316                         <tt>XMLRPC:error</tt> can be evaluated
3317                         to return an error message.
3318                 </p>
3319                 <p>
3320                         For more information,
3321                         please consult the header
3322                         of the file <tt>modules/xmlrpc-client.lsp</tt>.
3323                 </p>
3324
3325 <center>
3326 <span class="divider">(&nbsp;<font color="#7ba9d4">&sect;</font>&nbsp;)</span>
3327 </center>
3328
3329                 <a NAME="internationalization"></a>
3330                 <h2>
3331                         19. Customization, localization, and UTF-8
3332                 </h2>
3333                 <p>
3334                         All built-in primitives
3335                         in newLISP can be easily renamed:
3336                 </p>
3337 <blockquote><pre>
3338 (constant 'plus +)
3339 </pre></blockquote>             <p>
3340                         Now, <tt>plus</tt> is functionally equivalent to <tt>+</tt>
3341                         and runs at the same speed.
3342                         As with many scripting languages,
3343                         this allows for double precision floating point arithmetic
3344                         to be used throughout newLISP.
3345                 </p>
3346                 <p>
3347                         The <a href="#constant">constant</a> function,
3348                         rather than the <tt>set</tt> function,
3349                         must be used to rename built-in primitive symbols.
3350                         By default, all built-in function symbols
3351                         are protected against accidental overwriting.
3352                 </p>
3353 <blockquote><pre>
3354 (constant '+ add)
3355 (constant '- sub)
3356 (constant '* mul)
3357 (constant '/ div)
3358 </pre></blockquote>             <p>
3359                         All operations using <tt>+</tt>, <tt>-</tt>, <tt>*</tt>, and <tt>/</tt>
3360                         are now performed as floating point operations.
3361                 </p>
3362                 <p>
3363                         Using the same mechanism,
3364                         the names of built-in functions
3365                         can be translated into languages
3366                         other than English:
3367                 </p>
3368 <blockquote><pre>
3369 (constant 'wurzel sqrt)    ; German for 'square-root'
3370 (constant 'imprime print)  ; Spanish for 'print'
3371  &hellip;
3372 </pre></blockquote>             <br />
3373                 <a name="switching"></a>
3374                 <h3>
3375                         Switching the locale
3376                 </h3>
3377                 <p>
3378                         newLISP can switch locales
3379                         based on the platform and operating system.
3380                         On startup, newLISP attempts to
3381                         set the ISO C standard default POSIX locale,
3382                         available for most platforms and locales.
3383                         Use the <a href="#set-locale">set-locale</a> function
3384                         to switch to the default locale:
3385                 </p>
3386 <blockquote><pre>
3387 (set-locale "")
3388 </pre></blockquote>             <p>
3389                         This switches to the default locale
3390                         used on your platform/operating system
3391                         and ensures character handling
3392                         (e.g., <a href="#upper-case">upper-case</a>)
3393                         work correctly.
3394                 </p>
3395                 <p>
3396                         Many Unix systems have
3397                         a variety of locales available.
3398                         To find out which ones are available on
3399                         a particular Linux/UNIX/BSD system,
3400                         execute the following command
3401                         in a system shell:
3402                 </p>
3403 <blockquote><pre>
3404 locale -a
3405 </pre></blockquote>             <p>
3406                         This command prints a list of
3407                         all the locales available on your system.
3408                         Any of these may be
3409                         used as arguments to <a href="#set-locale">set-locale</a>:
3410                 </p>
3411 <blockquote><pre>
3412 (set-locale "es_US")
3413 </pre></blockquote>             <p>
3414                         This would switch to a U.S. Spanish locale.
3415                         Accents or other characters
3416                         used in a U.S. Spanish environment
3417                         would be correctly converted.
3418                 </p>
3419                 <p>
3420                         See the manual description for more details
3421                         on the usage of <a href="#set-locale">set-locale</a>.
3422                 </p>
3423                 <br />
3424                 <a name="decimal_point"></a>
3425                 <h3>
3426                         Decimal point and decimal comma
3427                 </h3>
3428                 <p>
3429                         Many countries use a comma instead of a period
3430                         as a decimal separator in numbers.
3431                         newLISP correctly parses numbers
3432                         depending on the locale set:
3433                 </p>
3434 <blockquote><pre>
3435 ;; switch to German locale on a Linux system
3436 (set-locale "de_DE")
3437
3438 ;; newLISP source and output use a decimal comma
3439 (div 1,2 3)  <span class=arw>&rarr;</span> 0,4
3440 </pre></blockquote>             <p>
3441                         The default POSIX C locale,
3442                         which is set when newLISP starts up,
3443                         uses a period as a decimal separator.
3444                 </p>
3445                 <p>
3446                         The following countries
3447                         use a period as a decimal separator:
3448                 </p>
3449                 <blockquote>Australia, Botswana, Canada (English-speaking), China, Costa Rica, Dominican Republic, El Salvador, Guatemala, Honduras, Hong Kong, India, Ireland, Israel, Japan, Korea (both North and South), Malaysia, Mexico, Nicaragua, New Zealand, Panama, Philippines, Puerto Rico, Saudi Arabia, Singapore, Thailand, United Kingdom, and United States
3450                 </blockquote>
3451                 <p>
3452                         The following countries use
3453                         a comma as a decimal separator:
3454                 </p>
3455                 <blockquote>Albania, Andorra, Argentina, Austria, Belarus, Belgium, Bolivia, Brazil, Bulgaria, Canada (French-speaking), Croatia, Cuba, Chile, Colombia, Czech Republic, Denmark, Ecuador, Estonia, Faroes, Finland, France, Germany, Greece, Greenland, Hungary, Indonesia, Iceland, Italy, Latvia, Lithuania, Luxembourg, Macedonia, Moldova, Netherlands, Norway, Paraguay, Peru, Poland, Portugal, Romania, Russia, Serbia, Slovakia, Slovenia, Spain, South Africa, Sweden, Switzerland, Ukraine, Uruguay, Venezuela, and Zimbabwe
3456                 </blockquote>
3457                 <br />
3458                 <a name="unicode_utf8"></a>
3459                 <h3>
3460                         Unicode and UTF-8 encoding
3461                 </h3>
3462                 <p>
3463                         Note that for many European languages,
3464                         the <a href="#set-locale">set-locale</a> mechanism
3465                         is sufficient to display
3466                         non-ASCII character sets,
3467                         as long as each character is presented
3468                         as <em>one</em> byte internally.
3469                         UTF-8 encoding is only necessary for
3470                         multibyte character sets as described in
3471                         this chapter.
3472                 </p>
3473                 <p>
3474                         newLISP can be compiled
3475                         as a UTF-8&ndash;enabled application.
3476                         UTF-8 is a multibyte encoding
3477                         of the international Unicode character set.
3478                         A UTF-8&ndash;enabled newLISP
3479                         running on an operating system with UTF-8 enabled
3480                         can handle any character of the installed locale.
3481                 </p>
3482                 <p>
3483                         The following steps
3484                         make UTF-8 work with newLISP
3485                         on a specific operating system and platform:
3486                 </p>
3487                 <p>
3488                         <tt>(1)</tt> Use one of the makefiles
3489                         ending in <tt>utf8</tt>
3490                         to compile newLISP as
3491                         a UTF-8 application.
3492                         If no UTF-8 makefile
3493                         is available for your platform,
3494                         the normal makefile
3495                         for your operating system
3496                         contains instructions
3497                         on how to change it
3498                         for UTF-8.
3499                 </p>
3500                 <p>
3501                         The Mac OS X binary installer contains
3502                         a UTF-8&ndash;enabled version by default.
3503                 </p>
3504                 <p>
3505                         <tt>(2)</tt> Enable the UTF-8 locale
3506                         on your operating system.
3507                         Check and set a UTF-8 locale
3508                         on Unix and Unix-like OSes
3509                         by using the <tt>locale</tt> command
3510                         or the <tt>set-locale</tt> function within newLISP.
3511                         On Linux, the locale can be changed by setting
3512                         the appropriate environment variable.
3513                         The following example uses <tt>bash</tt>
3514                         to set the U.S. locale:
3515                 </p>
3516 <blockquote><pre>
3517 export LC_CTYPE=en_US.UTF-8
3518 </pre></blockquote>             <p>
3519                         <tt>(3)</tt> The UTF-8&ndash;enabled newLISP
3520                         automatically switches to the locale found
3521                         on the operating system.
3522                         Make sure the command shell
3523                         is UTF-8&ndash;enabled.
3524                         When using the Tcl/Tk front-end on Linux/UNIX,
3525                         Tcl/Tk will automatically switch to UTF-8 display
3526                         as long as the UNIX environment variable
3527                         is set correctly.
3528                         The U.S. version of WinXP's <tt>notepad.exe</tt>
3529                         can display Unicode UTF-8&ndash;encoded characters,
3530                         but the command shell and the Tcl/Tk front-end cannot.
3531                         On Linux and other UNIXes,
3532                         the Xterm shell can be used
3533                         when started as follows:
3534                 </p>
3535 <blockquote><pre>
3536 LC_CTYPE=en_US.UTF-8 xterm
3537 </pre></blockquote>             <p>
3538                         The following procedure can now be used
3539                         to check for UTF-8 support.
3540                         After starting newLISP, type:
3541                 </p>
3542 <blockquote><pre>
3543 (println (char 937))               ; displays Greek uppercase omega
3544 (println (lower-case (char 937)))  ; displays lowercase omega
3545 </pre></blockquote>             <p>
3546                         While the uppercase omega (&Omega;) looks
3547                         like a big O on two tiny legs,
3548                         the lowercase omega (&omega;) has
3549                         a shape similar to a small <tt>w</tt>
3550                         in the Latin alphabet.
3551                 </p>
3552                 <p>
3553                         Note: Only the output of <tt>println</tt>
3554                         will be displayed as a character;
3555                         <tt>println</tt>'s return value
3556                         will appear on the console
3557                         as a multibyte ASCII character.
3558                 </p>
3559                 <p>
3560                         When UTF-8&ndash;enabled newLISP
3561                         is used on a non-UTF-8&ndash;enabled display,
3562                         both the output and the return value
3563                         will be two characters.
3564                         These are the two bytes necessary
3565                         to encode the omega character.
3566                 </p>
3567                 <p>
3568                         When UTF-8&ndash;enabled newLISP is used,
3569                         the following string functions work
3570                         on character rather than byte boundaries:
3571                 </p>
3572 <br />
3573 <center>
3574 <table class="list" width="95%" summary="functions working on character boundaries in UTF-8">
3575 <tr align="left"><th>function</th><th>description</th></tr>
3576
3577 <tr>
3578 <td class="left"><a href="#bind">bind</a></td>
3579 <td class="right">binds variable associations in a list</td>
3580 </tr>
3581
3582 <tr>
3583 <td class="left"><a href="#char">char</a></td>
3584 <td class="right">translates between characters and ASCII/Unicode</td>
3585 </tr>
3586
3587 <tr>
3588
3589 <td class="left"><a href="#chop">chop</a></td>
3590 <td class="right">chops characters from the end of a string</td>
3591 </tr>
3592
3593 <tr>
3594 <td class="left"><a href="#date">date</a></td>
3595 <td class="right">converts date number to string (when used with the third argument)</td>
3596
3597 </tr>
3598
3599 <tr>
3600 <td class="left"><a href="#explode">explode</a></td>
3601 <td class="right">transforms a string into a list of characters</td>
3602 </tr>
3603
3604 <tr>
3605 <td class="left"><a href="#first">first</a></td>
3606 <td class="right">gets first element in a list (car, head) or string</td>
3607 </tr>
3608
3609 <tr>
3610
3611 <td class="left"><a href="#last">last</a></td>
3612 <td class="right">returns the last element of a list or string</td>
3613 </tr>
3614
3615
3616 <tr>
3617 <td class="left"><a href="#lower-case">lower-case</a></td>
3618 <td class="right">converts a string to lowercase characters</td>
3619 </tr>
3620
3621 <tr>
3622 <td class="left"><a href="#nth">nth</a></td>
3623 <td class="right">gets the <em>nth</em> element of a list or string</td>
3624 </tr>
3625
3626 <tr>
3627 <td class="left"><a href="#nth-set">nth-set</a></td>
3628 <td class="right">changes the <em>nth</em> element of a list or string</td>
3629 </tr>
3630
3631 <tr>
3632 <td class="left"><a href="#pop">pop</a></td>
3633 <td class="right">deletes an element from a list or string</td>
3634 </tr>
3635
3636 <tr>
3637 <td class="left"><a href="#push">push</a></td>
3638 <td class="right">inserts a new element in a list or string</td>
3639 </tr>
3640
3641 <tr>
3642 <td class="left"><a href="#rest">rest</a></td>
3643 <td class="right">gets all but the first element of a list (cdr, tail) or string</td>
3644 </tr>
3645
3646 <tr>
3647 <td class="left"><a href="#select">select</a></td>
3648 <td class="right">selects and permutes elements from a list or string</td>
3649 </tr>
3650
3651 <tr>
3652 <td class="left"><a href="#set-nth">set-nth</a></td>
3653 <td class="right">changes an element in a list or string</td>
3654 </tr>
3655
3656 <tr>
3657 <td class="left"><a href="#title-case">title-case</a></td>
3658 <td class="right">converts the first character of a string to uppercase</td>
3659 </tr>
3660
3661 <tr>
3662 <td class="left"><a href="#trim">trim</a></td>
3663 <td class="right">trims a string from both sides</td>
3664 </tr>
3665
3666 <tr>
3667 <td class="left"><a href="#upper-case">upper-case</a></td>
3668 <td class="right">converts a string to uppercase characters</td>
3669 </tr>
3670
3671 </table></center>
3672
3673                 <br />
3674                 <p>
3675                         All other string functions work on bytes.
3676                         When positions are returned,
3677                         as in <a href="#find">find</a> or <a href="#regex">regex</a>,
3678                         they are byte positions rather than character positions.
3679                         The <a href="#slice">slice</a> function
3680                         takes not character offset, but byte offsets.
3681                         The <a href="#reverse">reverse</a> function reverses
3682                         a byte vector, not a character vector.
3683                         The last two functions can still be used to manipulate
3684                         binary non-textual data in the UTF-8&ndash;enabled version of newLISP.
3685                 </p>
3686                 <p>
3687                         To enable UTF-8 in Perl Compatible Regular Expressions (PCRE)
3688                         &mdash; used by <a href="#directory">directory</a>, <a href="#find">find</a>, <a href="#parse">parse</a>, <a href="#regex">regex</a>, and
3689                         <a href="#replace">replace</a> &mdash;
3690                         set the option number accordingly (2048).
3691                         See the <a href="#regex">regex</a> documentation for details.
3692                 </p>
3693                 <p>
3694                         Use <a href="#explode">explode</a> to obtain an array
3695                         of UTF-8 characters and to manipulate characters rather than bytes
3696                         when a UTF-8&ndash;enabled function is unavailable:
3697                 </p>
3698 <blockquote><pre>
3699 (join (reverse (explode str)))  ; reverse UTF-8 characters
3700 </pre></blockquote>             <p>
3701                         The above string functions
3702                         (often used to manipulate non-textual binary data)
3703                         now work on character,
3704                         rather than byte, boundaries,
3705                         so care must be exercised
3706                         when using the UTF-8&ndash;enabled version.
3707                         The size of the first 127 ASCII characters &mdash;
3708                         along with the characters in popular code pages such as ISO 8859 &mdash;
3709                         is one byte long.
3710                         When working exclusively within these code pages,
3711                         UTF-8&ndash;enabled newLISP is not required.
3712                         The <a href="#set-locale">set-locale</a> function alone
3713                         is sufficient for localized behavior.
3714                 </p>
3715                 <p>
3716                         Two new functions are available
3717                         for converting between four-byte Unicode (UCS-4)
3718                         and multibyte UTF-8 code.
3719                         The <a href="#utf8">UTF-8</a> function converts UCS-4
3720                         to UTF-8, and the <a href="#unicode">unicode</a> function converts UTF-8
3721                         or ASCII strings into USC-4 Unicode.
3722                 </p>
3723                 <p>
3724                         These functions are rarely used in practice,
3725                         as most Unicode text files
3726                         are already UTF-8&ndash;encoded
3727                         (rather than UCS-4,
3728                         which uses four-byte integer characters).
3729                         Unicode can be displayed directly
3730                         when using the <tt>"%ls"</tt> <a href="#format">format</a> specifier.
3731                 </p>
3732                 <p>
3733                 For further details on UTF-8 and Unicode,
3734                 consult <a href="http://www.cl.cam.ac.uk/~mgk25/unicode.html"><em>UTF-8 and Unicode FAQ for Unix/Linux</em></a> by Markus Kuhn.
3735
3736 <center>
3737 <span class="divider">(&nbsp;<font color="#7ba9d4">&sect;</font>&nbsp;)</span>
3738 </center>
3739
3740                 <a NAME="commas"></a>
3741                 <h2>
3742                         20. Commas in parameter lists
3743                 </h2>
3744                 <p>
3745                         Some of the example programs contain functions
3746                         that use a comma to separate the parameters into two groups.
3747                         This is not a special syntax of newLISP,
3748                         but rather a visual trick.
3749                         The comma is a symbol just like any other symbol.
3750                         The parameters after the comma are not required
3751                         when calling the function;
3752                         they simply declare local variables in a convenient way.
3753                         This is possible in newLISP because parameter variables in lambda expressions
3754                         are local and arguments are optional:
3755                 </p>
3756 <blockquote><pre>
3757 (define (my-func a b c , x y z)
3758     (set 'x &hellip;)
3759     (&hellip;))
3760 </pre></blockquote>             <p>
3761                         When calling this function,
3762                         only <tt>a, b</tt>, and <tt>c</tt> are used as parameters.
3763                         The others (<tt>x, y</tt>, and <tt>z</tt>)
3764                         are initialized to nil
3765                         and are local to the function.
3766                         After execution, the function's contents are forgotten
3767                         and the environment's symbols are restored
3768                         to their previous values.
3769                 </p>
3770                 <p>
3771                         For other ways of declaring and initializing local variables,
3772                         see <a HREF="#let">let</a>, <a href="#letex">letex</a>,
3773                         <a href="#letn">letn</a> and <a href="#local">local</a>.
3774                 </p>
3775
3776 <center>
3777 <span class="divider">(&nbsp;<font color="#7ba9d4">&sect;</font>&nbsp;)</span>
3778 </center>
3779
3780                 <a NAME="linking"></a>
3781                 <h2>
3782                         21. Linking newLISP source and executable
3783                 </h2>
3784                 <p>
3785                         Source code and the newLISP executable
3786                         can be linked together to build
3787                         a self-contained application
3788                         by using <tt>link.lsp</tt>. This program is located in the <tt>newlisp/util</tt> directory of the distributions.
3789                         As an example,
3790                         the following code is linked to the newLISP executable
3791                         to form a simple, self-contained application:
3792                 </p>
3793 <blockquote><pre>
3794 ;; uppercase.lsp - Link example
3795 (println (upper-case (main-args 1)))
3796 (exit)
3797 </pre></blockquote>             <p>
3798                         This program, which resides in the file <tt>uppercase.lsp</tt>, takes the first word on the command line and converts it to uppercase.
3799                 </p>
3800                 <p>
3801                         To build this program as a self-contained executable,
3802                         follow these four steps:
3803                 </p>
3804                 <p>
3805                         <tt>(1)</tt> Put the following files into the same directory:
3806                         (a) a copy of the newLISP executable; (b) <tt>newlisp</tt>
3807                         (or <tt>newlisp.exe</tt> on Win32); (c) <tt>link.lsp</tt>; and (d) the program to link with (<tt>uppercase.lsp</tt> in this example).
3808                 </p>
3809                 <p>
3810                         <tt>(2)</tt> In a shell,
3811                         go to the directory referred to in step 1
3812                         and load <tt>link.lsp</tt>:
3813                 </p>
3814 <blockquote><pre>
3815 newlisp link.lsp
3816 </pre></blockquote>             <p>
3817                         <tt>(3)</tt> In the newLISP shell, type one of the following:
3818                 </p>
3819 <blockquote><pre>
3820 (link "newlisp.exe" "uppercase.exe" "uppercase.lsp")  ; Win32
3821 (link "newlisp" "uppercase" "uppercase.lsp")          ; Linux/BSD
3822 </pre></blockquote>             <p>
3823                         <tt>(4)</tt> Exit the newLISP shell and type:
3824                 </p>
3825 <blockquote><pre>
3826 uppercase "convert me to uppercase"
3827 </pre></blockquote>             <p>
3828                         The console should print:
3829                 </p>
3830 <blockquote><pre>
3831 CONVERT ME TO UPPERCASE
3832 </pre></blockquote>             <p>
3833                         Note: On Linux/BSD, the new file must be marked
3834                         executable for the operating system to recognize it:
3835                 </p>
3836 <blockquote><pre>
3837 chmod 755 uppercase
3838 </pre></blockquote>             <p>
3839                         This gives the file executable permission
3840                         (this step is unnecessary on Win32).
3841                 </p>
3842                 <br />
3843
3844 <br /><br /><br />
3845
3846 <a NAME="symbol_names"></a>
3847
3848 <center style="font-size: 150%">
3849 <span class="divider">(&nbsp;<font color="#7ba9d4">&part;</font>&nbsp;)</span>
3850 </center>
3851
3852
3853 <CENTER><H1>newLISP Function Reference</H1></CENTER>
3854
3855 <br /><br />
3856
3857
3858 <h2>1. Syntax of symbol variables and numbers</h2>
3859 <p>
3860         Source code in newLISP is parsed according the rules outlined here.
3861         When in doubt, verify the behavior of newLISP's internal parser
3862         by calling <a href="#parse">parse</a> without optional arguments.
3863 </p>
3864
3865
3866 <h3>Symbols for variable names</h3>
3867 <p>
3868         The following rules apply to the naming of symbols
3869         used as variables or functions:
3870 </p>
3871
3872 <blockquote>
3873 <ol>
3874 <li>Variable symbols may not start with any of the following characters:<br />
3875 <tt># ; " ' ( )  { } . , 0 1 2 3 4 5 6 7 8 9</tt><br /><br /></li>
3876
3877 <li>Variable symbols starting with a <tt>+</tt> or <tt>-</tt> cannot have a number as the second character.<br /><br /></li>
3878
3879 <li>Any character is allowed inside a variable name, except for:<br />
3880  <tt>" ' ( ) : ,</tt> and the space character. These mark the end of a variable symbol.<br /><br /></li>
3881
3882 <li>A symbol name starting with <tt>[</tt> (left square bracket) and ending with <tt>]</tt> (right square bracket) may contain any character except the right square bracket.</li>
3883
3884 </ol>
3885 </blockquote>
3886
3887
3888 <p>
3889         All of the following symbols are legal variable names in newLISP:
3890 </p>
3891
3892 <b>example:</b>
3893 <blockquote>
3894 <pre>
3895 myvar
3896 A-name
3897 X34-zz
3898 [* 7 5 ()};]
3899 *111*
3900 </pre>
3901 </blockquote>
3902
3903 <p>
3904         Sometimes it is useful to create hash-like <a href="#hash">lookup dictionaries</a>
3905         with keys containing characters that are illegal in newLISP variables.
3906         The functions <a href="#sym">sym</a> and <a href="#context">context</a>
3907         can be used to create symbols containing these characters:
3908 </p>
3909
3910
3911 <blockquote>
3912 <pre>
3913 (set (sym "(#:L*") 456)  <span class=arw>&rarr;</span> 456
3914
3915 (eval (sym "(#:L*"))  <span class=arw>&rarr;</span> 456
3916
3917 (set (sym 1) 123)  <span class=arw>&rarr;</span> 123
3918
3919 (eval (sym 1))  <span class=arw>&rarr;</span> 123
3920
3921 1        <span class=arw>&rarr;</span> 1
3922 (+ 1 2)  <span class=arw>&rarr;</span> 3
3923 </pre>
3924 </blockquote>
3925
3926 <p>
3927         The last example creates the symbol <tt>1</tt>
3928         containing the value <tt>123</tt>.
3929         Also note that creating such a symbol does not alter newLISP's normal operations,
3930         since <tt>1</tt> is still parsed as the number one.
3931 </p>
3932
3933 <br />
3934
3935 <h3>Numbers</h3>
3936
3937 <p>
3938         newLISP recognizes the following number formats:
3939 </p>
3940
3941 <p>
3942         <b>Integers</b> are one or more digits long,
3943         optionally preceded by a <tt>+</tt> or <tt>-</tt> sign.
3944         Any other character marks the end of the integer
3945         or may be part of the sequence
3946         if parsed as a float (see float syntax below).
3947 </p>
3948
3949 <b>example:</b>
3950 <blockquote>
3951 <pre>
3952 123
3953 +4567
3954 -999
3955 </pre>
3956 </blockquote>
3957
3958 <p>
3959         <b>Hexadecimals</b> start with a <tt>0x</tt> (or <tt>0X</tt>)
3960         followed by any combination of the hexadecimal digits:
3961         <tt>0123456789abcdefABCDEF</tt>.
3962         Any other character ends the hexadecimal number.
3963 </p>
3964
3965 <b>example:</b>
3966 <blockquote>
3967 <pre>
3968 0xFF    <span class=arw>&rarr;</span>  255
3969 0x10ab  <span class=arw>&rarr;</span> 4267
3970 0X10CC  <span class=arw>&rarr;</span> 4300
3971 </pre>
3972 </blockquote>
3973
3974 <p>
3975         <b>Octals</b> start with an optional <tt>+</tt> (plus) or <tt>-</tt> (minus) sign and a <tt>0</tt> (zero),
3976         followed by any combination of the octal digits: <tt>01234567</tt>.
3977         Any other character ends the octal number.
3978 </p>
3979
3980 <b>example:</b>
3981 <blockquote>
3982 <pre>
3983 012   <span class=arw>&rarr;</span>  10
3984 010   <span class=arw>&rarr;</span>   8
3985 077   <span class=arw>&rarr;</span>  63
3986 -077  <span class=arw>&rarr;</span> -63
3987 </pre>
3988 </blockquote>
3989
3990
3991 <p>
3992         <b>Floating point</b> numbers can start
3993         with an optional <tt>+</tt> (plus) or <tt>-</tt> (minus) sign,
3994         but they cannot be followed by a <tt>0</tt> (zero) if they are.
3995         This would make them octal numbers instead of floating points.
3996         A single <tt>.</tt> (decimal point) can appear anywhere within
3997         a floating point number, including at the beginning.
3998 </p>
3999
4000 <b>example:</b>
4001 <blockquote>
4002 <pre>
4003 1.23     <span class=arw>&rarr;</span>  1.23
4004 -1.23    <span class=arw>&rarr;</span> -1.23
4005 +2.3456  <span class=arw>&rarr;</span>  2.3456
4006 .506     <span class=arw>&rarr;</span>  0.506
4007 </pre>
4008 </blockquote>
4009
4010 <p>
4011         As described above, <b>scientific notation</b>
4012         starts with a floating point number
4013         called the <em>significand</em> (or <em>mantissa</em>),
4014         followed by the letter <tt>e</tt> or <tt>E</tt>
4015         and an integer <em>exponent</em>.
4016 </p>
4017
4018 <b>example:</b>
4019 <blockquote>
4020 <pre>
4021 1.23e3    <span class=arw>&rarr;</span>  1230
4022 -1.23E3   <span class=arw>&rarr;</span> -1230
4023 +2.34e-2  <span class=arw>&rarr;</span>     0.0234
4024 .506E3    <span class=arw>&rarr;</span>   506
4025 </pre>
4026 </blockquote>
4027
4028
4029 <br /><br /><br />
4030
4031 <a NAME="type_ids"></a>
4032 <h2>2. Data types and names in the reference</h2>
4033
4034 <p>
4035         To describe the types and names
4036         of a function's parameters,
4037         the following naming convention
4038         is used throughout the reference section:
4039 </p>
4040
4041 <blockquote>
4042 <b>syntax: (format <em>str-format</em> <em>exp-data-1</em> [<em>exp-data-i</em> ... ])</b>
4043
4044 </blockquote>
4045
4046 <p>
4047         Arguments are represented by symbols
4048         formed by the argument's type and name,
4049         separated by a <tt>-</tt> (hyphen).
4050         Here, <em>str-format</em> (a string) and <em>exp-data-1</em> (an expression)
4051         are named "format" and "data-1", respectively.
4052 </p>
4053
4054 <h3>bool</h3>
4055
4056 <p>
4057         <tt>true</tt>, <tt>nil</tt>,
4058         or an expression evaluating to
4059         one of these two.
4060 </p>
4061
4062 <blockquote>
4063 <pre>
4064 true, nil, (&lt;= X 10)
4065 </pre>
4066 </blockquote>
4067
4068 <h3>int</h3>
4069
4070 <p>
4071         An integer or an expression evaluating to an integer.
4072         Generally, if a floating point number is used
4073         when an int is expected,
4074         the value is truncated to an integer.
4075 </p>
4076
4077 <blockquote>
4078 <pre>
4079 123, 5, (* X 5)
4080 </pre>
4081 </blockquote>
4082
4083 <h3>num</h3>
4084 <p>
4085         An integer, a floating point number,
4086         or an expression evaluating to one of these two.
4087         If an integer is passed,
4088         it is converted to a floating point number.
4089 </p>
4090 <blockquote>
4091 <pre>
4092 1.234, (div 10 3), (sin 1)
4093 </pre>
4094 </blockquote>
4095
4096 <h3>matrix</h3>
4097 <p>
4098         A list in which each row element is itself a list
4099         or an array in which each row element is itself an array.
4100         All element lists or arrays (rows) are of the same length.
4101         When using <a href="#det">det</a>,
4102         <A HREF="#multiply">multiply</A>,
4103         or <A HREF="#invert">invert</A>,
4104         all numbers must be floats or integers.
4105 </p>
4106
4107 <p>
4108         The dimensions of a matrix are defined
4109         by indicating the number of rows
4110         and the number of column elements per row.
4111         Functions working on matrices
4112         ignore superfluous columns in a row.
4113         For missing row elements,
4114         <tt>0.0</tt> is assumed by the functions
4115         <a href="#det">det</a>, <a href="#multiply">multiply</a>,
4116         and <a href="#invert">invert</a>,
4117         while <a href="#transpose">transpose</a> assumes <tt>nil</tt>.
4118         Special rules apply for <a href="#transpose">transpose</a>
4119         when a whole row is not a list or an array,
4120         but some other data type.
4121 </p>
4122
4123 <blockquote>
4124 <pre>
4125 ((1  2  3  4)
4126  (5  6  7  8)
4127  (9 10 11 12))       ; 3 rows 4 columns
4128
4129 ((1 2) (3 4) (5 6))  ; 3 rows 2 columns
4130 </pre>
4131 </blockquote>
4132
4133 <h3>str</h3>
4134 <p>
4135         A string or an expression that evaluates to a string.
4136 </p>
4137 <blockquote>
4138 <pre>
4139 "Hello", (append first-name  " Miller")
4140 </pre>
4141 </blockquote>
4142
4143 <p>
4144         Special characters can be included in quoted strings
4145         by placing a <tt>\</tt> (backslash) before the character
4146         or digits to escape them:
4147 </p>
4148 <br />
4149 <center>
4150 <table border="0" cellpadding="1" width="95%" summary="escaping special characters in strings">
4151 <tr align="left" valign="bottom"><th>escaped<br />character</th><th>description</th></tr>
4152 <tr>
4153 <td><tt>\n</tt></td>
4154 <td>the line feed character (ASCII 10)</td>
4155 </tr>
4156
4157 <tr>
4158 <td><tt>\r</tt></td>
4159 <td>the carriage return character (ASCII 13)</td>
4160 </tr>
4161
4162 <tr>
4163 <td><tt>\t</tt></td>
4164 <td>the tab character (ASCII 9)</td>
4165 </tr>
4166
4167 <tr>
4168 <td><tt>\nnn</tt></td>
4169 <td>a decimal ASCII code where nnn is between 000 and 255</td>
4170 </tr>
4171
4172 <tr>
4173 <td><tt>\xnn</tt></td>
4174 <td>a hexadecimal code where nn is between 00 and FF</td>
4175 </tr>
4176
4177 </table>
4178 </center>
4179 <br />
4180
4181 <blockquote>
4182 <pre>
4183 "\065\066\067" <span class=arw>&rarr;</span> "ABC"
4184 "\x41\x42\x43" <span class=arw>&rarr;</span> "ABC"
4185 </pre>
4186 </blockquote>
4187
4188 <p>
4189         Instead of a <tt>"</tt> (double quote),
4190         a <tt>{</tt> (left curly bracket)
4191         and <tt>}</tt> (right curly bracket)
4192         can be used to delimit strings.
4193         This is useful when quotation marks need to occur inside strings.
4194         Quoting with the curly brackets
4195         suppresses the backslash escape effect for special characters.
4196         Balanced nested curly brackets may be used within a string.
4197         This aids in writing regular expressions or short sections of HTML.
4198 </p>
4199
4200 <blockquote>
4201 <pre>
4202 (print "&lt;A HREF=\"http://mysite.com\"&gt;" ) ; the cryptic way
4203
4204 (print {&lt;A HREF="http://mysite.com"&gt;} )   ; the readable way
4205
4206 ;; also possible because the inner brackets are balanced
4207 (regex {abc{1,2}} line)
4208
4209 (print [text]
4210   this could be
4211   a very long (&gt; 2048 characters) text,
4212   i.e. HTML.
4213 [/text])
4214 </pre>
4215 </blockquote>
4216
4217 <p>
4218         The tags <tt>[text]</tt> and <tt>[/text]</tt>
4219         can be used to delimit long strings
4220         and suppress escape character translation.
4221         This is useful for delimiting long HTML passages
4222         in CGI files written in newLISP
4223         or for situations where character translation
4224         should be completely suppressed.
4225         Always use the <tt>[text]</tt> tags
4226         for strings longer than 2048 characters.
4227 </p>
4228
4229 <h3>sym</h3>
4230
4231 <p>
4232         A symbol or expression evaluating to a symbol.
4233 </p>
4234
4235 <blockquote>
4236 <pre>
4237 'xyz, (first '(+ - /)), '*, '- , 'someSymbol,
4238 </pre>
4239 </blockquote>
4240
4241 <h3>context</h3>
4242
4243 <p>
4244         An expression evaluating to a context (namespace)
4245         or a variable symbol holding a context.
4246 </p>
4247
4248 <blockquote>
4249 <pre>
4250 MyContext, aCtx, TheCTX
4251 </pre>
4252 </blockquote>
4253
4254 <p>
4255         Most of the context symbols in this manual
4256         start with an uppercase letter
4257         to distinguish them from other symbols.
4258 </p>
4259
4260 <h3>sym-context</h3>
4261 <p>
4262         A symbol, an existing context,
4263         or an expression evaluating to a symbol
4264         from which a context will be created.
4265         If a context does not already exist,
4266         many functions implicitly create them
4267         (e.g., <a href="#bayes-train">bayes-train</a>, <a Href="#context">context</a>, <a href="#eval-string">eval-string</a>,
4268 <a href="#load">load</a>, <a href="#sym">sym</a>, and <a href="#xml-parse">xml-parse</a>).
4269         The context must be specified
4270         when these functions are used
4271         on an existing context.
4272         Even if a context already exists,
4273         some functions may continue to take symbols
4274         (e.g., <a href="#context">context</a>).
4275         For other functions,
4276         such as <a href="#contextp">context?</a>,
4277         the distinction is critical.
4278 </p>
4279
4280 <h3>func</h3>
4281
4282 <p>
4283         A symbol or an expression evaluating to
4284         an operator symbol or lambda expression.
4285 </p>
4286
4287 <blockquote>
4288 <pre>
4289 +, add, (first '(add sub)), (lambda (x) (+ x x))
4290 </pre>
4291 </blockquote>
4292
4293 <h3>list</h3>
4294 <p>
4295         A list of elements (any type)
4296         or an expression evaluating to a list.
4297 </p>
4298 <blockquote>
4299 <pre>
4300
4301 (a b c "hello" (+ 3 4))
4302 </pre>
4303 </blockquote>
4304
4305
4306 <h3>array</h3>
4307 <p>
4308         An array
4309         (constructed with the
4310         <a href="#array">array</a> function).
4311 </p>
4312
4313 <h3>exp</h3>
4314
4315 <p>
4316         Any of the above.
4317 </p>
4318
4319 <h3>body</h3>
4320
4321 <p>
4322         One or more expressions that can be evaluated.
4323         The expressions are evaluated sequentially
4324         if there is more than one.
4325 </p>
4326
4327 <blockquote>
4328 <pre>
4329 1 7.8
4330 nil
4331 (+ 3 4)
4332 "Hi" (+ a b)(print result)
4333 (do-this)(do-that) 123
4334 </pre>
4335 </blockquote>
4336 <br />
4337
4338
4339
4340 <br /><br /><br />
4341
4342 <a NAME="functions"></a>
4343 <h2>3. Functions in groups</h2>
4344
4345 <p>
4346         Some functions appear in more than one group.
4347 </p>
4348
4349 <a NAME="list_processing"></a>
4350 <h3>List processing, flow control, and integer arithmetic</h3>
4351 <blockquote>
4352 <table border="0" cellpadding="1" width="95%" align="center" summary="List processing, flow control and integer
4353 arithmetic">
4354
4355 <tr>
4356 <td WIDTH="16%"><a href="#arithmetic">+, -, *, /, %</a></td>
4357 <td WIDTH="80%">integer arithmetic</td>
4358 </tr>
4359
4360 <tr>
4361 <td><a href="#logical">&lt;, &gt;, =</a></td>
4362 <td>compares any data type: less, greater, equal</td>
4363 </tr>
4364
4365 <tr>
4366 <td><a href="#logical">&lt;=, &gt;=, !=</a></td>
4367 <td>compares any data type: less-equal, greater-equal, not-equal</td>
4368 </tr>
4369
4370 <tr>
4371 <td><a href="#colon">:</a></td>
4372 <td>constructs a context symbol and applies it to an object.</td>
4373 </tr>
4374
4375 <tr>
4376 <td><a href="#and">and</a></td>
4377 <td>logical <tt>and</tt></td>
4378 </tr>
4379
4380 <tr>
4381 <td><a href="#append">append</a></td>
4382 <td>appends lists ,arrays or strings to form a new list, array or string</td>
4383 </tr>
4384
4385 <tr>
4386 <td><a href="#apply">apply</a></td>
4387 <td>applies a function or primitive to a list of arguments</td>
4388 </tr>
4389
4390 <tr>
4391 <td><a href="#args">args</a></td>
4392 <td>retrieves the argument list of a macro expression</td>
4393 </tr>
4394
4395 <tr>
4396 <td><a href="#assoc">assoc</a></td>
4397 <td>searches for keyword associations in a list</td>
4398 </tr>
4399
4400 <tr>
4401 <td><a href="#assoc-set">assoc-set</a></td>
4402 <td>replaces an association in a list</td>
4403 </tr>
4404
4405 <tr>
4406 <td><a href="#begin">begin</a></td>
4407 <td>begins a block of functions</td>
4408 </tr>
4409
4410 <tr>
4411 <td><a href="#case">case</a></td>
4412 <td>branches depending on contents of control variable</td>
4413 </tr>
4414
4415 <tr>
4416 <td><a href="#catch">catch</a></td>
4417 <td>evaluates an expression, possibly catching errors</td>
4418 </tr>
4419
4420 <tr>
4421 <td><a href="#chop">chop</a></td>
4422 <td>chops elements from the end of a list</td>
4423 </tr>
4424
4425 <tr>
4426 <td><a href="#clean">clean</a></td>
4427 <td>cleans elements from a list</td>
4428 </tr>
4429
4430 <tr>
4431 <td><a href="#cond">cond</a></td>
4432 <td>branches conditionally to expressions</td>
4433 </tr>
4434
4435 <tr>
4436 <td><a href="#cons">cons</a></td>
4437 <td>prepends an element to a list, making a new list</td>
4438 </tr>
4439
4440 <tr>
4441 <td><a href="#constant">constant</a></td>
4442 <td>defines a constant symbol</td>
4443 </tr>
4444
4445 <tr>
4446 <td><a href="#count">count</a></td>
4447 <td>counts elements of one list that occur in another list</td>
4448 </tr>
4449
4450 <tr>
4451 <td><a href="#curry">curry</a></td>
4452 <td>Transforms a function f(x, y) into a function fx(y)</td>
4453 </tr>
4454
4455 <tr>
4456 <td><a href="#define">define</a></td>
4457 <td>defines a new function or lambda expression</td>
4458 </tr>
4459
4460 <tr>
4461 <td><a href="#define-macro">define-macro</a></td>
4462 <td>defines a macro or lambda-macro expression</td>
4463 </tr>
4464
4465 <tr>
4466 <td><a href="#def-new">def-new</a></td>
4467 <td>copies a symbol to a different context (namespace)</td>
4468 </tr>
4469
4470 <tr>
4471 <td><a href="#difference">difference</a></td>
4472 <td>returns the difference between two lists</td>
4473 </tr>
4474
4475 <tr>
4476 <td><a href="#doargs">doargs</a></td>
4477 <td>iterates through the arguments of a function</td>
4478 </tr>
4479
4480 <tr>
4481 <td><a href="#dolist">dolist</a></td>
4482 <td>evaluates once for each element in a list</td>
4483 </tr>
4484
4485 <tr>
4486 <td><a href="#dolist">dostring</a></td>
4487 <td>evaluates once for each character in a string</td>
4488 </tr>
4489
4490 <tr>
4491 <td><a href="#dotimes">dotimes</a></td>
4492 <td>evaluates once for each number in a range</td>
4493 </tr>
4494
4495 <tr>
4496 <td><a href="#dotree">dotree</a></td>
4497 <td>iterates through the symbols of a context</td>
4498 </tr>
4499
4500 <tr>
4501 <td><a href="#do-until">do-until</a></td>
4502 <td>repeats evaluation of an expression until the condition is met</td>
4503 </tr>
4504
4505 <tr>
4506 <td><a href="#do-while">do-while</a></td>
4507 <td>repeats evaluation of an expression while the condition is true</td>
4508 </tr>
4509
4510 <tr>
4511 <td><a href="#dup">dup</a></td>
4512 <td>duplicates a list or string a specified number of times</td>
4513 </tr>
4514
4515 <tr>
4516 <td><a href="#ends-with">ends-with</a></td>
4517 <td>checks the end of a string or list against a key of the same type</td>
4518 </tr>
4519
4520 <tr>
4521 <td><a href="#eval">eval</a></td>
4522 <td>evaluates an expression</td>
4523
4524 </tr>
4525 <tr>
4526 <td><a href="#exists">exists</a></td>
4527 <td>checks for the existens of a condition in a list</td>
4528 </tr>
4529
4530 <tr>
4531 <td><a href="#expand">expand</a></td>
4532 <td>replaces a symbol in a nested list</td>
4533 </tr>
4534
4535 <tr>
4536 <td><a href="#first">first</a></td>
4537 <td>gets the first element of a list or string</td>
4538 </tr>
4539
4540 <tr>
4541 <td><a href="#filter">filter</a></td>
4542 <td>filters a list</td>
4543 </tr>
4544
4545 <tr>
4546 <td><a href="#find">find</a></td>
4547 <td>searches for an element in a list or string</td>
4548 </tr>
4549
4550 <tr>
4551 <td><a href="#flat">flat</a></td>
4552 <td>returns the flattened list</td>
4553 </tr>
4554
4555 <tr>
4556 <td><a href="#define">fn</a></td>
4557 <td>defines a new function or lambda expression</td>
4558 </tr>
4559
4560 <tr>
4561 <td><a href="#for">for</a></td>
4562 <td>evaluates once for each number in a range</td>
4563 </tr>
4564
4565 <tr>
4566 <td><a href="#for-all">for-all</a></td>
4567 <td>checks if all elements in a list meet a condition</td>
4568 </tr>
4569
4570 <tr>
4571 <td><a href="#if">if</a></td>
4572 <td>evaluates an expression conditionally</td>
4573 </tr>
4574
4575 <tr>
4576 <td><a href="#index">index</a></td>
4577 <td>filters elements from a list and returns their indices</td>
4578 </tr>
4579
4580
4581 <tr>
4582 <td><a href="#intersect">intersect</a></td>
4583 <td>returns the intersection of two lists</td>
4584 </tr>
4585
4586 <tr>
4587 <td><a href="#define">lambda</a></td>
4588 <td>defines a new function or lambda expression</td>
4589 </tr>
4590
4591 <tr>
4592 <td><a href="#last">last</a></td>
4593 <td>returns the last element of a list or string</td>
4594 </tr>
4595
4596 <tr>
4597 <td><a href="#length">length</a></td>
4598 <td>calculates the length of a list or string</td>
4599 </tr>
4600
4601 <tr>
4602 <td><a href="#let">let</a></td>
4603 <td>declares and initializes local variables</td>
4604 </tr>
4605
4606 <tr>
4607 <td><a href="#letex">letex</a></td>
4608 <td>expands local variables into an expression, then evaluates</td>
4609 </tr>
4610
4611 <tr>
4612 <td><a href="#letn">letn</a></td>
4613 <td>initializes local variables incrementally, like <em>nested lets</em></td>
4614 </tr>
4615
4616 <tr>
4617 <td><a href="#list">list</a></td>
4618 <td>makes a list</td>
4619 </tr>
4620
4621 <tr>
4622 <td><a href="#local">local</a></td>
4623 <td>declares local variables</td>
4624 </tr>
4625
4626 <tr>
4627 <td><a href="#lookup">lookup</a></td>
4628 <td>looks up members in an association list</td>
4629 </tr>
4630
4631 <tr>
4632 <td><a href="#map">map</a></td>
4633 <td>maps a function over members of a list, collecting the results</td>
4634 </tr>
4635
4636 <tr>
4637 <td><a href="#match">match</a></td>
4638 <td>matches patterns against lists; for matching against strings, see <a href="#find">find</a> and <a href="#regex">regex</a></td>
4639 </tr>
4640
4641 <tr>
4642 <td><a href="#member">member</a></td>
4643 <td>finds a member of a list or string</td>
4644 </tr>
4645
4646 <tr>
4647 <td><a href="#name">name</a></td>
4648 <td>returns the name of a symbol or its context as a string</td>
4649 </tr>
4650
4651 <tr>
4652 <td><a href="#not">not</a></td>
4653 <td>logical <tt>not</tt></td>
4654 </tr>
4655
4656 <tr>
4657 <td><a href="#nth">nth</a></td>
4658 <td>gets the <em>nth</em> element of a list or string</td>
4659 </tr>
4660
4661 <tr>
4662 <td><a href="#nth-set">nth-set</a></td>
4663 <td>changes the <em>nth</em> element of a list or string</td>
4664 </tr>
4665
4666 <tr>
4667 <td><a href="#or">or</a></td>
4668 <td>logical <tt>or</tt></td>
4669 </tr>
4670
4671 <tr>
4672 <td><a href="#pop">pop</a></td>
4673 <td>deletes and returns an element from a list or string</td>
4674 </tr>
4675
4676 <tr>
4677 <td><a href="#push">push</a></td>
4678 <td>inserts a new element into a list or string</td>
4679 </tr>
4680
4681 <tr>
4682 <td><a href="#quote">quote</a></td>
4683 <td>quotes an expression</td>
4684 </tr>
4685
4686 <tr>
4687 <td><a href="#ref">ref</a></td>
4688 <td>returns the position of an element inside a nested list</td>
4689 </tr>
4690
4691 <tr>
4692 <td><a href="#ref-all">ref-all</a></td>
4693 <td>returns a list of index vectors of element inside a nested list</td>
4694 </tr>
4695
4696 <tr>
4697 <td><a href="#ref-set">ref-set</a></td>
4698 <td>searches for an element in a nested list and replaces it</td>
4699 </tr>
4700
4701 <tr>
4702 <td><a href="#rest">rest</a></td>
4703 <td>returns all but the first element of a list or string</td>
4704 </tr>
4705
4706 <tr>
4707 <td><a href="#replace">replace</a></td>
4708 <td>replaces elements inside a list or string</td>
4709 </tr>
4710
4711 <tr>
4712 <td><a href="#reverse">reverse</a></td>
4713 <td>reverses a list or string</td>
4714 </tr>
4715
4716 <tr>
4717 <td><a href="#rotate">rotate</a></td>
4718 <td>rotates a list or string</td>
4719 </tr>
4720
4721 <tr>
4722 <td><a href="#select">select</a></td>
4723 <td>selects and permutes elements from a list or string</td>
4724 </tr>
4725
4726 <tr>
4727 <td><a href="#set">set</a></td>
4728 <td>sets the binding or contents of a symbol</td>
4729 </tr>
4730
4731 <tr>
4732 <td><a href="#setq">setq</a></td>
4733 <td>sets the binding or contents of an unquoted symbol</td>
4734 </tr>
4735
4736 <tr>
4737 <td><a href="#set-assoc">set-assoc</a></td>
4738 <td>replaces an association within a list</td>
4739 </tr>
4740
4741 <tr>
4742 <td><a href="#set-nth">set-nth</a></td>
4743 <td>changes the <em>nth</em> element of a list or string</td>
4744 </tr>
4745
4746 <tr>
4747 <td><a href="#set-ref">set-ref</a></td>
4748 <td>searches for an element in a nested list and replaces it</td>
4749 </tr>
4750
4751 <tr>
4752 <td><a href="#set-ref-all">set-ref-all</a></td>
4753 <td>searches for an element in a nested list and replaces all instances</td>
4754 </tr>
4755
4756 <tr>
4757 <td><a href="#silent">silent</a></td>
4758 <td>works like <a HREF="#begin">begin</a> but suppresses console output of the return value</td>
4759 </tr>
4760
4761 <tr>
4762 <td><a href="#slice">slice</a></td>
4763 <td>extracts a sublist or substring</td>
4764 </tr>
4765
4766 <tr>
4767 <td><a href="#sort">sort</a></td>
4768 <td>sorts the members of a list</td>
4769 </tr>
4770
4771 <tr>
4772 <td><a href="#starts-with">starts-with</a></td>
4773 <td>checks the beginning of a string or list against a key of the same type</td>
4774 </tr>
4775
4776 <tr>
4777 <td><a href="#swap">swap</a></td>
4778 <td>swaps two elements inside a list or string</td>
4779 </tr>
4780
4781 <tr>
4782 <td><a href="#unify">unify</a></td>
4783 <td>unifies two expressions</td>
4784 </tr>
4785
4786 <tr>
4787 <td><a href="#unique">unique</a></td>
4788 <td>returns a list without duplicates</td>
4789 </tr>
4790
4791 <tr>
4792 <td><a href="#unless">unless</a></td>
4793 <td>evaluates an expression conditionally</td>
4794 </tr>
4795
4796 <tr>
4797 <td><a href="#until">until</a></td>
4798 <td>repeats evaluation of an expression until the condition is met</td>
4799 </tr>
4800
4801 <tr>
4802 <td><a href="#when">when</a></td>
4803 <td>evaluate a block of statements conditionally</td>
4804 </tr>
4805
4806 <tr>
4807 <td><a href="#while">while</a></td>
4808 <td>repeats evaluation of an expression while the condition is true</td>
4809 </tr>
4810 </table>
4811 </blockquote>
4812
4813 <a NAME="string_operators"></a>
4814 <h3>String and conversion functions</h3>
4815
4816 <blockquote>
4817 <table border="0" cellpadding="1" width="95%" align="center" summary="String and conversion functions">
4818
4819
4820 <tr>
4821 <td WIDTH="16%"><a href="#address">address</a></td>
4822 <td WIDTH="84%">gets the memory address of a number or string</td>
4823 </tr>
4824
4825
4826 <tr>
4827 <td><a href="#append">append</a></td>
4828 <td>appends lists, arrays or strings to form a new list, array  or string</td>
4829 </tr>
4830
4831
4832 <tr>
4833 <td><a href="#char">char</a></td>
4834 <td>translates between characters and ASCII codes</td>
4835 </tr>
4836
4837 <tr>
4838 <td><a href="#chop">chop</a></td>
4839
4840 <td>chops off characters from the end of a string</td>
4841 </tr>
4842
4843 <tr>
4844 <td><a href="#dup">dup</a></td>
4845 <td>duplicates a list or string a specified number of times</td>
4846 </tr>
4847
4848 <tr>
4849 <td><a href="#ends-with">ends-with</a></td>
4850 <td>checks the end of a string or list against a key of the same type</td>
4851 </tr>
4852
4853 <tr>
4854 <td><a href="#encrypt">encrypt</a></td>
4855 <td>does a one-time&ndash;pad encryption and decryption of a string</td>
4856 </tr>
4857
4858 <tr>
4859 <td><a href="#eval-string">eval-string</a></td>
4860 <td>compiles, then evaluates a string</td>
4861 </tr>
4862
4863 <tr>
4864 <td><a href="#explode">explode</a></td>
4865
4866 <td>transforms a string into a list of characters</td>
4867 </tr>
4868
4869 <tr>
4870 <td><a href="#find">find</a></td>
4871 <td>searches for an element in a list or string</td>
4872 </tr>
4873
4874 <!-- 8.9.4 -->
4875 <tr>
4876 <td><a href="#find-all">find-all</a></td>
4877 <td>returns a list of all pattern matches found in string</td>
4878 </tr>
4879
4880 <tr>
4881 <td><a href="#first">first</a></td>
4882 <td>gets the first element in a list or string</td>
4883 </tr>
4884
4885 <tr>
4886 <td><a href="#float">float</a></td>
4887 <td>translates a string or integer into a floating point number</td>
4888 </tr>
4889
4890 <tr>
4891 <td><a href="#format">format</a></td>
4892 <td>formats numbers and strings as in the C language</td>
4893 </tr>
4894
4895 <tr>
4896 <td><a href="#get-char">get-char</a></td>
4897
4898 <td>gets a character from a memory address</td>
4899 </tr>
4900
4901 <tr>
4902 <td><a href="#get-float">get-float</a></td>
4903 <td>gets a double float from a memory address</td>
4904 </tr>
4905
4906 <tr>
4907 <td><a href="#get-int">get-int</a>&nbsp;&nbsp;</td>
4908 <td>gets an 32-bitinteger from a memory address</td>
4909 </tr>
4910
4911 <tr>
4912 <td><a href="#get-long">get-long</a>&nbsp;&nbsp;</td>
4913 <td>gets a long 64-bit integer from a memory address</td>
4914 </tr>
4915
4916 <tr>
4917 <td><a href="#get-string">get-string</a></td>
4918 <td>gets a string from a memory address</td>
4919 </tr>
4920
4921 <tr>
4922 <td><a href="#int">int</a></td>
4923 <td>translates a string or float into an integer</td>
4924 </tr>
4925
4926 <tr>
4927 <td><a href="#join">join</a></td>
4928 <td>joins a list of strings</td>
4929 </tr>
4930
4931 <tr>
4932 <td><a href="#last">last</a></td>
4933 <td>returns the last element of a list or string</td>
4934 </tr>
4935
4936 <tr>
4937 <td><a href="#lower-case">lower-case</a></td>
4938 <td>converts a string to lowercase characters</td>
4939 </tr>
4940
4941 <tr>
4942 <td><a href="#member">member</a></td>
4943 <td>finds a list or string member</td>
4944 </tr>
4945
4946 <tr>
4947 <td><a href="#name">name</a></td>
4948 <td>returns the name of a symbol or its context as a string</td>
4949 </tr>
4950
4951 <tr>
4952 <td><a href="#nth">nth</a></td>
4953 <td>gets the <em>nth</em> element in a list or string</td>
4954 </tr>
4955
4956 <tr>
4957 <td><a href="#nth-set">nth-set</a></td>
4958 <td>changes the <em>nth</em> element of a list or string</td>
4959 </tr>
4960
4961
4962 <tr>
4963 <td><a href="#pack">pack</a></td>
4964 <td>packs LISP expressions into a binary structure</td>
4965 </tr>
4966
4967 <tr>
4968 <td><a href="#parse">parse</a></td>
4969 <td>breaks a string into tokens</td>
4970 </tr>
4971
4972 <tr>
4973 <td><a href="#pop">pop</a></td>
4974 <td>pops from a string</td>
4975 </tr>
4976
4977 <tr>
4978 <td><a href="#push">push</a></td>
4979 <td>pushes onto a string</td>
4980 </tr>
4981
4982 <tr>
4983 <td><a href="#regex">regex</a></td>
4984 <td>performs a Perl-compatible regular expression search</td>
4985 </tr>
4986
4987 <tr>
4988 <td><a href="#replace">replace</a></td>
4989 <td>replaces elements in a list or string</td>
4990
4991 </tr>
4992
4993 <tr>
4994 <td><a href="#rest">rest</a></td>
4995 <td>gets all but the first element of a list or string</td>
4996 </tr>
4997
4998 <tr>
4999 <td><a href="#reverse">reverse</a></td>
5000 <td>reverses a list or string</td>
5001 </tr>
5002
5003 <tr>
5004 <td><a href="#rotate">rotate</a></td>
5005 <td>rotates a list or string</td>
5006 </tr>
5007
5008 <tr>
5009 <td><a href="#select">select</a></td>
5010 <td>selects and permutes elements from a list or string</td>
5011 </tr>
5012
5013
5014 <tr>
5015 <td><a href="#set-nth">set-nth</a></td>
5016 <td>changes the element in a list or string</td>
5017 </tr>
5018
5019 <tr>
5020 <td><a href="#slice">slice</a></td>
5021
5022 <td>extracts a substring or sublist</td>
5023 </tr>
5024
5025 <tr>
5026 <td><a href="#source">source</a></td>
5027 <td>returns the source required to bind a symbol to a string</td>
5028 </tr>
5029
5030 <tr>
5031 <td><a href="#starts-with">starts-with</a></td>
5032 <td>checks the start of the string or list against a key string or list</td>
5033 </tr>
5034
5035 <tr>
5036 <td><a href="#string">string</a></td>
5037 <td>transforms anything into a string</td>
5038 </tr>
5039
5040 <tr>
5041 <td><a href="#sym">sym</a></td>
5042 <td>translates a string into a symbol</td>
5043 </tr>
5044
5045 <tr>
5046 <td><a href="#title-case">title-case</a></td>
5047
5048 <td>converts the first character of a string to uppercase</td>
5049 </tr>
5050
5051 <tr>
5052 <td><a href="#trim">trim</a></td>
5053 <td>trims a string of one or both sides</td>
5054 </tr>
5055
5056 <tr>
5057 <td><a href="#unicode">unicode</a></td>
5058 <td>converts ASCII or UTF-8 to UCS-4 Unicode</td>
5059 </tr>
5060
5061 <tr>
5062 <td><a href="#utf8">utf8</a></td>
5063 <td>converts UCS-4 Unicode to UTF-8</td>
5064 </tr>
5065
5066 <tr>
5067 <td><a href="#utf8len">utf8</a></td>
5068 <td>returns length of an UTF-8 string in UTF-8 characters</td>
5069 </tr>
5070
5071
5072 <tr>
5073 <td><a href="#unpack">unpack</a></td>
5074 <td>unpacks a binary structure into LISP expressions</td>
5075 </tr>
5076
5077 <tr>
5078
5079 <td><a href="#upper-case">upper-case</a></td>
5080 <td>converts a string to uppercase characters</td>
5081 </tr>
5082
5083 </table>
5084 </blockquote>
5085
5086
5087 <a NAME="floating_point"></a>
5088 <h3>Floating point math and special functions</h3>
5089
5090 <blockquote>
5091 <table border="0" cellpadding="1" width="95%" align="center" summary="Floating point math and special functions">
5092
5093
5094 <tr>
5095 <td WIDTH="16%"><a href="#abs">abs</a></td>
5096 <td WIDTH="84%">calculates the absolute value of a number</td>
5097 </tr>
5098
5099 <tr>
5100 <td><a href="#acos">acos</a></td>
5101 <td>calculates the arccosine of a number</td>
5102 </tr>
5103
5104 <tr>
5105 <td><a href="#acosh">acosh</a></td>
5106 <td>calculates the inverse hyperbolic cosine of a number</td>
5107 </tr>
5108
5109 <tr>
5110 <td><a href="#add">add</a></td>
5111 <td>adds floating point or integer numbers</td>
5112 </tr>
5113
5114 <tr>
5115 <td><a href="#array">array</a></td>
5116 <td>creates an array</td>
5117 </tr>
5118
5119 <tr>
5120 <td><a href="#array-list">array-list</a></td>
5121 <td>returns a list conversion from an array</td>
5122 </tr>
5123
5124 <tr>
5125 <td><a href="#asin">asin</a></td>
5126 <td>calculates the arcsine of a number</td>
5127 </tr>
5128
5129 <tr>
5130 <td><a href="#asinh">asinh</a></td>
5131 <td>calculates the inverse hyperbolic sine of a number</td>
5132 </tr>
5133
5134
5135 <tr>
5136 <td><a href="#atan">atan</a></td>
5137 <td>calculates the arctangent of a number</td>
5138 </tr>
5139
5140 <tr>
5141 <td><a href="#atanh">atanh</a></td>
5142 <td>calculates the inverse hyperbolic tangent of a number</td>
5143 </tr>
5144
5145 <tr>
5146 <td><a href="#atan2">atan2</a></td>
5147 <td>computes the principal value of the arctangent of Y / X in radians</td>
5148 </tr>
5149
5150 <tr>
5151 <td><a href="#beta">beta</a></td>
5152 <td>calculates the beta function</td>
5153 </tr>
5154
5155 <tr>
5156 <td><a href="#betai">betai</a></td>
5157 <td>calculates the incomplete beta function</td>
5158 </tr>
5159
5160 <tr>
5161 <td><a href="#binomial">binomial</a></td>
5162 <td>calculates the binomial function</td>
5163 </tr>
5164
5165 <tr>
5166 <td><a href="#ceil">ceil</a></td>
5167
5168 <td>rounds up to the next integer</td>
5169 </tr>
5170
5171 <tr>
5172 <td><a href="#cos">cos</a></td>
5173 <td>calculates the cosine of a number</td>
5174
5175 </tr>
5176 <tr>
5177 <td><a href="#cosh">cosh</a></td>
5178 <td>calculates the hyperbolic cosine of a number</td>
5179 </tr>
5180
5181 <tr>
5182 <td><a href="#crc32">crc32</a></td>
5183 <td>calculates a 32-bit CRC for a data buffer</td>
5184 </tr>
5185
5186 <tr>
5187 <td><a href="#crit-chi2">crit-chi2</a></td>
5188 <td>calculates the Chi&sup2; for a given probability</td>
5189 </tr>
5190
5191 <tr>
5192 <td><a href="#crit-z">crit-z</a></td>
5193 <td>calculates the normal distributed Z for a given probability</td>
5194 </tr>
5195 <tr>
5196 <td><a href="#dec">dec</a></td>
5197
5198 <td>decrements a number</td>
5199 </tr>
5200
5201 <tr>
5202 <td><a href="#div">div</a></td>
5203 <td>divides floating point or integer numbers</td>
5204 </tr>
5205
5206 <tr>
5207 <td><a href="#erf">erf</a></td>
5208 <td>calculates the error function of a number</td>
5209 </tr>
5210
5211 <tr>
5212 <td><a href="#exp">exp</a></td>
5213 <td>calculates the exponential <em>e</em> of a number</td>
5214 </tr>
5215
5216 <tr>
5217 <td><a href="#factor">factor</a></td>
5218 <td>factors a number into primes</td>
5219 </tr>
5220
5221
5222 <tr>
5223 <td><a href="#fft">fft</a></td>
5224 <td>performs a fast Fourier transform (FFT)</td>
5225 </tr>
5226
5227 <tr>
5228 <td><a href="#floor">floor</a></td>
5229 <td>rounds down to the next integer</td>
5230 </tr>
5231
5232 <tr>
5233
5234 <td><a href="#flt">flt</a></td>
5235 <td>converts a number to a 32-bit integer representing a float</td>
5236 </tr>
5237
5238 <tr>
5239 <td><a href="#gammai">gammai</a></td>
5240 <td>calculates the incomplete Gamma function</td>
5241 </tr>
5242
5243 <tr>
5244 <td><a href="#gammaln">gammaln</a></td>
5245 <td>calculates the log Gamma function</td>
5246 </tr>
5247
5248 <tr>
5249 <td><a href="#gcd">gcd</a></td>
5250 <td>calculates the greates common divisor of a group of integers</td>
5251 </tr>
5252
5253 <tr>
5254 <td><a href="#ifft">ifft</a></td>
5255 <td>performs an inverse fast Fourier transform (IFFT)</td>
5256 </tr>
5257
5258 <tr>
5259 <td><a href="#inc">inc</a></td>
5260 <td>increments a number</td>
5261 </tr>
5262
5263 <tr>
5264
5265 <td><a href="#log">log</a></td>
5266 <td>calculates the natural or other logarithm of a number</td>
5267 </tr>
5268
5269 <tr>
5270 <td><a href="#min">min</a></td>
5271 <td>finds the smallest value in a series of values</td>
5272 </tr>
5273
5274 <tr>
5275 <td><a href="#max">max</a></td>
5276 <td>finds the largest value in a series of values</td>
5277
5278 </tr>
5279
5280 <tr>
5281 <td><a href="#mod">mod</a></td>
5282 <td>calculates the modulo of two numbers</td>
5283 </tr>
5284
5285 <tr>
5286 <td><a href="#mul">mul</a></td>
5287 <td>multiplies floating point or integer numbers</td>
5288 </tr>
5289
5290 <tr>
5291 <td><a href="#round">round</a></td>
5292 <td>rounds a number</td>
5293 </tr>
5294
5295 <tr>
5296 <td><a href="#pow">pow</a></td>
5297 <td>calculates <em>x</em> to the power of <em>y</em></td>
5298 </tr>
5299
5300 <tr>
5301 <td><a href="#sequence">sequence</a></td>
5302 <td>generates a list sequence of numbers</td>
5303 </tr>
5304
5305 <tr>
5306 <td><a href="#series">series</a></td>
5307
5308 <td>creates a geometric sequence of numbers</td>
5309 </tr>
5310
5311 <tr>
5312 <td><a href="#sgn">sgn</a></td>
5313 <td>calculates the signum function of a number</td>
5314 </tr>
5315
5316 <tr>
5317 <td><a href="#sin">sin</a></td>
5318 <td>calculates the sine of a number</td>
5319 </tr>
5320
5321 <tr>
5322 <td><a href="#sinh">sinh</a></td>
5323 <td>calculates the hyperbolic sine of a number</td>
5324 </tr>
5325
5326 <tr>
5327 <td><a href="#sqrt">sqrt</a></td>
5328 <td>calculates the square root of a number</td>
5329 </tr>
5330
5331 <tr>
5332 <td><a href="#sub">sub</a></td>
5333 <td>subtracts floating point or integer numbers</td>
5334 </tr>
5335
5336 <tr>
5337 <td><a href="#tanh">tanh</a></td>
5338 <td>calculates the hyperbolic tangent of a number</td>
5339 </tr>
5340
5341 <tr>
5342 <td><a href="#uuid">uuid</a>&nbsp;</td>
5343 <td>returns a UUID (Universal Unique IDentifier)</td>
5344 </tr>
5345
5346 </table>
5347 </blockquote>
5348
5349
5350 <a NAME="matrices"></a>
5351 <h3>Matrix functions</h3>
5352
5353 <blockquote>
5354 <table border="0" cellpadding="1" width="95%" align="center" summary="Matrix functions">
5355
5356 <tr>
5357 <td  WIDTH="16%"><a href="#det">det</a></td>
5358 <td  WIDTH="84%">return the determinant of a matrix</td>
5359 </tr>
5360
5361 <tr>
5362 <td><a href="#invert">invert</a></td>
5363 <td>return the inversion of a matrix</td>
5364 </tr>
5365
5366 <tr>
5367 <td><a href="#mat">mat</a></td>
5368 <td>perform scalar operations on matrices</td>
5369 </tr>
5370
5371 <tr>
5372 <td><a href="#multiply">multiply</a></td>
5373 <td>multiplies two matrices</td>
5374 </tr>
5375
5376 <tr>
5377 <td><a href="#transpose">transpose</a>&nbsp;</td>
5378 <td>returns the transposition of a matrix</td>
5379 </tr>
5380
5381 </table>
5382 </blockquote>
5383
5384 <a NAME="array-funcs"></a>
5385 <h3>Array functions</h3>
5386
5387 <blockquote>
5388 <table border="0" cellpadding="1" width="95%" align="center" summary="Array functions">
5389
5390 <tr>
5391 <td width="16%" ><a href="#append">append</a></td>
5392 <td width="84%">appends arrays</td>
5393 </tr>
5394
5395 <tr>
5396 <td><a href="#array">array</a></td>
5397 <td>creates and initializes an array with up to 16 dimensions</td>
5398 </tr>
5399
5400 <tr>
5401 <td><a href="#array-list">array-list</a></td>
5402 <td>converts an array into a list</td>
5403 </tr>
5404
5405 <tr>
5406 <td><a href="#arrayp">array?</a></td>
5407 <td>checks if expression is an array</td>
5408 </tr>
5409
5410 <tr>
5411 <td ><a href="#det">det</a></td>
5412 <td>returns the determinant of a matrix</td>
5413 </tr>
5414
5415 <tr>
5416 <td ><a href="#first">first</a></td>
5417 <td>returns the first row of an array</td>
5418 </tr>
5419
5420 <tr>
5421 <td ><a href="#invert">invert</a></td>
5422 <td>returns the inversion of a matrix</td>
5423 </tr>
5424
5425 <tr>
5426 <td ><a href="#last">last</a></td>
5427 <td>returns the last row of an array</td>
5428 </tr>
5429
5430 <tr>
5431 <td><a href="#mat">mat</a></td>
5432 <td>perform scalar operations on matrices</td>
5433 </tr>
5434
5435
5436 <tr>
5437 <td ><a href="#multiply">multiply</a></td>
5438 <td>multiplies two matrices</td>
5439 </tr>
5440
5441 <tr>
5442 <td ><a href="#nth">nth</a></td>
5443 <td>returns an element of and array</td>
5444 </tr>
5445
5446 <tr>
5447 <td ><a href="#nth-set">nth-set</a></td>
5448 <td>changes the element, returning the old; significantly faster than <tt>set-nth</tt></td>
5449 </tr>
5450
5451 <tr>
5452 <td ><a href="#rest">rest</a></td>
5453 <td>returns all but the first row of an array</td>
5454 </tr>
5455
5456 <tr>
5457 <td ><a href="#set-nth">set-nth</a></td>
5458 <td>changes the element and returns the changed array</td>
5459 </tr>
5460
5461 <tr>
5462 <td ><a href="#slice">slice</a></td>
5463 <td>returns a slice of an array</td>
5464 </tr>
5465
5466 <tr>
5467 <td ><a href="#transpose">transpose</a></td>
5468 <td>transposes a matrix</td>
5469 </tr>
5470 </table>
5471 </blockquote>
5472
5473 <a NAME="bit_operators"></a>
5474 <h3>Bit operators</h3>
5475
5476 <blockquote>
5477 <table border="0" cellpadding="1" width="95%" align="center" summary="bit operators">
5478
5479
5480 <tr>
5481 <td WIDTH="16%"><a href="#bit_shift">&lt;&lt;, &gt;&gt;</a>&nbsp;&nbsp;&nbsp;</td>
5482 <td WIDTH="84%">bit shift left, bit shift right</td>
5483 </tr>
5484
5485 <tr>
5486 <td><a href="#bit_and">&amp;</a></td>
5487 <td>bitwise and</td>
5488 </tr>
5489
5490 <tr>
5491 <td><a href="#bit_inclusive">|</a></td>
5492 <td>bitwise inclusive or</td>
5493
5494 </tr>
5495
5496 <tr>
5497 <td><a href="#bit_exclusive">^</a></td>
5498 <td>bitwise exclusive or</td>
5499 </tr>
5500
5501 <tr>
5502 <td><a href="#bit_not">~</a></td>
5503 <td>bitwise not</td>
5504 </tr>
5505 </table>
5506 </blockquote>
5507
5508 <a NAME="predicates"></a>
5509 <h3>Predicates</h3>
5510
5511 <blockquote>
5512 <table border="0" cellpadding="1" width="95%" align="center" summary="Predicates">
5513
5514 <tr>
5515 <td width="16%"><a href="#atomp">atom?</a></td>
5516 <td width="84%">checks if an expression is an atom</td>
5517 </tr>
5518
5519 <tr>
5520 <td><a href="#arrayp">array?</a></td>
5521 <td>checks if an expression is an array</td>
5522 </tr>
5523
5524 <tr>
5525 <td><a href="#contextp">context?</a></td>
5526 <td>checks if an expression is a context</td>
5527 </tr>
5528
5529 <tr>
5530 <td><a href="#directoryp">directory?</a></td>
5531 <td>checks if a disk node is a directory</td>
5532 </tr>
5533
5534 <tr>
5535 <td><a href="#emptyp">empty?</a></td>
5536 <td>checks if a list or string is empty</td>
5537 </tr>
5538
5539 <tr>
5540 <td><a href="#filep">file?</a></td>
5541 <td>checks for the existence of a file</td>
5542 </tr>
5543
5544 <tr>
5545 <td><a href="#floatp">float?</a></td>
5546 <td>checks if an expression is a float</td>
5547 </tr>
5548
5549 <tr>
5550 <td><a href="#globalp">global?</a></td>
5551 <td>checks if a symbol is global</td>
5552 </tr>
5553
5554 <tr>
5555 <td><a href="#integerp">integer?</a></td>
5556 <td>checks if an expression is an integer</td>
5557 </tr>
5558
5559 <tr>
5560 <td><a href="#lambdap">lambda?</a></td>
5561 <td>checks if an expression is a lambda expression</td>
5562 </tr>
5563
5564 <tr>
5565 <td><a href="#legalp">legal?</a></td>
5566 <td>checks if a string contains a legal symbol</td>
5567 </tr>
5568
5569 <tr>
5570 <td><a href="#listp">list?</a></td>
5571 <td>checks if an expression is a list</td>
5572 </tr>
5573
5574 <tr>
5575 <td><a href="#macrop">macro?</a></td>
5576 <td>checks if an expression is a lambda-macro expression</td>
5577 </tr>
5578
5579 <tr>
5580 <td><a href="#NaNp">NaN?</a></td>
5581 <td>checks if a float is NaN (not a number)</td>
5582 </tr>
5583
5584 <tr>
5585 <td><a href="#nilp">nil?</a></td>
5586 <td>checks if an expression is <tt>nil</tt></td>
5587 </tr>
5588
5589 <tr>
5590 <td><a href="#nullp">null?</a></td>
5591 <td>checks if an expression is <tt>nil</tt>, <tt>""</tt>, <tt>()</tt> or <tt>0</tt>.</td>
5592 </tr>
5593
5594 <tr>
5595 <td><a href="#numberp">number?</a></td>
5596 <td>checks if an expression is a float or an integer</td>
5597 </tr>
5598
5599 <tr>
5600 <td><a href="#protectedp">protected?</a></td>
5601 <td>checks if a symbol is protected</td>
5602 </tr>
5603
5604 <tr>
5605 <td><a href="#primitivep">primitive?</a></td>
5606 <td>checks if an expression is a primitive</td>
5607 </tr>
5608
5609 <tr>
5610 <td><a href="#quotep">quote?</a></td>
5611 <td>checks if an expression is quoted</td>
5612 </tr>
5613
5614 <tr>
5615 <td><a href="#stringp">string?</a></td>
5616 <td>checks if an expression is a string</td>
5617 </tr>
5618
5619 <tr>
5620 <td><a href="#symbolp">symbol?</a></td>
5621 <td>checks if an expression is a symbol</td>
5622 </tr>
5623
5624 <tr>
5625 <td><a href="#truep">true?</a></td>
5626 <td>checks if an expression is not <tt>nil</tt></td>
5627 </tr>
5628
5629 <tr>
5630 <td><a href="#zerop">zero?</a></td>
5631 <td>checks if an expression is <tt>0</tt> or <tt>0.0</tt></td>
5632 </tr>
5633
5634 </table>
5635 </blockquote>
5636
5637
5638 <a NAME="timedate"></a>
5639 <h3>Time and date functions</h3>
5640
5641 <blockquote>
5642 <table border="0" cellpadding="1" width="95%" align="center" summary="Time and date functions">
5643
5644
5645 <tr>
5646 <td WIDTH="16%"><a href="#date">date</a></td>
5647 <td WIDTH="84%">converts a date-time value to a string</td>
5648 </tr>
5649
5650 <tr>
5651 <td><a href="#date-value">date-value</a></td>
5652 <td>calculates the time in seconds since January 1, 1970 for a date and time</td>
5653 </tr>
5654
5655 <tr>
5656 <td><a href="#parse-date">parse-date</a></td>
5657 <td>parse a data string</td>
5658 </tr>
5659
5660 <tr>
5661 <td><a href="#now">now</a></td>
5662 <td>returns a list of current date-time information</td>
5663 </tr>
5664
5665 <tr>
5666 <td><a href="#time">time</a></td>
5667 <td>calculates the time it takes to evaluate an expression in milliseconds</td>
5668 </tr>
5669
5670 <tr>
5671 <td><a href="#time-of-day">time-of-day</a></td>
5672 <td>calculates the number of milliseconds elapsed since the day started</td>
5673 </tr>
5674
5675 </table>
5676 </blockquote>
5677
5678 <a NAME="montecarlo"></a>
5679 <h3>Simulation and modeling math functions</h3>
5680
5681 <blockquote>
5682 <table border="0" cellpadding="1" width="95%" align="center" summary="Simulation and modelling math functions">
5683
5684
5685 <tr>
5686 <td width="16%"><a href="#amb">amb</a></td>
5687 <td width="84%">randomly picks an argument and evaluates it</td>
5688 </tr>
5689
5690 <tr>
5691 <td width="16%"><a href="#bayes-query">bayes-query</a></td>
5692 <td width="84%">calculates Bayesian probabilities for a data set</td>
5693 </tr>
5694
5695 <tr>
5696 <td width="16%"><a href="#bayes-train">bayes-train</a></td>
5697 <td width="84%">counts items in lists for Bayesian or frequency analysis</td>
5698 </tr>
5699
5700 <tr>
5701 <td><a href="#normal">normal</a></td>
5702 <td>makes a list of normal distributed floating point numbers</td>
5703 </tr>
5704
5705 <tr>
5706 <td><a href="#prob-chi2">prob-chi2</a></td>
5707
5708 <td>calculates the cumulated probability of Chi&sup2;</td>
5709 </tr>
5710
5711 <tr>
5712 <td><a href="#prob-z">prob-z</a></td>
5713 <td>calculates the cumulated probability of a Z-value</td>
5714 </tr>
5715
5716 <tr>
5717 <td><a href="#rand">rand</a></td>
5718 <td>generates random numbers in a range</td>
5719 </tr>
5720
5721 <tr>
5722 <td><a href="#random">random</a></td>
5723 <td>generates a list of evenly distributed floats</td>
5724 </tr>
5725
5726 <tr>
5727 <td><a href="#randomize">randomize</a></td>
5728 <td>shuffles all of the elements in a list</td>
5729 </tr>
5730
5731 <tr>
5732 <td><a href="#seed">seed</a></td>
5733
5734 <td>seeds the internal random number generator</td>
5735 </tr>
5736
5737 </table>
5738 </blockquote>
5739
5740 <a NAME="pattern"></a>
5741 <h3>Pattern matching</h3>
5742
5743 <blockquote>
5744 <table border="0" cellpadding="1" width="95%" align="center" summary="Time and date functions">
5745
5746 <tr>
5747 <td><a href="#ends-with">ends-with</a></td>
5748 <td>Test if a list or string ends with a pattern</td>
5749 </tr>
5750
5751 <tr>
5752 <td WIDTH="16%"><a href="#find">find</a></td>
5753 <td WIDTH="84%">Search for a pattern in a list or string</td>
5754 </tr>
5755
5756 <tr>
5757 <td><a href="#find-all">find-all</a></td>
5758 <td>Find all ocurrences of a pattern in a string</td>
5759 </tr>
5760
5761 <tr>
5762 <td><a href="#match">match</a></td>
5763 <td>Match list patterns</td>
5764 </tr>
5765
5766 <tr>
5767 <td><a href="#parse">parse</a></td>
5768 <td>Break a string along around patterns</td>
5769 </tr>
5770
5771 <tr>
5772 <td><a href="#regex">regex</a></td>
5773 <td>Find patterns in a string</td>
5774 </tr>
5775
5776 <tr>
5777 <td><a href="#replace">replace</a></td>
5778 <td>Replace patterns in a string</td>
5779 </tr>
5780
5781 <tr>
5782 <td><a href="#search">search</a></td>
5783 <td>Search for a pattern in a file</td>
5784 </tr>
5785
5786 <tr>
5787 <td><a href="#starts-with">starts-with</a></td>
5788 <td>Test if a list or string starts with a pattern</td>
5789 </tr>
5790
5791 <tr>
5792 <td><a href="#unify">unify</a></td>
5793 <td>Logical unification of patterns</td>
5794 </tr>
5795
5796 </table>
5797 </blockquote>
5798
5799
5800 <a NAME="financial"></a>
5801 <h3>Financial math functions</h3>
5802
5803 <blockquote>
5804 <table border="0" cellpadding="1" width="95%" align="center" summary="Financial math functions">
5805
5806 <tr>
5807 <td WIDTH="16%"><a href="#fv">fv</a></td>
5808 <td WIDTH="84%">returns the future value of an investment</td>
5809 </tr>
5810
5811 <tr>
5812 <td><a href="#irr">irr</a></td>
5813 <td>calculates the internal rate of return</td>
5814 </tr>
5815
5816 <tr>
5817 <td><a href="#nper">nper</a></td>
5818 <td>calculates the number of periods for an investment</td>
5819 </tr>
5820
5821 <tr>
5822 <td><a href="#npv">npv</a></td>
5823 <td>calculates the net present value of an investment</td>
5824 </tr>
5825
5826 <tr>
5827 <td><a href="#pv">pv</a></td>
5828
5829 <td>calculates the present value of an investment</td>
5830 </tr>
5831
5832 <tr>
5833 <td><a href="#pmt">pmt</a></td>
5834 <td>calculates the payment for a loan</td>
5835 </tr>
5836
5837 </table>
5838 </blockquote>
5839
5840
5841 <a NAME="input_output"></a>
5842 <h3>Input/output and file operations</h3>
5843
5844 <blockquote>
5845 <table border="0" cellpadding="1" width="95%" align="center" summary="Input/output and file operations">
5846
5847
5848 <tr>
5849 <td WIDTH="16%"><a href="#append-file">append-file</a></td>
5850 <td WIDTH="84%">appends data to a file</td>
5851 </tr>
5852
5853 <tr>
5854 <td><a href="#close">close</a></td>
5855 <td>closes a file</td>
5856 </tr>
5857
5858 <tr>
5859 <td><a href="#command-line">command-line</a>&nbsp;&nbsp;&nbsp;</td>
5860 <td>enables or disables interactive command line</td>
5861
5862 </tr>
5863
5864 <tr>
5865 <td><a href="#current-line">current-line</a></td>
5866 <td>retrieves contents of last read-line buffer</td>
5867 </tr>
5868
5869 <tr>
5870 <td><a href="#device">device</a></td>
5871 <td>sets or inquires about current print device</td>
5872 </tr>
5873
5874 <tr>
5875
5876 <td><a href="#exec">exec</a></td>
5877 <td>launches another program, then reads from or writes to it</td>
5878 </tr>
5879
5880 <tr>
5881 <td><a href="#load">load</a></td>
5882 <td>loads and evaluates a file of LISP code</td>
5883 </tr>
5884
5885 <tr>
5886 <td><a href="#open">open</a></td>
5887 <td>opens a file for reading or writing</td>
5888
5889 </tr>
5890
5891 <tr>
5892 <td><a href="#peek">peek</a></td>
5893 <td>checks file descriptor for number of bytes ready for reading</td>
5894 </tr>
5895
5896 <tr>
5897 <td><a href="#print">print</a></td>
5898 <td>prints to the console or a device</td>
5899 </tr>
5900
5901 <tr>
5902
5903 <td><a href="#println">println</a></td>
5904 <td>prints to the console or a device with a line feed</td>
5905 </tr>
5906
5907 <tr>
5908 <td><a href="#read-buffer">read-buffer</a></td>
5909 <td>reads binary data from a file</td>
5910 </tr>
5911
5912 <tr>
5913 <td><a href="#read-char">read-char</a></td>
5914 <td>reads an 8-bit character from a file</td>
5915
5916 </tr>
5917
5918 <tr>
5919 <td><a href="#read-file">read-file</a></td>
5920 <td>reads a whole file in one operation</td>
5921 </tr>
5922
5923 <tr>
5924 <td><a href="#read-key">read-key</a></td>
5925 <td>reads a keyboard key</td>
5926 </tr>
5927
5928 <tr>
5929 <td><a href="#read-line">read-line</a></td>
5930 <td>reads a line from the console or file</td>
5931 </tr>
5932
5933 <tr>
5934 <td><a href="#save">save</a></td>
5935 <td>saves a workspace, context, or symbol to a file</td>
5936 </tr>
5937
5938 <tr>
5939 <td><a href="#search">search</a></td>
5940 <td>searches a file for a string</td>
5941
5942 </tr>
5943
5944 <tr>
5945 <td><a href="#seek">seek</a></td>
5946 <td>sets or reads a file position</td>
5947 </tr>
5948
5949 <tr>
5950 <td><a href="#write-buffer">write-buffer</a></td>
5951 <td>writes binary data to a file or string</td>
5952 </tr>
5953
5954 <tr>
5955
5956 <td><a href="#write-char">write-char</a></td>
5957 <td>writes a character to a file</td>
5958 </tr>
5959
5960 <tr>
5961 <td><a href="#write-file">write-file</a></td>
5962 <td>writes a file in one operation</td>
5963 </tr>
5964
5965 <tr>
5966 <td><a href="#write-line">write-line</a></td>
5967 <td>writes a line to the console or a file</td>
5968 </tr>
5969
5970 </table>
5971 </blockquote>
5972
5973
5974 <a NAME="process_threads"></a>
5975 <h3>Processes, pipes and threads</h3>
5976
5977 <blockquote>
5978 <table border="0" cellpadding="1" width="95%" align="center" summary="Processes, pipes and threads">
5979
5980 <tr>
5981 <td WIDTH="16%"><a href="#shell">!</a></td>
5982 <td WIDTH="84%">shells out to the operating system</td>
5983 </tr>
5984
5985 <tr>
5986 <td><a href="#destroy">destroy</a></td>
5987 <td>Destroys a process created with with <tt>fork</tt> or <tt>process</tt></td>
5988 </tr>
5989
5990 <tr>
5991 <td><a href="#exec">exec</a></td>
5992 <td>runs a process, then reads from or writes to it</td>
5993 </tr>
5994
5995 <tr>
5996 <td><a href="#fork">fork</a></td>
5997 <td>launches a newLISP child process thread</td>
5998 </tr>
5999
6000 <tr>
6001 <td><a href="#pipe">pipe</a></td>
6002
6003 <td>creates a pipe for interprocess communication</td>
6004 </tr>
6005
6006 <tr>
6007 <td><a href="#process">process</a></td>
6008 <td>launches a child process, remapping standard I/O and standard error</td>
6009 </tr>
6010
6011 <tr>
6012 <td><a href="#semaphore">semaphore</a></td>
6013 <td>creates and controls semaphores</td>
6014 </tr>
6015
6016 <tr>
6017 <td><a href="#share">share</a></td>
6018 <td>shares memory with other processes and threads</td>
6019 </tr>
6020
6021 <tr>
6022 <td><a href="#wait-pid">wait-pid</a></td>
6023 <td>waits for a child process to end</td>
6024 </tr>
6025
6026 </table>
6027 </blockquote>
6028
6029
6030 <a NAME="directory_management"></a>
6031 <h3>File and directory management</h3>
6032
6033 <blockquote>
6034 <table border="0" cellpadding="1" width="95%" align="center" summary="File and directory management">
6035
6036 <tr>
6037 <td WIDTH="16%"><a href="#change-dir">change-dir</a>&nbsp;</td>
6038 <td WIDTH="84%">changes to a different drive and directory</td>
6039 </tr>
6040
6041 <tr>
6042 <td><a href="#copy-file">copy-file</a></td>
6043 <td>copies a file</td>
6044 </tr>
6045
6046 <tr>
6047 <td><a href="#delete-file">delete-file</a></td>
6048 <td>deletes a file</td>
6049 </tr>
6050
6051 <tr>
6052 <td><a href="#directory">directory</a></td>
6053 <td>returns a list of directory entries</td>
6054 </tr>
6055
6056 <tr>
6057 <td><a href="#file-info">file-info</a></td>
6058 <td>gets file size, date, time, and attributes</td>
6059 </tr>
6060
6061 <tr>
6062 <td><a href="#make-dir">make-dir</a></td>
6063 <td>makes a new directory</td>
6064 </tr>
6065
6066 <tr>
6067 <td><a href="#real-path">real-path</a></td>
6068 <td>returns the full path of the relative file path</td>
6069 </tr>
6070
6071 <tr>
6072 <td><a href="#remove-dir">remove-dir</a></td>
6073 <td>removes an empty directory</td>
6074 </tr>
6075
6076 <tr>
6077 <td><a href="#rename-file">rename-file</a></td>
6078 <td>renames a file or directory</td>
6079 </tr>
6080
6081 </table>
6082 </blockquote>
6083
6084 <a NAME="http_api"></a>
6085 <h3>HTTP networking API</h3>
6086
6087 <blockquote>
6088 <table border="0" cellpadding="1" width="95%" align="center" summary="HTTP networking API">
6089
6090
6091 <tr>
6092 <td width="16%"><a href="#base64-enc">base64-enc</a></td>
6093 <td width="84%">encodes a string into BASE64 format</td>
6094 </tr>
6095
6096 <tr>
6097 <td><a href="#base64-dec">base64-dec</a></td>
6098
6099 <td>decodes a string from BASE64 format</td>
6100 </tr>
6101
6102 <tr>
6103 <td><a href="#delete-url">delete-url</a></td>
6104 <td>deletes a file or page from the web</td>
6105 </tr>
6106
6107 <tr>
6108 <td><a href="#get-url">get-url</a></td>
6109 <td>reads a file or page from the web</td>
6110 </tr>
6111
6112 <tr>
6113 <td><a href="#post-url">post-url</a></td>
6114 <td>posts info to a URL address</td>
6115 </tr>
6116
6117 <tr>
6118 <td><a href="#put-url">put-url</a></td>
6119 <td>uploads a page to a URL address</td>
6120 </tr>
6121
6122 <tr>
6123 <td><a href="#xml-error">xml-error</a></td>
6124 <td>returns last XML parse error</td>
6125 </tr>
6126
6127 <tr>
6128 <td><a href="#xml-parse">xml-parse</a></td>
6129
6130 <td>parses an XML document</td>
6131 </tr>
6132
6133 <tr>
6134 <td><a href="#xml-type-tags">xml-type-tags</a>&nbsp;</td>
6135 <td>shows or modifies XML type tags</td>
6136 </tr>
6137
6138 </table>
6139 </blockquote>
6140
6141 <a NAME="socket_tcpip"></a>
6142 <h3>Socket TCP/IP and UDP network API</h3>
6143
6144 <blockquote>
6145 <table border="0" cellpadding="1" width="95%" align="center" summary="Socket TCP/IP and UDP network API">
6146
6147
6148 <tr>
6149 <td WIDTH="16%"><a href="#net-accept">net-accept</a></td>
6150 <td WIDTH="84%">accepts a new incoming connection</td>
6151 </tr>
6152
6153 <tr>
6154 <td><a href="#net-close">net-close</a></td>
6155 <td>closes a socket connection</td>
6156 </tr>
6157
6158 <tr>
6159 <td><a href="#net-connect">net-connect</a></td>
6160 <td>connects to a remote host</td>
6161 </tr>
6162
6163 <tr>
6164 <td><a href="#net-error">net-error</a></td>
6165 <td>returns the last error</td>
6166 </tr>
6167
6168 <tr>
6169 <td><a href="#net-eval">net-eval</a></td>
6170 <td>evaluates expressions on multiple remote newLISP servers</td>
6171 </tr>
6172
6173 <tr>
6174 <td><a href="#net-listen">net-listen</a></td>
6175 <td>listens for connections to a local socket</td>
6176 </tr>
6177
6178 <tr>
6179 <td><a href="#net-local">net-local</a></td>
6180 <td>returns the local IP and port number for a connection</td>
6181 </tr>
6182
6183 <tr>
6184 <td><a href="#net-lookup">net-lookup</a></td>
6185 <td>returns the name for an IP number</td>
6186 </tr>
6187
6188 <tr>
6189 <td><a href="#net-peer">net-peer</a></td>
6190 <td>returns the remote IP and port for a net connect</td>
6191 </tr>
6192
6193 <tr>
6194 <td><a href="#net-peek">net-peek</a></td>
6195
6196 <td>returns the number of characters ready to be read</td>
6197 </tr>
6198
6199 <tr>
6200 <td><a href="#net-ping">net-ping</a></td>
6201 <td>sends a ping packet (ICMP echo request) to one or more addresses</td>
6202 </tr>
6203
6204 <tr>
6205 <td><a href="#net-receive">net-receive</a></td>
6206 <td>reads data on a socket connection</td>
6207 </tr>
6208
6209 <tr>
6210 <td><a href="#net-receive-from">net-receive-from</a>&nbsp;</td>
6211 <td>reads a UDP on an open connection</td>
6212 </tr>
6213
6214 <tr>
6215 <td><a href="#net-receive-udp">net-receive-udp</a></td>
6216 <td>reads a UDP and closes the connection</td>
6217 </tr>
6218
6219 <tr>
6220 <td><a href="#net-select">net-select</a></td>
6221
6222 <td>checks a socket or list of sockets for status</td>
6223 </tr>
6224
6225 <tr>
6226 <td><a href="#net-send">net-send</a></td>
6227 <td>sends data on a socket connection</td>
6228 </tr>
6229
6230 <tr>
6231 <td><a href="#net-send-to">net-send-to</a></td>
6232 <td>sends a UDP on an open connection</td>
6233 </tr>
6234
6235 <tr>
6236 <td><a href="#net-send-udp">net-send-udp</a></td>
6237 <td>sends a UDP and closes the connection</td>
6238 </tr>
6239
6240 <tr>
6241 <td><a href="#net-service">net-service</a></td>
6242 <td>translates a service name into a port number</td>
6243 </tr>
6244
6245 <tr>
6246 <td><a href="#net-sessions">net-sessions</a></td>
6247
6248 <td>returns a list of currently open connections </td>
6249 </tr>
6250 </table>
6251 </blockquote>
6252
6253
6254 <a NAME="system_functions"></a>
6255 <h3>System functions</h3>
6256
6257 <blockquote>
6258 <table border="0" cellpadding="1" width="95%" align="center" summary="System functions">
6259
6260 <tr>
6261 <td width="16%"><a href="#systemsymbol">$</a></td>
6262 <td width="84%">accesses system variables $0 -&gt; $15</td>
6263 </tr>
6264
6265 <tr>
6266 <td><a href="#catch">catch</a></td>
6267 <td>evaluates an expression, catching errors and early returns</td>
6268 </tr>
6269
6270 <tr>
6271 <td><a href="#context">context</a></td>
6272 <td>creates or switches to a different namespace</td>
6273 </tr>
6274
6275 <tr>
6276 <td><a href="#debug">debug</a></td>
6277 <td>debugs a user-defined function</td>
6278 </tr>
6279
6280
6281 <tr>
6282 <td><a href="#default">default</a></td>
6283 <td>returns the default functor of a context</td>
6284 </tr>
6285
6286
6287 <tr>
6288 <td><a href="#delete">delete</a></td>
6289 <td>deletes symbols from the symbol table</td>
6290 </tr>
6291
6292 <tr>
6293 <td><a href="#env">env</a></td>
6294 <td>gets or sets the operating system's environment</td>
6295 </tr>
6296
6297 <tr>
6298 <td><a href="#error-event">error-event</a></td>
6299 <td>defines an error handler</td>
6300 </tr>
6301
6302 <tr>
6303 <td><a href="#error-number">error-number</a></td>
6304 <td>gets the last error number</td>
6305 </tr>
6306
6307 <tr>
6308 <td><a href="#error-text">error-text</a></td>
6309 <td>gets the error text for an error number</td>
6310 </tr>
6311
6312 <tr>
6313 <td><a href="#exit">exit</a></td>
6314 <td>exits newLISP, setting the exit value</td>
6315 </tr>
6316
6317 <tr>
6318 <td><a href="#global">global</a></td>
6319 <td>makes a symbol accessible outside MAIN</td>
6320 </tr>
6321
6322 <tr>
6323 <td><a href="#import">import</a></td>
6324 <td>imports a function from a shared library</td>
6325 </tr>
6326
6327 <tr>
6328 <td><a href="#main-args">main-args</a></td>
6329 <td>gets command-line arguments</td>
6330 </tr>
6331
6332 <tr>
6333 <td><a href="#new">new</a></td>
6334 <td>creates a copy of a context</td>
6335 </tr>
6336
6337 <tr>
6338 <td><a href="#ostype">ostype</a></td>
6339 <td>contains a string describing the OS platform</td>
6340 </tr>
6341
6342 <tr>
6343 <td><a href="#pretty-print">pretty-print</a></td>
6344 <td>changes the pretty-printing characteristics</td>
6345 </tr>
6346
6347
6348 <tr>
6349 <td><a href="#reset">reset</a></td>
6350 <td>goes to the top level</td>
6351 </tr>
6352
6353 <tr>
6354 <td><a href="#set-locale">set-locale</a></td>
6355 <td>switches to a different locale</td>
6356 </tr>
6357
6358 <tr>
6359 <td><a href="#signal">signal</a></td>
6360 <td>sets a signal handler</td>
6361 </tr>
6362
6363 <tr>
6364 <td><a href="#sleep">sleep</a></td>
6365 <td>suspends processing for specified milliseconds</td>
6366 </tr>
6367
6368 <tr>
6369 <td><a href="#symbols">symbols</a></td>
6370 <td>returns a list of all symbols in the system</td>
6371 </tr>
6372
6373 <tr>
6374 <td><a href="#sys-error">sys-error</a></td>
6375 <td>reports OS system error numbers</td>
6376 </tr>
6377
6378 <tr>
6379 <td><a href="#sys-info">sys-info</a></td>
6380 <td>gives information about system resources</td>
6381 </tr>
6382
6383
6384 <tr>
6385 <td><a href="#throw">throw</a></td>
6386 <td>causes a previous <a href="#catch">catch</a> to return</td>
6387 </tr>
6388
6389 <tr>
6390 <td><a href="#throw-error">throw-error</a></td>
6391 <td>throws a user-defined error</td>
6392 </tr>
6393
6394 <tr>
6395 <td><a href="#timer">timer</a></td>
6396 <td>starts a one-shot timer, firing an event</td>
6397 </tr>
6398
6399 <tr>
6400 <td><a href="#trace">trace</a></td>
6401 <td>sets or inquires about trace mode</td>
6402 </tr>
6403
6404 <tr>
6405 <td><a href="#trace-highlight">trace-highlight</a></td>
6406 <td>sets highlighting strings in trace mode</td>
6407 </tr>
6408
6409 </table>
6410 </blockquote>
6411
6412 <a NAME="importing_libraries"></a>
6413 <h3>Importing libraries</h3>
6414
6415 <blockquote>
6416 <table border="0" cellpadding="1" width="95%" align="center" summary="Importing libraries<">
6417
6418
6419 <tr>
6420 <td WIDTH="16%"><a href="#address">address</a></td>
6421 <td WIDTH="84%">gets the memory address of a number or string</td>
6422
6423 </tr>
6424
6425 <tr>
6426 <td><a href="#flt">flt</a></td>
6427 <td>converts a number to a 32-bit integer representing a float</td>
6428 </tr>
6429
6430 <tr>
6431 <td><a href="#float">float</a></td>
6432 <td>translates a string or integer into a floating point number</td>
6433 </tr>
6434
6435 <tr>
6436
6437 <td><a href="#get-char">get-char</a></td>
6438 <td>gets a character from a memory address</td>
6439 </tr>
6440
6441 <tr>
6442 <td><a href="#get-float">get-float</a></td>
6443 <td>gets a double float from a memory address</td>
6444 </tr>
6445
6446 <tr>
6447 <td><a href="#get-int">get-int</a>&nbsp;&nbsp;</td>
6448 <td>gets an integer from a memory address</td>
6449 </tr>
6450
6451 <tr>
6452 <td><a href="#get-long">get-int</a>&nbsp;&nbsp;</td>
6453 <td>gets an integer from a memory address</td>
6454 </tr>
6455
6456 <tr>
6457 <td><a href="#get-string">get-string</a></td>
6458 <td>gets a string from a memory address</td>
6459 </tr>
6460
6461 <tr>
6462 <td><a href="#import">import</a></td>
6463 <td>imports a function from a shared library</td>
6464 </tr>
6465
6466 <tr>
6467
6468 <td><a href="#int">int</a></td>
6469 <td>translates a string or float into an integer</td>
6470 </tr>
6471
6472 <tr>
6473 <td><a href="#pack">pack</a></td>
6474 <td>packs LISP expressions into a binary structure</td>
6475 </tr>
6476
6477 <tr>
6478 <td><a href="#unpack">unpack</a></td>
6479 <td>unpacks a binary structure into LISP expressions</td>
6480
6481 </tr>
6482 </table>
6483 </blockquote>
6484
6485
6486 <a NAME="internals"></a>
6487 <h3>newLISP internals API</h3>
6488
6489 <blockquote>
6490 <table border="0" cellpadding="1" width="95%" align="center" summary="newLISP internals API">
6491
6492
6493 <tr>
6494 <td WIDTH="16%"><a href="#cpymem">cpymem</a></td>
6495 <td WIDTH="84%">copies memory between addresses</td>
6496
6497 </tr>
6498
6499 <tr>
6500 <td><a href="#dump">dump</a></td>
6501 <td>shows memory address and contents of newLISP cells</td>
6502 </tr>
6503 </table>
6504 </blockquote>
6505
6506 <br /><br /><br />
6507
6508 <a NAME="functions_alphabetical"></a>
6509
6510 <center style="font-size: 150%">
6511 <span class="divider">(&nbsp;<font color="#7ba9d4">&part;</font>&nbsp;)</span>
6512 </center>
6513
6514
6515 <center><h1>Functions in alphabetical order</h1></center>
6516
6517 <a NAME="shell"></a>
6518 <h2><span class="function">!</span></h2>
6519 <b>syntax: (! <em>str-command</em>)</b>
6520
6521 <p>
6522         Executes the command in <em>str-command</em>
6523         by shelling out to the operating system
6524         and executing.
6525         This function returns a different value
6526         depending on the host operating system.
6527 </p>
6528
6529 <b>example:</b>
6530 <blockquote>
6531 <pre>
6532 (! "vi")
6533 (! "ls -ltr")
6534 </pre>
6535 </blockquote>
6536
6537 <p>
6538         Use the <a href="#exec">exec</a> function
6539         to execute a shell command
6540         and capture the standard output
6541         or to feed standard input.
6542         The <a href="#process">process</a> function
6543         may be used to launch a non-blocking child process
6544         and redirect std I/O and std error to pipes.
6545 </p>
6546
6547 <p>
6548         Note that <tt>!</tt> (exclamation mark) can be also be used as
6549         a command-line shell operator
6550         by omitting the parenthesis and space after the <tt>!</tt>:
6551 </p>
6552
6553 <b>example:</b>
6554 <blockquote>
6555 <pre>
6556 <b>&gt;</b> !ls -ltr    ; executed in the newLISP shell window
6557 </pre>
6558 </blockquote>
6559
6560 <p>
6561         Used in this way,
6562         the <tt>!</tt> operator
6563         is not a newLISP function at all,
6564         but rather a special feature of
6565         the newLISP command shell.
6566         The <tt>!</tt> must be entered
6567         as the first character
6568         on the command line.
6569 </p>
6570
6571 <br /><br />
6572
6573 <a NAME="systemsymbol"></a>
6574 <h2><span class="function">$</span></h2>
6575 <b>syntax: ($ <em>int-idx</em>)</b>
6576
6577 <p>
6578         The functions that use regular expressions
6579         (<a href="#directory">directory</a>,
6580 <a href="#find">find</a>, <a href="#parse">parse</a>, <a href="#regex">regex</a>, <a href="#search">search</a>, and <a href="#replace">replace</a>)
6581         all bind their results to
6582         the predefined system variables
6583         <tt>$0</tt>, <tt>$1</tt>, <tt>$2</tt>&ndash;<tt>$15</tt>
6584         after or during the function's execution.
6585         Both <a href="#nth-set">nth-set</a> and <a href="#set-nth">set-nth</a>
6586         store the replaced expression in <tt>$0</tt>.
6587         System variables can be treated
6588         the same as any other symbol.
6589         As an alternative,
6590         the contents of these variables may also be accessed
6591         by using <tt>($ 0)</tt>, <tt>($ 1)</tt>, <tt>($ 2)</tt>, etc.
6592         This method allows indexed access
6593         (i.e., <tt>($ i)</tt>, where <tt>i</tt> is an integer).
6594 </p>
6595
6596 <b>example:</b>
6597 <blockquote>
6598 <pre>
6599 (set 'str  "http://newlisp.org:80")
6600 (find "http://(.*):(.*)" str 0)  <span class=arw>&rarr;</span> 0
6601
6602 $0  <span class=arw>&rarr;</span> "http://newlisp.org:80"
6603 $1  <span class=arw>&rarr;</span> "newlisp.org"
6604 $2  <span class=arw>&rarr;</span> "80"
6605
6606 ($ 0)  <span class=arw>&rarr;</span> "http://newlisp.org:80"
6607 ($ 1)  <span class=arw>&rarr;</span> "newlisp.org"
6608 ($ 2)  <span class=arw>&rarr;</span> "80"
6609
6610 (set 'L '(a b c d e f g))
6611 (set-nth (L 2) 'x)  <span class=arw>&rarr;</span> (a b x d e f g)
6612
6613 $0     <span class=arw>&rarr;</span> c
6614 ($ 0)  <span class=arw>&rarr;</span> c
6615 </pre>
6616 </blockquote>
6617
6618 <p>
6619         For using captures within substitutions,
6620         the <tt>$</tt> system variables
6621         can be accessed from within the functions
6622         <a href="#nth-set">nth-set</a>, <a href="#set-nth">set-nth</a>, and <a href="#replace">replace</a>:
6623 </p>
6624
6625 <blockquote>
6626 <pre>
6627 (set 'lst '(1 2 3 4))
6628 (nth-set (lst 3) (* $0 3))  <span class=arw>&rarr;</span> 4
6629 lst                         <span class=arw>&rarr;</span> (1 2 3 12)
6630 </pre>
6631 </blockquote>
6632
6633 <br /><br />
6634
6635 <a NAME="arithmetic"></a>
6636 <h2><span class="function">+, -, *, / ,%</span></h2>
6637 <b>syntax: (+ <em>int-1</em> [<em>int-2</em> ... ])</b>
6638
6639 <p>
6640         Returns the sum of all numbers
6641         in <em>int-1</em> &mdash;.
6642 </p>
6643
6644 <b>syntax: (- <em>int-1</em> [<em>int-2</em> ... ])</b>
6645
6646 <p>
6647         Subtracts <em>int-2</em> from <em>int-1</em>,
6648         then the next <em>int-i</em>
6649         from the previous result.
6650         If only one argument is given,
6651         its sign is reversed.
6652 </p>
6653
6654 <b>syntax: (* <em>int-1</em> [<em>int-2</em> ... ])</b>
6655
6656 <p>
6657         The product is calculated for
6658         <em>int-1</em> to <em>int-i</em>.
6659 </p>
6660
6661 <b>syntax: (/ <em>int-1</em> [<em>int-2</em> ... ])</b>
6662
6663 <p>
6664         Each result is divided successively
6665         until the end of the list is reached.
6666         Division by zero causes an error.
6667 </p>
6668
6669 <b>syntax: (% <em>int-1</em> [<em>int-2</em> ... ])</b>
6670
6671 <p>
6672         Each result is divided successively
6673         by the next <em>int</em>,
6674         then the rest (modulo operation) is returned.
6675         Division by zero causes an error.
6676         For floating point numbers,
6677         use the <a href="#mod">mod</a> function.
6678 </p>
6679
6680 <b>example:</b>
6681 <blockquote>
6682 <pre>
6683 (+ 1 2 3 4 5)        <span class=arw>&rarr;</span> 15
6684 (+ 1 2 (- 5 2) 8)    <span class=arw>&rarr;</span> 14
6685 (- 10 3 2 1)         <span class=arw>&rarr;</span> 4
6686 (- (* 3 4) 6 1 2)    <span class=arw>&rarr;</span> 3
6687 (- 123)              <span class=arw>&rarr;</span> -123
6688 (map - '(10 20 30))  <span class=arw>&rarr;</span> (-10 -20 -30)
6689 (* 1 2 3)            <span class=arw>&rarr;</span> 6
6690 (* 10 (- 8 2))       <span class=arw>&rarr;</span> 60
6691 (/ 12 3)             <span class=arw>&rarr;</span> 4
6692 (/ 120 3 20 2)       <span class=arw>&rarr;</span> 1
6693 (% 10 3)             <span class=arw>&rarr;</span> 1
6694 (% -10 3)            <span class=arw>&rarr;</span> -1
6695 (+ 1.2 3.9)          <span class=arw>&rarr;</span> 4
6696 </pre>
6697 </blockquote>
6698
6699 <p>
6700         Floating point values in arguments to
6701         <tt>+</tt>, <tt>-</tt>, <tt>*</tt>, <tt>/</tt>, and <tt>%</tt>
6702         are truncated to their floor value.
6703 </p>
6704
6705 <p>
6706         Floating point values larger or smaller than
6707         the maximum (<tt>9,223,372,036,854,775,807</tt>)
6708         or minimum (<tt>-9,223,372,036,854,775,808</tt>) integer values
6709         are truncated to those values.
6710 </p>
6711
6712 <p>
6713         Calculations resulting in values
6714         larger than <tt>9,223,372,036,854,775,807</tt>
6715         or smaller than <tt>-9,223,372,036,854,775,808</tt>
6716         wrap around from positive to negative
6717         or negative to positive.
6718 </p>
6719
6720 <p>
6721         For floating point values that evaluate to <tt>NaN</tt> (Not a Number),
6722         both <tt>+INF</tt> and <tt>-INF</tt> are treated as <tt>0</tt> (zero).
6723 </p>
6724
6725 <br /><br />
6726
6727 <a NAME="logical"></a>
6728 <h2><span class="function">&lt;, &gt;, =, &lt;=, &gt;=, !=</span></h2>
6729
6730 <b>syntax: (&lt; <em>exp-1</em> [<em>exp-2 exp-3</em> ... ])</b><br />
6731
6732 <b>syntax: (&gt; <em>exp-1</em> [<em>exp-2 exp-3</em> ... ])</b><br />
6733 <b>syntax: (= <em>exp-1</em> [<em>exp-2 exp-3</em> ... ])</b><br />
6734 <b>syntax: (&lt;= <em>exp-1</em> [<em>exp-2 exp-3</em> ... ])</b><br />
6735
6736 <b>syntax: (&gt;= <em>exp-1</em> [<em>exp-2 exp-3</em> ... ])</b><br />
6737 <b>syntax: (!= <em>exp-1</em> [<em>exp-2 exp-3</em> ... ])</b>
6738
6739 <p>
6740         Expressions are evaluated and the results are compared successively.
6741         As long as the comparisons conform to the comparison operators,
6742         evaluation and comparison will continue
6743         until all arguments are tested
6744         and the result is <tt>true</tt>.
6745         As soon as one comparison fails,
6746         <tt>nil</tt> is returned.
6747 </p>
6748
6749 <p>If only one argument is supplied,
6750 all comparison operators assume <tt>0</tt> (zero)
6751 as a second argument.</p>
6752
6753
6754 <p>
6755         All types of expressions can be compared:
6756         atoms, numbers, symbols, and strings.
6757         List expressions can also be compared
6758         (list elements are compared recursively).
6759 </p>
6760
6761 <p>
6762         When comparing lists,
6763         elements at the beginning of the list
6764         are considered more significant than the elements following
6765         (similar to characters in a string).
6766         When comparing lists of different lengths but equal elements,
6767         the longer list is considered greater (see examples).
6768 </p>
6769
6770 <p>
6771         In mixed-type expressions,
6772         the types are compared from lowest to highest.
6773         Floats and integers are compared by first
6774         converting them to the needed type,
6775         then comparing them as numbers.
6776 </p>
6777
6778 <pre>
6779   Atoms: nil, true, integer or float, string, symbol, primitive
6780   Lists: quoted list/expression, list/expression, lambda, lambda-macro
6781 </pre>
6782 <br />
6783 <b>example:</b>
6784 <blockquote>
6785 <pre>
6786 (&lt; 3 5 8 9)                     <span class=arw>&rarr;</span> true
6787 (&gt; 4 2 3 6)                     <span class=arw>&rarr;</span> nil
6788 (&lt; "a" "c" "d")                 <span class=arw>&rarr;</span> true
6789 (&gt;= duba aba)                   <span class=arw>&rarr;</span> true
6790 (&lt; '(3 4) '(1 5))               <span class=arw>&rarr;</span> nil
6791 (&gt; '(1 2 3) '(1 2))             <span class=arw>&rarr;</span> true
6792 (= '(5 7 8) '(5 7 8))           <span class=arw>&rarr;</span> true
6793 (!= 1 4 3 7 3)                  <span class=arw>&rarr;</span> true
6794 (&lt; 1.2 6 "Hello" 'any '(1 2 3))           <span class=arw>&rarr;</span> true
6795 (&lt; nil true)                              <span class=arw>&rarr;</span> true
6796 (&lt; '(((a b))) '(((b c))))                 <span class=arw>&rarr;</span> true
6797 (&lt; '((a (b c)) '(a (b d)) '(a (b (d)))))  <span class=arw>&rarr;</span> true
6798
6799 ; with single argument copares against 0
6800
6801 (&gt; 1)    <span class=arw>&rarr;</span> true ; checks for positive
6802 (&gt; -1)   <span class=arw>&rarr;</span> nil ; checks for negative
6803 (= 123)  <span class=arw>&rarr;</span> nil ; checks for zero
6804
6805 (map &gt; '(1 3 -4 -3 1 2))   <span class=arw>&rarr;</span> (true true nil nil true true)
6806 </pre>
6807 </blockquote>
6808
6809
6810 <br /><br />
6811
6812 <a NAME="bit_shift"></a>
6813 <h2><span class="function">&lt;&lt;, &gt;&gt;</span></h2>
6814
6815 <b>syntax: (&lt;&lt; <em>int-1 int-2</em> [<em>int-3</em> ... ])</b><br />
6816
6817 <b>syntax: (&gt;&gt; <em>int-1 int-2</em> [<em>int-3</em> ... ])</b><br />
6818
6819 <b>syntax: (&lt;&lt; <em>int-1</em>)</b><br />
6820 <b>syntax: (&gt;&gt; <em>int-1</em>)</b>
6821
6822 <p>
6823         The number <em>int-1</em> is arithmetically shifted
6824         to the left or right by the number of bits given as <em>int-2</em>,
6825         then shifted by <em>int-3</em> and so on.
6826         For example, 64-bit integers may be shifted up to 63 positions.
6827         When shifting right,
6828         the most significant bit is duplicated
6829         (<em>arithmetic shift</em>):
6830 </p>
6831
6832 <blockquote>
6833 <pre>
6834 (&gt;&gt; 0x800000000000000 1)  <span class=arw>&rarr;</span> 0xC00000000000000   ; not 0x040000000000000!
6835 </pre>
6836 </blockquote>
6837 <br />
6838 <b>example:</b>
6839 <blockquote>
6840 <pre>
6841 (&lt;&lt; 1 3)      <span class=arw>&rarr;</span>  8
6842 (&lt;&lt; 1 2 1)    <span class=arw>&rarr;</span>  8
6843 (&gt;&gt; 1024 10)  <span class=arw>&rarr;</span>  1
6844 (&gt;&gt; 160 2 2)  <span class=arw>&rarr;</span> 10
6845
6846 (&lt;&lt; 3)        <span class=arw>&rarr;</span>  6
6847 (&gt;&gt; 8)        <span class=arw>&rarr;</span>  4
6848 </pre>
6849 </blockquote>
6850
6851 <p>When <em>int-1</em> is the only argument <tt>&lt;&lt;</tt>
6852 and <tt>&gt;&gt;</tt> shift by one bit.
6853 </p>
6854
6855 <br /><br />
6856
6857 <a NAME="bit_and"></a>
6858 <h2><span class="function">&amp;</span></h2>
6859 <b>syntax: (&amp; <em>int-1</em> <em>int-2</em> [<em>int-3</em> ... ])</b>
6860
6861 <p>
6862         A bitwise <tt>and</tt> operation is performed
6863         on the number in <em>int-1</em> with the number in <em>int-2</em>,
6864         then successively with <em>int-3</em>, etc.
6865 </p>
6866
6867 <b>example:</b>
6868 <blockquote>
6869 <pre>
6870 (&amp; 0xAABB 0x000F)  <span class=arw>&rarr;</span> 11  ; which is 0xB
6871 </pre>
6872 </blockquote>
6873 <br /><br />
6874
6875 <a NAME="bit_inclusive"></a>
6876 <h2><span class="function">|</span></h2>
6877 <b>syntax: (| <em>int-1</em> <em>int-2</em> [<em>int-3</em> ... ])</b>
6878
6879 <p>
6880         A bitwise <tt>or</tt> operation is performed
6881         on the number in <em>int-1</em> with the number in <em>int-2</em>,
6882         then successively with <em>int-3</em>, etc.
6883 </p>
6884
6885 <b>example:</b>
6886 <blockquote>
6887 <pre>
6888 (| 0x10 0x80 2 1)  <span class=arw>&rarr;</span> 147
6889 </pre>
6890
6891 </blockquote>
6892 <br /><br />
6893
6894 <a NAME="bit_exclusive"></a>
6895 <h2><span class="function">^</span></h2>
6896
6897 <b>syntax: (^ <em>int-1</em> <em> int-2</em> [<em>int-3</em> ... ])</b>
6898
6899 <p>
6900         A bitwise <tt>xor</tt> operation is performed
6901         on the number in <em>int-1</em> with the number in <em>int-2</em>,
6902         then successively with <em>int-3</em>, etc.
6903 </p>
6904
6905 <b>example:</b>
6906 <blockquote>
6907 <pre>
6908 (^ 0xAA 0x55)  <span class=arw>&rarr;</span> 255
6909 </pre>
6910 </blockquote>
6911
6912 <br /><br />
6913
6914 <a NAME="bit_not"></a>
6915 <h2><span class="function">~</span></h2>
6916 <b>syntax: (~ <em>int</em>)</b>
6917
6918 <p>
6919         A bitwise <tt>not</tt> operation is performed
6920         on the number in <em>int</em>,
6921         reversing all of the bits.
6922 </p>
6923
6924 <b>example:</b>
6925 <blockquote>
6926 <pre>
6927 (format "%X" (~ 0xFFFFFFAA))  <span class=arw>&rarr;</span> "55"
6928 (~ 0xFFFFFFFF)                <span class=arw>&rarr;</span> 0
6929 </pre>
6930 </blockquote>
6931 <br /><br />
6932
6933 <a NAME="colon"></a>
6934 <h2><span class="function">:</span></h2>
6935 <b>syntax: (: <em>sym-function</em> <em>list-object</em> [...])</b>
6936
6937 <p>When used as an operator, the colon <tt>:</tt> constructs a context symbol from the context name in the object list and the symbol following the colon. The object list in <em>list-object</em> can be followed by other parameters.</p>
6938
6939 <p>The <tt>:</tt> operator implements <em>polymorphism</em> of object methods, which are part of different object classes represented by contexts (namespaces). In newLISP, an object is represented by a list, the first element of which is the symbol (name) of its class context.
6940 The class context implements the functions applicable to the object. No space is required between the colon and the symbol following it.</p>
6941
6942 <b>example:</b>
6943 <blockquote>
6944 <pre>
6945 (define (Rectangle:area p)
6946         (mul (p 3) (p 4)))
6947
6948 (define (Circle:area c)
6949         (mul (pow (c 3) 2) (acos 0) 2))
6950
6951 (define (Rectangle:move p dx dy)
6952         (list rectangle (add (p 1) dx) (add (p 2) dy) (p 3) (p 4)))
6953
6954 (define (Circle:move p dx dy)
6955         (list circle (add (p 1) dx) (add (p 2) dy) (p 3)))
6956
6957 (set 'myrect '(Rectangle 5 5 10 20)) ; x y width height
6958 (set 'mycircle '(Circle 1 2 10)) ; x y radius
6959
6960 ;; explicit naming of the context methods
6961
6962 (Rectangle:area myrect)
6963 (Circle:area mycircle)
6964
6965 (set 'myrect (Rectangle:move myrect 2 3))
6966 (set 'mycircle ((Circle:move mycircle 4 5))
6967
6968 ;; using the : (colon) operator to polymorphically
6969 ;; resolve to a specific context
6970
6971 (:area myrect)     <span class=arw>&rarr;</span> 200
6972 (:area mycircle)   <span class=arw>&rarr;</span> 314.1592654
6973
6974 ;; change object attributes using a function and re-assigning
6975 ;; to the objects name
6976
6977 (set 'myrect (:move myrect 2 3))       <span class=arw>&rarr;</span> (Rectangle 7 8 10 20)
6978 (set 'mycircle (:move mycircle 4 5))   <span class=arw>&rarr;</span> (Circle 5 7 10)
6979 </pre>
6980 </blockquote>
6981
6982 <p>Using the colon <tt>:</tt> operator does not prohibit naming the method context explicitly when it is known.</p>
6983
6984 <p>In the first usage, the <tt>:</tt> is part of the syntax for qualifying a symbol with its context. The second usage of the <tt>:</tt> as an operator implements polymorphism by resolving the context at runtime.</p>
6985
6986 <p>Note that in the above example, the <tt>:move</tt> methods are implemented in a <em>functional</em> way, reassigning shapes with changed <tt>x</tt> and <tt>y</tt> coordinates to <tt>myrect</tt> and <tt>mycircle</tt>.
6987 </p>
6988
6989 <br /><br />
6990
6991 <a NAME="abs"></a>
6992 <h2><span class="function">abs</span></h2>
6993
6994 <b>syntax: (abs <em>num</em>)</b>
6995
6996 <p>
6997         Returns the absolute value of the number in <em>num</em>.
6998 </p>
6999
7000 <b>example:</b>
7001 <blockquote>
7002 <pre>
7003 (abs -3.5)  <span class=arw>&rarr;</span> 3.5
7004 </pre>
7005 </blockquote>
7006 <br /><br />
7007
7008 <a NAME="acos"></a>
7009 <h2><span class="function">acos</span></h2>
7010 <b>syntax: (acos <em>num</em>)</b>
7011
7012 <p>
7013         The arccosine function is calculated
7014         from the number in <em>num-radians</em>.
7015 </p>
7016
7017 <b>example:</b>
7018 <blockquote>
7019 <pre>
7020 (acos 1)  <span class=arw>&rarr;</span> 0
7021 (cos (acos 1)) <span class=arw>&rarr;</span> 1
7022 </pre>
7023 </blockquote>
7024 <br /><br />
7025
7026 <a NAME="acosh"></a>
7027 <h2><span class="function">acosh</span></h2>
7028 <b>syntax: (acosh <em>num-radians</em>)</b>
7029
7030 <p>Calculates the inverse hyperbolic cosine of <em>num-radians</em>,
7031 the value whose hyperbolic cosine is <em>num-radians</em>.
7032 If <em>num-radians</em> is less than 1,
7033 <tt>acosh</tt> returns <tt>NaN</tt>.</p>
7034
7035 <b>example:</b>
7036 <blockquote>
7037 <pre>
7038 (acosh 2)  <span class=arw>&rarr;</span> 1.316957897
7039 (cosh (acosh 2)) <span class=arw>&rarr;</span> 2
7040 (acosh 0.5) <span class=arw>&rarr;</span> NaN
7041 </pre>
7042 </blockquote>
7043
7044 <br /><br />
7045
7046
7047 <a NAME="add"></a>
7048 <h2><span class="function">add</span></h2>
7049 <b>syntax: (add <em>num-1</em> [<em>num-2</em> ... ])</b>
7050
7051 <p>
7052         All of the numbers in <em>num-1</em>, <em>num-2</em>, and on
7053         are summed.
7054         <tt>add</tt> accepts float or integer operands,
7055         but it always returns a floating point number.
7056         Any floating point calculation with <tt>NaN</tt>
7057         also returns <tt>NaN</tt>.
7058 </p>
7059
7060 <b>example:</b>
7061 <blockquote>
7062 <pre>
7063 (add 2 3.25 9)   <span class=arw>&rarr;</span> 14.25
7064 (add 1 2 3 4 5)  <span class=arw>&rarr;</span> 15
7065 </pre>
7066 </blockquote>
7067
7068 <br /><br />
7069
7070
7071 <a name="address"></a>
7072 <h2><span class="function">address</span></h2>
7073 <b>syntax: (address <em>int</em>)</b> <br />
7074
7075 <b>syntax: (address <em>float</em>)</b> <br />
7076 <b>syntax: (address <em>str</em>)</b>
7077
7078 <p>
7079         Returns the memory address of the integer in <em>int</em>,
7080         the double floating point number in <em>float</em>,
7081         or the string in <em>str</em>.
7082         This function is used for passing parameters to library functions
7083         that have been imported using the <a href="#import">import</a> function.
7084 </p>
7085
7086 <b>example:</b>
7087 <blockquote>
7088 <pre>
7089 (set 's "\001\002\003\004")
7090
7091 (get-char (+ (address s) 3))   <span class=arw>&rarr;</span> 4
7092
7093 (set 'x 12345)
7094
7095 ; on a big-endian CPU, i.e. PPC or SPARC
7096 (get-int (+ (address x) 4))    <span class=arw>&rarr;</span> 12345
7097
7098 ; on a little-endian CPU, i.e. Intel i386
7099 (get-int (address x))          <span class=arw>&rarr;</span> 12345
7100
7101 ; on both architectures (integers are 64 bit in newLISP)
7102 (set 'x 1234567890)
7103 (get-long (address x))         <span class=arw>&rarr;</span>  1234567890
7104
7105 </pre>
7106 </blockquote>
7107
7108 <p>
7109         When a string is passed,
7110         the address of the string is automatically used.
7111         As the example shows,
7112         <tt>address</tt> can be used to do pointer arithmetic
7113         on the string's address.
7114 </p>
7115
7116 <p><tt>address</tt> should only be used on persistent addresses from
7117 data objects referred to by a variable symbol, not from volatile intermediate
7118 expression objects.</p>
7119
7120 <p>
7121         See also the <a href="#get-char">get-char</a>, <a href="#get-int">get-int</a>,
7122         <a href="#get-long">get-long</a> and <a href="#get-float">get-float</a> functions.
7123 </p>
7124
7125 <br /> <br />
7126
7127 <a NAME="amb"></a>
7128 <h2><span class="function">amb</span></h2>
7129
7130 <b>syntax: (amb <em>exp-1 exp-2</em> [<em>exp-3</em>... ])</b>
7131
7132 <p>
7133         One of the expressions <em>exp-1 ... n</em> is selected at random,
7134         and the evaluation result is returned.
7135 </p>
7136
7137 <b>example:</b>
7138 <blockquote>
7139 <pre>
7140 (amb 'a 'b 'c 'd 'e)  <span class=arw>&rarr;</span> one of: a, b, c, d, or e at random
7141
7142 (dotimes (x 10) (print (amb 3 5 7)))  <span class=arw>&rarr;</span> 35777535755
7143 </pre>
7144 </blockquote>
7145
7146 <p>
7147         Internally, newLISP uses the same function as <a href="#rand">rand</a> to pick a random number.
7148         To generate random floating point numbers,
7149         use <a href="#random">random</a>,
7150         <a href="#randomize">randomize</a>, or <a href="#normal">normal</a>.
7151         To initialize the pseudo random number generating process
7152         at a specific starting point,
7153         use the <a href="#seed">seed</a> function.
7154 </p>
7155
7156 <br /> <br />
7157
7158 <a NAME="and"></a>
7159 <h2><span class="function">and</span></h2>
7160 <b>syntax: (and <em>exp-1 exp-2</em> [<em>exp-3</em>... ])</b>
7161
7162 <p>
7163         The expressions <em>exp-1</em>, <em>exp-2</em>, <em>etc.</em> are evaluated in order,
7164         returning the result of the last expression.
7165         If any of the expressions yield <tt>nil</tt> or the empty list <tt>()</tt>,
7166         evaluation is terminated and <tt>nil</tt> or the empty list <tt>()</tt> is returned.
7167 </p>
7168
7169 <b>example:</b>
7170 <blockquote>
7171 <pre>
7172 (set 'x 10)                       <span class=arw>&rarr;</span> 10
7173 (and (&lt; x 100) (&gt; x 2))           <span class=arw>&rarr;</span> true
7174 (and (&lt; x 100) (&gt; x 2) "passed")  <span class=arw>&rarr;</span> "passed"
7175 (and '())                         <span class=arw>&rarr;</span> ()
7176 (and true)                        <span class=arw>&rarr;</span> true
7177 (and)                             <span class=arw>&rarr;</span> nil
7178 </pre>
7179 </blockquote>
7180 <br /><br />
7181
7182 <a NAME="append"></a>
7183 <h2><span class="function">append</span></h2>
7184 <b>syntax: (append <em>list-1</em> [<em>list-2</em> ... ])</b><br />
7185 <b>syntax: (append <em>array-1</em> [<em>array-2</em> ... ])</b> <br />
7186 <b>syntax: (append <em>str-1</em> [<em>str-2</em> ... ])</b>
7187
7188 <p>
7189         In the first form,
7190         <tt>append</tt> works with lists,
7191         appending <em>list-1</em> through <em>list-n</em> to form a new list.
7192         The original lists are left unchanged.
7193 </p>
7194
7195 <b>example:</b>
7196 <blockquote>
7197 <pre>
7198 (append '(1 2 3) '(4 5 6) '(a b))  <span class=arw>&rarr;</span> (1 2 3 4 5 6 a b)
7199
7200 (set 'aList '("hello" "world"))    <span class=arw>&rarr;</span> ("hello" "world")
7201
7202 (append aList '("here" "I am"))    <span class=arw>&rarr;</span> ("hello" "world" "here" "I am")
7203 </pre>
7204 </blockquote>
7205
7206 <p>In the second form <tt>append</tt> works on arrays:</p>
7207
7208 <b>example:</b>
7209 <blockquote>
7210 <pre>
7211 (set 'A (array 3 2 (sequence 1 6)))
7212 <span class=arw>&rarr;</span> ((1 2) (3 4) (5 6))
7213 (set 'B (array 2 2 (sequence 7 10)))
7214 <span class=arw>&rarr;</span> ((7 8) (9 10))
7215
7216 (append A B)
7217 <span class=arw>&rarr;</span> ((1 2) (3 4) (5 6) (7 8) (9 10))
7218
7219 (append B B B)
7220 <span class=arw>&rarr;</span> ((7 8) (9 10) (7 8) (9 10) (7 8) (9 10))
7221
7222 </pre>
7223 </blockquote>
7224
7225 <p>
7226         In the third form,
7227         <tt>append</tt> works on strings.
7228         The strings in <em>str-n</em> are concatenated into
7229         a new string and returned.
7230 </p>
7231
7232 <b>example:</b>
7233 <blockquote>
7234 <pre>
7235 (set 'more " how are you")       <span class=arw>&rarr;</span> " how are you"
7236
7237 (append "Hello " "world," more)  <span class=arw>&rarr;</span> "Hello world, how are you"
7238 </pre>
7239 </blockquote>
7240
7241 <p>
7242         <tt>append</tt> is also suitable
7243         for processing binary strings
7244         containing zeroes.
7245 </p>
7246
7247 <p>
7248         Linkage characters or strings can be specified
7249         using the <a HREF="#join">join</a> function.
7250         Use the <a HREF="#string">string</a> function
7251         to convert arguments to strings and append in one step.
7252 </p>
7253
7254 <p>
7255         Use the functions <a href="#push">push</a> or
7256         <a href="#write-buffer">write-buffer</a>
7257         (with its special syntax)
7258         to append to an existing string <em>in place</em>.
7259 </p>
7260 <br /><br />
7261
7262 <a NAME="append-file"></a>
7263 <h2><span class="function">append-file</span></h2>
7264 <b>syntax: (append-file <em>str-filename</em> <em>str-buffer</em>)</b>
7265
7266 <p>
7267         Works similarly to <a href="#write-file">write-file</a>,
7268         but the content in <em>str-buffer</em> is appended
7269         if the file in <em>str-filename</em> exists.
7270         If the file does not exist, it is created
7271         (in this case, <tt>append-file</tt> works identically to <a href="#write-file">write-file</a>).
7272         This function returns the number of bytes written.
7273 </p>
7274
7275 <b>example:</b>
7276 <blockquote>
7277 <pre>
7278 (write-file "myfile.txt" "ABC")
7279 (append-file "myfile.txt" "DEF")
7280
7281 (read-file "myfile.txt")  <span class=arw>&rarr;</span> "ABCDEF"
7282 </pre>
7283 </blockquote>
7284
7285 <p><tt>append-file</tt> can take a <tt>http://</tt> or <tt>file://</tt> URL
7286 in <em>str-file-name</em>. In this case <tt>append-file</tt> works exactly like
7287 <a href="#put-url">put-url</a> with <tt>"Pragma: append\r\n"</tt>
7288 in the header option and can take the same additional parameters. The
7289 <tt>"Pragma: append\r\n"</tt> option is supplied automatically.
7290 </p>
7291
7292 <b>example:</b>
7293 <blockquote>
7294 <pre>
7295 (append-file "http://asite.com/message.txt" "More message text.")
7296 </pre>
7297 </blockquote>
7298
7299 <p>The file <tt>message.txt</tt> is appended at a remote
7300 location <tt>http://asite.com</tt> with the contents of
7301 <em>str-buffer</em>. If the file does not yet exist, it
7302 will be created. In this mode, <tt>append-file</tt> can also be used
7303 to transfer files to remote newLISP server nodes.
7304 </p>
7305
7306
7307
7308 <p>See also <a href="#read-file">read-file</a> and
7309 <a href="#write-file">write-file</a>.
7310 </p>
7311
7312
7313
7314 <br /><br />
7315
7316 <a NAME="apply"></a>
7317 <h2><span class="function">apply</span></h2>
7318 <b>syntax: (apply <em>func list</em> [<em>int-reduce</em>])</b>
7319
7320 <p>
7321         Applies the contents of <em>func</em>
7322         (primitive, user-defined function, or lambda expression)
7323         to the arguments in <em>list</em>.
7324 </p>
7325
7326 <b>example:</b>
7327 <blockquote>
7328 <pre>
7329 (apply + '(1 2 3 4))                   <span class=arw>&rarr;</span> 10
7330 (set 'aList '(3 4 5))                  <span class=arw>&rarr;</span> (3 4 5)
7331 (apply * aList)                        <span class=arw>&rarr;</span> 60
7332 (apply sqrt '(25))                     <span class=arw>&rarr;</span> 5
7333 (apply (lambda (x y) (* x y)) '(3 4))  <span class=arw>&rarr;</span> 12
7334 </pre>
7335 </blockquote>
7336
7337
7338 <p>
7339         The <em>int-reduce</em> parameter can optionally contain
7340         the number of arguments taken by the function in <em>func</em>.
7341         In this case,
7342         <em>func</em> will be repeatedly applied using the previous result
7343         as the first argument and taking the other arguments required
7344         successively from <em>list</em>
7345         (in left-associative order).
7346         For example, if <tt>op</tt> takes two arguments, then:
7347 </p>
7348
7349 <blockquote>
7350 <pre>
7351 (apply op '(1 2 3 4 5) 2)
7352
7353 ;; is equivalent to
7354
7355 (op (op (op (op 1 2) 3) 4) 5)
7356
7357 ;; find the greatest common divisor
7358 ;; of two or more integers
7359 ;; note that newLISP already has a gcd function
7360
7361 (define (gcd_ a b)
7362 (let (r (% b a))
7363     (if (= r 0) a (gcd_ r a))))
7364
7365 (define-macro (my-gcd)
7366     (apply gcd_ (args) 2))
7367
7368 (my-gcd 12 18 6)    <span class=arw>&rarr;</span> 6
7369 (my-gcd 12 18 6 4)  <span class=arw>&rarr;</span> 2
7370 </pre>
7371 </blockquote>
7372
7373 <p>
7374         The last example shows how <tt>apply</tt>'s <em>reduce</em> functionality
7375         can be used to convert a two-argument function
7376         into one that takes multiple arguments.
7377 </p>
7378
7379 <p>
7380         <tt>apply</tt> should only be used on functions and operators
7381         that evaluate all of their arguments,
7382         not on <em>special forms</em>
7383         like <a href="#setq">setq</a> or <a href="#case">case</a>,
7384         which evaluate only some of their arguments.
7385         Doing so will cause the function to fail.
7386 </p>
7387
7388 <br /><br />
7389
7390 <a NAME="args"></a>
7391 <h2><span class="function">args</span></h2>
7392 <b>syntax: (args)</b><br />
7393 <b>syntax: (args <em>int-idx-1</em> [<em>int-idx-2 ...</em>])</b>
7394
7395 <p>
7396         Accesses a list of all unbound arguments
7397         passed to the currently evaluating
7398         <a href="#define">define</a>, <a HREF="#define-macro">define-macro</a>
7399         lambda, or lambda-macro expression.
7400         Only the arguments of the current function or macro
7401         that remain after local variable binding has occurred
7402         are available.
7403         The <tt>args</tt> function is useful for defining functions or macros
7404         with a variable number of parameters.
7405 </p>
7406
7407 <p>
7408         <tt>args</tt> can be used to define hygienic macros
7409         that avoid the danger of variable capture.
7410         See <a href="#define-macro">define-macro</a>.
7411 </p>
7412
7413 <b>example:</b>
7414 <blockquote>
7415 <pre>
7416 (define-macro (print-line)
7417     (dolist (x (args))
7418         (print x "\n")))
7419
7420 (print-line "hello" "World")
7421 </pre>
7422 </blockquote>
7423 <p>
7424         This example prints a line feed after each argument.
7425         The macro mimics the effect of the built-in function
7426         <a HREF="#println">println</a>.
7427 </p>
7428
7429 <p>
7430         In the second syntax,
7431         <tt>args</tt> can take one or more indices (<em>int-idx-n</em>).
7432 </p>
7433
7434 <b>example:</b>
7435 <blockquote>
7436 <pre>
7437 (define-macro (foo)
7438   (print (args 2) (args 1) (args 0)))
7439
7440 (foo x y z)
7441 <b>zyx</b>
7442
7443 (define (bar)
7444         (args 0 2 -1))
7445
7446 (bar '(1 2 (3 4)))  <span class=arw>&rarr;</span> 4
7447 </pre>
7448 </blockquote>
7449
7450 <p>
7451         The function <tt>foo</tt>
7452         prints out the arguments in reverse order.
7453         The <tt>bar</tt> function
7454         shows <tt>args</tt> being used
7455         with multiple indices
7456         to access nested lists.
7457 </p>
7458
7459 <p>
7460         Remember that <tt>(args)</tt> only contains the arguments
7461         not already bound to local variables
7462         of the current function or macro:
7463 </p>
7464
7465 <b>example:</b>
7466 <blockquote>
7467 <pre>
7468 (define (foo a b) (args))
7469
7470 (foo 1 2)        <span class=arw>&rarr;</span> ()
7471
7472 (foo 1 2 3 4 5)  <span class=arw>&rarr;</span> (3 4 5)
7473 </pre>
7474 </blockquote>
7475
7476 <p>
7477         In the first example,
7478         an empty list is returned because
7479         the arguments are bound to the
7480         two local symbols, <tt>a</tt> and <tt>b</tt>.
7481         The second example demonstrates that,
7482         after the first two arguments are bound
7483         (as in the first example), three arguments remain
7484         and are then returned by <tt>args</tt>.
7485 </p>
7486
7487 <p>
7488         <tt>(args)</tt> can be used as an argument
7489         to a built-in or user-defined function call,
7490         but it should not be used as an argument to another macro,
7491         in which case <tt>(args)</tt> would not be evaluated
7492         and would therefore have the wrong
7493         contents in the new macro environment.
7494 </p>
7495
7496 <br /><br />
7497
7498
7499 <a NAME="array"></a>
7500 <h2><span class="function">array</span></h2>
7501
7502 <b>syntax: (array <em>int-n1</em> [<em>int-n2</em> ... ] [<em>list-init</em>])</b>
7503
7504 <p>
7505         Creates an array with <em>int-n1</em> elements,
7506         optionally initializing it with the contents of <em>list-init</em>.
7507         Up to sixteen dimensions may be specified for multidimensional arrays.
7508 </p>
7509
7510 <p>
7511         Internally,
7512         newLISP builds multidimensional arrays
7513         by using arrays as the elements of an array.
7514         newLISP arrays should be used
7515         whenever random indexing into a large list
7516         becomes too slow.
7517         Only a subset of the list functions
7518         may be used on arrays.
7519         For a more detailed discussion,
7520         see the chapter on <a href="#arrays">arrays</a>.
7521 </p>
7522
7523 <b>example:</b>
7524 <blockquote>
7525 <pre>
7526 (array 5)                  <span class=arw>&rarr;</span> (nil nil nil nil nil)
7527
7528 (array 5 (sequence 1  5))  <span class=arw>&rarr;</span> (1 2 3 4 5)
7529
7530 (array 10 '(1 2))          <span class=arw>&rarr;</span> (1 2 1 2 1 2 1 2 1 2)
7531 </pre>
7532 </blockquote>
7533
7534
7535 <P>
7536         Arrays can be initialized with objects of any type.
7537         If fewer initializers than elements are provided,
7538         the list is repeated until all elements of the array are initialized.
7539 </p>
7540
7541 <blockquote>
7542 <pre>
7543
7544 (set 'myarray (array 3 4 (sequence 1 12)))
7545 <span class=arw>&rarr;</span> ((1 2 3 4) (5 6 7 8) (9 10 11 12))
7546 </pre>
7547 </blockquote>
7548
7549 <P>
7550         Arrays are modified and accessed
7551         using the same list functions:
7552 </p>
7553
7554 <blockquote>
7555 <pre>
7556 (set-nth (myarray 2 3) 99)
7557 <span class=arw>&rarr;</span> ((1 2 3 4) (5 6 7 8) (9 10 11 99))
7558
7559 (nth-set (myarray 1 1) "hello")  <span class=arw>&rarr;</span> 6
7560
7561 myarray
7562 <span class=arw>&rarr;</span> ((1 2 3 4) (5 "hello" 7 8) (9 10 11 99))
7563
7564 (set-nth (myarray 1) (array 4 '(a b c d)))
7565 <span class=arw>&rarr;</span> ((1 2 3 4) (a b c d) (9 10 11 99))
7566
7567 (nth 1 myarray)     <span class=arw>&rarr;</span> (a b c d)  ; access a whole row
7568
7569 (nth (myarray 0 -1))  <span class=arw>&rarr;</span> 4
7570
7571 ;; use implicit indexing and slicing on arrays
7572
7573 (myarray 1)     <span class=arw>&rarr;</span> (a b c d)
7574
7575 (myarray 0 -1)  <span class=arw>&rarr;</span> 4
7576
7577 (2 myarray)     <span class=arw>&rarr;</span> (c d)
7578
7579 (-3 2 myarray)  <span class=arw>&rarr;</span> (b c)
7580 </pre>
7581 </blockquote>
7582
7583 <P>
7584         Care must be taken to use an array
7585         when replacing a whole row.
7586 </p>
7587
7588 <p>
7589         <a href="#array-list">array-list</a> can be used
7590         to convert arrays back into lists:
7591 </p>
7592
7593 <blockquote>
7594 <pre>
7595 (array-list myarray)  <span class=arw>&rarr;</span> ((1 2 3 4) (a b c d) (1 2 3 99))
7596 </pre>
7597 </blockquote>
7598
7599 <p>
7600         To convert a list back into an array,
7601         apply <a href="#flat">flat</a> to the list:
7602 </p>
7603
7604 <blockquote>
7605 <pre>
7606 (set 'aList '((1 2) (3 4)))             <span class=arw>&rarr;</span> ((1 2) (3 4))
7607
7608 (set 'aArray (array 2 2 (flat aList)))  <span class=arw>&rarr;</span> ((1 2) (3 4))
7609 </pre>
7610 </blockquote>
7611
7612 <p>The <a href="#arrayp">array?</a> function
7613 can be used to check if an expression is an array:
7614 </p>
7615
7616 <blockquote>
7617 <pre>
7618 (array? myarray)               <span class=arw>&rarr;</span> true
7619
7620 (array? (array-list myarray))  <span class=arw>&rarr;</span> nil
7621 </pre>
7622
7623 </blockquote>
7624
7625 <p>
7626         When serializing arrays using the  function
7627         <a href="#source">source</a> or <a href="#save">save</a>,
7628         the code includes the <tt>array</tt> statement
7629         necessary to create them.
7630         This way,
7631         variables containing arrays are correctly serialized
7632         when saving with <a href="#save">save</a> or creating source strings
7633         using <a href="#source">source</a>.
7634
7635
7636 <blockquote>
7637 <pre>
7638 (set 'myarray (array 3 4 (sequence 1 12)))
7639
7640 (save "array.lsp" 'myarray)
7641
7642 ;; contents of file arraylsp ;;
7643
7644 (set 'myarray (array 3 4 (flat '(
7645   (1 2 3 4)
7646   (5 6 7 8)
7647   (9 10 11 12)))))
7648 </pre>
7649 </blockquote>
7650
7651
7652 <br /><br />
7653
7654
7655 <a NAME="array-list"></a>
7656 <h2><span class="function">array-list</span></h2>
7657 <b>syntax: (array-list <em>array</em>)</b>
7658
7659 <P>
7660         Returns a list conversion from <em>array</em>,
7661         leaving the original array unchanged:
7662 </p>
7663
7664 <b>example:</b>
7665 <blockquote>
7666 <pre>
7667 (set 'myarray (array 3 4 (sequence 1 12)))
7668 <span class=arw>&rarr;</span> ((1 2 3 4) (5 6 7 8) (9 10 11 12))
7669
7670 (set 'mylist (array-list myarray))
7671 <span class=arw>&rarr;</span> ((1 2 3 4) (5 6 7 8) (9 10 11 12))
7672
7673 (list (array? myarray) (list? mylist))
7674 <span class=arw>&rarr;</span> (true true)
7675 </pre>
7676
7677 </blockquote>
7678
7679 <br /><br />
7680
7681
7682 <a NAME="arrayp"></a>
7683 <h2><span class="function">array?</span></h2>
7684 <b>syntax: (array? <em>expr</em>)</b>
7685
7686 <p>
7687         Checks if <em>expr</em> is an array:
7688 </p>
7689
7690 <b>example:</b>
7691 <blockquote>
7692 <pre>
7693 (set 'M (array 3 4 (sequence 1 4)))
7694 <span class=arw>&rarr;</span> ((1 2 3 4) (1 2 3 4) (1 2 3 4)))
7695
7696
7697 (array? M)               <span class=arw>&rarr;</span> true
7698
7699 (array? (array-list M))  <span class=arw>&rarr;</span> nil
7700 </pre>
7701 </blockquote>
7702
7703
7704 <br /><br />
7705
7706 <a NAME="asin"></a>
7707 <h2><span class="function">asin</span></h2>
7708 <b>syntax: (asin <em>num-radians</em>)</b>
7709
7710 <p>
7711         Calculates the arcsine function from the number in <em>num-radians</em>
7712         and returns the result.
7713 </p>
7714
7715 <b>example:</b>
7716 <blockquote>
7717 <pre>
7718 (asin 1)  <span class=arw>&rarr;</span> 1.570796327
7719 (sin (asin 1)) <span class=arw>&rarr;</span> 1
7720 </pre>
7721 </blockquote>
7722 <br /><br />
7723
7724 <a NAME="asinh"></a>
7725 <h2><span class="function">asinh</span></h2>
7726 <b>syntax: (asinh <em>num-radians</em>)</b>
7727
7728 <p>Calculates the inverse hyperbolic sine of <em>num-radians</em>,
7729 the value whose hyperbolic sine is <em>num-radians</em>.</p
7730
7731 <b>example:</b>
7732 <blockquote>
7733 <pre>
7734 (asinh 2)  <span class=arw>&rarr;</span> 1.443635475
7735 (sinh (asinh 2)) <span class=arw>&rarr;</span> 2
7736 </pre>
7737 </blockquote>
7738 <br /><br />
7739
7740 <a NAME="assoc"></a>
7741 <h2><span class="function">assoc</span></h2>
7742 <b>syntax: (assoc <em>exp-key</em> <em>list-alist</em>)</b><br/>
7743 <b>syntax: (assoc (<em>list-alist</em> <em>exp-key-1</em> [<em>exp-key-2</em> ...]))</b>
7744
7745
7746 <p>
7747 In the first syntax the value of <em>exp-key</em> is used
7748 to search <em>list-alist</em> for a <em>member-list</em>
7749 whose first element matches the key value.
7750 If found, the <em>member-list</em> is returned;
7751 otherwise, the result will be <tt>nil</tt>.
7752 </p>
7753
7754 <b>example:</b>
7755 <blockquote>
7756 <pre>
7757 (assoc 1 '((3 4) (1 2)))  <span class=arw>&rarr;</span> (1 2)
7758
7759 (set 'data '((apples 123) (bananas 123 45) (pears 7)))
7760
7761 (assoc 'bananas data)  <span class=arw>&rarr;</span> (bananas 123 45)
7762 (assoc 'oranges data)  <span class=arw>&rarr;</span> nil
7763 </pre>
7764 </blockquote>
7765
7766 <p>In the second syntax more then one key expressions can be specified
7767 to search in nested, multilevel association lists:</p>
7768
7769 <b>example:</b>
7770 <blockquote>
7771 <pre>
7772 (set 'persons '(
7773     (id001 (name "Anne") (address (country "USA") (city "New York")))
7774     (id002 (name "Jean") (address (country "France") (city "Paris")))
7775 ))
7776
7777 (assoc (persons 'id001 'address)) <span class=arw>&rarr;</span> (address (country "USA") (city "New York"))
7778 (assoc (persons 'id001 'address 'city)) <span class=arw>&rarr;</span> (city "New York")
7779 </pre>
7780 </blockquote>
7781
7782 <p>The list in <em>list-aList</em> can be a context which will be interpreted
7783 as its <em>default functor</em>. This way very big lists can be passed by reference
7784 for speedier access and less memory usage:</p>
7785
7786 <blockquote>
7787 <pre>
7788 (set 'persons:persons '(
7789     (id001 (name "Anne") (address (country "USA") (city "New York")))
7790     (id002 (name "Jean") (address (country "France") (city "Paris")))
7791 ))
7792
7793 (define (get-city db id)
7794         (last (assoc (db id 'address 'city)))
7795 )
7796
7797 (get-city persons 'id001) <span class=arw>&rarr;</span> "New York"
7798 </pre>
7799 </blockquote>
7800
7801 <p>
7802 For making replacements in association lists, use the
7803 <a HREF="#set-assoc">set-assoc</a> function.
7804 The <a href="#lookup">lookup</a> function is used to perform association lookup
7805 and element extraction in one step and on single level association lists.
7806 </p>
7807
7808 <br /><br />
7809
7810 <a NAME="assoc-set"></a>
7811 <h2><span class="function">assoc-set</span></h2>
7812
7813 <b>syntax: (assoc-set <em>exp-key</em> <em>list-alist</em> <em>exp-replacement</em>)</b><br/>
7814 <b>syntax: (assoc-set (<em>list-alist</em> <em>exp-key-1</em> [<em>exp-key-2</em> ...]) <em>exp-replacement</em>)</b>
7815
7816 <p>This function works like <a href="#set-assoc">set-assoc</a> but returns the replaced
7817 association instead of the entire changed association list.</p>
7818
7819
7820 <br /><br />
7821
7822 <a NAME="atan"></a>
7823 <h2><span class="function">atan</span></h2>
7824 <b>5,900,000
7825  (atan <em>num-radians</em>)</b>
7826
7827 <p>
7828         The arctangent of <em>num-radians</em>
7829         is calculated and returned.
7830 </p>
7831
7832 <b>example:</b>
7833 <blockquote>
7834 <pre>
7835 (atan 1)  <span class=arw>&rarr;</span> 0.7853981634
7836 (tan (atan 1)) <span class=arw>&rarr;</span> 1
7837 </pre>
7838 </blockquote>
7839 <br /><br />
7840
7841
7842 <a NAME="atan2"></a>
7843 <h2><span class="function">atan2</span></h2>
7844 <b>syntax: (atan2 <em>num-Y-radians</em> <em>num-X-radians</em>)</b>
7845
7846 <p>
7847         The <tt>atan2</tt> function computes
7848         the principal value of
7849         the arctangent of Y / X in radians.
7850         It uses the signs of both arguments
7851         to determine the quadrant of
7852         the return value.
7853         <tt>atan2</tt> is useful for converting
7854         Cartesian coordinates
7855         into polar coordinates.
7856 </p>
7857
7858 <b>example:</b>
7859 <blockquote>
7860 <pre>
7861 (atan2 1 1)                       <span class=arw>&rarr;</span> 0.7853981634
7862 (div (acos 0) (atan2 1 1))        <span class=arw>&rarr;</span> 2
7863 (atan2 0 -1)                      <span class=arw>&rarr;</span> 3.141592654
7864 (= (atan2 1 2) (atan (div 1 2)))  <span class=arw>&rarr;</span> true
7865 </pre>
7866 </blockquote>
7867
7868 <br /><br />
7869
7870 <a NAME="atanh"></a>
7871 <h2><span class="function">atanh</span></h2>
7872 <b>syntax: (atanh <em>num-radians</em>)</b>
7873
7874 <p>Calculates the inverse hyperbolic tangent of <em>num-radians</em>, the value whose hyperbolic tangent is <em>num-radians</em>. If the absolute value of <em>num-radians</em> is greater than 1, <tt>atanh</tt> returns <tt>NaN</tt>; if it is equal to 1, <tt>atanh</tt> returns infinity.</p>
7875
7876 <b>example:</b>
7877 <blockquote>
7878 <pre>
7879 (atanh 0.5) <span class=arw>&rarr;</span> 0.5493061443
7880 (tanh (atanh 0.5)) <span class=arw>&rarr;</span> 0.5
7881 (atanh 1.1) <span class=arw>&rarr;</span> NaN
7882 (atanh 1) <span class=arw>&rarr;</span> inf
7883 </pre>
7884 </blockquote>
7885
7886 <br /><br />
7887
7888 <a NAME="atomp"></a>
7889 <h2><span class="function">atom?</span></h2>
7890 <b>syntax: (atom? <em>exp</em>)</b>
7891
7892 <p>
7893         Returns <tt>true</tt> if the value of <em>exp</em> is an atom,
7894         otherwise <tt>nil</tt>.
7895         An expression is an atom, if it evaluates to nil,
7896         true, an integer, a float, a string, a symbol or a primitive.
7897         Lists, lambda or lambda-macro expressions,
7898         and quoted expressions are not atoms.
7899 </p>
7900
7901 <b>example:</b>
7902 <blockquote>
7903 <pre>
7904 (atom? '(1 2 3))      <span class=arw>&rarr;</span> nil
7905 (and (atom? 123)
7906      (atom? "hello")
7907      (atom? 'foo))    <span class=arw>&rarr;</span> true
7908 (atom? ''foo)         <span class=arw>&rarr;</span> nil
7909 </pre>
7910 </blockquote>
7911
7912 <br /><br />
7913
7914 <a NAME="base64-dec"></a>
7915 <h2><span class="function">base64-dec</span></h2>
7916 <b>syntax: (base64-dec <em>str</em>)</b>
7917
7918 <p>
7919         The BASE64 string in <em>str</em> is decoded.
7920         Note that <em>str</em> is not verified
7921         to be a valid BASE64 string.
7922         The decoded string is returned.
7923 </p>
7924
7925 <b>example:</b>
7926 <blockquote>
7927 <pre>
7928 (base64-dec "SGVsbG8gV29ybGQ=")  <span class=arw>&rarr;</span> "Hello World"
7929 </pre>
7930 </blockquote>
7931
7932 <p>
7933         For encoding,
7934         use the <a href="#base64-enc">base64-enc</a> function.
7935 </p>
7936
7937 <p>
7938         newLISP's BASE64 handling is derived from
7939         routines found in the UNIX <a href="http://curl.haxx.se/">curl</a> utility.
7940 </p>
7941
7942 <br /><br />
7943
7944
7945 <a NAME="base64-enc"></a>
7946 <h2><span class="function">base64-enc</span></h2>
7947 <b>syntax: (base64-enc <em>str</em>)</b>
7948
7949 <p>
7950         The string in <em>str</em> is encoded into BASE64 format.
7951         This format encodes groups of 3 * 8 = 24 input bits
7952         into 4 * 8 = 32 output bits,
7953         where each 8-bit output group
7954         represents 6 bits from the input string.
7955         The 6 bits are encoded into 64 possibilities
7956         from the letters A&ndash;Z and a&ndash;z;
7957         the numbers 0&ndash;9;
7958         and the characters + (plus sign) and / (slash).
7959         The = (equals sign) is used as a filler
7960         in unused 3- to 4-byte translations.
7961         This function is helpful for converting binary content
7962         into printable characters.
7963 </p>
7964
7965 <p>
7966         The encoded string is returned.
7967 </p>
7968
7969 <p>
7970         BASE64 encoding is used with many Internet protocols
7971         to encode binary data for inclusion in text-based messages
7972         (e.g., XML-RPC).
7973 </p>
7974
7975 <b>example:</b>
7976 <blockquote>
7977 <pre>
7978 (base64-enc "Hello World")  <span class=arw>&rarr;</span> "SGVsbG8gV29ybGQ="
7979 </pre>
7980 </blockquote>
7981
7982 <p>
7983         Note that <tt>base64-enc</tt> does not insert
7984         carriage-return/line-feed pairs in longer BASE64 sequences
7985         but instead returns a pure BASE64-encoded string.
7986 </p>
7987
7988
7989 <p>
7990         For decoding,
7991         use the <a href="#base64-dec">base64-dec</a> function.
7992 </p>
7993
7994 <p>
7995         newLISP's BASE64 handling is derived from routines
7996         found in the UNIX <a href="http://curl.haxx.se/">curl</a> utility.
7997 </p>
7998
7999 <br /><br />
8000
8001 <a NAME="bayes-query"></a>
8002 <h2><span class="function">bayes-query</span></h2>
8003 <b>syntax: (bayes-query <em>list-L</em> <em>context-D</em> [<em>bool-chain</em> [<em>bool-probs</em>]])</b>
8004
8005 <p>
8006         Takes a list of tokens (<em>list-L</em>)
8007         and a trained dictionary (<em>context-D</em>)
8008         and returns a list of the combined probabilities
8009         of the tokens in one category
8010         (<em>A</em> or <em>Mc</em>)
8011         versus a category (<em>B</em>)
8012         against all other categories (<em>Mi</em>).
8013         All tokens in <em>list-L</em>
8014         should occur in <em>context-D</em>.
8015         When using the default <em>R.A. Fisher Chi&sup2;</em> mode,
8016         nonexistent tokens will skew results
8017         toward equal probability in all categories.
8018 </p>
8019
8020 <p>
8021         Non-existing tokens will not have any influence
8022         on the result when using the true <em>Chain Bayesian</em> mode
8023         with <em>bool-chain</em> set to <tt>true</tt>.
8024         The optional last flag, <em>bool-probs</em>,
8025         indicates whether frequencies or probability values
8026         are used in the data set.
8027         The <a href="#bayes-train">bayes-train</a> function
8028         is typically used to generate
8029         a data set's frequencies.
8030 </p>
8031
8032 <p>
8033         Tokens can be strings or symbols.
8034         If strings are used,
8035         they are prepended with an underscore
8036         before being looked up in <em>context-D</em>.
8037         If <a href="#bayes-train">bayes-train</a> was used
8038         to generate <em>context-D</em>'s frequencies,
8039         the underscore was automatically prepended
8040         during the learning process.
8041 </p>
8042
8043 <p>
8044         Depending on the flag specified in <em>bool-probs</em>,
8045         <a href="#bayes-query">bayes-query</a> employs either the
8046         R. A. Fisher Chi&sup2; method of compounding probabilities
8047         or the Chain Bayesian method.
8048         By default, when no flag or <tt>nil</tt> is specified in <em>bool-probs</em>,
8049         the <em>Chi&sup2;</em> method of compounding probabilities is used.
8050         When specifying <tt>true</tt> in <em>bool-probs</em>,
8051         the Chain Bayesian method is used.
8052 </p>
8053
8054 <p>
8055         If the R.A. Fisher Chi&sup2; method is used,
8056         the total number of tokens
8057         in the different training set's categories
8058         should be equal or similar.
8059         Uneven frequencies in categories
8060         will skew the results.
8061 </p>
8062
8063 <p>
8064         For two categories <em>A</em> and <em>B</em>,
8065         <tt>bayes-query</tt> uses the following formula:
8066 </p>
8067
8068 <blockquote>
8069 <b><em>p(A|tkn) = p(tkn|A) * p(A) / p(tkn|A) * p(A) + p(tkn|B) * p(B)</em></b>
8070 </blockquote>
8071
8072 <p>
8073         For <em>N</em> categories,
8074         this formula is used:
8075 </p>
8076
8077 <blockquote>
8078 <b><em>p(Mc|tkn) = p(tkn|Mc) * p(Mc) / sum-i-N( p(tkn|Mi) * p(Mi) )</em></b>
8079 </blockquote>
8080
8081 <p>
8082         The probabilities (<em>p(Mi)</em> or <em>p(A)</em>, along with <em>p(B)</em>)
8083         represent the <em>Bayesian prior probabilities</em>.
8084         <em>p(Mx|tkn)</em> and <em>p(A|tkn)</em> are the
8085         <em>posterior Bayesian</em> probabilities of a category or model.
8086 </p>
8087
8088 <p>
8089         Priors are handled differently,
8090         depending on whether the R.A. Fisher Chi&sup2;
8091         or the Chain Bayesian method is used.
8092         While in Chain Bayesian mode,
8093         posteriors from one token calculation get the priors in the next calculation.
8094         In the default R.A. Fisher method,
8095         priors are not passed on via chaining,
8096         but probabilities are compounded using the Chi&sup2; method.
8097 </p>
8098
8099 <p>
8100         In Chain Bayes mode,
8101         tokens with zero frequency in one category
8102         will effectively put the probability of that category to 0 (zero).
8103         This also causes all posterior priors to be set to 0
8104         and the category to be completely suppressed in the result.
8105         Queries resulting in zero probabilities for all categories
8106         yield <em>NaN</em> values.
8107 </p>
8108
8109 <p>
8110         The default R.A. Fisher Chi&sup2; method
8111         is less sensitive about zero frequencies
8112         and still maintains a low probability for that token.
8113         This may be an important feature in natural language processing
8114         when using <em>Bayesian statistics</em>.
8115         Imagine that five different language <em>corpus</em> categories have been trained,
8116         but some words occurring in one category are not present in another.
8117         When the pure Chain Bayesian method is used,
8118         a sentence could never be classified into its correct category
8119         because the zero-count of just one word token could effectively exclude it
8120         from the category to which it belongs.
8121 </p>
8122
8123 <p>
8124         On the other hand,
8125         the Chain Bayesian method offers exact results
8126         for specific proportions in the data.
8127         When using Chain Bayesian mode for natural language data,
8128         all zero frequencies should be removed from the trained dictionary first.
8129 </p>
8130
8131 <p>
8132         The return value of <tt>bayes-query</tt>
8133         is a list of probability values,
8134         one for each category.
8135         Following are two examples:
8136         the first for the default R.A. Fisher mode,
8137         the second for a data set processed with the Chain Bayesian method.
8138 </p>
8139
8140 <br />
8141 <h3>R.A. Fisher Chi&sup2; method</h3>
8142
8143 <p>
8144         In the following example,
8145         the two data sets are books from Project Gutenberg.
8146         We assume that different authors
8147         use certain words with different frequencies
8148         and want to determine if a sentence is more likely to occur in one
8149         or the other author's writing.
8150         A similar method is frequently used to differentiate between spam
8151         and legitimate email.
8152 </p>
8153
8154 <blockquote>
8155 <pre>
8156 ;; from Project Gutenberg: http://www.gutenberg.org/catalog/
8157 ;; The Adventures of Sherlock Holmes - Sir Arthur Conan Doyle
8158
8159 (bayes-train (parse (lower-case (read-file "Doyle.txt"))
8160                     "[^a-z]+" 0) '() 'DoyleDowson)
8161
8162 ;; A Comedy of Masks - Ernest Dowson and Arthur Moore
8163
8164 (bayes-train '() (parse (lower-case (read-file "Dowson.txt"))
8165                     "[^a-z]+" 0) 'DoyleDowson)
8166
8167 (save "DoyleDowson.lsp" 'DoyleDowson)
8168 </pre>
8169 </blockquote>
8170
8171 <p>
8172         The two training sets are loaded, split into tokens,
8173         and processed by the <a href="#bayes-train">bayes-train</a> function.
8174         In the end, the <tt>DoyleDowson</tt> dictionary is saved to a file,
8175         which will be used later with the <tt>bayes-query</tt> function.
8176 </p>
8177
8178 <p>
8179         The following code illustrates how <tt>bayes-query</tt> is used
8180         to classify a sentence as <em>Doyle</em> or <em>Dowson</em>:
8181 </p>
8182
8183 <blockquote>
8184 <pre>
8185 (load "DoyleDowson.lsp")
8186 (bayes-query (parse "he was putting the last touches to a picture")
8187     'DoyleDowson)
8188 <span class=arw>&rarr;</span> (0.03801673331 0.9619832667)
8189
8190 (bayes-query (parse "immense faculties and extraordinary powers of observation")
8191     'DoyleDowson)
8192 <span class=arw>&rarr;</span> (0.9851075608 0.01489243923)
8193 </pre>
8194 </blockquote>
8195
8196 <p>
8197         The queries correctly identify the first sentence as a <em>Dowson</em> sentence,
8198         and the second one as a <em>Doyle</em> sentence.
8199 </p>
8200
8201 <br />
8202
8203 <h3>Chain Bayesian method</h3>
8204
8205 <p>
8206         The second example is frequently found
8207         in introductory literature on Bayesian statistics.
8208         It shows the Chain Bayesian method of
8209         using <tt>bayes-query</tt> on the data of a previously processed data set:
8210 </p>
8211
8212 <b>example:</b>
8213 <blockquote>
8214 <pre>
8215 (set 'Data:test-positive '(8 18))
8216 (set 'Data:test-negative '(2 72))
8217 (set 'Data:total '(10 90))
8218 </pre>
8219 </blockquote>
8220
8221 <p>
8222         A disease occurs in 10 percent of the population.
8223         A blood test developed to detect this disease
8224         produces a false positive rate of 20 percent in the healthy population
8225         and a false negative rate of 20 percent in the sick.
8226         What is the probability of a person carrying
8227         the disease after testing positive?</p>
8228
8229 <b>example:</b>
8230 <blockquote>
8231 <pre>
8232 (bayes-query '(test-positive) Data true)
8233 <span class=arw>&rarr;</span> (0.3076923077 0.6923076923)
8234
8235 (bayes-query '(test-positive test-positive) Data true)
8236 <span class=arw>&rarr;</span> (0.64 0.36)
8237
8238 (bayes-query '(test-positive test-positive test-positive) Data true)
8239 <span class=arw>&rarr;</span> (0.8767123288 0.1232876712)
8240 </pre>
8241 </blockquote>
8242
8243 <p>
8244         Note that the Bayesian formulas used
8245         assume statistical independence of events
8246         for the <tt>bayes-query</tt> to work correctly.
8247 </p>
8248
8249 <p>
8250         The example shows that a person must test positive several times
8251         before they can be confidently classified as sick.
8252 </p>
8253
8254 <p>
8255         Calculating the same example using the R.A. Fisher Chi&sup2; method
8256         will give less-distinguished results.
8257 </p>
8258
8259 <br>
8260 <h3>Specifying probabilities instead of counts</h3>
8261
8262 <p>
8263         Often, data is already available as probability values
8264         and would require additional work to reverse them into frequencies.
8265         In the last example, the data were originally defined as percentages.
8266         The additional optional <em>bool-probs</em> flag
8267         allows probabilities to be entered directly
8268         and should be used together with the Chain Bayesian mode
8269         for maximum performance:
8270 </p>
8271
8272 <b>example:</b>
8273 <blockquote>
8274 <pre>
8275 (set 'Data:test-positive '(0.8 0.2))
8276 (set 'Data:test-negative '(0.2 0.8))
8277 (set 'Data:total '(0.1 0.9))
8278
8279 (bayes-query '(test-positive) Data true true)
8280 <span class=arw>&rarr;</span> (0.3076923077 0.6923076923)
8281
8282 (bayes-query '(test-positive test-positive) Data true true)
8283 <span class=arw>&rarr;</span> (0.64 0.36)
8284
8285 (bayes-query '(test-positive test-positive test-positive) Data true true)
8286 <span class=arw>&rarr;</span> (0.8767123288 0.1232876712)
8287 </pre>
8288 </blockquote>
8289
8290 <p>
8291         As expected, the results are the same for probabilities
8292         as they are for frequencies.
8293 </p>
8294
8295 <br /><br />
8296
8297 <a NAME="bayes-train"></a>
8298 <h2><span class="function">bayes-train</span></h2>
8299 <b>syntax: (bayes-train <em>list-M1</em> [<em>list-M2 ... </em>] <em>sym-context-D</em>)</b>
8300
8301 <p>
8302         Takes one or more lists of tokens (<em>M1</em>, <em>M2&mdash;</em>)
8303         from a joint set of tokens.
8304         In newLISP, tokens can be symbols or strings
8305         (other data types are ignored).
8306         Tokens are placed in a common dictionary
8307         in <em>sym-context-D</em>,
8308         and the frequency is counted  for each token
8309         in each category <em>Mi</em>.
8310         If the context does not yet exist,
8311         it must be quoted.
8312 </p>
8313
8314 <p>
8315         The <em>M</em> categories represent data models
8316         for which sequences of tokens can be classified
8317         (see <a href="#bayes-query">bayes-query</a>).
8318         Each token in <em>D</em> is a content-addressable symbol
8319         containing a list of the frequencies
8320         for this token within each category.
8321         String tokens are prepended with an <tt>_</tt> (underscore)
8322         before being converted into symbols.
8323         A symbol named <tt>total</tt> is created
8324         containing the total of each category.
8325         The <tt>total</tt> symbol cannot be part
8326         of the symbols passed as an <em>Mi</em> category.
8327 </p>
8328
8329 <p>
8330         The function returns a list of token frequencies
8331         found in the different categories or models.
8332 </p>
8333
8334 <b>example:</b>
8335 <blockquote>
8336 <pre>
8337 (bayes-train '(A A B C C) '(A B B C C C) 'L)  <span class=arw>&rarr;</span> (5 6)
8338
8339 L:A      <span class=arw>&rarr;</span> (2 1)
8340 L:B      <span class=arw>&rarr;</span> (1 2)
8341 L:C      <span class=arw>&rarr;</span> (2 3)
8342 L:total  <span class=arw>&rarr;</span> (5 6)
8343
8344 (bayes-train '("one" "two" "two" "three")
8345              '("three" "one" "three")
8346              '("one" "two" "three") 'S)
8347 <span class=arw>&rarr;</span> (4 3 3)
8348
8349 S:_one    <span class=arw>&rarr;</span> (1 1 1)
8350 S:_two    <span class=arw>&rarr;</span> (2 0 1)
8351 S:_three  <span class=arw>&rarr;</span> (1 2 1)
8352 S:total   <span class=arw>&rarr;</span> (4 3 3)
8353 </pre>
8354 </blockquote>
8355
8356 <p>
8357         The first example shows training with two lists of symbols.
8358         The second example illustrates how an <tt>_</tt> is prepended
8359         when training with strings.
8360 </p>
8361
8362 <p>
8363         Note that these examples are just for demonstration purposes.
8364         In reality, training sets may contain thousands or millions of words,
8365         especially when training natural language models.
8366         But small data sets may be used when then the frequency of symbols
8367         just describe already-known proportions.
8368         In this case, it may be better to describe the model data set explicitly,
8369         without the <tt>bayes-train</tt> function:
8370 </p>
8371
8372 <blockquote>
8373 <pre>
8374 (set 'Data:tested-positive '(8 18))
8375 (set 'Data:tested-negative '(2 72))
8376 (set 'Data:total '(10 90))
8377 </pre>
8378 </blockquote>
8379
8380 <p>
8381         The last data are from a popular example used
8382         to describe the <a href="#bayes-query">bayes-query</a> function
8383         in introductory papers and books about <em>bayesian networks</em>.
8384 </p>
8385
8386 <p>
8387         Training can be done in different stages
8388         by using <tt>bayes-train</tt> on an existing trained context
8389         with the same number of categories.
8390         The new symbols will be added,
8391         then counts and totals will be correctly updated.
8392 </p>
8393
8394 <p>
8395         Training in multiple batches may be necessary
8396         on big text corpora or documents
8397         that must be tokenized first.
8398         These corpora can be tokenized in small portions,
8399         then fed into <tt>bayes-train</tt> in multiple stages.
8400         Categories can also be singularly trained
8401         by specifying an empty list for the absent corpus:
8402 </p>
8403
8404 <blockquote>
8405 <pre>
8406 (bayes-train shakespeare1 '() 'data)
8407 (bayes-train shakespeare2 '() 'data)
8408 (bayes-train '() hemingway1 'data)
8409 (bayes-train '() hemingway2 'data)
8410 (bayes-train shakepeare-rest hemingway-rest 'data)
8411 </pre>
8412 </blockquote>
8413
8414 <p>
8415         <tt>bayes-train</tt> will correctly update word counts and totals.
8416 </p>
8417
8418 <p>
8419         Using <tt>bayes-train</tt> inside a context other than <tt>MAIN</tt>
8420         requires the training contexts to have been created previously within
8421         the <tt>MAIN</tt> context via the <a href="#context">context</a> function.
8422 </p>
8423
8424 <p>
8425         <tt>bayes-train</tt> is not only useful with the <a href="#bayes-query">bayes-query</a> function,
8426         but also as a function for counting in general.
8427         For instance, the resulting frequencies
8428         could be analyzed using <a href="#prob-chi2">prob-chi2</a>
8429         against a <em>null hypothesis</em> of proportional distribution
8430         of items across categories.
8431 </p>
8432
8433 <br /><br />
8434
8435 <a NAME="begin"></a>
8436 <h2><span class="function">begin</span></h2>
8437 <b>syntax: (begin <em>body</em>)</b>
8438
8439 <p>
8440         The <tt>begin</tt> function is used to group a block of expressions.
8441         The expressions in <em>body</em> are evaluated in sequence, and
8442         the value of the last expression in <em>body</em> is returned.
8443 </p>
8444
8445 <b>example:</b>
8446 <blockquote>
8447 <pre>
8448 (begin
8449   (print "This is a block of 2 expressions\n")
8450   (print "================================"))
8451 </pre>
8452 </blockquote>
8453
8454 <p>
8455         Some built-in functions like <a HREF="#cond">cond</a>, <a HREF="#define">define</a>,
8456         <a HREF="#dolist">dolist</a>, <a HREF="#dotimes">dotimes</a>, and <a HREF="#while">while</a>
8457         already allow multiple expressions in their bodies,
8458         but <tt>begin</tt> is often used in an <a HREF="#if">if</a> expression.
8459 </p>
8460
8461 <p>
8462         The <a HREF="#silent">silent</a> function works like <tt>begin</tt>,
8463         but suppresses console output on return.
8464 </p>
8465
8466 <br /><br />
8467
8468 <a NAME="beta"></a>
8469 <h2><span class="function">beta</span></h2>
8470 <b>syntax: (beta <em>cum-a</em> <em>num-b</em>)</b>
8471
8472 <p>
8473         The <em>Beta</em> function, <tt>beta</tt>,
8474         is derived from the <em>log Gamma</em>
8475         <tt>gammaln</tt> function as follows:
8476 </p>
8477
8478 <blockquote>
8479 <em><b>
8480 beta = exp(gammaln(a) + gammaln(b) - gammaln(a + b))
8481 </b></em>
8482 </blockquote>
8483
8484 <b>example:</b>
8485 <blockquote>
8486 <pre>
8487 (beta 1 2)  <span class=arw>&rarr;</span> 0.5
8488 </pre>
8489 </blockquote>
8490
8491 <br /><br />
8492
8493 <a NAME="betai"></a>
8494 <h2><span class="function">betai</span></h2>
8495
8496 <b>syntax: (betai <em>num-x</em> <em>num-a</em> <em>num-b</em>)</b>
8497
8498 <p>
8499         The <em>Incomplete Beta</em> function, <tt>betai</tt>,
8500         equals the cumulative probability of the <em>Beta</em> distribution, <tt>betai</tt>,
8501         at <em>x</em> in <em>num-x</em>.
8502         The cumulative binomial distribution is defined as the probability of an event, <em>pev</em>,
8503         with probability <em>p</em> to occur <em>k</em> or more times in <em>N</em> trials:
8504 </p>
8505
8506 <blockquote>
8507 <em><b> pev = Betai(p, k, N - k + 1) </b></em>
8508 </blockquote>
8509 <b>example:</b>
8510 <blockquote>
8511 <pre>
8512 (betai 0.5 3 8)  <span class=arw>&rarr;</span> 0.9453125
8513
8514 ;; probability of F ratio for df1/df2
8515 ;;
8516 (define (f-prob f df1 df2)
8517   (let (prob (mul 2 (betai (div df2 (add df2 (mul df1 f)))
8518                            (mul 0.5 df2)
8519                            (mul 0.5 df1))))
8520     (div (if (&gt; prob 1) (sub 2 prob) prob) 2)))
8521 </pre>
8522 </blockquote>
8523
8524 <p>
8525         The first example calculates the probability for an event,
8526         with a probability of 0.5 to occur 3 or more times in 10 trials (8 = 10 - 3 + 1).
8527         The incomplete Beta distribution can be used to derive a variety of other functions
8528         in mathematics and statistics.
8529         The second example calculates the one-tailed probability of a variance, <em>F ratio</em>.
8530         In similar fashion, <em>students t</em> could be calculated using <tt>betai</tt>.
8531         See also the <a HREF="#binomial">binomial</a> function.
8532 </p>
8533
8534 <br /><br />
8535
8536 <a NAME="bind"></a>
8537
8538 <h2><span class="function">bind</span></h2>
8539 <b>syntax: (bind <em>list-variable-associations</em> [<em>boolean_eval</em>])</b>
8540
8541 <p><em>list-variable-associations</em> contains an association list of
8542 symbols and their values. <tt>bind</tt> sets all symbols
8543 to their associated values.</p>
8544
8545 <p>Depending or the presence and value of the <em>boolean-eval</em> flag the
8546 associated values are evaluated:</p>
8547
8548 <blockquote><pre>
8549 (set 'lst '((a (+ 3 4)) (b "hello")))
8550
8551 (bind lst)         <span class=arw>&rarr;</span> "hello"
8552
8553 a    <span class=arw>&rarr;</span> (+ 3 4)
8554 b    <span class=arw>&rarr;</span> "hello"
8555
8556 (bind lst true)    <span class=arw>&rarr;</span> "hello"
8557
8558 a    <span class=arw>&rarr;</span> 7
8559 </pre></blockquote>
8560
8561 <p>The return value of bind is the value of the last association.</p>
8562
8563 <p><tt>bind</tt> is often used to bind association lists returned
8564 by <a href="#unify">unify</a>.</p>
8565
8566 <blockquote><pre>
8567 (bind (unify '(p X Y a) '(p Y X X)))    <span class=arw>&rarr;</span> a
8568
8569 X    <span class=arw>&rarr;</span> a
8570 Y    <span class=arw>&rarr;</span> a
8571 </pre></blockquote>
8572
8573 <p>The return value of bind is the value of the last association.</p>
8574
8575 <br /><br />
8576
8577 <a NAME="binomial"></a>
8578
8579 <h2><span class="function">binomial</span></h2>
8580 <b>syntax: (binomial <em>int-n</em> <em>int-k</em> <em>float-p</em>)</b>
8581
8582 <p>
8583         The binomial distribution function is defined as
8584         the probability for an event to occur <em>int-k</em> times in <em>int-n</em> trials
8585         if that event has a probability of <em>float-p</em>
8586         and all trials are independent of one another:
8587 </p>
8588
8589 <blockquote>
8590 <em><b>binomial = n! / (k! * (n - k)!) * pow(p, k) * pow(1.0 - p, n - k)</b></em>
8591 </blockquote>
8592
8593 <p>
8594         where <em>x!</em> is the factorial of <em>x</em>
8595         and <em>pow(x, y)</em> is <em>x</em> raised to the power of <em>y</em>.
8596 </p>
8597
8598 <br />
8599
8600 <b>example:</b>
8601 <blockquote>
8602 <pre>
8603 (binomial 10 3 0.5)  <span class=arw>&rarr;</span> 0.1171875
8604 </pre>
8605 </blockquote>
8606
8607 <p>
8608         The example calculates the probability for an event
8609         with a probability of 0.5 to occur 3 times in 10 trials.
8610         For a cumulated distribution,
8611         see the <a HREF="#betai">betai</a> function.
8612 </p>
8613
8614 <br /><br />
8615
8616 <a NAME="callback"></a>
8617 <h2><span class="function"> callback </span></h2>
8618 <b>syntax: (callback <em>int-index</em> <em>sym-function</em>)</b>
8619
8620 <p>Up to eight <em>callback</em> functions
8621 can be registered with imported libraries.
8622 The <tt>callback</tt> function returns a procedure address
8623 that invokes a user-defined function in <em>sym-function</em>.
8624 The following example shows the usage of callback functions
8625 when importing the
8626 <a href="http://www.opengl.org">OpenGL</a> graphics library:</p>
8627
8628 <b>example:</b>
8629 <blockquote>
8630 <pre>
8631 ...
8632 (define (draw)
8633     (glClear GL_COLOR_BUFFER_BIT )
8634     (glRotated rotx 0.0 1.0 0.0)
8635     (glRotated roty 1.0 0.0 0.0)
8636     (glutWireTeapot 0.5)
8637     (glutSwapBuffers))
8638
8639 (define (keyboard key x y)
8640     (if (= (&amp; key 0xFF) 27) (exit)) ; exit program with ESC
8641     (println "key:" (&amp; key 0xFF) " x:" x  " y:" y))
8642
8643 (define (mouse button state x y)
8644     (if (= state 0)
8645         (glutIdleFunc 0) ; stop rotation on button press
8646         (glutIdleFunc (callback 4 'rotation)))
8647     (println "button: " button " state:" state " x:" x " y:" y))
8648
8649 (glutDisplayFunc (callback 0 'draw))
8650 (glutKeyboardFunc (callback 1 'keyboard))
8651 (glutMouseFunc (callback 2 'mouse))
8652 ...
8653 </pre>
8654 </blockquote>
8655
8656 <p>The address returned by <tt>callback</tt>
8657 is registered with the <a href="http://www.opengl.org/documentation/specs/glut/spec3/spec3.html">Glut</a> library.
8658 The above code is a snippet from the file <tt>opengl-demo.lsp</tt>,
8659 in the <tt>examples/</tt> directory of the source distribution of newLISP.</p>
8660
8661 <br /><br />
8662
8663 <a NAME="case"></a>
8664 <h2><span class="function">case</span></h2>
8665 <b>syntax: (case exp-switch (<em>exp-1</em> <em>body-1</em>) [ (<em>exp-2</em> <em>body-2</em>) ... ] )</b>
8666
8667 <p>
8668         The result of evaluating <em>exp-switch</em>
8669         is compared to each of the <em>unevaluated</em> expressions
8670         <em>exp-1, exp-2,</em> &mdash;.
8671         If a match is found,
8672         the corresponding expressions in <em>body</em> are evaluated.
8673         The result of the last match is returned
8674         as the result for the entire <tt>case</tt> expression. </p>
8675
8676
8677 <b>example:</b>
8678 <blockquote>
8679 <pre>
8680 (define (translate n)
8681   (case n
8682     (1 "one")
8683     (2 "two")
8684     (3 "three")
8685     (4 "four")
8686     (true "Can't translate this")))
8687 (translate 3)   <span class=arw>&rarr;</span> "three"
8688 (translate 10)  <span class=arw>&rarr;</span> "Can't translate this"
8689 </pre>
8690 </blockquote>
8691
8692 <p>
8693         The example shows how,
8694         if no match is found,
8695         the last expression in the body of a <tt>case</tt> function
8696         can be evaluated.
8697 </p>
8698
8699 <br /><br />
8700
8701 <a NAME="catch"></a>
8702 <h2><span class="function">catch</span></h2>
8703
8704 <b>syntax: (catch <em>exp</em>)</b><br />
8705 <b>syntax: (catch <em>exp</em> <em>symbol</em> )</b>
8706
8707 <p>
8708         In the first syntax,
8709         <tt>catch</tt> will return the result of the evaluation of <em>exp</em>
8710         or the evaluated argument of a <a href="#throw">throw</a>
8711         executed during the evaluation of <em>exp</em>:
8712 </p>
8713
8714 <b>example:</b>
8715 <blockquote>
8716 <pre>
8717 (catch (dotimes (x 1000)
8718   (if (= x 500) (throw x))))  <span class=arw>&rarr;</span> 500
8719 </pre>
8720 </blockquote>
8721
8722 <p>
8723         This form is useful for breaking out of iteration loops
8724         and for forcing an early return
8725         from a function or expression block:
8726 </p>
8727
8728 <blockquote>
8729 <pre>
8730 (define (foo x)
8731    &hellip;
8732   (if condition (throw 123))
8733     &hellip;
8734   456)
8735
8736 ;; if condition is true
8737
8738 (catch (foo p))  <span class=arw>&rarr;</span> 123
8739
8740 ;; if condition is not true
8741
8742 (catch (foo p))  <span class=arw>&rarr;</span> 456
8743 </pre>
8744 </blockquote>
8745
8746
8747 <p>
8748         In the second syntax,
8749         <tt>catch</tt> evaluates the expression <em>exp</em>,
8750         stores the result in <em>symbol</em>,
8751         and returns <tt>true</tt>.
8752         If an error occurs during evaluation,
8753         <tt>catch</tt> returns <tt>nil</tt>
8754         and stores the error message in <em>symbol</em>.
8755         This form can be useful when errors are expected
8756         as a normal potential outcome of a function
8757         and are dealt with during program execution.
8758 </p>
8759
8760 <b>example:</b>
8761 <blockquote>
8762 <pre>
8763 (catch (func 3 4) 'result)  <span class=arw>&rarr;</span> nil
8764 result
8765 <span class=arw>&rarr;</span> "invalid function in function catch : (func 3 4)"
8766
8767 (constant 'func +)          <span class=arw>&rarr;</span> add &lt;4068A6&gt;
8768 (catch (func 3 4) 'result)  <span class=arw>&rarr;</span> true
8769 result                      <span class=arw>&rarr;</span> 7
8770 </pre>
8771 </blockquote>
8772
8773 <p>
8774         When a <a href="#throw">throw</a> is executed during the evaluation of <em>expr</em>,
8775         <tt>catch</tt> will return <tt>true</tt>,
8776         and the <tt>throw</tt> argument will be stored in <em>symbol</em>:
8777 </p>
8778
8779 <blockquote>
8780 <pre>
8781 (catch (dotimes (x 100)
8782   (if (= x 50) (throw "fin")) 'result)  <span class=arw>&rarr;</span> true
8783
8784 result  <span class=arw>&rarr;</span> "fin"
8785 </pre>
8786 </blockquote>
8787
8788 <p>
8789         As well as being used for early returns from functions and
8790         for breaking out of iteration loops (as in the first syntax),
8791         the second syntax of <tt>catch</tt> can also be used to catch errors.
8792         The <a href="#throw-error">throw-error</a> function may be used
8793         to throw user-defined errors.
8794 </p>
8795
8796
8797 <br /><br />
8798
8799 <a NAME="ceil"></a>
8800 <h2><span class="function">ceil</span></h2>
8801 <b>syntax: (ceil <em>number</em> )</b>
8802
8803 <p>
8804         Returns the next highest integer above <em>number</em>
8805         as a floating point.
8806 </p>
8807
8808 <b>example:</b>
8809 <blockquote>
8810 <pre>
8811 (ceil -1.5)  <span class=arw>&rarr;</span> -1
8812 (ceil 3.4)   <span class=arw>&rarr;</span> 4
8813 </pre>
8814 </blockquote>
8815
8816 <p>See also the <a HREF="#floor">floor</a> function.
8817 </p>
8818
8819 <br /><br />
8820
8821
8822 <a NAME="change-dir"></a>
8823 <h2><span class="function">change-dir</span></h2>
8824 <b>syntax: (change-dir <em>str-path</em>)</b>
8825
8826 <p>
8827         Changes the current directory to be the one given in <em>str-path</em>.
8828         If successful, <tt>true</tt> is returned; otherwise <tt>nil</tt> is returned.
8829 </p>
8830
8831 <b>example:</b>
8832 <blockquote>
8833 <pre>
8834 (change-dir "/etc")
8835 </pre>
8836 </blockquote>
8837
8838 <p>
8839         Makes <tt>/etc</tt> the current directory.
8840 </p>
8841
8842 <br /><br />
8843
8844 <a NAME="char"></a>
8845 <h2><span class="function">char</span></h2>
8846 <b>syntax: (char <em>str</em> [<em>int-index</em>] )</b><br />
8847 <b>syntax: (char <em>int</em>)</b>
8848
8849 <p>
8850         Given a string argument,
8851         extracts the character at <em>int-index</em> from <em>str</em>,
8852         returning the ASCII value of that character.
8853         If <em>int-index</em> is omitted,
8854         0 (zero) is assumed.
8855 </p>
8856
8857 <p>
8858         See <a HREF="#indexing">Indexing elements of strings and lists</a>.
8859 </p>
8860
8861 <p>
8862         Given an integer argument,
8863         <tt>char</tt> returns a string containing the ASCII character
8864         with value <em>int</em>.
8865 </p>
8866
8867 <p>
8868         On UTF-8&ndash;enabled versions of newLISP,
8869         the value in <em>int</em> is taken as Unicode
8870         and a UTF-8 character is returned.
8871 </p>
8872
8873 <b>example:</b>
8874 <blockquote>
8875 <pre>
8876 (char "ABC")     <span class=arw>&rarr;</span> 65  ; ASCII code for "A"
8877 (char "ABC" 1)   <span class=arw>&rarr;</span> 66  ; ASCII code for "B"
8878 (char "ABC" -1)  <span class=arw>&rarr;</span> 67  ; ASCII code for "C"
8879 (char "B")       <span class=arw>&rarr;</span> 66  ; ASCII code for "B"
8880
8881 (char 65)  <span class=arw>&rarr;</span> "A"
8882 (char 66)  <span class=arw>&rarr;</span> "B"
8883
8884 (char (char 65))  <span class=arw>&rarr;</span> 65      ; two inverse applications
8885
8886 (map char (sequence 1 255))  ; returns current character set
8887 </pre>
8888 </blockquote>
8889
8890 <br /><br />
8891
8892 <a NAME="chop"></a>
8893 <h2><span class="function">chop</span></h2>
8894 <b>syntax: (chop <em>str</em> [<em>int-chars</em>] )</b><br />
8895 <b>syntax: (chop <em>list</em> [<em>int-elements</em>] )</b>
8896
8897 <p>
8898         If the first argument evaluates to a string,
8899         <tt>chop</tt> returns a copy of <em>str</em>
8900         with the last <em>int-char</em> characters omitted.
8901         If the <em>int-char</em> argument is absent,
8902         one character is omitted.
8903         <tt>chop</tt> does not alter <em>str</em>.
8904
8905
8906 <p>
8907         If the first argument evaluates to a list,
8908         a copy of <em>list</em> is returned
8909         with <em>int-elements</em> omitted
8910         (same as for strings).
8911 </p>
8912
8913 <b>example:</b>
8914 <blockquote>
8915 <pre>
8916 (set 'str "newLISP")  <span class=arw>&rarr;</span> "newLISP"
8917
8918 (chop str)    <span class=arw>&rarr;</span> "newLIS"
8919 (chop str 2)  <span class=arw>&rarr;</span> "newLI"
8920
8921 str  <span class=arw>&rarr;</span> "newLISP"
8922
8923 (set 'lst '(a b (c d) e))
8924
8925 (chop lst)    <span class=arw>&rarr;</span> (a b (c d))
8926 (chop lst 2)  <span class=arw>&rarr;</span> (a b)
8927
8928 lst  <span class=arw>&rarr;</span> (a b (c d) e)
8929 </pre>
8930 </blockquote>
8931
8932 <br /><br />
8933
8934 <a NAME="clean"></a>
8935 <h2><span class="function">clean</span></h2>
8936 <b>syntax: (clean <em>exp-predicate</em> <em>list</em>)</b>
8937
8938 <p>
8939         The predicate <em>exp-predicate</em> is applied
8940         to each element of <em>list</em>.
8941         In the returned list,
8942         all elements for which <em>exp-predicate</em> is <tt>true</tt>
8943         are eliminated.
8944 </p>
8945
8946 <p>
8947         <tt>clean</tt> works like <a href="#filter">filter</a>
8948         with a negated predicate.
8949 </p>
8950
8951 <b>example:</b>
8952 <blockquote>
8953 <pre>
8954 (clean symbol? '(1 2 d 4 f g 5 h))   <span class=arw>&rarr;</span> (1 2 4 5)
8955
8956 (filter symbol? '(1 2 d 4 f g 5 h))  <span class=arw>&rarr;</span> (d f g h)
8957
8958 (define (big? x) (&gt; x 5))        <span class=arw>&rarr;</span> (lambda (x) (&gt; x 5))
8959
8960 (clean big? '(1 10 3 6 4 5 11))  <span class=arw>&rarr;</span> (1 3 4 5)
8961
8962 (clean &lt;= '(3 4 -6 0 2 -3 0))  <span class=arw>&rarr;</span> (3 4 2)
8963
8964 (clean (curry match '(a *)) '((a 10) (b 5) (a 3) (c 8) (a 9)))
8965 <span class=arw>&rarr;</span>  ((b 5) (c 8))
8966 </pre>
8967 </blockquote>
8968
8969 <p>
8970         The predicate may be a built-in predicate
8971         or a user-defined function or lambda expression.
8972 </p>
8973
8974 <p>
8975         For cleaning numbers from one list
8976         using numbers from another,
8977         use <a href="#difference">difference</a>
8978         or <a href="#intersect">intersect</a>
8979         (with the <em>list</em> option).
8980 </p>
8981
8982 <p>
8983         See also the related function <a HREF="#index">index</a>,
8984         which returns the indices of the remaining elements,
8985         and <a href="#filter">filter</a>,
8986         which returns all elements for which a predicate returns true.
8987 </p>
8988
8989 <br /><br />
8990
8991 <a NAME="close"></a>
8992 <h2><span class="function">close</span></h2>
8993 <b>syntax: (close <em>int-file</em>)</b>
8994
8995 <p>
8996         Closes the file specified by the file handle in <em>int-file</em>.
8997         The handle would have been obtained
8998         from a previous <a HREF="#open">open</a> operation.
8999         If successful, <tt>close</tt> returns <tt>true</tt>; otherwise  <tt>nil</tt> is returned.
9000 </p>
9001
9002 <b>example:</b>
9003 <blockquote>
9004 <pre>
9005 (close (device))  <span class=arw>&rarr;</span> true
9006 (close 7)         <span class=arw>&rarr;</span> true
9007 (close aHandle)   <span class=arw>&rarr;</span> true
9008 </pre>
9009 </blockquote>
9010
9011 <p>
9012         Note that using <tt>close</tt> on <a href="#device">device</a>
9013         automatically resets it to 0 (zero, the screen device).
9014 </p>
9015
9016 <br /><br />
9017
9018 <a NAME="command-line"></a>
9019 <h2><span class="function">command-line</span></h2>
9020 <b>syntax: (command-line [<em>bool</em>])</b>
9021
9022 <p>
9023         Enables or disables the console's
9024         interactive command-line mode.
9025         The command line is switched off
9026         if <em>bool</em> evaluates to <tt>nil</tt>,
9027         and on for anything else.
9028         The command line is also switched on
9029         if reset or an error condition occurs.
9030 </p>
9031
9032 <b>example:</b>
9033 <blockquote>
9034 <pre>
9035 (command-line nil)
9036 </pre>
9037 </blockquote>
9038
9039 <p>
9040         On Linux/UNIX,
9041         this will also disable the Ctrl-C handler.
9042 </p>
9043 <br /><br />
9044
9045
9046 <a NAME="cond"></a>
9047 <h2><span class="function">cond</span></h2>
9048
9049 <b>syntax: (cond (<em>exp-condition-1</em> <em>body-1</em>) [(<em>exp-condition-2</em> <em>body-2</em>) ... ]</b>
9050
9051 <p>
9052         Like <tt>if</tt>, <tt>cond</tt> conditionally evaluates the expressions
9053         within its body.
9054         The <em>exp-condition</em>s are evaluated in turn,
9055         until some <em>exp-condition-i</em> is found
9056         that evaluates to anything other than <tt>nil</tt>
9057         or an empty list <tt>()</tt>.
9058         The result of evaluating <em>body-i</em>
9059         is then returned as the result of the entire <em>cond-expression</em>.
9060         If all conditions evaluate to <tt>nil</tt>
9061         or an empty list,
9062         <em>cond</em> returns the value of the last <em>cond-expression</em>.
9063 </p>
9064
9065 <b>example:</b>
9066 <blockquote>
9067 <pre>
9068 (define (classify x)
9069   (cond
9070     ((&lt; x 0) "negative")
9071     ((&lt; x 10) "small")
9072     ((&lt; x 20) "medium")
9073     ((&gt;= x 30) "big")))
9074
9075 (classify 15)   <span class=arw>&rarr;</span> "medium"
9076 (classify 22)   <span class=arw>&rarr;</span> "nil"
9077 (classify 100)  <span class=arw>&rarr;</span> "big"
9078 (classify -10)  <span class=arw>&rarr;</span> "negative"
9079 </pre>
9080 </blockquote>
9081
9082 <p>
9083         When a <em>body-n</em> is missing,
9084         the value of the last <em>cond-expression</em> evaluated
9085         is returned.
9086         If no condition evaluates to <tt>true</tt>,
9087         the value of the last conditional expression is returned
9088         (i.e., <tt>nil</tt> or an empty list).
9089 </p>
9090
9091 <blockquote>
9092 <pre>
9093 (cond ((+ 3 4)))  <span class=arw>&rarr;</span> 7
9094 </pre>
9095 </blockquote>
9096
9097 <p>
9098         When used with multiple arguments,
9099         the function <a href="#if">if</a>
9100         behaves like <tt>cond</tt>,
9101         except it does not need extra parentheses
9102         to enclose the condition-body pair
9103         of expressions.
9104 </p>
9105
9106 <br /><br />
9107
9108 <a NAME="cons"></a>
9109 <h2><span class="function">cons</span></h2>
9110 <b>syntax: (cons <em>exp-1</em> <em>exp-2</em>)</b>
9111
9112 <p>
9113         If <em>exp-2</em> evaluates to a list,
9114         then a list is returned with the result of evaluating <em>exp-1</em>
9115         inserted as the first element.
9116         If <em>exp-2 </em>evaluates to anything other than a list,
9117         the results of evaluating <em>exp-1</em> and <em>exp-2</em>
9118         are returned in a list.
9119         Note that there is no <em>dotted pair</em> in newLISP:
9120         <em>consing</em> two atoms constructs a list, not a dotted pair.
9121 </p>
9122
9123 <b>example:</b>
9124 <blockquote>
9125 <pre>
9126 (cons 'a 'b)            <span class=arw>&rarr;</span> (a b)
9127 (cons 'a '(b c))        <span class=arw>&rarr;</span> (a b c)
9128 (cons (+ 3 4) (* 5 5))  <span class=arw>&rarr;</span> (7 25)
9129 (cons '(1 2) '(3 4))    <span class=arw>&rarr;</span> ((1 2) 3 4)
9130 (cons nil 1)            <span class=arw>&rarr;</span> (nil 1)
9131 (cons 1 nil)            <span class=arw>&rarr;</span> (1 nil)
9132 (cons 1)                <span class=arw>&rarr;</span> (1)
9133 (cons)                  <span class=arw>&rarr;</span> ()
9134 </pre>
9135 </blockquote>
9136
9137 <p>
9138         Unlike other LISPs that return <tt>(s)</tt>
9139         as the result of the expression <tt>(cons 's nil)</tt>,
9140         newLISP's <tt>cons</tt> returns <tt>(s nil)</tt>.
9141         In newLISP, <tt>nil</tt> is a boolean value
9142         and is not equivalent to an empty list,
9143         and a LISP cell holds only one value.
9144 </p>
9145
9146 <p>
9147         <tt>cons</tt> behaves like the inverse operation of <a href="#first">first</a>
9148 and <a href="#rest">rest</a>
9149         (or <a href="#first">first</a> and <a href="#last">last</a> if the list is a pair):
9150 </p>
9151
9152 <blockquote>
9153 <pre>
9154 (cons (first '(a b c)) (rest '(a b c)))  <span class=arw>&rarr;</span> (a b c)
9155
9156 (cons (first '(x y)) (last '(x y)))      <span class=arw>&rarr;</span> (x y)
9157 </pre>
9158 </blockquote>
9159 <br /><br />
9160
9161 <a NAME="constant"></a>
9162 <h2><span class="function">constant</span></h2>
9163 <b>syntax: (constant <em>sym-1</em> <em>exp-1</em> [<em>sym-2</em> <em>exp-2</em> ... ])</b>
9164
9165 <p>
9166         Identical to <a href="#set">set</a> in functionality,
9167         <tt>constant</tt> further protects the symbols from subsequent modification.
9168         A symbol set with <tt>constant</tt> can only be modified
9169         using the <tt>constant</tt> function again.
9170         When an attempt is made to modify the contents of a symbol protected with <tt>constant</tt>,
9171         newLISP generates an error message.
9172         Only symbols from the current context can be used with <tt>constant</tt>.
9173         This prevents the overwriting of symbols
9174         that have been protected in their home context.
9175 </p>
9176
9177 <p>
9178         Symbols initialized with <a href="#set">set</a>, <a href="#define">define</a>, or <a href="#define-macro"> define-macro</a>
9179 can still be protected by using the <tt>constant</tt> function:
9180 </p>
9181 <blockquote>
9182 <pre>
9183
9184 (constant 'aVar 123)  <span class=arw>&rarr;</span> 123
9185 (set 'aVar 999)
9186 <span class=err>error: symbol is protected in function set: aVar</span>
9187
9188 (define (double x) (+ x x))
9189
9190 (constant 'double)
9191
9192 ;; equivalent to
9193
9194 (constant 'double (fn (x) (+ x x)))
9195 </pre>
9196 </blockquote>
9197
9198 <p>
9199         The first example defines a constant, <tt>aVar</tt>,
9200         which can only be changed by using another <tt>constant</tt> statement.
9201         The second example protects <tt>double</tt> from being changed
9202         (except by <tt>constant</tt>).
9203         Because a function definition in newLISP
9204         is equivalent to an assignment of a lambda function,
9205         both steps can be collapsed into one,
9206         as shown in the last statement line.
9207         This could be an important technique
9208         for avoiding protection errors
9209         when a file is loaded multiple times.
9210 </p>
9211
9212 <p>
9213         The last value to be assigned can be omitted.
9214         <tt>constant</tt> returns the contents of
9215         the last symbol set and protected.
9216 </p>
9217
9218 <p>
9219         Built-in functions can be assigned to symbols
9220         or to the names of other built-in functions,
9221         effectively redefining them as different functions.
9222         There is no performance loss when renaming functions.
9223 </p>
9224
9225 <blockquote>
9226 <pre>
9227 (constant 'squareroot sqrt)  <span class=arw>&rarr;</span> sqrt &lt;406C2E&gt;
9228 (constant '+ add)            <span class=arw>&rarr;</span> add &lt;4068A6&gt;
9229 </pre>
9230 </blockquote>
9231
9232 <p>
9233         <tt>squareroot</tt> will behave like <tt>sqrt</tt>.
9234         The <tt>+</tt> (plus sign) is redefined
9235         to use the mixed type floating point mode of <tt>add</tt>.
9236         The hexadecimal number displayed in the result
9237         is the binary address of the built-in function
9238         and varies on different platforms and OSes.
9239 </p>
9240
9241 <br /><br />
9242
9243 <a NAME="context"></a>
9244 <h2><span class="function">context</span></h2>
9245 <b>syntax: (context [<em>sym-context</em>])</b><br /><br />
9246 <b>syntax: (context <em>sym-context</em> <em>str|sym</em> <em>exp-value</em>)</b><br />
9247 <b>syntax: (context <em>sym-context</em> <em>str|sym</em>)</b>
9248
9249 <p>
9250         In the first syntax, <tt>context</tt> is used
9251         to switch to a different context namespace.
9252         Subsequent <a href="#load">load</a>s of newLISP source
9253         or functions like <a href="#eval-string">eval-string</a>
9254         will put newly created symbols and
9255         function definitions in the new context.
9256 </p>
9257
9258 <p>
9259         If the context still needs to be created,
9260         the symbol for the new context should be specified.
9261         When no argument is passed to <tt>context</tt>, then
9262         the symbol for the current context is returned. </p>
9263
9264 <p>
9265         Because contexts evaluate to themselves,
9266         a quote is not necessary
9267         to switch to a different context
9268         if that context already exists.
9269 </p>
9270
9271 <b>example:</b>
9272 <blockquote>
9273 <pre>
9274 (context 'GRAPH)          ; create / switch context GRAPH
9275
9276 (define (foo-draw x y z)  ; function resides in GRAPH
9277   (&hellip;))
9278
9279 (set 'var 12345)
9280 (symbols)  <span class=arw>&rarr;</span> (foo-draw var)  ; GRAPH has now two symbols
9281
9282 (context MAIN)                ; switch back to MAIN (quote not required)
9283
9284 (print GRAPH:var) <span class=arw>&rarr;</span> 12345    ; contents of symbol in GRAPH
9285
9286 (GRAPH:foo-draw 10 20 30)     ; execute function in GRAPH
9287 (set 'GRAPH:var 6789)         ; assign to a symbol in GRAPH
9288 </pre>
9289 </blockquote>
9290
9291 <p>
9292         If a context symbol is referred to before the context exists,
9293         the context will be created implicitly.
9294 </p>
9295
9296 <blockquote>
9297 <pre>
9298 (set 'person:age 0)       ; no need to create context first
9299 (set 'person:address "")  ; useful for quickly defining data structures
9300 </pre>
9301 </blockquote>
9302
9303 <p>
9304         Contexts can be copied:
9305 </p>
9306
9307 <blockquote>
9308 <pre>
9309 (new person 'JohnDoe)  <span class=arw>&rarr;</span>  JohnDoe
9310
9311 (set 'JohnDoe:age 99)
9312 </pre>
9313 </blockquote>
9314
9315 <p>
9316         Contexts can be referred to by a variable:
9317 </p>
9318
9319 <blockquote>
9320 <pre>
9321 (set 'human JohnDoe)
9322
9323 human:age  <span class=arw>&rarr;</span> 99
9324
9325 (set 'human:address "1 Main Street")
9326
9327 JohnDoe:address  <span class=arw>&rarr;</span> "1 Main Street"
9328 </pre>
9329 </blockquote>
9330
9331
9332 <p>An evaluated context (no quote) can be given as an argument:
9333 </p>
9334
9335 <blockquote>
9336 <pre>
9337 <b>></b> (context 'FOO)
9338 <b>FOO</b>
9339 <b>FOO></b> (context MAIN)
9340 <b>MAIN</b>
9341 <b>></b> (set 'old FOO)
9342 FOO
9343 <b>></b> (context 'BAR)
9344 <b>BAR</b>
9345 <b>BAR></b> (context MAIN:old)
9346 <b>FOO</b>
9347 <b>FOO></b>
9348 </pre>
9349 </blockquote>
9350
9351
9352 <p>
9353         If an identifier with the same symbol already exists,
9354         it is redefined to be a context.
9355 </p>
9356
9357 <p>
9358         Symbols within the current context
9359         are referred to simply by their names,
9360         as are built-in functions and special symbols
9361         like <tt>nil</tt> and <tt>true</tt>.
9362         Symbols outside the current context
9363         are referenced by prefixing the symbol name
9364         with the context name and a <tt>:</tt> (colon).
9365         To quote a symbol in a different context,
9366         prefix the context name with a <tt>'</tt> (single quote).
9367 </p>
9368
9369 <p>
9370         Within a given context, symbols may be created
9371         with the same name as built-in functions
9372         or context symbols in MAIN.
9373         This overwrites the symbols in MAIN
9374         when they are prefixed with a context:
9375 </p>
9376
9377 <blockquote>
9378 <pre>
9379 (context 'CTX)
9380 (define (CTX:new var)
9381     (&hellip;))
9382
9383 (context 'MAIN)
9384 </pre>
9385 </blockquote>
9386
9387 <p>
9388         <tt>CTX:new</tt> will overwrite new in MAIN.
9389 </p>
9390
9391 <p>
9392         In the second syntax,
9393         <tt>context</tt> is used to create <em>dictionaries</em>
9394         for <em>hash</em>-like associative memory access:
9395 </p>
9396
9397 <blockquote>
9398 <pre>
9399 ;; create a symbol and store data in it
9400 (context 'MyHash "John Doe" 123)         <span class=arw>&rarr;</span> 123
9401 (context 'MyHash "@#$%^" "hello world")  <span class=arw>&rarr;</span> "hello world"
9402 (context 'myHash 'xyz 999)               <span class=arw>&rarr;</span> 999
9403
9404 ;; retrieve contents from  symbol
9405 (context 'MyHash "john Doe")  <span class=arw>&rarr;</span> 123
9406 (context 'MyHash "@#$%^")     <span class=arw>&rarr;</span> "hello world"
9407 (context 'MyHash 'xyz)        <span class=arw>&rarr;</span> 999
9408 MyHash:xyz                    <span class=arw>&rarr;</span> 999
9409 </pre>
9410 </blockquote>
9411
9412 <p>
9413         The first three statements create a symbol
9414         and store a value of any data type inside.
9415         The first statement also creates
9416         the hash context named <tt>MyHash</tt>.
9417 When a symbol is specified for the name, the name is taken
9418 from the symbol and creates a symbol with the same name
9419 in the context <tt>MyHash</tt>.
9420 </p>
9421
9422 <p>
9423         Hash symbols can contain spaces
9424         or any other special characters
9425         not typically allowed in newLISP symbols
9426         being used as variable names.
9427         This second syntax of <tt>context</tt>
9428         only creates the new symbol
9429         and returns the value contained in it.
9430         It does not switch to the new namespace.
9431 </p>
9432
9433 <p>The following function definition can be used as a comfortable shorter
9434 method to handle dictionaries:
9435 </p>
9436
9437 <blockquote>
9438 <pre>
9439 (define (myhash:myhash key value)
9440    (if value
9441        (context 'myhash key value)
9442        (context 'myhash key)))
9443
9444 (myhash "hello" 123)
9445
9446 (myhash "hello")  <span class=arw>&rarr;</span> 123
9447 </pre>
9448 </blockquote>
9449
9450 <p>Note that <tt>context</tt> cannot be used to modify the
9451 <a href="#default_function">default functor</a>. This protects a function
9452 like the previous against modifying itself.
9453 </p>
9454
9455 <br /><br />
9456
9457 <a NAME="contextp"></a>
9458 <h2><span class="function">context?</span></h2>
9459
9460 <b>syntax: (context? <em>exp</em>)</b><br />
9461 <b>syntax: (context? <em>exp</em> <em>str-sym</em>)</b>
9462
9463 <p>
9464         In the first syntax,
9465         <em>context?</em> is a predicate that returns <tt>true</tt>
9466         only if <em>exp</em> evaluates to a context;
9467         otherwise, it returns <tt>nil</tt>.
9468 </p>
9469
9470 <b>example:</b>
9471 <blockquote>
9472 <pre>
9473 (context? MAIN)  <span class=arw>&rarr;</span> true
9474 (set 'x 123)
9475 (context? x)     <span class=arw>&rarr;</span> nil
9476
9477 (set 'FOO:q "hola")  <span class=arw>&rarr;</span> "hola"
9478 (set 'ctx FOO)
9479 (context? ctx)       <span class=arw>&rarr;</span> true  ; ctx contains context foo
9480 </pre>
9481 </blockquote>
9482
9483 <p>
9484         The second syntax checks for the existence of a symbol in a context.
9485         The symbol is specified by its name string in <em>str-sym</em>.
9486 </p>
9487
9488 <blockquote>
9489 <pre>
9490 (context? FOO "q")  <span class=arw>&rarr;</span> true
9491 (context? FOO "p")  <span class=arw>&rarr;</span> nil
9492 </pre>
9493 </blockquote>
9494
9495 <p>
9496         Use <a href="#context">context</a> to change and create namespaces
9497         and to create hash symbols in contexts.
9498 </p>
9499
9500 <br /><br />
9501
9502 <a NAME="copy-file"></a>
9503 <h2><span class="function">copy-file</span></h2>
9504 <b>syntax: (copy-file <em>str-from-name</em> <em>str-to-name</em>)</b>
9505
9506 <p>
9507         Copies a file from a path-file-name given in <em>str-from-name</em>
9508         to a path-file-name given in <em>str-to-name</em>.
9509         Returns <tt>true</tt> or <tt>nil</tt>,
9510         depending on if the copy was successful or not.
9511 </p>
9512
9513 <b>example:</b>
9514 <blockquote>
9515 <pre>
9516 (copy-file "/home/me/newlisp/data.lsp" "/tmp/data.lsp")
9517 </pre>
9518 </blockquote>
9519
9520 <br /><br />
9521
9522
9523 <a NAME="cos"></a>
9524 <h2><span class="function">cos</span></h2>
9525 <b>syntax: (cos <em>num-radians</em>)</b>
9526
9527 <p>
9528         The cosine function is calculated from <em>num</em>,
9529         and the result is returned.
9530 </p>
9531
9532 <b>example:</b>
9533 <blockquote>
9534 <pre>
9535 (cos 1)                     <span class=arw>&rarr;</span> 0.5403023059
9536 (set 'pi (mul 2 (acos 0)))  <span class=arw>&rarr;</span> 3.141592654
9537 (cos pi)                    <span class=arw>&rarr;</span> -1
9538 </pre>
9539 </blockquote>
9540
9541 <br /><br />
9542
9543 <a NAME="cosh"></a>
9544 <h2><span class="function">cosh</span></h2>
9545 <b>syntax: (cosh <em>num-radians</em>)</b>
9546
9547 <p>Calculates the hyperbolic cosine of <em>num-radians</em>.
9548 The hyperbolic sine is defined mathematically as:
9549 <em>(exp (x) + exp (-x)) / 2</em>.
9550 An overflow to <tt>inf</tt> may occur
9551 if <em>num-radians</em> is too large.</p>
9552
9553 <b>example:</b>
9554 <blockquote>
9555 <pre>
9556 (cosh 1)     <span class=arw>&rarr;</span> 1.543080635
9557 (cosh 10)    <span class=arw>&rarr;</span> 11013.23292
9558 (cosh 1000)  <span class=arw>&rarr;</span> inf
9559 (= (cosh 1) (div (add (exp 1) (exp -1)) 2))  <span class=arw>&rarr;</span> true
9560 </pre>
9561 </blockquote>
9562
9563 <br /><br />
9564
9565 <a NAME="count"></a>
9566 <h2><span class="function">count</span></h2>
9567 <b>syntax: (count <em>list-1</em> <em>list-2</em>)</b>
9568
9569 <p>
9570         Counts elements of <em>list-1</em> in <em>list-2</em>
9571         and returns a list of those counts.
9572 </p>
9573
9574 <b>example:</b>
9575 <blockquote>
9576 <pre>
9577 (count '(1 2 3) '(3 2 1 4 2 3 1 1 2 2))  <span class=arw>&rarr;</span> (3 4 2)
9578 (count '(z a) '(z d z b a z y a))        <span class=arw>&rarr;</span> (3 2)
9579
9580 (set 'lst (explode (read-file "myFile.txt")))
9581 (set 'letter-counts (count (unique lst) lst))
9582 </pre>
9583 </blockquote>
9584 <p>
9585         The second example counts all occurrences
9586         of different letters in <tt>myFile.txt</tt>.
9587 </p>
9588
9589 <p>
9590         The first list in <tt>count</tt>,
9591         which specifies the items to be counted in the second list,
9592         should be unique.
9593         For items that are not unique,
9594         only the first instance will carry a count;
9595         all other instances will display <tt>0</tt> (zero).
9596 </p>
9597
9598 <br /><br />
9599
9600 <a name="cpymem"></a>
9601 <h2><span class="function">cpymem</span></h2>
9602 <b>syntax: (cpymem <em>int-from-address</em> <em>int-to-address</em> <em>int-bytes</em>)</b>
9603
9604 <p>
9605         Copies <em>int-bytes</em> of memory
9606         from <em>int-from-address</em>
9607         to <em>int-to-address</em>.
9608         This function can be used for
9609         direct memory writing/reading
9610         or for hacking newLISP internals
9611         (e.g., type bits in LISP cells,
9612         or building functions with binary executable code on the fly).
9613 </p>
9614
9615 <p>
9616         Note that this function should only be used
9617         when familiar with newLISP internals.
9618         <tt>cpymem</tt> can crash the system
9619         or make it unstable if used incorrectly.
9620 </p>
9621
9622 <b>example:</b>
9623 <blockquote>
9624 <pre>
9625 (cpymem (pack "c c" 0 32) (last (dump 'sym)) 2)
9626
9627 (set 's "0123456789")
9628
9629 (cpymem "xxx" (+ (address s) 5) 3)
9630
9631 s  <span class=arw>&rarr;</span> "01234xxx89")
9632 </pre>
9633 </blockquote>
9634
9635 <p>
9636         The first example would remove
9637         the protection bit in symbol <tt>sym</tt>.
9638         The second example copies a string directly
9639         into a string variable.
9640 </p>
9641
9642 <p>
9643         The following example creates a new function from scratch,
9644         runs a piece of binary code, and adds up two numbers.
9645         This assembly language snippet shows the x86 code
9646         to add up two numbers and return the result:
9647 </p>
9648
9649 <blockquote>
9650 <pre>
9651  55       push epb
9652  8B EC    mov  ebp, esp
9653  8B 45 08 mov  eax, [ebp+08]
9654  03 45 0C add  eax, [ebp+0c]
9655  5D       pop  ebp
9656  C3       ret
9657 </pre>
9658 </blockquote>
9659
9660 <p>
9661         The binary representation is attached
9662         to a new function created in newLISP:
9663 </p>
9664
9665 <blockquote>
9666 <pre>
9667 ;; set code
9668 (set 'bindata (pack "ccccccccccc"
9669     0x55 0x8B 0xEC 0x8B 0x45 0x08 0x03 0x45 0x0C 0x5D 0xC3))
9670
9671 ;; get function template
9672 (set 'foo print)
9673
9674 ;; change type to library import and OS calling conventions
9675 ;(cpymem (pack "ld" 265) (first (dump foo)) 4) ; Win32 stdcall
9676 (cpymem (pack "ld" 264) (first (dump foo)) 4)  ; Linux cdecl
9677
9678 ;; set code pointer
9679 (cpymem (pack "ld" (address bindata)) (+ (first (dump foo)) 12) 4)
9680
9681 ;; execute
9682 (foo 3 4) <span class=arw>&rarr;</span> 7
9683 </pre>
9684 </blockquote>
9685
9686 <p>
9687         Use the <a href="#dump">dump</a> function
9688         to retrieve binary addresses
9689         and the contents from newLISP cells.
9690 </p>
9691
9692 <br /><br />
9693
9694 <a name="crc32"></a>
9695 <h2><span class="function">crc32</span></h2>
9696 <b>syntax: (crc32 <em>str-data</em>)</b>
9697
9698 <p>
9699         Calculates a running 32-bit CRC (Circular Redundancy Check) sum
9700         from the buffer in <em>str-data</em>,
9701         starting with a CRC of <tt>0xffffffff</tt> for the first byte.
9702         <tt>crc32</tt> uses an algorithm published
9703         by <a href="http://www.w3.org">www.w3.org</a>.
9704 </p>
9705
9706 <b>example:</b>
9707 <blockquote>
9708 <pre>
9709 (crc32 "abcdefghijklmnopqrstuvwxyz")  <span class=arw>&rarr;</span> 1277644989
9710 </pre>
9711 </blockquote>
9712
9713 <p>
9714         <tt>crc32</tt> is often used to verify data integrity
9715         in unsafe data transmissions.
9716 </p>
9717
9718 <br /><br />
9719
9720 <a NAME="crit-chi2"></a>
9721 <h2><span class="function">crit-chi2</span></h2>
9722
9723 <b>syntax: (crit-chi2 <em>num-probability</em> <em>num-df</em>)</b>
9724
9725 <p>
9726         Calculates the critical minimum Chi&sup2;
9727         for a given confidence probability <em>num-probability</em>
9728         and the degrees of freedom <em>num-df</em>
9729         for testing the significance of a statistical null hypothesis.
9730 </p>
9731
9732 <b>example:</b>
9733 <blockquote>
9734 <pre>
9735 (crit-chi2 0.99 4)  <span class=arw>&rarr;</span> 13.27670443
9736 </pre>
9737 </blockquote>
9738
9739 <p>
9740         See also the inverse function <a href="#prob-chi2">prob-chi2</a>.
9741 </p>
9742
9743 <br /><br />
9744
9745 <a NAME="crit-z"></a>
9746 <h2><span class="function">crit-z</span></h2>
9747 <b>syntax: (crit-z <em>num-probability</em>)</b>
9748
9749 <p>
9750         Calculates the critical normal distributed Z value
9751         of a given cumulated probability (<em>num-probability</em>)
9752         for testing of statistical significance and confidence intervals.
9753 </p>
9754
9755 <b>example:</b>
9756 <blockquote>
9757 <pre>
9758 (crit-z 0.999)  <span class=arw>&rarr;</span> 3.090232372
9759 </pre>
9760 </blockquote>
9761
9762 <p>
9763         See also the inverse function <a href="#prob-z">prob-z</a>.
9764 </p>
9765
9766 <br /><br />
9767
9768 <a NAME="current-line"></a>
9769 <h2><span class="function">current-line</span></h2>
9770 <b>syntax: (current-line)</b>
9771
9772 <p>
9773         Retrieves the contents of the last
9774         <a HREF="#read-line">read-line</a> operation.
9775         <tt>current-line</tt>'s contents are also implicitly used
9776         when <a HREF="#write-line">write-line</a>
9777         is called without a string parameter.
9778 </p>
9779
9780 <p>
9781         The following source shows the typical code pattern
9782         for creating a UNIX command-line filter:
9783 </p>
9784
9785 <b>example:</b>
9786 <blockquote>
9787 <pre>
9788 #!/usr/bin/newlisp
9789
9790 (set 'inFile (open (main-args 2) "read"))
9791 (while (read-line inFile)
9792   (if (starts-with (current-line) ";;")
9793     (write-line)))
9794 (exit)
9795 </pre>
9796 </blockquote>
9797
9798 <p>
9799         The program is invoked:
9800 </p>
9801
9802 <blockquote>
9803 <pre>
9804 ./filter myfile.lsp
9805 </pre>
9806 </blockquote>
9807
9808 <p>
9809         This displays all comment lines starting with <tt>;;</tt>
9810         from a file given as a command-line argument
9811         when invoking the script <tt>filter</tt>.
9812 </p>
9813
9814 <br /><br />
9815
9816 <a NAME="curry"></a>
9817
9818 <h2><span class="function">curry</span></h2>
9819 <b>syntax: (curry <em>func</em> <em>expr</em>)</b>
9820
9821 <p>Transforms <em>func</em> from a function <em>f(x, y)</em> that takes two arguments into a function <em>fx(y)</em> that takes a single argument. <tt>curry</tt> works like a
9822 macro in that it does not evaluate its arguments. Instead, they are
9823 evaluated during the application of <em>func</em>.</p>
9824
9825
9826 <b>example:</b>
9827 <blockquote>
9828 <pre>
9829 (set 'f (curry + 10))  <span class=arw>&rarr;</span> (lambda (_x) (+ 10 _x))
9830
9831 (f 7)  <span class=arw>&rarr;</span> 17
9832
9833 (filter (curry match '(a *)) '((a 10) (b 5) (a 3) (c 8) (a 9)))
9834 <span class=arw>&rarr;</span>  ((a 10) (a 3) (a 9))
9835
9836 (clean (curry match '(a *)) '((a 10) (b 5) (a 3) (c 8) (a 9)))
9837 <span class=arw>&rarr;</span>  ((b 5) (c 8))
9838
9839 (map (curry list 'x) (sequence 1 5))
9840 <span class=arw>&rarr;</span>  ((x 1) (x 2) (x 3) (x 4) (x 5))
9841 </pre>
9842 </blockquote>
9843
9844 <p><tt>curry</tt> can be used on all functions taking two arguments.</p>
9845
9846 <br /><br />
9847
9848 <a NAME="date"></a>
9849
9850 <h2><span class="function">date</span></h2>
9851 <b>syntax: (date)</b><br />
9852 <b>syntax: (date <em>int-secs</em> [<em>int-offset</em>])</b><br />
9853 <b>syntax: (date <em>int-secs</em> <em>int-offset</em> <em>str-format</em>)</b>
9854
9855 <p>
9856         The first syntax returns the local time zone's
9857         current date and time as a string representation.
9858 </p>
9859
9860 <p>
9861         In the second syntax, <tt>date</tt> translates the number of seconds
9862         in <em>int-secs</em> into its date/time string representation
9863         for the local time zone.
9864         The number in <em>int-secs</em> is usually retrieved from the system
9865         using <a HREF="#date-value">date-value</a>.
9866         Optionally, a time-zone offset (in minutes) can be specified
9867         in <em>int-offset</em>, which is added
9868         or subtracted before conversion of <em>int-sec</em> to a string.
9869 </p>
9870
9871
9872 <b>example:</b>
9873 <blockquote>
9874 <pre>
9875 (date)                   <span class=arw>&rarr;</span> "Fri Oct 29 09:56:58 2004"
9876
9877 (date (date-value))      <span class=arw>&rarr;</span> "Sat May 20 11:37:15 2006"
9878 (date (date-value) 300)  <span class=arw>&rarr;</span> "Sat May 20 16:37:19 2006"  ; 5 hours offset
9879 (date 0)                 <span class=arw>&rarr;</span> "Wed Dec 31 16:00:00 1969"
9880 </pre>
9881 </blockquote>
9882
9883 <p>
9884         Note that on some Win32-compiled versions,
9885         values resulting in dates earlier than
9886         January 1, 1970, 00:00:00
9887         return <tt>nil</tt>.
9888         But the MinGW compiled version will also work
9889         with values that result in dates up to 24 hours
9890         prior to 1/1/1970, returning a date-time string for 12/31/1969.
9891 </p>
9892
9893 <p>
9894         The way the date and time are presented in a string
9895         depends on the underlying operating system.
9896 </p>
9897
9898 <p>
9899         The second example would show 1-1-1970 0:0
9900         when in the Greenwich time zone,
9901         but it displays a time lag of 8 hours when
9902         in Pacific Standard Time (PST).
9903         <tt>date</tt> assumes the <em>int-secs</em> given are in
9904         Coordinated Universal Time (UCT; formerly Greenwich Mean Time (GMT))
9905         and converts it according to the local time-zone.
9906 </p>
9907
9908 <p>
9909         The third syntax makes the date string fully customizable
9910         by using a format specified in <em>str-format</em>.
9911         This allows the day and month names to be translated into
9912         results appropriate for the current locale:
9913 </p>
9914
9915 <b>example:</b>
9916 <blockquote>
9917 <pre>
9918 (set-locale "german") <span class=arw>&rarr;</span> "de_DE"
9919
9920 (date (date-value) 0 "%A %-d. %B %Y")
9921 <span class=arw>&rarr;</span> "Montag  7. M&auml;rz 2005"
9922 ; on Linux - suppresses the leading 0
9923
9924 (set-locale "C")  ; default POSIX
9925
9926 (date (date-value) 0 "%A %B %d %Y")
9927 <span class=arw>&rarr;</span> "Monday March 07 2005"
9928
9929 (date (date-value) 0 "%a %#d %b %Y")
9930 <span class=arw>&rarr;</span> "Mon 7 Mar 2005"
9931 ; suppressing leading 0 on Win32 using #
9932
9933 (set-locale "german")
9934
9935 (date (date-value) 0 "%x")
9936 <span class=arw>&rarr;</span> "07.03.2005"   ; day month year
9937
9938 (set-locale "C")
9939
9940 (date (date-value) 0 "%x")
9941
9942 <span class=arw>&rarr;</span> "03/07/05"     ; month day year
9943 </pre>
9944 </blockquote>
9945
9946 <p>
9947         The following table summarizes all format specifiers available
9948         on both Win32 and Linux/UNIX platforms.
9949         More format options are available on Linux/UNIX.
9950         For details, consult the documentation for the C function
9951         <tt>strftime()</tt> in the individual platform's C library.
9952 </p>
9953 <br />
9954 <center>
9955 <table border="0" cellpadding="1" width="95%" summary="date formatting">
9956 <tr align="left"><th>format</th><th>description</th></tr>
9957 <tr><td>%a</td><td>abbreviated weekday name according to the current locale</td></tr>
9958
9959 <tr><td>%A</td><td>full weekday name according to the current locale</td></tr>
9960 <tr><td>%b</td><td>abbreviated month name according to the current locale</td></tr>
9961 <tr><td>%B</td><td>full month name according to the current locale</td></tr>
9962 <tr><td>%c</td><td>preferred date and time representation for the current locale</td></tr>
9963 <tr><td>%d</td><td>day of the month as a decimal number (range 01&ndash;31)</td></tr>
9964 <tr><td>%H</td><td>hour as a decimal number using a 24-hour clock (range 00&ndash;23)</td></tr>
9965
9966 <tr><td>%I</td><td>hour as a decimal number using a 12-hour clock (range 01&ndash;12)</td></tr>
9967 <tr><td>%j</td><td>day of the year as a decimal number (range 001&ndash;366)</td></tr>
9968 <tr><td>%m</td><td>month as a decimal number (range 01&ndash;12)</td></tr>
9969 <tr><td>%M</td><td>minute as a decimal number</td></tr>
9970 <tr><td>%p</td><td>either 'am' or 'pm' according to the given time value or
9971 the corresponding strings for the current locale</td></tr>
9972 <tr><td>%S</td><td>second as a decimal number 0&ndash;61 (60 and 61 to account
9973 for occasional leap seconds)</td></tr>
9974
9975 <tr><td>%U</td><td>week number of the current year as a decimal number,
9976 starting with the first Sunday as the first day of the first week</td></tr>
9977 <tr><td>%w</td><td>day of the week as a decimal, Sunday being 0</td></tr>
9978 <tr><td>%W</td><td>week number of the current year as a decimal number,
9979 starting with the first Monday as the first day of the first week</td></tr>
9980 <tr><td>%x</td><td>preferred date representation for the current locale
9981 without the time</td></tr>
9982 <tr><td>%X</td><td>preferred time representation for the current locale
9983 without the date</td></tr>
9984 <tr><td>%y</td><td>year as a decimal number without a century (range 00&ndash;99)</td></tr>
9985
9986 <tr><td>%Y</td><td>year as a decimal number including the century</td></tr>
9987 <tr><td>%z</td><td>time zone or name or abbreviation (same as %Z on Win32,
9988 different on Linux/UNIX)</td></tr>
9989 <tr><td>%Z</td><td>time zone or name or abbreviation (same as %z on Win32,
9990 different on Linux/UNIX)</td></tr>
9991 <tr><td>%%</td><td>a literal '%' character</td></tr>
9992 </table></center>
9993 <br />
9994 <p>
9995         Leading zeroes in the display of decimal numbers can be suppressed
9996         using <tt>-</tt> (minus) on Linux/UNIX and <tt>#</tt> (number sign) on Win32.
9997 </p>
9998
9999 <p>
10000         See also <a HREF="#date-value">date-value</a>,
10001     <a href="#parse-date">parse-date</a>,
10002         <a HREF="#time-of-day">time-of-day</a>,
10003         <a HREF="#time">time</a>, and <a HREF="#now">now</a>.
10004 </p>
10005
10006 <br /><br />
10007
10008 <a NAME="date-value"></a>
10009 <h2><span class="function">date-value</span></h2>
10010
10011 <b>syntax: (date-value <em>int-year</em> <em>int-month</em> <em>int-day</em> [<em>int-hour</em> <em>int-min</em> <em>int-sec</em>])</b><br />
10012 <b>syntax: (date-value)</b>
10013
10014 <p>
10015         In the first syntax, <tt>date-value</tt> returns the time
10016         in seconds since 1970-1-1 00:00:00 for a given date and time.
10017         The parameters for the hour, minutes, and seconds are optional.
10018         The time is assumed to be Coordinated Universal Time (UCT),
10019         not adjusted for the current time zone.
10020 </p>
10021
10022 <p>
10023         In the second syntax, <tt>date-value</tt> returns the time value
10024         in seconds for the current time.
10025 </p>
10026
10027 <b>example:</b>
10028 <blockquote>
10029 <pre>
10030 (date-value 2002 2 28)       <span class=arw>&rarr;</span> 1014854400
10031 (date-value 1970 1 1 0 0 0)  <span class=arw>&rarr;</span> 0
10032
10033 (date (apply date-value (now)))  <span class=arw>&rarr;</span> "Wed May 24 10:02:47 2006"
10034 (date (date-value))              <span class=arw>&rarr;</span> "Wed May 24 10:02:47 2006"
10035 (date)                           <span class=arw>&rarr;</span> "Wed May 24 10:02:47 2006"
10036 </pre>
10037 </blockquote>
10038
10039 <p>
10040         The following function can be used
10041         to transform a <tt>date-value</tt>
10042         back into a list:
10043 </p>
10044
10045 <blockquote>
10046 <pre>
10047 (define (value-date val)
10048   (append
10049     (slice (now (+ (/ (date-value) -60) (/ val 60))) 0 5)
10050     (list (% val 60))))
10051
10052 (value-date 1014854400)  <span class=arw>&rarr;</span> (2002 2 28 0 0 0)
10053 </pre>
10054 </blockquote>
10055
10056 <p>
10057         See also <a HREF="#date">date</a>, <a HREF="#time-of-day">time-of-day</a>,
10058         <a HREF="#time">time</a>, and <a HREF="#now">now</a>.
10059 </p>
10060
10061 <br /><br />
10062
10063 <a NAME="debug"></a>
10064 <h2><span class="function">debug</span></h2>
10065 <b>syntax: (debug <em>func</em>)</b>
10066
10067 <p>
10068         Calls <a HREF="#trace">trace</a> and begins evaluating
10069         the user-defined function in <em>func</em>.
10070         <tt>debug</tt> is a shortcut for executing <tt>(trace true)</tt>,
10071         then entering the function to be debugged.
10072 </p>
10073
10074 <b>example:</b>
10075 <blockquote>
10076 <pre>
10077 ;; instead of doing
10078 (trace true)
10079 (my-func a b c)
10080 (trace nil)
10081
10082 ;; use debug as a shortcut
10083 (debug (my-func a b c))
10084 </pre>
10085 </blockquote>
10086
10087 <p>
10088         See also the <a HREF="#trace">trace</a> function.
10089 </p>
10090
10091 <br /><br />
10092
10093 <a NAME="dec"></a>
10094 <h2><span class="function">dec</span></h2>
10095 <b>syntax: (dec <em>sym</em> [<em>num</em>])</b>
10096
10097 <p>
10098         The number in <em>sym</em> is decremented by one
10099         (or the optional number <em>num</em>) and returned.
10100         <tt>dec</tt> performs mixed integer and floating point
10101         arithmetic according to the rules outlined below.
10102 </p>
10103
10104 <p>
10105         If <em>sym</em> contains a float and <tt>num</tt> is absent,
10106         the input argument is truncated to an integer.
10107 </p>
10108
10109 <p>
10110         Integer calculations (without <em>num</em>) resulting in numbers
10111         greater than 9,223,372,036,854,775,807 wrap around to negative numbers.
10112         Results smaller than -9,223,372,036,854,775,808 wrap around to positive numbers.
10113 </p>
10114
10115 <p>
10116         If <em>num</em> is supplied, <tt>dec</tt>
10117         always returns the result as a floating point number
10118         (even for integer arguments).
10119 </p>
10120
10121 <b>example:</b>
10122 <blockquote>
10123 <pre>
10124 (set 'x 10)    <span class=arw>&rarr;</span> 10
10125 (dec 'x)       <span class=arw>&rarr;</span> 9
10126 x              <span class=arw>&rarr;</span> 9
10127 (dec 'x 0.25)  <span class=arw>&rarr;</span> 8.75
10128 x              <span class=arw>&rarr;</span> 8.75
10129 </pre>
10130 </blockquote>
10131
10132 <p>
10133         Use the <a HREF="#inc">inc</a> function to increment numbers.
10134 </p>
10135
10136 <br /><br />
10137
10138 <a NAME="define"></a>
10139 <h2><span class="function">define</span></h2>
10140 <b>syntax: (define (<em>sym-name</em> [<em>sym-param-1</em> ... ]) [<em>body-1</em> ... ])</b><br />
10141 <!-- 8.9.4 -->
10142 <b>syntax: (define (<em>sym-name</em> [(<em>sym-param-1</em> <em>exp-default</em>) ... ]) [<em>body-1</em> ... ])</b>
10143 <br />
10144
10145
10146 <b>syntax: (define <em>sym-name</em> <em>exp</em> )</b>
10147
10148 <p>
10149         Defines the new function <em>sym-name</em>,
10150         with optional parameters <em>sym-param-1</em>&mdash;.
10151         <tt>define</tt> is equivalent to assigning
10152         a lambda expression to <em>sym-name</em>.
10153         When calling a defined function,
10154         all arguments are evaluated and assigned
10155         to the variables in <em>sym-param-1</em>&mdash;,
10156         then the <em>body-1&mdash;      </em> expressions are evaluated.
10157         When a function is defined, the lambda expression
10158         bound to <em>sym-name</em> is returned.
10159 </p>
10160
10161 <p>
10162         All parameters defined are optional.
10163         When a user-defined function is called without arguments,
10164         those parameters assume the value <tt>nil</tt>.
10165 <!-- 8.9.4 -->If those parameters have a default value
10166         specified in <em>exp-default</em>,
10167         they assume that value.
10168 </p>
10169
10170 <p>
10171         The return value of <tt>define</tt>
10172         is the assigned <em>lambda</em> expression.
10173         When calling a user-defined function,
10174         the return value is the last expression evaluated
10175         in the function body.
10176 </p>
10177
10178 <b>example:</b>
10179 <blockquote>
10180 <pre>
10181 (define (area x y) (* x y))  <span class=arw>&rarr;</span> (lambda (x y) (* x y))
10182 (area 2 3)                   <span class=arw>&rarr;</span> 6
10183 </pre>
10184 </blockquote>
10185
10186 <p>
10187         As an alternative, <tt>area</tt> could be defined
10188         as a function without using <tt>define</tt>.
10189 </p>
10190
10191 <blockquote>
10192 <pre>
10193 (set 'area (lambda (x y) (* x y))
10194 </pre>
10195 </blockquote>
10196
10197 <p>
10198         <em>lambda</em> or <em>fn</em> expressions may be used by themselves
10199         as <em>anonymous</em> functions without being defined as a symbol:
10200 </p>
10201
10202 <blockquote>
10203 <pre>
10204 ((lambda ( x y) (* x y)) 2 3)  <span class=arw>&rarr;</span> 6
10205 ((fn ( x y) (* x y)) 2 3)      <span class=arw>&rarr;</span> 6
10206 </pre>
10207 </blockquote>
10208
10209 <p>
10210         <tt>fn</tt> is just a shorter form of writing <tt>lambda</tt>.
10211 </p>
10212
10213 <!-- 8.9.4 -->
10214 <p>
10215         Parameters can have default values specified:
10216 </p>
10217
10218 <blockquote>
10219 <pre>
10220 (define (foo (a 1) (b 2))
10221   (list a b))
10222
10223 (foo)      <span class=arw>&rarr;</span> (1 2)
10224 (foo 3)    <span class=arw>&rarr;</span> (3 2)
10225 (foo 3 4)  <span class=arw>&rarr;</span> (3 4)
10226 </pre>
10227 </blockquote>
10228
10229 <p>
10230         Expressions in <em>exp-default</em>
10231         are evaluated in the function's
10232         current environment.
10233 </p>
10234
10235 <blockquote>
10236 <pre>
10237 (define-macro (foo (a 10) (b (div a 2)))
10238   (list a b))
10239
10240 (foo)      <span class=arw>&rarr;</span> (10 5)
10241 (foo 30)   <span class=arw>&rarr;</span> (30 15)
10242 (foo 3 4)  <span class=arw>&rarr;</span> (3 4)
10243 </pre>
10244 </blockquote>
10245
10246 <p>
10247         The second version of <tt>define</tt>
10248         works like the <a HREF="#set">set</a> function.
10249 </p>
10250
10251 <b>example:</b>
10252 <blockquote>
10253 <pre>
10254 (define x 123)  <span class=arw>&rarr;</span>   123
10255 ;; is equivalent to
10256 (set 'x 123)    <span class=arw>&rarr;</span>   123
10257
10258 (define area (lambda ( x y) (* x y)))
10259 ;; is equivalent to
10260 (set 'area (lambda ( x y) (* x y)))
10261 ;; is equivalent to
10262 (define (area x y) (* x y))
10263 </pre>
10264 </blockquote>
10265
10266 <p>
10267         Trying to redefine a protected symbol will cause an error message.
10268 </p>
10269
10270 <br /><br />
10271
10272
10273 <a NAME="define-macro"></a>
10274 <h2><span class="function">define-macro</span></h2>
10275 <b>syntax: (define-macro (<em>sym-name</em> [<em>sym-param-1</em> ... ]) <em>body</em>)</b><!-- 8.9.4 --><br />
10276 <b>syntax: (define-macro (<em>sym-name</em> [(<em>sym-param-1</em> <em>expr-default</em>) ... ]) <em>body</em>)</b>
10277 <p>
10278         Defines the new macro <em>sym-name</em>,
10279         with optional arguments <em>sym-param-1</em>&mdash;.
10280         <tt>define-macro</tt> is equivalent to assigning
10281         a lambda-macro expression to a symbol.
10282         When a macro-defined function is called,
10283         arguments are assigned to the variables
10284         in <em>sym-param-1</em>&mdash;,
10285         without evaluating the arguments first.
10286         Then the <em>body</em> expressions are evaluated.
10287         When evaluating the <tt>define-macro</tt> function,
10288         the lambda-macro expression is returned.
10289 </p>
10290
10291
10292 <b>example:</b>
10293 <blockquote>
10294 <pre>
10295 ;; use underscores on symbols
10296 (define-macro (my-setq _x _y) (set _x (eval _y)))
10297 <span class=arw>&rarr;</span> (lambda-macro (_x _y) (set _x (eval _y)))
10298
10299 (my-setq x 123)  <span class=arw>&rarr;</span> 123
10300 </pre>
10301 </blockquote>
10302
10303 <p>
10304         Macros in newLISP are similar to <tt>define</tt> functions,
10305         but they do <em>not</em> evaluate their arguments.
10306         New functions can be created to behave like built-in functions
10307         that delay the evaluation of certain arguments.
10308         Since macros can access the arguments inside a parameter list,
10309         they can be used to create flow-control functions
10310         like those already built into newLISP.
10311 </p>
10312 <p>
10313         All parameters defined are optional.
10314         When a macro is called without arguments,
10315         those parameters assume the value <tt>nil</tt>.
10316         <!-- 8.9.4 -->If those parameters have a default value
10317         specified in <em>exp-default</em>,
10318         they assume that default value.
10319 </p>
10320
10321 <blockquote>
10322 <pre>
10323 (define-macro (foo (a 1) (b 2))
10324   (list a b))
10325
10326 (foo)      <span class=arw>&rarr;</span> (1 2)
10327 (foo 3)    <span class=arw>&rarr;</span> (3 2)
10328 (foo 3 4)  <span class=arw>&rarr;</span> (3 4)
10329 </pre>
10330 </blockquote>
10331
10332 <p>
10333         Expressions in <em>exp-default</em> are evaluated
10334         in the function's current environment.
10335 </p>
10336
10337 <blockquote>
10338 <pre>
10339 (define-macro (foo (a 10) (b (div a 2)))
10340   (list a b))
10341
10342 (foo)      <span class=arw>&rarr;</span> (10 5)
10343 (foo 30)   <span class=arw>&rarr;</span> (30 15)
10344 (foo 3 4)  <span class=arw>&rarr;</span> (3 4)
10345 </pre>
10346 </blockquote>
10347
10348 <p>
10349         Note that in macros, the danger exists of passing a parameter
10350         with the same variable name as used in the macro definition.
10351         In this case, the macro internal variable would end up
10352         receiving <tt>nil</tt> instead of the intended value:
10353 </p>
10354
10355 <blockquote>
10356 <pre>
10357 ;; not a good definition!
10358
10359 (define-macro (my-setq x y) (set x (eval y)))
10360
10361 ;; symbol name clash for x
10362
10363 (my-setq x 123)  <span class=arw>&rarr;</span> 123
10364 x                <span class=arw>&rarr;</span> nil
10365 </pre>
10366 </blockquote>
10367
10368 <p>
10369         There are several methods that can be used
10370         to avoid this problem, known as <em>variable capture</em>,
10371         and to write <em>hygienic</em> macros:
10372 </p>
10373
10374 <ul>
10375 <li>
10376         Prefix all macro variable names with an underscore character.
10377         Using this or a similar convention,
10378         the danger of symbol name clashes can be avoided.</li>
10379
10380 <li>
10381         Put the macro into its own lexically closed namespace context.
10382         If the function has the same name as the context,
10383         it can be called by using the context name alone.
10384         A function with this characteristic is called a
10385         <a href="#default_function"><em>default function</em></a>.
10386 </li>
10387
10388 <li>
10389         Use <a href="#args">args</a> to access
10390         arguments passed by the function.</li>
10391
10392 </ul>
10393
10394 <b>example:</b>
10395 <blockquote>
10396 <pre>
10397 ;; a macro as a lexically isolated function
10398 ;; avoiding variable capture in passed parameters
10399
10400 (context 'my-setq)
10401
10402 (define-macro (my-setq:my-setq x y) (set x (eval y)))
10403
10404 (context MAIN)
10405
10406 (my-setq x 123)  <span class=arw>&rarr;</span> 123  ; no symbol clash
10407 </pre>
10408 </blockquote>
10409
10410 <p>
10411         The macro in the example is lexically isolated,
10412         and no variable capture can occur.
10413         Instead of the macro being called using <tt>(my-setq:my-setq &hellip;)</tt>,
10414         it can be called with just <tt>(my-setq &hellip;)</tt>
10415         because it is a <a href="#default_function"><em>default function</em></a>.
10416 </p>
10417
10418 <p>
10419         A third possibility is to refer to passed parameters
10420         using <a href="#args">args</a>:
10421 </p>
10422
10423 <b>example:</b>
10424 <blockquote>
10425 <pre>
10426 ;; avoid variable capture in macros using the args function
10427
10428 (define-macro (my-setq) (set (args 0) (eval (args 1))))
10429 </pre>
10430 </blockquote>
10431
10432 <p>
10433         The last example shows how <a href="#letex">letex</a> can be combined with
10434         <tt>define-macro</tt> to expand macro variables into an expression to be evaluated: </p>
10435
10436 <b>example:</b>
10437 <blockquote>
10438 <pre>
10439 (define-macro (dolist-while)
10440   (letex (var (args 0 0)
10441           lst (args 0 1)
10442           cnd (args 0 2)
10443           body (cons 'begin (1 (args))))
10444     (let (res)
10445       (catch (dolist (var lst)
10446                (if (set 'res cnd) body (throw res)))))))
10447
10448 &gt; (dolist-while (x '(a b c d e f) (!= x 'd)) (println x))
10449 <strong>a
10450 b
10451 c
10452 nil</strong>
10453 &gt;
10454 </pre>
10455 </blockquote>
10456
10457 <p>
10458         <tt>dolist-while</tt> loops through a list
10459         while the condition is true.
10460         Note that a similar feature is already built into
10461         <a href="#dolust">dolist</a> as a <em>break condition</em>
10462         optional parameter.
10463 </p>
10464
10465 <p>
10466         Also, the <a href="#expand">expand</a> function performs variable
10467         expansion explicitly, without evaluating the expanded expression.
10468 </p>
10469
10470 <br /><br />
10471
10472 <a NAME="def-new"></a>
10473 <h2><span class="function">def-new</span></h2>
10474 <b>syntax: (def-new <em>sym-source</em> [<em>sym-target</em>])</b>
10475
10476 <p>
10477         This function works similarly to <a href="#new">new</a>,
10478         but it only creates a copy of one symbol
10479         and its contents from the symbol in <em>sym-source</em>.
10480         When <em>sym-target</em> is not given,
10481         a symbol with the same name is created
10482         in the current context.
10483         All symbols referenced inside <em>sym-source</em>
10484         will be translated into symbol references into the current context,
10485     which must not be MAIN.</p>
10486 <p>
10487         If an argument is present in <em>sym-target</em>,
10488         the copy will be made into a symbol and context
10489         as referenced by the symbol in <em>sym-target</em>.
10490         In addition to allowing renaming of the function while copying,
10491         this also enables the copy to be placed in a different context.
10492         All symbol references will be translated into symbol references
10493         of the target context.
10494 </p>
10495
10496 <p>
10497         <tt>def-new</tt> returns the symbol created:
10498 </p>
10499
10500 <b>example:</b>
10501 <blockquote>
10502 <pre>
10503 > (set 'foo:var '(foo:x foo:y))
10504 <b>(foo:x foo:y)</b>
10505
10506 > (def-new 'foo:var 'ct:myvar)
10507 <b>ct:myvar</b>
10508
10509 > ct:myvar
10510 <b>(ct:x ct:y)</b>
10511
10512 > (context 'K)
10513
10514 K> (def-new 'foo:var)
10515 <b>var</b>
10516
10517 K> var
10518 <b>(x y)</b>
10519 </pre>
10520 </blockquote>
10521
10522 <p>
10523         The function <tt>def-new</tt> can be used to configure contexts
10524         or context objects in a more granular fashion than is possible
10525         with <a href="#new">new</a>, which copies a whole context.
10526 </p>
10527
10528 <br /><br />
10529
10530 <a NAME="default"></a>
10531 <h2><span class="function">default</span></h2>
10532 <b>syntax: (default <em>context</em>)</b> <br />
10533
10534 <p>Returns the default functor of a context. The <em>default functor</em> is the
10535 symbol which carries the same name as the context it belongs to:</p>
10536
10537 <b>example:</b>
10538 <blockquote>
10539 <pre>
10540 (set 'foo:foo '(a b c d e f))
10541
10542 (set 'ctx foo)
10543
10544 (default foo) <span class=arw>&rarr;</span> foo:foo
10545 (default ctx) <span class=arw>&rarr;</span> foo:foo
10546
10547 (sort (eval (default ctx)) >)
10548
10549 foo:foo <span class=arw>&rarr;</span> (f e d c b a)
10550 </pre>
10551 </blockquote>
10552
10553 <br /><br />
10554
10555 <a NAME="delete"></a>
10556 <h2><span class="function">delete</span></h2>
10557 <b>syntax: (delete <em>symbol</em> [<em>bool</em>])</b> <br />
10558
10559 <b>syntax: (delete <em>sym-context</em> [<em>bool</em>])</b>
10560
10561 <p>
10562         Deletes a symbol, <em>symbol</em>, or a context in <em>sym-context</em>
10563         with all contained symbols from newLISP's symbol table.
10564         References to the symbol will be changed to <tt>nil</tt>.
10565         When the expression in <em>bool</em> evaluates
10566         to <tt>true</tt> or anything other than <tt>nil</tt>,
10567         symbols are only deleted when they are not referenced.
10568 </p>
10569
10570 <p>
10571         Protected symbols of built-in functions and special symbols
10572         like <tt>nil</tt> and <tt>true</tt> cannot be deleted.
10573 </p>
10574
10575 <p>
10576         <tt>delete</tt> returns <tt>true</tt> if the symbol was deleted,
10577         else it returns <tt>nil</tt>.
10578 </p>
10579
10580 <b>example:</b>
10581 <blockquote>
10582 <pre>
10583 (set 'lst '(a b aVar c d))
10584
10585 (delete 'aVar)  ; aVar deleted, references marked nil
10586
10587 lst  <span class=arw>&rarr;</span> (a b nil c d)
10588
10589 (set 'lst '(a b aVar c d))
10590
10591 (delete 'aVar true)
10592 <span class=arw>&rarr;</span> nil ; protect aVar if referenced
10593
10594 lst  <span class=arw>&rarr;</span> (a b aVar c d)
10595
10596 (set 'foo:x 123)
10597 (set 'foo:y "hello")
10598
10599 ;; in contexts, the quote may be omitted
10600 (delete foo)  <span class=arw>&rarr;</span> foo:x, foo:y deleted
10601 </pre>
10602 </blockquote>
10603
10604 <p>In the last example only the symbols inside context <tt>foo</tt>
10605 will be deleted but not the context symbol <tt>foo</tt> itself. It
10606 will be converted to a normal unprotected symbol and contain <tt>nil</tt>.
10607 </p>
10608
10609 <p>
10610         Note that deleting a symbol that is part of a function
10611         which is currently executing can crash the system
10612         or have other unforeseen effects.
10613 </p>
10614
10615
10616 <br /><br />
10617
10618
10619 <a NAME="delete-file"></a>
10620 <h2><span class="function">delete-file</span></h2>
10621 <b>syntax: (delete-file <em>str-file-name</em>)</b>
10622
10623 <p>
10624         Deletes a file given in <em>str-file-name</em>.
10625         Returns <tt>true</tt> or <tt>nil</tt> depending
10626         on the outcome of the delete operation.
10627 </p>
10628
10629 <p>The file name can be given as a URL.</p>
10630
10631 <b>example:</b>
10632 <blockquote>
10633 <pre>
10634 (delete-file "junk")
10635
10636 (delete-file "http://asite.com/example.html")
10637 </pre>
10638 </blockquote>
10639 <p>
10640 The first example deletes the file <tt>junk</tt> in the current directory.
10641 The second example shows how to use a URL to specify the file.
10642 In this form, additional parameters can be given.
10643 See <a href="#delete-url">delete-url</a> for details.
10644 </p>
10645
10646 <br /><br />
10647
10648 <a NAME="destroy"></a>
10649 <h2><span class="function">destroy</span></h2>
10650 <b>syntax: (destroy <em>int-pid</em>)</b>
10651
10652 <p>Destroys a process with process id in <em>int-pid</em> and returns <tt>true</tt>
10653 on success or <tt>nil</tt> on failure. The process id is obtained from a previous
10654 call to <a href="#fork">fork</a> on Mac OS X and other UNIX or <a href="#process">process</a>.
10655 on all platforms.
10656 </p>
10657
10658 <b>example:</b>
10659 <blockquote>
10660 <pre>
10661 (set 'pid (process "/usr/bin/bc" bcin bcout))
10662 (destroy pid)
10663
10664 (set 'pid (fork (dotimes (i 1000) (println i) (sleep 10))))
10665 (sleep 100) (destroy pid)
10666 </pre>
10667 </blockquote>
10668
10669 <br /><br />
10670
10671 <a NAME="det"></a>
10672 <h2><span class="function">det</span></h2>
10673 <b>syntax: (det <em>matrix</em>)</b>
10674
10675 <p>
10676         Returns the determinant of a square matrix.
10677         A matrix can either be a nested list
10678         or an <a href="#array">array</a>.
10679 </p>
10680
10681 <b>example:</b>
10682 <blockquote>
10683 <pre>
10684 (set 'A '((-1 1 1) (1 4 -5) (1 -2 0)))
10685
10686 (det A)  <span class=arw>&rarr;</span> -1
10687 </pre>
10688 </blockquote>
10689
10690 <p>
10691         If the matrix is singular,
10692         <tt>nil</tt> is returned.
10693 </p>
10694
10695
10696 <p>See also the other matrix operations
10697 <a href="#invert">invert</a>, <a href="#mat">mat</a>,
10698 <a href="#multiply">multiply</a> and <a href="#transpose">transpose</a>.
10699 </p>
10700
10701 <br />
10702
10703 <a NAME="device"></a>
10704 <h2><span class="function">device</span></h2>
10705 <b>syntax: (device [<em>int</em>])</b>
10706
10707 <p>
10708         <em>int</em> is an I/O device number, which is 0 (zero)
10709         for the default STD I/O console window.
10710         <em>int</em> may also be a file handle
10711         previously obtained using <a href="#open">open</a>.
10712         When no argument is supplied,
10713         the current I/O device number is returned.
10714         The I/O channel specified by <tt>device</tt>
10715         is used internally by the functions
10716         <a HREF="#print">print</a> and <a HREF="#read-line">read-line</a>.
10717         When the current I/O device is 0 (zero), <a HREF="#print">print</a>
10718         sends output to the console window and <a HREF="#read-line">read-line</a>
10719         accepts input from the keyboard.
10720         If the current I/O device has been set by opening a file,
10721         then <a HREF="#print">print</a> and <a HREF="#read-line">read-line</a> work on that file.
10722 </p>
10723
10724 <b>example:</b>
10725 <blockquote>
10726 <pre>
10727 (device (open "myfile" "write"))  <span class=arw>&rarr;</span> 5
10728 (print "This goes in myfile")     <span class=arw>&rarr;</span> "This goes in myfile"
10729 (close (device))                  <span class=arw>&rarr;</span> true
10730 </pre>
10731 </blockquote>
10732
10733 <p>
10734         Note that using <a HREF="#close">close</a> on <tt>device</tt>
10735         automatically resets <tt>device</tt> to 0 (zero).
10736 </p>
10737
10738 <br /><br />
10739
10740 <a NAME="delete-url"></a>
10741 <h2><span class="function">delete-url</span></h2>
10742 <b>syntax: (delete-file <em>str-url</em>)</b>
10743
10744 <p>This function deletes the file
10745 on a remote HTTP server
10746 specified in <em>str-url</em>.
10747 The HTTP <tt>DELETE</tt> protocol
10748 must be enabled on the target web server,
10749 or an error message string may be returned.
10750 The target file must also have
10751 access permissions set accordingly.
10752 Additional parameters such as timeout and custom headers
10753 are available exactly as in the
10754 <a href="#get-url">get-url</a> function.</p>
10755
10756 <p>This feature is also available when the <a href="#delete-file">delete-file</a>
10757 function is used and a URL is specified for the filename.</p>
10758
10759 <b>example:</b>
10760 <blockquote>
10761 <pre>
10762 (delete-url "http://www.aserver.com/somefile.txt")
10763 (delete-url "http://site.org:8080/page.html" 5000)
10764 </pre>
10765 </blockquote>
10766
10767 <p>The second example configures a timeout option of five seconds.
10768 Other options such as special HTTP protocol headers
10769 can be specified, as well.
10770 See the <a href="#get-url">get-url</a> function for details.</p>
10771
10772 <br /><br />
10773
10774 <a NAME="difference"></a>
10775 <h2><span class="function">difference</span></h2>
10776 <b>syntax: (difference <em>list-A</em> <em>list-B</em>)</b><br />
10777 <b>syntax: (difference <em>list-A</em> <em>list-B</em> <em>bool</em>)</b>
10778
10779 <p>
10780         In the first syntax, <tt>difference</tt> returns
10781         the <em>set</em> difference between <em>list-A</em> and <em>list-B</em>.
10782         The resulting list only has elements occurring in <em>list-A</em>,
10783         but not in <em>list-B</em>.
10784         All elements in the resulting list are unique,
10785         but <em>list-A</em> and <em>list-B</em> need not be unique.
10786         Elements in the lists can be any type of LISP expression.
10787 </p>
10788
10789 <b>example:</b>
10790 <blockquote>
10791 <pre>
10792 (difference '(2 5 6 0 3 5 0 2) '(1 2 3 3 2 1))  <span class=arw>&rarr;</span> (5 6 0)
10793 </pre>
10794 </blockquote>
10795
10796 <p>
10797         In the second syntax, <tt>difference</tt> works in <em>list</em> mode.
10798         <em>bool</em> specifies <tt>true</tt>
10799         or an expression not evaluating to <tt>nil</tt>.
10800         In the resulting list, all elements of <em>list-B</em>
10801         are eliminated in <em>list-A</em>,
10802         but duplicates of other elements in <em>list-A</em> are left.
10803 </p>
10804 <b>example:</b>
10805 <blockquote>
10806 <pre>
10807 (difference '(2 5 6 0 3 5 0 2) '(1 2 3 3 2 1) true)  <span class=arw>&rarr;</span> (5 6 0 5 0)
10808 </pre>
10809 </blockquote>
10810
10811
10812 <p>
10813         See also the set functions <a HREF="#intersect">intersect</a>
10814         and <a HREF="#unique">unique</a>.
10815 </p>
10816
10817 <br /><br />
10818
10819 <a NAME="directory"></a>
10820 <h2><span class="function">directory</span></h2>
10821 <b>syntax: (directory [<em>str-path</em>])</b><br />
10822 <b>syntax: (directory <em>str-path</em> <em>str-pattern</em> [<em>int-option</em>])</b>
10823
10824 <p>
10825         A list of directory entry names is returned
10826         for the directory path given in <em>str-path</em>.
10827         On failure, <tt>nil</tt> is returned.
10828         When <em>str-path</em> is omitted,
10829         the list of entries in the current directory is returned.
10830 </p>
10831
10832 <b>example:</b>
10833 <blockquote>
10834 <pre>
10835 (directory "/bin")
10836
10837 (directory "c:/")
10838 </pre>
10839 </blockquote>
10840
10841 <p>
10842         The first example returns the directory of <tt>/bin</tt>,
10843         the second line returns a list of directory entries
10844         in the root directory of drive C:.
10845         Note that on Win32 systems,
10846         a forward slash (<tt>/</tt>) can be included in path names.
10847         When used, a backslash (<tt>\</tt>) must be
10848         preceded by a second backslash.
10849 </p>
10850
10851 <p>
10852         In the second syntax, <tt>directory</tt> can take
10853         a regular expression pattern in <em>str-pattern</em>.
10854         Only filenames matching the pattern will be returned
10855         in the list of directory entries.
10856         In <em>int-options</em>, special regular expression options
10857         can be specified; see <a href="#regex">regex</a> for details.
10858 </p>
10859
10860 <b>example:</b>
10861 <blockquote>
10862 <pre>
10863 (directory "." "\\.c")  <span class=arw>&rarr;</span> ("foo.c" "bar.c")
10864 ;; or using braces as string pattern delimiters
10865 (directory "." {\.c})  <span class=arw>&rarr;</span> ("foo.c" "bar.c")
10866
10867 ; show only hidden files (starting with dot)
10868 (directory "." "^[.]")   <span class=arw>&rarr;</span> ("." ".." ".profile" ".rnd" ".ssh")</pre>
10869 </blockquote>
10870
10871 <p>
10872         The regular expression forces <tt>directory</tt>
10873         to return only file names containing the string <tt>".c"</tt>.
10874 </p>
10875
10876 <p>
10877         Other functions that use regular expressions
10878         are <a href="#find">find</a>, <!-- 8.9.4 --><a href="#find-all">find-all</a>,
10879         <a href="#parse">parse</a>,
10880         <a HREF="#regex">regex</a>, <a href="#replace">replace</a>,
10881         and <a href="#search">search</a>.
10882 </p>
10883
10884
10885 <br /><br />
10886
10887 <a NAME="directoryp"></a>
10888 <h2><span class="function">directory?</span></h2>
10889 <b>syntax: (directory? <em>str-path</em>)</b>
10890
10891 <p>
10892         Checks if <em>str-path</em> is a directory.
10893         Returns <tt>true</tt> or <tt>nil</tt> depending on the outcome.
10894 </p>
10895
10896 <blockquote>
10897 <pre>
10898 (directory? "/etc")            <span class=arw>&rarr;</span> true
10899 (directory? "/usr/bin/emacs/")  <span class=arw>&rarr;</span> nil
10900 </pre>
10901 </blockquote>
10902
10903 <br /><br />
10904
10905 <a NAME="div"></a>
10906 <h2><span class="function">div</span></h2>
10907 <b>syntax: (div <em>num-1</em> <em>num-2</em> [<em>num-3</em> ... ])</b><br />
10908 <b>syntax: (div <em>num-1</em>)</b>
10909
10910 <p>
10911         Successively divides <em>num-1</em>
10912         by the number in <em>num-2&mdash;</em>.
10913         <tt>div</tt> can perform mixed-type arithmetic,
10914         but it always returns floating point numbers.
10915         Any floating point calculation
10916         with <tt>NaN</tt> also returns <tt>NaN</tt>.
10917 </p>
10918
10919
10920 <b>example:</b>
10921 <blockquote>
10922 <pre>
10923 (div 10 3)                 <span class=arw>&rarr;</span> 3.333333333
10924 (div 120 (sub 9.0 6) 100)  <span class=arw>&rarr;</span> 0.4
10925
10926 (div 10)                   <span class=arw>&rarr;</span> 0.1
10927 </pre>
10928 </blockquote>
10929
10930 <p>
10931         When <em>num-1</em> is the only argument,
10932         <tt>div</tt> calculates the inverse of <em>num-1</em>.
10933 </p>
10934
10935 <br /><br />
10936
10937 <a NAME="doargs"></a>
10938 <h2><span class="function">doargs</span></h2>
10939 <b>syntax: (doargs (<em>sym</em> [<em>exp-break</em>])<em> body</em>)</b>
10940
10941 <p>Iterates through all members of the argument list
10942 inside a user-defined function or macro. This function or macro can be defined using <a href="#define">define</a>,
10943 <a href="#define-macro">define-macro</a>, <a href="#lambda">lambda</a>, or
10944 <a href="#lambda-macro">lambda-macro</a>.
10945 The variable in <em>sym</em>
10946 is set sequentially to all members in the argument list
10947 until the list is exhausted
10948 or an optional break expression
10949 (defined in <em>exp-break</em>)
10950 evaluates to <tt>true</tt> or a logical true value.
10951 The <tt>doargs</tt> expression always returns
10952 the result of the last evaluation.</p>
10953
10954 <b>example:</b>
10955 <blockquote>
10956 <pre>
10957 (define (foo)
10958     (doargs (i) (println i)))
10959
10960 <b>&gt;</b> (foo 1 2 3 4 5)
10961 <b>1
10962 2
10963 3
10964 4
10965 5</b>
10966 </pre>
10967 </blockquote>
10968
10969 <p>The optional break expression causes <tt>doargs</tt>
10970 to interrupt processing of the arguments:</p>
10971
10972 <blockquote>
10973 <pre>
10974 (define-macro (foo)
10975     (doargs (i (= i 'x))
10976         (println i)))
10977
10978 <b>&gt;</b> (foo a b c x e f g)
10979 <b>a
10980 b
10981 c
10982 true</b>
10983 </pre>
10984 </blockquote>
10985
10986 <p>Use the <a href="#args">args</a> function
10987 to access the entire argument list at once.</p>
10988
10989 <br /><br />
10990
10991 <a NAME="dolist"></a>
10992 <h2><span class="function">dolist</span></h2>
10993 <b>syntax: (dolist (<em>sym  list</em> [<em>exp-break</em>])<em> body</em>)</b>
10994
10995 <p>
10996         The expressions in <em>body</em> are evaluated
10997         for each element in <em>list</em>.
10998         The variable in <em>sym</em> is set to each of the elements
10999         before evaluation of the body expressions.
11000         The variable used as loop index is local
11001         and behaves according to the rules of dynamic scoping.
11002 </p>
11003
11004 <p>
11005         Optionally, a condition for early loop exit
11006         may be defined in <em>exp-break</em>.
11007         If the break expression evaluates to any non-<tt>nil</tt> value,
11008         the <tt>dolist</tt> loop returns with the value of <em>exp-break</em>.
11009         The break condition is tested before evaluating <em>body.</em></p>
11010
11011 <b>example:</b>
11012 <blockquote>
11013 <pre>
11014 (set 'x 123)
11015 (dolist (x '(a b c d e f g))  ; prints: abcdefg
11016     (print x))  <span class=arw>&rarr;</span> g          ; return value
11017
11018 (dolist (x '(a b c d e f g) (= x 'e))  ; prints: abcd
11019     (print x))
11020
11021 ;; x is local in dolist
11022 ;; x has still its old value outside the loop
11023
11024 x  <span class=arw>&rarr;</span> 123  ; x has still its old value
11025 </pre>
11026 </blockquote>
11027
11028 <p>
11029         This example prints <tt>abcdefg</tt> in the console window.
11030         After the execution of <tt>dolist</tt>,
11031         the value for <tt>x</tt> remains unchanged
11032         because the <tt>x</tt> in <tt>dolist</tt> has local scope.
11033         The return value of <tt>dolist</tt> is the result
11034         of the last evaluated expression.
11035 </p>
11036
11037 <p>
11038         The internal system variable <tt>$idx</tt>
11039         keeps track of the current offset
11040         into the list passed to <tt>dolist</tt>,
11041         and it can be accessed during its execution:
11042 </p>
11043
11044 <blockquote>
11045 <pre>
11046 (dolist (x '(a b d e f g))
11047   (println $idx ":" x))  <span class=arw>&rarr;</span> g
11048
11049 <b>0:a
11050 1:b
11051 2:d
11052 3:e
11053 4:f
11054 5:g</b>
11055 </pre>
11056 </blockquote>
11057
11058 <p>
11059         The console output is shown in boldface.
11060         <tt>$idx</tt> is protected and cannot be changed by the user.
11061 </p>
11062
11063 <br /><br />
11064
11065 <a NAME="dostring"></a>
11066 <h2><span class="function">dostring</span></h2>
11067 <b>syntax: (dostring (<em>sym  string</em> [<em>exp-break</em>])<em>body</em>)</b>
11068
11069 <p>
11070         The expressions in <em>body</em> are evaluated
11071         for each character in <em>string</em>.
11072         The variable in <em>sym</em> is set to each ASCII or UTF-8 integer value of the characters
11073         before evaluation of the body expressions.
11074         The variable used as loop index is local
11075         and behaves according to the rules of dynamic scoping.
11076 </p>
11077
11078 <p>
11079         Optionally, a condition for early loop exit
11080         may be defined in <em>exp-break</em>.
11081         If the break expression evaluates to any non-<tt>nil</tt> value,
11082         the <tt>dolist</tt> loop returns with the value of <em>exp-break</em>.
11083         The break condition is tested before evaluating <em>body.</em>
11084 </p>
11085
11086 <b>example:</b>
11087 <blockquote>
11088 <pre>
11089 (set 'str "abcdefg")
11090 (dostring (c str)
11091         (println i))
11092 <b>97
11093 98
11094 99
11095 100
11096 101
11097 102
11098 103</b>
11099 </pre>
11100 </blockquote>
11101
11102 <p>
11103         This example prints prints the value of each character
11104     in the console window. In UTF-8 enabled versions of newLISP
11105     individual characters may be longer than one byte and the
11106     number in the loop variable may exceed 255.
11107         The return value of <tt>dostring</tt> is the result
11108         of the last evaluated expression.
11109 </p>
11110
11111 <p>
11112         The internal system variable <tt>$idx</tt>
11113         keeps track of the current offset
11114         into the list passed to <tt>dostring</tt>,
11115         and it can be accessed during its execution.
11116 </p>
11117 <br></br>
11118
11119 <a NAME="dotimes"></a>
11120 <h2><span class="function">dotimes</span></h2>
11121 <b>syntax: (dotimes (<em>sym-var</em> <em>int-count</em> [<em>exp-break</em>]) <em>body</em>)</b>
11122
11123 <p>
11124         The expressions in <em>body</em> are evaluated <em>int</em> times.
11125         The variable in <em>sym</em> is set from 0 (zero) to (<em>int</em> - 1)
11126         each time before evaluating the body expression(s).
11127         The variable used as the loop index is local to the <tt>dotimes</tt>
11128         expression and behaves according the rules of dynamic scoping.
11129         The loop index is of integer type.
11130         <tt>dotimes</tt> returns the result of
11131         the last expression evaluated in <em>body</em>.
11132 </p>
11133
11134 <p>
11135         Optionally, a condition for early loop exit
11136         may be defined in <em>exp-break</em>.
11137         If the break expression evaluates to any non-<tt>nil</tt> value,
11138         the <tt>dotimes</tt> loop returns with the value of <em>exp-break</em>.
11139         The break condition is tested before evaluating <em>body</em>.
11140 </p>
11141
11142 <b>example:</b>
11143 <blockquote>
11144 <pre>
11145 (dotimes (x 10)
11146   (print x))  <span class=arw>&rarr;</span> 9  ; return value
11147 </pre>
11148 </blockquote>
11149
11150 <p>
11151         This prints <tt>0123456789</tt> to the console window.
11152 </p>
11153
11154 <br /><br />
11155
11156 <a NAME="dotree"></a>
11157 <h2><span class="function">dotree</span></h2>
11158 <b>syntax: (dotree (<em>sym-context</em>) <em>body</em>)</b>
11159
11160 <p>
11161         The expressions in <em>body</em> are evaluated
11162         for all symbols in <em>sym-context</em>.
11163         The symbols are accessed in a sorted order.
11164         Before each evaluation of the body expression(s),
11165         the variable in <em>sym</em> is set
11166         to the next symbol from <em>sym-context</em>.
11167         The variable used as the loop index is local
11168         to the <tt>dotree</tt> expression
11169         and behaves according the rules of dynamic scoping.
11170 </p>
11171
11172 <b>example:</b>
11173 <blockquote>
11174 <pre>
11175 ;; faster and less memory overhead
11176 (dotree (s 'SomeCTX) (print s " "))
11177
11178 ;; the quote can be omitted
11179 (dotree (s SomeCTX) (print s " "))
11180
11181 ;; slower and more memory usage
11182 (dolist (s (symbols 'SomeCTX)) (print s " "))
11183 </pre>
11184 </blockquote>
11185
11186 <p>
11187         This example prints the names of all symbols inside SomeCTX to the console window.
11188 </p>
11189
11190 <br /><br />
11191
11192 <a NAME="do-until"></a>
11193
11194 <h2><span class="function">do-until</span></h2>
11195 <b>syntax: (do-until <em>exp-condition body</em>)</b>
11196
11197 <p>
11198         The expressions in <em>body</em> are evaluated
11199         before <em>exp-condition</em> is evaluated.
11200         If the evaluation of <em>exp-condition</em> is not <tt>nil</tt>,
11201         then the <tt>do-until</tt> expression is finished;
11202         otherwise, the expressions in <em>body</em> get evaluated again.
11203         Note that <tt>do-until</tt> evaluates the conditional expression
11204         <em>after</em> evaluating the body expressions,
11205         whereas <a href="#until">until</a> checks the condition
11206         <em>before</em> evaluating the body.
11207         The return value of the <tt>do-until</tt> expression
11208         is the last evaluation of the <em>body</em> expression.
11209 </p>
11210
11211 <b>example:</b>
11212 <blockquote>
11213 <pre>
11214 (set 'x 1)
11215 (do-until (= x 1) (inc 'x))
11216 x  <span class=arw>&rarr;</span> 2
11217
11218 (set 'x 1)
11219 (until (= x 1) (inc 'x))
11220 x  <span class=arw>&rarr;</span> 1
11221 </pre>
11222 </blockquote>
11223
11224 <p>
11225         While <tt>do-until</tt> goes through the loop at least once,
11226         <a href="#until">until</a> never enters the loop.
11227 </p>
11228
11229 <p>
11230         See also the functions <a href="#while">while</a>
11231         and <a href="#do-while">do-while</a>.
11232 </p>
11233
11234 <br /><br />
11235
11236 <a NAME="do-while"></a>
11237 <h2><span class="function">do-while</span></h2>
11238 <b>syntax: (do-while <em>exp-condition body</em>)</b>
11239
11240 <p>
11241         The expressions in <em>body</em> are evaluated
11242         before <em>exp-condition</em> is evaluated.
11243         If the evaluation of <em>exp-condition</em> is <tt>nil</tt>,
11244         then the <tt>do-while</tt> expression is finished;
11245         otherwise the expressions in <em>body</em> get evaluated again.
11246         Note that <tt>do-while</tt> evaluates the conditional expression
11247         <em>after</em> evaluating the body expressions,
11248         whereas <a href="#while">while</a> checks the condition
11249         <em>before</em> evaluating the body.
11250         The return value of the <tt>do-while</tt> expression
11251         is the last evaluation of the <em>body</em> expression.
11252 </p>
11253
11254
11255 <b>example:</b>
11256 <blockquote>
11257 <pre>
11258 (set 'x 10)
11259 (do-while (&lt; x 10) (inc 'x))
11260 x  <span class=arw>&rarr;</span> 11
11261
11262 (set 'x 10)
11263 (while (&lt; x 10) (inc 'x))
11264 x  <span class=arw>&rarr;</span> 10
11265 </pre>
11266 </blockquote>
11267
11268 <p>
11269         While <tt>do-while</tt> goes through the loop at least once,
11270         <a href="#while">while</a> never enters the loop.
11271 </p>
11272
11273 <p>
11274         See also the functions <a href="#until">until</a>
11275         and <a  href="#do-until">do-until</a>.
11276 </p>
11277
11278 <br /><br />
11279
11280 <a name="dump"></a>
11281 <h2><span class="function">dump</span></h2>
11282 <b>syntax: (dump [<em>exp</em>])</b>
11283
11284 <p>
11285         Shows the binary contents of a newLISP cell.
11286         Without an argument, this function outputs
11287         a listing of all LISP cells to the console.
11288         When <em>exp</em> is given,
11289         it is evaluated and the contents
11290         of a LISP cell are returned in a list.
11291 </p>
11292
11293 <b>example:</b>
11294 <blockquote>
11295 <pre>
11296 (dump 'a)   <span class=arw>&rarr;</span> (9586996 5 9578692 9578692 9759280)
11297
11298 (dump 999)  <span class=arw>&rarr;</span> (9586996 130 9578692 9578692 999)
11299 </pre>
11300 </blockquote>
11301
11302 <p>
11303         The list contains the following memory addresses and information:
11304 </p>
11305
11306 <pre>
11307     (0) memory address of the LISP cell
11308     (1) cell-&gt;type: mayor/minor type, see newlisp.h for details
11309     (2) cell-&gt;next: linked list ptr
11310     (3) cell-&gt;aux:
11311                     string length+1 or
11312                     low (little endian) or high (big endian) word of 64-bit integer or
11313                     low word of IEEE 754 double float
11314     (4) cell-&gt;contents:
11315                     string/symbol address or
11316                     high (little endian) or low (big endian) word of 64-bit integer or
11317                     high word of IEEE 754 double float
11318 </pre>
11319
11320 <p>
11321         This function is valuable for changing type bits in cells
11322         or hacking other parts of newLISP internals.
11323         See the function <a href="#cpymem">cpymem</a>
11324         for a comprehensive example.
11325 </p>
11326
11327 <br /><br />
11328
11329
11330 <a NAME="dup"></a>
11331 <h2><span class="function">dup</span></h2>
11332
11333 <b>syntax: (dup <em>exp</em> <em>int-n</em> [<em>bool</em>])</b><br/>
11334 <b>syntax: (dup <em>exp</em>)</b>
11335
11336 <p>
11337         If the expression in <em>exp</em> evaluates to a string,
11338         it will be replicated <em>int-n</em> times within a string and returned.
11339         When specifying an expression evaluating
11340         to anything other than <tt>nil</tt> in <em>bool</em>,
11341         the string will not be concatenated
11342         but replicated in a list like any other data type.
11343 </p>
11344
11345 <p>
11346         If <em>exp</em> contains any data type other than string,
11347         the returned list will contain <em>int-n</em> evaluations of <em>exp</em>.
11348 </p>
11349
11350 <p>Without the repetition parameter <tt>dup</tt> assumes 2.</p>
11351
11352 <b>example:</b>
11353 <blockquote>
11354 <pre>
11355 (dup "A" 6)       <span class=arw>&rarr;</span> "AAAAAA"
11356 (dup "A" 6 true)  <span class=arw>&rarr;</span> ("A" "A" "A" "A" "A" "A")
11357 (dup "A" 0)       <span class=arw>&rarr;</span> ""
11358 (dup "AB" 5)      <span class=arw>&rarr;</span> "ABABABABAB"
11359 (dup 9 7)         <span class=arw>&rarr;</span> (9 9 9 9 9 9 9)
11360 (dup 9 0)         <span class=arw>&rarr;</span> ()
11361 (dup 'x 8)        <span class=arw>&rarr;</span> (x x x x x x x x)
11362 (dup '(1 2) 3)    <span class=arw>&rarr;</span> ((1 2) (1 2) (1 2))
11363 (dup "\000" 4)    <span class=arw>&rarr;</span> "\000\000\000\000"
11364
11365 (dup "*")         <span class=arw>&rarr;</span> "**"
11366 </pre>
11367 </blockquote>
11368
11369 <p>
11370         The last example shows handling of binary information,
11371         creating a string filled with four binary zeroes.
11372 </p>
11373
11374 <p>
11375         See also the functions <a href="#sequence">sequence</a>
11376         and <a href="#series">series</a>.
11377 </p>
11378
11379 <br /><br />
11380
11381 <a NAME="emptyp"></a>
11382 <h2><span class="function">empty?</span></h2>
11383 <b>syntax: (empty? <em>exp</em>)</b><br />
11384 <b>syntax: (empty? <em>str</em>)</b>
11385
11386
11387 <p>
11388         <em>exp</em> is tested for an empty list
11389         (or <em>str</em> for an empty string).
11390         Depending on whether the argument contains elements,
11391         <tt>true</tt> or <tt>nil</tt> is returned.
11392 </p>
11393
11394 <b>example:</b>
11395 <blockquote>
11396 <pre>
11397 (set 'var '())
11398 (empty? var)         <span class=arw>&rarr;</span> true
11399 (empty? '(1 2 3 4))  <span class=arw>&rarr;</span> nil
11400 (empty? "hello")     <span class=arw>&rarr;</span> nil
11401 (empty? "")          <span class=arw>&rarr;</span> true
11402 </pre>
11403 </blockquote>
11404
11405 <p>
11406         The first example checks a list,
11407         while the second two examples check a string.
11408 </p>
11409
11410 <br /><br />
11411
11412 <a NAME="encrypt"></a>
11413 <h2><span class="function">encrypt</span></h2>
11414 <b>syntax: (encrypt <em>str-source</em> <em>str-pad</em>)</b>
11415
11416 <p>
11417         Performs a one-time&ndash;pad encryption of <em>str-source</em>
11418         using the encryption pad in <em>str-pad</em>.
11419         The longer <em>str-pad</em> is
11420         and the more random the bytes are,
11421         the safer the encryption.
11422         If the pad is as long as the source text,
11423         is fully random, and is used only once,
11424         then one-time&ndash;pad encryption
11425         is virtually impossible to break,
11426         since the encryption seems to contain only random data.
11427         To retrieve the original,
11428         the same function and pad
11429         are applied again to the encrypted text:
11430 </p>
11431
11432 <b>example:</b>
11433 <blockquote>
11434 <pre>
11435 (set 'secret
11436   (encrypt "A secret message" "my secret key"))
11437 <span class=arw>&rarr;</span> ",YS\022\006\017\023\017TM\014\022\n\012\030E"
11438
11439 (encrypt secret "my secret key")  <span class=arw>&rarr;</span> "A secret message"
11440 </pre>
11441 </blockquote>
11442
11443 <p>
11444         The second example encrypts a whole file:
11445 </p>
11446
11447 <blockquote>
11448
11449 <pre>
11450 (write-file "myfile.enc"
11451   (encrypt (read-file "myfile") "29kH67*"))
11452 </pre>
11453 </blockquote>
11454
11455 <br /><br />
11456
11457 <a NAME="ends-with"></a>
11458 <h2><span class="function">ends-with</span></h2>
11459 <!-- 8.9.4 -->
11460 <b>syntax: (ends-with <em>str-data</em> <em>str-key</em> [<em>option</em>] )</b><br />
11461 <!-- 8.9.0
11462 <b>syntax: (ends-with <em>str-data str-key</em> [<em>bool</em>] )</b><br /> -->
11463 <b>syntax: (ends-with <em>list</em> <em>exp</em>)</b>
11464
11465 <p>
11466         In the first syntax, <tt>ends-with</tt> tests
11467         the string in <em>str-data</em> to see if it
11468         ends with the string specified in <em>str-key</em>.
11469         It returns <tt>true</tt> or <tt>nil</tt>
11470         depending on the outcome. </p>
11471 <p>
11472         When <tt>nil</tt> or any expression evaluating to nil
11473         as a third parameter in <em>bool</em> is specified,
11474         the comparison is case-insensitive.
11475 </p>
11476
11477 <!-- 8.9.4 -->
11478 <p>If a regular expression <em>option</em> number is
11479 specified <em>str-key</em> contains a regular expression pattern. See
11480 <a href="#regex">regex</a> for valid numbers for <em>option</em>.
11481 </p>
11482
11483 <b>example:</b>
11484 <blockquote>
11485 <pre>
11486 (ends-with "newLISP" "LISP")         <span class=arw>&rarr;</span> true
11487 (ends-with "newLISP" "lisp")         <span class=arw>&rarr;</span> nil
11488 (ends-with "newLISP" "lisp" nil)     <span class=arw>&rarr;</span> true
11489 <!-- 8.9.4 -->;; use regular espressions
11490 (ends-with "newLISP" "lisp|york" 1)  <span class=arw>&rarr;</span> true
11491
11492 </pre>
11493 </blockquote>
11494
11495 <p>
11496         In the second syntax,
11497         <tt>ends-with</tt> checks if a list
11498         ends with the list element in <em>exp</em>.
11499         <tt>true</tt> or <tt>nil</tt> is returned depending on outcome.
11500 </p>
11501
11502 <b>example:</b>
11503 <blockquote>
11504 <pre>
11505 (ends-with '(1 2 3 4 5) 5)             <span class=arw>&rarr;</span> true
11506 (ends-with '(a b c d e) 'b)            <span class=arw>&rarr;</span> nil
11507 (ends-with '(a b c (+ 3 4)) '(+ 3 4))  <span class=arw>&rarr;</span> true
11508 </pre>
11509 </blockquote>
11510
11511 <p>
11512         The last example shows that <em>exp</em> could be a list by itself.
11513 </p>
11514
11515 <p>
11516         See also the <a HREF="#starts-with">starts-with</a> function.
11517 </p>
11518
11519 <br /><br />
11520
11521 <a NAME="env"></a>
11522
11523 <h2><span class="function">env</span></h2>
11524 <b>syntax: (env)</b><br />
11525 <b>syntax: (env <em>var-str</em>)</b><br />
11526 <b>syntax: (env <em>var-str</em> <em>value-str</em>)</b>
11527
11528 <p>
11529         In the first syntax (without arguments),
11530         the operating system's environment is
11531         retrieved as a list in which each entry is a string.
11532 </p>
11533
11534 <b>example:</b>
11535 <blockquote>
11536 <pre>
11537 (env)  <span class=arw>&rarr;</span> ("PATH=/bin:/usr/bin:/sbin" "USER=LUTZ")
11538 </pre>
11539 </blockquote>
11540
11541 <p>
11542         In the second syntax,
11543         the name of an environment variable
11544         is given in <em>var-str</em>.
11545         <tt>env</tt> returns the value
11546         of the variable or <tt>nil</tt>
11547         if the variable does not exist
11548         in the environment.
11549 </p>
11550
11551 <b>example:</b>
11552 <blockquote>
11553 <pre>
11554 (env "PATH")  <span class=arw>&rarr;</span> "/bin:/usr/bin:/usr/local/bin"
11555 </pre>
11556 </blockquote>
11557
11558 <p>
11559 The third syntax (variable name in <em>var-str</em>
11560 and value pair in <em>value-str</em>) sets or creates
11561 an environment variable. If <em>value-str</em> is the
11562 empty string <tt>""</tt>, then the variable is completely
11563 removed from the environment except when running on Solaris,
11564 wjere the variable stays with an empty string.
11565 </p>
11566
11567 <b>example:</b>
11568 <blockquote>
11569 <pre>
11570 (env "NEWLISPBIN" "/usr/bin/")  <span class=arw>&rarr;</span> true
11571 (env "NEWLISPBIN")              <span class=arw>&rarr;</span> "/usr/bin/"
11572 (env "NEWLISPBIN" "")           <span class=arw>&rarr;</span> true
11573 (env "NEWLISPBIN")              <span class=arw>&rarr;</span> nil
11574 </pre>
11575 </blockquote>
11576
11577 <p>
11578         <tt>env</tt> replaces the deprecated <tt>environ</tt>,
11579         <tt>getenv</tt>, and <tt>putenv</tt> functions.
11580 </p>
11581
11582 <br /><br />
11583
11584 <a NAME="erf"></a>
11585 <h2><span class="function">erf</span></h2>
11586 <b>syntax: (erf <em>num</em>)</b>
11587
11588 <p>
11589         <tt>erf</tt> calculates the error function
11590         of a number in <em>num</em>.
11591         The error function is defined as:
11592 </p>
11593
11594 <blockquote>
11595 <b><em>erf (x) = 2/sqrt(pi) * integral from 0 to x of exp(-t^2) dt</em></b>
11596 </blockquote>
11597
11598 <b>example:</b>
11599 <blockquote>
11600 <pre>
11601 (map erf (sequence 0.0 6.0 0.5))
11602 <span class=arw>&rarr;</span>
11603 (0 0.5204998778 0.8427007929 0.9661051465 0.995322265 0.999593048
11604  0.9999779095 0.9999992569 0.9999999846 0.9999999998 1 1 1)
11605 </pre>
11606 </blockquote>
11607
11608 <br /><br />
11609
11610 <a NAME="error-event"></a>
11611 <h2><span class="function">error-event</span></h2>
11612 <b>syntax: (error-event <em>sym</em>)</b><br />
11613 <b>syntax: (error-event <em>func</em>)</b>
11614
11615 <p>
11616         <em>sym</em> contains a user-defined function for handling errors.
11617         Whenever an error occurs,
11618         the system performs a <a HREF="#reset">reset</a>
11619         and executes the user-defined error handler.
11620         The error handler can use the built-in function
11621         <a HREF="#error-number">error-number</a>
11622         to retrieve the number of the error.
11623 </p>
11624
11625 <b>example:</b>
11626 <blockquote>
11627 <pre>
11628 (define (my-handler)
11629   (print "error # " (error-number) " has occurred\n")
11630   (restart-program))
11631
11632 (error-event 'my-handler)  <span class=arw>&rarr;</span> my-handler
11633
11634 ;; specify a function directly
11635
11636 (error-event my-handler)  <span class=arw>&rarr;</span> $error-event
11637
11638 (error-event
11639   (fn () (print "error # " (error-number) " has occurred\n")))
11640
11641 (error-event exit)  <span class=arw>&rarr;</span> $error-event
11642 </pre>
11643 </blockquote>
11644
11645 <p>
11646         For a different way of handling errors,
11647         see the <a href="#catch">catch</a> function.
11648         Use <a href="#throw-error">throw-error</a>
11649         to throw user-defined errors.
11650 </p>
11651
11652 <br /><br />
11653
11654 <a NAME="error-number"></a>
11655 <h2><span class="function">error-number</span></h2>
11656 <b>syntax: (error-number)</b>
11657
11658 <p>
11659         Returns the number of the last error.
11660 </p>
11661
11662 <b>example:</b>
11663 <blockquote>
11664 <pre>
11665 (define (my-handler)
11666   (print "error # " (error-number) " has occurred\n")
11667   (restart-program))
11668
11669 (error-event 'my-handler)
11670 </pre>
11671 </blockquote>
11672
11673 <p>
11674         See also the functions <a href="#sys-error">sys-error</a>,
11675         <a href="#throw-error">throw-error</a>,
11676         <a HREF="#error-event">error-event</a>,
11677         and <a HREF="#error_codes">error codes</a>
11678         in the appendix.
11679 </p>
11680
11681 <br /><br />
11682
11683 <a NAME="error-text"></a>
11684 <h2><span class="function">error-text</span></h2>
11685 <b>syntax: (error-text [<em>int-error</em>])</b>
11686
11687 <p>
11688         Returns a descriptive text for
11689         the error number in <em>int-error</em>:
11690 </p>
11691
11692 <b>example:</b>
11693 <blockquote>
11694 <pre>
11695 (error-text 5)  <span class=arw>&rarr;</span> "Not an expression"
11696 </pre>
11697 </blockquote>
11698
11699 <p>
11700         If no <em>int-error</em> is given,
11701         the last error is assumed.
11702 </p>
11703
11704 <p>
11705         See also the list of <a HREF="#error_codes">error codes</a>
11706         in the appendix and the functions
11707         <a HREF="#error-event">error-event</a>,
11708         <a href="#catch">catch</a>,
11709         <a href="#sys-error">sys-error</a>,
11710         and <a href="#throw-error">throw-error</a>.
11711 </p>
11712
11713 <br /><br />
11714
11715 <a NAME="eval"></a>
11716 <h2><span class="function">eval</span></h2>
11717 <b>syntax: (eval <em>exp</em>)</b>
11718
11719 <p>
11720         <em>eval</em> evaluates the result of evaluating <em>exp</em>.
11721 </p>
11722
11723 <b>example:</b>
11724 <blockquote>
11725 <pre>
11726 (set 'expr '(+ 3 4))  <span class=arw>&rarr;</span> (+ 3 4)
11727 (eval expr)           <span class=arw>&rarr;</span> 7
11728 (eval (list + 3 4))   <span class=arw>&rarr;</span> 7
11729 (eval ''x)            <span class=arw>&rarr;</span> x
11730 (set 'y 123)
11731 (set 'x 'y)
11732 x            <span class=arw>&rarr;</span> y
11733 (eval x)     <span class=arw>&rarr;</span> 123
11734 </pre>
11735 </blockquote>
11736
11737 <p>
11738         newLISP passes all arguments by value.
11739         Using a quoted symbol,
11740         expressions can be passed
11741         by reference through the symbol.
11742         <tt>eval</tt> can be used
11743         to access the original contents of the symbol:
11744 </p>
11745
11746 <blockquote>
11747 <pre>
11748 (define (change-list aList) (push 999 (eval aList)))
11749
11750 (set 'data '(1 2 3 4 5))
11751
11752 (change-list 'data)  <span class=arw>&rarr;</span> (999 1 2 3 4 5)
11753 </pre>
11754 </blockquote>
11755
11756 <p>
11757         In the example, the parameter <tt>'data </tt> is quoted,
11758         so <tt>push</tt> can work on the original list.
11759 </p>
11760
11761 <p>
11762         It is also possible to pass arguments by reference in newLISP
11763         by enclosing the data inside context objects.
11764         See the chapter <a href="#context_objects">Programming
11765         with context objects</a> and the sub-chapter <a href="#pass_big">
11766         Passing objects by reference</a>.
11767 </p>
11768
11769 <br /><br />
11770
11771 <a NAME="eval-string"></a>
11772 <h2><span class="function">eval-string</span></h2>
11773 <b>syntax: (eval-string <em>str</em> [<em>expr</em> [<em>sym-context</em>]])</b>
11774
11775 <p>
11776         Before being evaluated,
11777         the result of <em>str</em> is compiled
11778         into newLISP's internal format, and
11779         the result of the evaluation is returned.
11780         If the string contains more than one expression,
11781         the result of the last evaluation is returned.
11782 </p>
11783
11784 <p>
11785         A second optional argument, <em>expr</em>,
11786         can be passed that is evaluated
11787         and returned in case of an error.
11788         This permits programmatic control to be maintained
11789         if the evaluation of <em>str</em> produces errors.
11790         An optional third argument can be used to specify
11791         the context in which the string should be parsed and evaluated.
11792         When <em>sym-context</em> is specified,
11793         the failure expression in <em>expr</em>
11794         must be specified, as well.
11795 </p>
11796
11797 <b>example:</b>
11798 <blockquote>
11799 <pre>
11800 (eval-string "(+ 3 4)")  <span class=arw>&rarr;</span> 7
11801 (set 'X 123)             <span class=arw>&rarr;</span> 123
11802 (eval-string "X")        <span class=arw>&rarr;</span> 123
11803
11804 (define (lisp)
11805   (while true
11806     (print "\n=&gt;" (eval-string (read-line) "syntax error"))))
11807
11808 (set 'a 10)
11809 (set 'b 20)
11810 (set 'foo:a 11)
11811 (set 'foo:b 22)
11812
11813 (eval-string "(+ a b)")           <span class=arw>&rarr;</span> 30
11814 (eval-string "(+ a b)" nil 'foo)  <span class=arw>&rarr;</span> 33
11815 </pre>
11816 </blockquote>
11817
11818 <p>
11819         The second example shows
11820         a simple LISP interpreter eval loop.
11821 </p>
11822
11823 <p>
11824         Use the <a href="#catch">catch</a> function
11825         to catch errors resulting from the evaluation
11826         of expressions, as opposed to strings.
11827 </p>
11828
11829 <p>
11830         The last example shows how to specify a target context for evaluation.
11831         The symbols <tt>a</tt> and <tt>b</tt> now refer to the
11832         values in context <tt>foo</tt> instead of <tt>MAIN</tt>.
11833 </p>
11834
11835 <br /><br />
11836
11837 <a NAME="exec"></a>
11838 <h2><span class="function">exec</span></h2>
11839 <b>syntax: (exec <em>str-process</em>)</b><br />
11840 <b>syntax: (exec <em>str-process</em> [<em>str-stdin</em>])</b>
11841
11842 <p>
11843         In the first form,
11844         <tt>exec</tt> launches a process described in <em>str-process</em>
11845         and returns all standard output as an array of strings
11846         (one for each line in <em>stdout</em>).
11847         <tt>exec</tt> returns <tt>nil</tt>
11848         if the process could not be launched.
11849 </p>
11850
11851
11852 <b>example:</b>
11853 <blockquote>
11854 <pre>
11855 (exec "ls *.c")  <span class=arw>&rarr;</span> ("newlisp.c" "nl-math.c" "nl-string.c")
11856 </pre>
11857 </blockquote>
11858
11859 <p>
11860         The example starts a process and performs the shell command <tt>ls</tt>,
11861         capturing the output in an array of strings.
11862 </p>
11863
11864 <p>
11865         In the second form,
11866         <tt>exec</tt> creates a process pipe,
11867         starts the process in <em>str-process</em>,
11868         and receives from <em>str-stdin</em>
11869         standard input for this process.
11870         The return value is <tt>true</tt>
11871         if the process was successfully launched;
11872         otherwise it is <tt>nil</tt>.
11873 </p>
11874
11875 <b>example:</b>
11876 <blockquote>
11877 <pre>
11878 (exec "cgiProc" query)
11879 </pre>
11880 </blockquote>
11881
11882 <p>
11883         In this example,
11884         cgiProc could be a cgi processor (e.g., Perl or newLISP)
11885         that receives and processes standard input supplied by a string
11886         contained in the variable query.
11887 </p>
11888
11889 <br /><br />
11890
11891 <a NAME="exit"></a>
11892 <h2><span class="function">exit</span></h2>
11893 <b>syntax: (exit [<em>int</em>])</b>
11894
11895 <p>
11896         Exits newLISP.
11897         An optional exit code, <em>int</em>, may be supplied.
11898         This code can be tested by the host operating system.
11899         When newLISP is run in <a HREF="#daemon">daemon server mode</a>
11900         using <tt>-d</tt> as a command-line option,
11901         only the network connection is closed,
11902         while newLISP stays resident,
11903         listening for a new connection.
11904 </p>
11905
11906 <b>example:</b>
11907 <blockquote>
11908 <pre>
11909 (exit 5)
11910 </pre>
11911 </blockquote>
11912
11913 <br /><br />
11914
11915 <a NAME="exists"></a>
11916 <h2><span class="function">exists</span></h2>
11917
11918 <b>syntax: (exists <em>func-condition</em> <em>list</em>)</b><br />
11919
11920 <p>Successively applies <em>func-condition</em>
11921 to the elements of <em>list</em>
11922 and returns the first element
11923 that meets the condition in <em>func-condition</em>.
11924 If no element meets the condition,
11925 <tt>nil</tt> is returned.</p>
11926
11927 <b>example:</b>
11928 <blockquote>
11929 <pre>
11930 (exists string? '(2 3 4 6 "hello" 7))       <span class=arw>&rarr;</span> "hello"
11931
11932 (exists string? '(3 4 2 -7 3 0))            <span class=arw>&rarr;</span> nil
11933
11934 (exists zero? '(3 4 2 -7 3 0))              <span class=arw>&rarr;</span> 0 ; check for 0 or 0.0
11935
11936 (exists &lt; '(3 4 2 -7 3 0))                  <span class=arw>&rarr;</span> -7 ; check for negative
11937
11938 (exists (fn (x) (&gt; x 3)) '(3 4 2 -7 3 0))   <span class=arw>&rarr;</span> 4
11939
11940 (exists (fn (x) (= x 10)) '(3 4 2 -7 3 0))  <span class=arw>&rarr;</span> nil
11941 </pre>
11942 </blockquote>
11943
11944 <p>Use the <a href="#for-all">for-all</a> function
11945 to check if a condition is met for all elements in a list.</p>
11946
11947 <br /><br />
11948
11949 <a NAME="exp"></a>
11950 <h2><span class="function">exp</span></h2>
11951 <b>syntax: (exp <em>num</em>)</b>
11952
11953 <p>
11954         The expression in <em>num</em> is evaluated,
11955         and the exponential function is calculated based on the result.
11956         <tt>exp</tt> is the inverse function of <tt>log</tt>.
11957 </p>
11958
11959 <b>example:</b>
11960 <blockquote>
11961 <pre>
11962 (exp 1)        <span class=arw>&rarr;</span> 2.718281828
11963 (exp (log 1))  <span class=arw>&rarr;</span> 1
11964 </pre>
11965 </blockquote>
11966
11967 <br /><br />
11968
11969 <a NAME="expand"></a>
11970 <h2><span class="function">expand</span></h2>
11971
11972 <b>syntax: (expand <em>list</em> <em>sym</em> [<em>sym_2</em> ... ])</b><br />
11973 <b>syntax: (expand <em>list</em> <em>list-assoc</em>)</b><br />
11974 <b>syntax: (expand <em>list</em>)</b>
11975
11976 <p>
11977         In the first syntax,
11978         one symbol in <em>sym</em>
11979         (or more in <em>sym_2</em> through <em>sym_n</em>)
11980         is looked up in a simple or nested <em>list</em>.
11981         They are then expanded
11982         to the current binding of the symbol,
11983         and the expanded list is returned.
11984         The original list remains unchanged.
11985 </p>
11986
11987 <b>example:</b>
11988 <blockquote>
11989 <pre>
11990 (set 'x 2 'a '(d e))
11991 (expand '(a x b) 'x)           <span class=arw>&rarr;</span> (a 2 b)
11992 (expand '(a x (b c x)) 'x)     <span class=arw>&rarr;</span> (a 2 (b c 2))
11993 (expand '(a x (b c x)) 'x 'a)  <span class=arw>&rarr;</span> ((d e) 2 (b c 2))
11994 </pre>
11995 </blockquote>
11996
11997 <p>
11998         <tt>expand</tt> is useful when composing lambda expressions
11999         or doing variable expansion inside macros.
12000 </p>
12001
12002 <blockquote>
12003 <pre>
12004 (define (raise-to power)
12005   (expand (fn (base) (pow base power)) 'power))
12006
12007 (define square (raise-to 2))
12008 (define cube (raise-to 3))
12009
12010 (square 5)  <span class=arw>&rarr;</span> 25
12011 (cube 5)    <span class=arw>&rarr;</span> 125
12012 </pre>
12013 </blockquote>
12014
12015 <p>
12016         If more than one symbol is present,
12017         <tt>expand</tt> will work in an incremental fashion:
12018 </p>
12019
12020 <blockquote>
12021 <pre>
12022 (set 'a '(b c))
12023 (set 'b 1)
12024
12025 (expand '(a b c) 'a 'b)  <span class=arw>&rarr;</span> ((1 c) 1 c)
12026 </pre>
12027 </blockquote>
12028
12029 <p>
12030         Like the <a href="#apply">apply</a> function,
12031         <tt>expand</tt> <em>reduces</em> its argument list.
12032 </p>
12033
12034 <br />
12035 <b>syntax: (expand <em>list</em> <em>list-assoc</em>)</b>
12036
12037 <p>
12038         The second syntax of <tt>expand</tt> allows
12039         expansion bindings to be specified on the fly,
12040         without performing a <a href="#set">set</a>
12041         on the participating variables:
12042 </p>
12043
12044 <b>example:</b>
12045 <blockquote>
12046 <pre>
12047 (expand '(a b c) '((a 1) (b 2)))              <span class=arw>&rarr;</span> (1 2 c)
12048 (expand '(a b c) '((a 1) (b 2) (c (x y z))))  <span class=arw>&rarr;</span> (1 2 (x y z))
12049 </pre>
12050 </blockquote>
12051
12052 <p>
12053         Note that the contents of the variables
12054         in the association list will not change.
12055         This is different from the <a href="#letex">letex</a> function,
12056         where variables are set by evaluating
12057         and assigning their association parts.
12058 </p>
12059
12060 <p>
12061         This form of <tt>expand</tt> is frequently used
12062         in logic programming,
12063         together with the <a href="#unify">unify</a> function.
12064 </p>
12065
12066 <br />
12067 <b>syntax: (expand <em>list</em>)</b>
12068
12069 <p>
12070         A third syntax is used to expand only the contents
12071         of variables starting with an uppercase character.
12072         This PROLOG mode may also be used
12073         in the context of logic programming.
12074         As in the first syntax of <tt>expand</tt>,
12075         symbols must be preset.
12076         Only uppercase variables and those bound
12077         to anything other than <tt>nil</tt>
12078         will be expanded:
12079 </p>
12080
12081
12082 <b>example:</b>
12083 <blockquote>
12084 <pre>
12085 (set 'A 1 'Bvar 2 'C nil 'd 5 'e 6)
12086 (expand '(A (Bvar) C d e f))  <span class=arw>&rarr;</span> (1 (2) C d e f)
12087 </pre>
12088 </blockquote>
12089
12090 <p>
12091         Only the symbols <tt>A</tt> and <tt>Bvar</tt> are expanded,
12092         since they have capitalized names
12093         and non-<tt>nil</tt> contents.
12094 </p>
12095
12096 <p>
12097         The <em>currying</em> function in the example
12098         demonstrating the first syntax of <tt>expand</tt>
12099         can now be written even more simply
12100         using an uppercase variable:
12101 </p>
12102
12103 <blockquote>
12104 <pre>
12105 (define (raise-to Power)
12106   (expand (fn (base) (pow base Power))))
12107
12108 &gt; (define cube (raise-to 3))
12109 <strong>(lambda (base) (pow base 3))</strong>
12110
12111 &gt; (cube 4)
12112 <strong>64</strong>
12113
12114 &gt; _
12115 </pre>
12116 </blockquote>
12117
12118 <p>
12119         See the <a href="#letex">letex</a> function,
12120         which also provides an expansion mechanism,
12121         and the function <a href="#unify">unify</a>,
12122         which is frequently used together with <tt>expand</tt>.
12123 </p>
12124
12125 <br /><br />
12126
12127 <a NAME="explode"></a>
12128 <h2><span class="function">explode</span></h2>
12129 <b>syntax: (explode <em>str</em> [<em>int-chunk</em> [<em>bool</em>] ])</b><br />
12130 <b>syntax: (explode <em>list</em> [<em>int-chunk</em> [<em>bool</em>] ])</b>
12131
12132 <p>
12133 In the first syntax,
12134 <tt>explode</tt> transforms the string (<em>str</em>)
12135 into a list of single-character strings.
12136 Optionally, a chunk size can be specified in <em>int-chunk</em>
12137 to break the string into multi-character chunks.
12138 When specifying a value for <em>bool</em> other than <tt>nil</tt>,
12139 the last chunk will be omitted
12140 if it does not have the full length specified
12141 in <em>int-chunk</em>.
12142 </p>
12143
12144 <b>example:</b>
12145 <blockquote>
12146 <pre>
12147 (explode "newLISP")  <span class=arw>&rarr;</span> ("n" "e" "w" "L" "I" "S" "P")
12148
12149 (join (explode "keep it together"))  <span class=arw>&rarr;</span> "keep it together"
12150
12151 (explode "newLISP" 2)    <span class=arw>&rarr;</span> ("ne" "wL" "IS" "P")
12152
12153 (explode "newLISP" 3)    <span class=arw>&rarr;</span> ("new" "LIS" "P")
12154
12155 ; omit last chunk if too short
12156 (explode "newLISP" 3 true)    <span class=arw>&rarr;</span> ("new" "LIS")
12157
12158 </pre>
12159 </blockquote>
12160
12161 <p>
12162         <tt>explode</tt> also works on binary content:
12163 </p>
12164
12165 <blockquote>
12166 <pre>
12167 (explode "\000\001\002\003")
12168 <span class=arw>&rarr;</span> ("\000" "\001" "\002" "\003")
12169 </pre>
12170 </blockquote>
12171
12172 <p>
12173         When called in UTF-8&ndash;enabled versions of newLISP,
12174         <tt>explode</tt> will work on character boundaries
12175         rather than byte boundaries.
12176         In UTF-8&ndash;encoded strings,
12177         characters may contain more than one byte.
12178 </p>
12179
12180 <p>
12181 In the second syntax,
12182 <tt>explode</tt> explodes a list (<em>list</em>)
12183 into sublists of chunk size <em>int-chunk</em>,
12184 which is 1 (one) by default.
12185 </p>
12186
12187 <p>
12188 The following shows an example of the last chunk being omitted
12189 when the value for <em>bool</em> is other than <tt>nil</tt>,
12190 and the chunk does not have the full length specified
12191 in <em>int-chunk</em>.
12192 </p>
12193
12194 <b>example:</b>
12195 <blockquote>
12196 <pre>
12197 (explode '(a b c d e f g h))    <span class=arw>&rarr;</span> ((a) (b) (c) (d) (e) (f) (g) (h))
12198 (explode '(a b c d e f g h) 2)  <span class=arw>&rarr;</span> ((a b) (c d) (e f) (g))
12199
12200 ; omit last chunk if too short
12201 (explode '(a b c d e f g h) 2 true)  <span class=arw>&rarr;</span> ((a b) (c d) (e f))
12202
12203 (transpose (explode '(a b c d e f g h) 2))
12204 <span class=arw>&rarr;</span> ((a c e g) (b d f h))
12205 </pre>
12206 </blockquote>
12207
12208 <p>
12209 The <a HREF="#join">join</a> and <a HREF="#append">append</a> functions
12210 are inverse operations of <tt>explode</tt>.
12211 </p>
12212
12213 <br /><br />
12214
12215 <a NAME="factor"></a>
12216 <h2><span class="function">factor</span></h2>
12217 <b>syntax: (factor <em>int</em>)</b>
12218
12219 <p>
12220         Factors the number in <em>int</em>
12221         into its prime components.
12222         Floating point numbers in <em>num</em>
12223         are truncated to their integer part.
12224 </p>
12225
12226 <b>example:</b>
12227 <blockquote>
12228 <pre>
12229 (factor 123456789123456789)  <span class=arw>&rarr;</span> (3 3 7 11 13 19 3607 3803 52579)
12230
12231 ;; check correctness of factoring
12232 (= (apply * (factor 123456789123456789)) 123456789123456789)
12233 <span class=arw>&rarr;</span> true
12234
12235 ;; factor the biggest integer
12236 (factor 9223372036854775807)  <span class=arw>&rarr;</span> (7 7 73 127 337 92737 649657)
12237
12238 ;; primes.lsp - return all primes in a list, up to n
12239
12240 (define (primes n , p)
12241   (dotimes (e n)
12242     (if (= (length (factor e)) 1)
12243       (push e p -1))) p)
12244
12245 (primes 20)  <span class=arw>&rarr;</span> (2 3 5 7 11 13 17 19)
12246 </pre>
12247 </blockquote>
12248
12249 <p>
12250         <tt>factor</tt> returns <tt>nil</tt>
12251         for numbers smaller than <tt>2</tt>.
12252         For numbers larger than 9,223,372,036,854,775,807
12253         (the largest 64-bit integer)
12254         converted from floating point numbers,
12255         the largest integer is factored.
12256 </p>
12257
12258 <br /><br />
12259
12260 <a NAME="fft"></a>
12261 <h2><span class="function">fft</span></h2>
12262 <b>syntax: (fft <em>list-num</em>)</b>
12263
12264 <p>
12265         Calculates the discrete Fourier transform
12266         on the list of complex numbers in <em>list-num</em>
12267         using the FFT method (Fast Fourier Transform).
12268         Each complex number is specified by its real part,
12269         followed by its imaginary part.
12270         If only real numbers are used,
12271         the imaginary part is set to <tt>0.0</tt> (zero).
12272         When the number of elements in <em>list-num</em>
12273         is not a power of 2,
12274         <tt>fft</tt> increases the number of elements
12275         by padding the list with zeroes.
12276         When the imaginary part of a complex number is 0,
12277         simple numbers can be used instead.
12278 </p>
12279
12280 <b>example:</b>
12281 <blockquote>
12282 <pre>
12283 (ifft (fft '((1 0) (2 0) (3 0) (4 0))))
12284 <span class=arw>&rarr;</span> ((1 0) (2 0) (3 0) (4 0))
12285
12286 ;; when imaginary part is 0, plain numbers work, too
12287 ;; complex numbers can be intermixed
12288
12289 (fft '(1 2 3 4))      <span class=arw>&rarr;</span> ((10 0) (-2 -2) (-2 0) (-2 2))
12290 (fft '(1 2 (3 0) 4))  <span class=arw>&rarr;</span> ((10 0) (-2 -2) (-2 0) (-2 2))
12291
12292 </pre>
12293 </blockquote>
12294
12295 <p>
12296         The inverse operation of <tt>fft</tt>
12297         is the <a HREF="#ifft">ifft</a> function.
12298 </p>
12299
12300 <br /><br />
12301
12302 <a NAME="file-info"></a>
12303 <h2><span class="function">file-info</span></h2>
12304 <b>syntax: (file-info <em>str_name</em>)</b>
12305
12306 <p>
12307         Returns a list of information about
12308         the file or directory in <em>str_name</em>.
12309         newLISP uses the POSIX system call <tt>lstat()</tt>
12310         to get the following information:
12311 </p>
12312 <br />
12313 <blockquote>
12314 <table border="0" cellpadding="1">
12315 <tr align="left"><th>offset</th><th>contents</th></tr>
12316 <tr><td>0</td><td>size</td></tr>
12317 <tr><td>1</td><td>mode</td></tr>
12318 <tr><td>2</td><td>device mode</td></tr>
12319 <tr><td>3</td><td>user ID</td></tr>
12320
12321 <tr><td>4</td><td>group ID</td></tr>
12322 <tr><td>5</td><td>access time</td></tr>
12323 <tr><td>6</td><td>modification time</td></tr>
12324 <tr><td>7</td><td>status change time</td></tr>
12325 </table>
12326 </blockquote>
12327
12328 <br />
12329
12330 <b>example:</b>
12331 <blockquote>
12332 <pre>
12333 (file-info ".bashrc")
12334 <span class=arw>&rarr;</span> (124 33188 0 500 0 920951022 920951022 920953074)
12335
12336 (date (last (file-info "/etc")))
12337 <span class=arw>&rarr;</span> "Mon Mar 8 18:23:17 1999"
12338 </pre>
12339 </blockquote>
12340
12341 <p>
12342         In the second example,
12343         the last status change date
12344         for the directory <em>/etc</em>
12345         is retrieved.
12346 </p>
12347
12348 <p><tt>file-info</tt> gives file statistics (size) for a linked file,
12349 not the link, except for the <em>mode</em> field.</p>
12350
12351 <br /><br />
12352
12353 <a NAME="filep"></a>
12354 <h2><span class="function">file?</span></h2>
12355
12356 <b>syntax: (file? <em>str-name</em>)</b>
12357
12358 <p>
12359         Checks for the existence of
12360         a file in <em>str-name</em>.
12361         Returns <tt>true</tt>
12362         if the file exists;
12363         otherwise, it returns <tt>nil</tt>.
12364         This function will also return
12365         <tt>true</tt> for directories.
12366         The existence of a file
12367         does not imply anything about
12368         its read or write permissions.
12369         A file may exist while not having the permissions
12370         to read from or write to it by the current user.
12371 </p>
12372
12373 <b>example:</b>
12374 <blockquote>
12375 <pre>
12376 (if (file? "afile") (set 'fileNo (open "afile" "read")))
12377 </pre>
12378 </blockquote>
12379
12380 <br /><br />
12381
12382 <a NAME="filter"></a>
12383 <h2><span class="function">filter</span></h2>
12384 <b>syntax: (filter <em>exp-predicate</em> <em>exp-list</em>)</b>
12385
12386 <p>
12387         The predicate <em>exp-predicate</em> is applied
12388         to each element of the list <em>exp-list</em>.
12389         A list is returned containing the elements
12390         for which <em>exp-predicate</em> is true.
12391         <tt>filter</tt> works like <a href="#clean">clean</a>,
12392         but with a negated predicate.
12393 </p>
12394
12395 <b>example:</b>
12396 <blockquote>
12397 <pre>
12398 (filter symbol? '(1 2 d 4 f g 5 h))  <span class=arw>&rarr;</span> (d f g h)
12399
12400 (define (big? x) (&gt; x 5))  <span class=arw>&rarr;</span> (lambda (x) (&gt; x 5))
12401
12402 (filter big? '(1 10 3 6 4 5 11))  <span class=arw>&rarr;</span> (10 6 11)
12403
12404 ; filter with comparison functor
12405
12406 (set 'L '((a 10 2 7) (b 5) (a 8 3) (c 8) (a 9)))
12407
12408 (filter (curry match '(a *)) L)   <span class=arw>&rarr;</span> ((a 10 2 7) (a 8 3) (a 9))
12409
12410 (filter (curry match '(? ?)) L)   <span class=arw>&rarr;</span> ((b 5) (c 8) (a 9))
12411
12412 (filter (curry match '(* 8 *)) L) <span class=arw>&rarr;</span> ((a 8 3) (c 8))
12413
12414 <span class=arw>&rarr;</span>  ((a 10) (a 3) (a 9))
12415 </pre>
12416 </blockquote>
12417
12418 <p>
12419         The predicate may be a built-in predicate,
12420         a user-defined function,
12421         or a lambda expression.
12422 </p>
12423
12424 <p>
12425         For filtering a list of elements
12426         with the elements from another list,
12427         use the <a href="#difference"> difference</a> function or
12428         <a href="#intersect">intersect</a>
12429         (with the <em>list</em> option).
12430 </p>
12431
12432 <p>
12433         See also the related function <a HREF="#index">index</a>,
12434         which returns the indices of the filtered elements
12435         and <a href="#clean">clean</a>,
12436         which returns all elements of a list
12437         for which a predicate is false.
12438 </p>
12439
12440 <br /><br />
12441
12442 <a NAME="find"></a>
12443 <h2><span class="function">find</span></h2>
12444 <b>syntax: (find <em>exp-key list</em> [<em>func-compare</em> | <em>int-option</em>])</b><br />
12445 <b>syntax: (find <em>str-key str-data</em> [<em>int-option</em>])</b>
12446
12447 <h4>Find an expressions in a list</h4>
12448 <p>
12449         If the second argument evaluates to a <em>list</em>,
12450         then <tt>find</tt> returns the index position (offset)
12451         of the element derived from evaluating <em>exp-key</em>.
12452 </p>
12453
12454 <p>
12455 Optionally, an operator or user-defined function
12456 can be specified in <em>func-compare</em>.
12457 If <em>exp-key</em> is a string,
12458 a regular expression option
12459 can be specified with <em>int-option</em> instead.</p>
12460
12461 <p>When using regular expressions or comparison functors the system
12462 variable <tt>$0</tt> is set to the last element found.</p>
12463
12464 <b>example:</b>
12465 <blockquote>
12466 <pre>
12467 ; find an expression in a list
12468 (find '(1 2) '((1 4) 5 6 (1 2) (8 9)))  <span class=arw>&rarr;</span> 3
12469
12470 (find "world" '("hello" "world"))       <span class=arw>&rarr;</span> 1
12471 (find "hi" '("hello" "world"))          <span class=arw>&rarr;</span> nil
12472
12473 (find "newlisp" '("Perl" "Python" "newLISP") 1)  <span class=arw>&rarr;</span> 2
12474
12475 ; use the comparison functor
12476 (find 3 '(8 4 3  7 2 6) &gt;)  <span class=arw>&rarr;</span> 4
12477 $0 <span class=arw>&rarr;</span> 2
12478
12479 (find "newlisp" '("Perl" "Python" "newLISP")
12480                  (fn (x y) (regex x y 1))) <span class=arw>&rarr;</span> 2
12481 $0 <span class=arw>&rarr;</span> "newLISP"
12482
12483 (find 5 '((l 3) (k 5) (a 10) (z 22))
12484          (fn (x y) (= x (last y))))  <span class=arw>&rarr;</span> 1
12485 $0 <span class=arw>&rarr;</span> (k 5)
12486
12487 (find '(a ?) '((l 3) (k 5) (a 10) (z 22)) match)  <span class=arw>&rarr;</span> 2
12488 $0 <span class=arw>&rarr;</span> (a 10)
12489
12490 (find '(X X) '((a b) (c d) (e e) (f g)) unify)  <span class=arw>&rarr;</span> 2
12491 $0 <span class=arw>&rarr;</span> (e e)
12492
12493 ; define the comparsion functor first for better readability
12494 (define (has-it-as-last x y) (= x (last y)))
12495
12496 (find 22 '((l 3) (k 5) (a 10) (z 22)) has-it-as-last)  <span class=arw>&rarr;</span> 3
12497 $0 <span class=arw>&rarr;</span> (z 22)
12498 </pre>
12499 </blockquote>
12500
12501 <p>
12502 Using <a href="#match">match</a> and <a href="#unify">unify</a>,
12503 list searches can be formulated which are as powerful
12504 as regular expression searches are for strings.
12505 </p>
12506
12507 <br />
12508
12509 <h4>Find a string in a string</h4>
12510 <p>
12511         If the second argument,
12512         <em>str-data</em>,
12513         evaluates to a string,
12514         then the offset position
12515         of the string <em>str-key</em>
12516         (found in the first argument,
12517         <em>str-data</em>)
12518         is returned.
12519         In this case,
12520         <tt>find</tt> also works
12521         on binary <em>str-data</em>.
12522 </p>
12523
12524 <p>
12525         The presence of a third parameter specifies a search
12526         using the regular expression pattern specified in <em>str-pattern</em>,
12527         as well as an option number specified in <em>int-option</em>
12528         (i.e., 1 (one) for case-insensitive search or 0 (zero)
12529         for no special options).
12530 </p>
12531
12532 <p>
12533         In newLISP, regular expressions are standard
12534         Perl Compatible Regular Expression (PCRE) searches.
12535         Found expressions or subexpressions are returned
12536         in the system variables <tt>$0</tt>, <tt>$1</tt>, <tt>$2</tt>, etc.,
12537         which can be used like any other symbol.
12538         As an alternative,
12539         the contents of these variables
12540         can also be accessed
12541         by using <tt>($ 0)</tt>, <tt>($ 1)</tt>, <tt>($ 2)</tt>, etc.
12542         This method allows indexed access
12543         (i.e., <tt>($ i)</tt>, where <tt>i</tt> is an integer).
12544 </p>
12545
12546 <p>
12547         See <a HREF="#regex">regex</a>
12548         for the meaning of the
12549         option numbers and more information
12550         on regular expression searching.
12551 </p>
12552
12553 <b>example:</b>
12554 <blockquote>
12555 <pre>
12556 ; simple string search
12557 (find "world" "Hello world")  <span class=arw>&rarr;</span> 6
12558 (find "WORLD" "Hello woRLd")  <span class=arw>&rarr;</span> nil
12559
12560 ; case-insensitive regex
12561
12562 (find "WorlD" "Hello woRLd" 1)  <span class=arw>&rarr;</span> 6
12563
12564 (find "hi" "hello world")       <span class=arw>&rarr;</span> nil
12565 (find "Hello" "Hello world")    <span class=arw>&rarr;</span> 0
12566
12567 ; regex with default options
12568
12569 (find "cat|dog" "I have a cat" 0)  <span class=arw>&rarr;</span> 9
12570 $0                                 <span class=arw>&rarr;</span> "cat"
12571 (find "cat|dog" "my dog" 0)        <span class=arw>&rarr;</span> 3
12572 $0                                 <span class=arw>&rarr;</span> "dog"
12573 (find "cat|dog" "MY DOG" 1)        <span class=arw>&rarr;</span> 3
12574 $0                                 <span class=arw>&rarr;</span> "DOG"
12575
12576 ;; find with subexpressions in regular expression
12577 ;; and access with system variables
12578
12579 (set 'str  "http://nuevatec.com:80")
12580
12581 (find "http://(.*):(.*)" str 0)  <span class=arw>&rarr;</span> 0
12582
12583 $0  <span class=arw>&rarr;</span> "http://nuevatec.com:80"
12584 $1  <span class=arw>&rarr;</span> "nuevatec.com"
12585 $2  <span class=arw>&rarr;</span> "80"
12586
12587 ;; system variables as an indexed expression (since 8.0.5)
12588 ($ 0)  <span class=arw>&rarr;</span> "http://nuevatec.com:80"
12589 ($ 1)  <span class=arw>&rarr;</span> "nuevatec.com"
12590 ($ 2)  <span class=arw>&rarr;</span> "80"
12591 </pre>
12592 </blockquote>
12593
12594 <p>
12595         For other functions using regular expressions,
12596         see <a href="#directory">directory</a>,
12597     <a href="#find-all">find-all</a>,
12598         <a href="#parse">parse</a>,
12599         <a HREF="#regex">regex</a>,
12600         <a href="#replace">replace</a>,
12601         and <a href="#search">search</a>.
12602
12603 <p>
12604         To find expressions in nested
12605         or multidimensional lists,
12606         use the <a href="#ref">ref</a> and <a href="#ref-all">ref-all</a> functions.
12607 </p>
12608
12609 <br /><br />
12610
12611 <a NAME="find-all"></a>
12612 <h2><span class="function">find-all</span></h2>
12613 <b>syntax: (find-all <em>str-pattern</em> <em>str-text</em> [<em>expr</em> [<em>int-option</em>]])</b><br />
12614 <b>syntax: (find-all <em>list-pattern</em> <em>list-lists</em> [<em>expr</em>])</b><br />
12615 <b>syntax: (find-all <em>expr-key</em> <em>list</em> <em>expr</em> <em>func-compare</em>)</b>
12616
12617 <p>
12618         In the first syntax <tt>find-all</tt> Finds all occurrences of <em>str-pattern</em>
12619         in the text <em>str-text</em>,
12620         returning a list containing all matching strings.
12621         The empty list <tt>()</tt> is returned
12622         if no matches are found.
12623 </p>
12624
12625 <p>
12626         Optionally, an expression can be specified
12627         to process the found string or regular subexpressions
12628         before placing them into the returned list.
12629         An additional option, <em>int-option</em>,
12630         specifies special regular expression options
12631         (see <a href="#regex">regex</a> for further details).
12632 </p>
12633
12634
12635 <b>example:</b>
12636 <blockquote>
12637 <pre>
12638 (find-all {\d+} "lkjhkljh34ghfdhgfd678gfdhfgd9")
12639 <span class=arw>&rarr;</span> ("34" "678" "9")
12640
12641 (find-all {(new)(lisp)} "newLISPisNEWLISP" (append $2 $1) 1)
12642 <span class=arw>&rarr;</span> ("LISPnew" "LISPNEW")
12643
12644 (unique (sort
12645     (find-all {[a-zA-Z]+}
12646         (replace "&lt;[^&gt;]+&gt;" (get-url "http://newlisp.org") "" 0) )
12647 ))
12648 <span class=arw>&rarr;</span> ("A" "ACC" "AI" "API" "About" "All" "Amazing" "Apps"
12649 ...
12650 "where" "whole" "width" "wiki" "will" "with" "work" "written")
12651 </pre>
12652 </blockquote>
12653
12654 <p>
12655         The first example discovers all numbers in a text.
12656         The second example shows how an optional expression in <em>expr</em>
12657         can work on subexpressions found by the regular expression pattern
12658         in <em>str-pattern</em>.
12659         The last example retrieves a web page,
12660         cleans out all HTML tags,
12661         and then collects all words
12662         into a unique and sorted list.
12663 </p>
12664
12665 <p>
12666         Note that <tt>find-all</tt> with strings
12667         always performs a regular expression search,
12668         even if the option in <em>int-option</em>
12669         is omitted.
12670 </p>
12671
12672 <p>In the second syntax <tt>find-all</tt> searches for all list <a href="#match">match</a>
12673 patterns <em>list-pattern</em> in <em>list-lists</em>. As in <tt>find-all</tt> for
12674 strings an expression can be specified in <em>expr</em> to further process the matched
12675 sublist:</p>
12676
12677 <b>example:</b>
12678 <blockquote>
12679 <pre>
12680 (find-all '(? 2) '((a 1) (b 2) (a 2) (c 4))) <span class=arw>&rarr;</span> ((b 2) (a 2))
12681
12682 (find-all '(? 2) '((a 1) (b 2) (a 2) (c 4)) (first $0)) <span class=arw>&rarr;</span> (b a)
12683 </pre>
12684 </blockquote>
12685
12686 <p><tt>find-all</tt> for list matches always uses <a href="#match">match</a> to compare when
12687 searching for sublists and always needs a list for the pattern expression.</p>
12688
12689 <p>In the third syntax <tt>find-all</tt> can speficy a built-in or user-defined
12690 function used for comparing list elements with the key expression in <em>expr-keyM</em>:</p>
12691
12692
12693 <b>example:</b>
12694 <blockquote>
12695 <pre>
12696 (find-all 5 '(2 7 4 5 9 2 4 9 7 4 8) $0 &lt;) <span class=arw>&rarr;</span> (7 9 9 7 8)
12697
12698 ; process the found element
12699
12700 (find-all 5 '(2 7 4 5 9 2 4 9 7 4 8) (* 3 $0) &lt;) <span class=arw>&rarr;</span> (21 27 27 21 24)
12701
12702 (find-all 5 '(2 7 4 5 9 2 4 9 7 4 8) ("abcdefghijk" $0) &lt;) <span class=arw>&rarr;</span> ("h" "j" "j" "h" "i")
12703 </pre>
12704 </blockquote>
12705
12706 <p>Any type of expression can be searched for or can be contained in the list. <tt>find-all</tt>
12707 in this syntax works similar to <a href="#filter">filter</a> but with the added benefit of
12708 beeing able to define a processing expression for the found element.</p>
12709
12710 <br /><br />
12711
12712
12713 <a NAME="first"></a>
12714 <h2><span class="function">first</span></h2>
12715 <b>syntax: (first <em>list</em>)</b><br />
12716 <b>syntax: (first <em>array</em>)</b><br />
12717 <b>syntax: (first <em>str</em>)</b>
12718
12719 <p>
12720         Returns the first element of a list
12721         or the first character of a string.
12722         The operand is not changed.
12723         This function is equivalent to <em>car</em>
12724         or <em>head</em> in other LISP dialects.
12725 </p>
12726
12727 <b>example:</b>
12728 <blockquote>
12729 <pre>
12730 (first '(1 2 3 4 5))       <span class=arw>&rarr;</span> 1
12731 (first '((a b) c d))       <span class=arw>&rarr;</span> (a b)
12732 (set 'aList '(a b c d e))  <span class=arw>&rarr;</span> (a b c d e)
12733 (first aList)              <span class=arw>&rarr;</span> a
12734 aList                      <span class=arw>&rarr;</span> (a b c d e)
12735
12736 (set 'A (array 3 2 (sequence 1 6)))
12737 <span class=arw>&rarr;</span>  ((1 2) (3 4) (5 6))
12738 (first A)                  <span class=arw>&rarr;</span> (1 2)
12739 </pre>
12740 </blockquote>
12741
12742 <p>
12743         In the second syntax,
12744         the first character is returned
12745         from the string in <em>str</em>
12746         as a string.
12747 </p>
12748
12749 <b>example:</b>
12750 <blockquote>
12751 <pre>
12752 (first "newLISP")         <span class=arw>&rarr;</span> "n"
12753 (first (rest "newLISP"))  <span class=arw>&rarr;</span> "e"
12754 </pre>
12755 </blockquote>
12756
12757 <p>
12758         Note that <a href="#first">first</a> works on character boundaries
12759         rather than byte boundaries
12760         when the UTF-8&ndash;enabled version of newLISP is used.
12761         See also the functions <a HREF="#last">last</a>
12762         and <a HREF="#rest">rest</a>.
12763 </p>
12764
12765 <br /><br />
12766
12767 <a NAME="flat"></a>
12768 <h2><span class="function">flat</span></h2>
12769 <b>syntax: (flat <em>list</em>)</b><br />
12770
12771 <p>
12772         Returns the flattened form of a list:
12773 </p>
12774
12775 <b>example:</b>
12776 <blockquote>
12777 <pre>
12778 (set 'lst '(a (b (c d))))
12779 (flat lst)  <span class=arw>&rarr;</span> (a b c d)
12780
12781 (map (fn (x) (ref x lst)) (flat lst))
12782 <span class=arw>&rarr;</span> ((0) (1 0) (1 1 0) (1 1 1))
12783 </pre>
12784 </blockquote>
12785
12786 <p>
12787         <tt>flat</tt> can be used
12788         to iterate through nested lists.
12789 </p>
12790
12791 <br /><br />
12792
12793 <a NAME="fn"></a>
12794 <h2><span class="function">fn</span></h2>
12795 <b>syntax: (fn (<em>list-parameters</em>) <em>exp-body</em>)</b>
12796
12797 <p>
12798         <tt>fn</tt> is used to define anonymous functions,
12799         which are frequently used in <a href="#map">map</a>,
12800         <a href="#sort">sort</a>,
12801         and anywhere functions can be used as a argument.
12802 </p>
12803
12804 <p>
12805         Using an anonymous function
12806         eliminates the need to define
12807         a new function with <a href="#define">define</a>.
12808         Instead, a function is defined on the fly:
12809 </p>
12810
12811 <b>example:</b>
12812 <blockquote>
12813 <pre>
12814 (map (fn (x) (+ x x)) '(1 2 3 4 5)) <span class=arw>&rarr;</span> (2 4 6 8 10)
12815
12816 (sort '(".." "..." "." ".....") (fn (x y) (&gt; (length x) (length y))))
12817 <span class=arw>&rarr;</span> ("....." "..." ".." ".")
12818 </pre>
12819 </blockquote>
12820
12821 <p>
12822         The example defines the function <em>fn(x)</em>,
12823         which takes an integer (<em>x</em>) and doubles it.
12824         The function is <em>mapped</em> onto a list of arguments
12825         using <a href="#map">map</a>.
12826         The second example shows strings being sorted by length.
12827 </p>
12828
12829 <p>
12830         The <a href="#lambda">lambda</a> function
12831         (the longer, traditional form)
12832         can be used in place of <tt>fn</tt>.
12833 </p>
12834
12835 <br /> <br />
12836
12837 <a NAME="float"></a>
12838 <h2><span class="function">float</span></h2>
12839 <b>syntax: (float <em>exp</em> [<em>exp-default</em>] )</b>
12840
12841 <p>
12842         If the expression in <em>exp</em>
12843         evaluates to a number or a string,
12844         the argument is converted to a float
12845         and returned.
12846         If <em>exp</em> cannot be converted to a float
12847         then <tt>nil</tt> or, if specified,
12848         the evaluation of <em>exp-default</em>
12849         will be returned.
12850         This function is mostly used to convert strings
12851         from user input or when reading and parsing text.
12852         The string must start with a digit
12853         or the <tt>+</tt> (plus sign), <tt>-</tt> (minus sign),
12854         or <tt>.</tt> (period).
12855         If <em>str</em> is invalid,
12856         <tt>float</tt> returns <tt>nil</tt>
12857         as a default value.
12858 </p>
12859
12860 <p>
12861         Floats with exponents larger than 1e308
12862         or smaller than -1e308
12863         are converted to +INF or -INF, respectively.
12864         The display of +INF and -INF
12865         differs on different platforms and compilers.
12866 </p>
12867
12868 <b>example:</b>
12869 <blockquote>
12870 <pre>
12871 (float "1.23")       <span class=arw>&rarr;</span> 1.23
12872 (float " 1.23")      <span class=arw>&rarr;</span> 1.23
12873 (float ".5")         <span class=arw>&rarr;</span> 0.50
12874 (float "-1.23")      <span class=arw>&rarr;</span> -1.23
12875 (float "-.5")        <span class=arw>&rarr;</span> nil
12876 (float "#1.23")      <span class=arw>&rarr;</span> nil
12877 (float "#1.23" 0.0)  <span class=arw>&rarr;</span> 0
12878
12879 (float? 123)          <span class=arw>&rarr;</span> nil
12880 (float? (float 123))  <span class=arw>&rarr;</span> true
12881
12882 (float '(a b c))    <span class=arw>&rarr;</span> nil
12883 (float '(a b c) 0)  <span class=arw>&rarr;</span> 0
12884 (float nil 0)       <span class=arw>&rarr;</span> 0
12885
12886 (float "abc" "not a number")  <span class=arw>&rarr;</span> "not a number"
12887 (float "1e500")               <span class=arw>&rarr;</span> inf
12888 (float "-1e500")              <span class=arw>&rarr;</span> -inf
12889
12890 (print "Enter a float num:")
12891 (set 'f-num (float (read-line)))
12892 </pre>
12893 </blockquote>
12894
12895 <p>
12896         Use the <a HREF="#int">int</a> function
12897         to parse integer numbers.
12898 </p>
12899
12900 <br /><br />
12901
12902 <a NAME="floatp"></a>
12903 <h2><span class="function">float?</span></h2>
12904 <b>syntax: (float? <em>exp</em>)</b>
12905
12906 <p>
12907         <tt>true</tt> is returned only
12908         if <em>exp</em> evaluates to a floating point number;
12909         otherwise, <tt>nil</tt> is returned.
12910 </p>
12911
12912 <b>example:</b>
12913 <blockquote>
12914 <pre>
12915 (set 'num 1.23)
12916 (float? num)  <span class=arw>&rarr;</span> true
12917 </pre>
12918 </blockquote>
12919 <br /><br />
12920
12921 <a NAME="floor"></a>
12922 <h2><span class="function">floor</span></h2>
12923 <b>syntax: (floor <em>number</em> )</b>
12924
12925 <p>
12926         Returns the next lowest integer below <em>number</em>
12927         as a floating point.
12928 </p>
12929
12930 <b>example:</b>
12931 <blockquote>
12932 <pre>
12933 (floor -1.5)  <span class=arw>&rarr;</span> -2
12934 (floor 3.4)   <span class=arw>&rarr;</span> 3
12935 </pre>
12936 </blockquote>
12937
12938 <p>
12939         See also the <a HREF="#ceil">ceil</a> function.
12940 </p>
12941
12942 <br /><br />
12943
12944 <a NAME="flt"></a>
12945 <h2><span class="function">flt</span></h2>
12946 <b>syntax: (flt <em>number</em> )</b>
12947
12948 <p>
12949         Converts <em>number</em> to a 32-bit float
12950         represented by an integer.
12951         This function is used when passing 32-bit floats
12952         to library routines.
12953         newLISP floating point numbers
12954         are 64-bit and are passed as 64-bit floats
12955         when calling imported C library routines.
12956 </p>
12957
12958
12959 <b>example:</b>
12960 <blockquote>
12961 <pre>
12962 (flt 1.23)  <span class=arw>&rarr;</span> 1067282596
12963
12964 ;; pass 32-bit float to C-function: foo(float value)
12965 (import "mylib.so" "foo")
12966 (foo (flt 1.23))
12967
12968 (get-int (pack "f" 1.23))  <span class=arw>&rarr;</span> 1067282596
12969
12970 (unpack "f" (pack "ld" (flt 1.2345)))  <span class=arw>&rarr;</span> (1.234500051)
12971 </pre>
12972 </blockquote>
12973
12974 <p>
12975         The last two statements illustrate
12976         the inner workings of <tt>flt</tt>.
12977 </p>
12978
12979 <p>
12980         Use the <a href="#import">import</a> function
12981         to import libraries.
12982 </p>
12983
12984 <br /><br />
12985
12986 <a NAME="for"></a>
12987 <h2><span class="function">for</span></h2>
12988 <b>syntax: (for (<em>sym</em> <em>num-from</em> <em>num-to</em> [<em>num-step</em> [<em>exp-break</em>]]) <em>body</em>)</b>
12989
12990 <p>
12991         Repeatedly evaluates the expressions in <em>body</em>
12992         for a range of values specified
12993         in <em>num-from</em> and <em>num-to</em>, inclusive.
12994         A step size may be specified with <em>num-step</em>.
12995         If no step size is specified, <tt>1.0</tt> is assumed.
12996 </p>
12997
12998 <p>
12999         Optionally, a condition for early loop exit
13000         may be defined in <em>exp-break</em>.
13001         If the break expression evaluates
13002         to any non-<tt>nil</tt> value,
13003         the <tt>for</tt> loop returns with
13004         the value of <em>exp-break</em>.
13005         The break condition is tested
13006         before evaluating <em>body</em>. If a
13007         break condition is defined <em>num-step</em>
13008         must be defined too.
13009 </p>
13010
13011 <p>
13012         The symbol <em>sym</em>
13013         is local in dynamic scope
13014         to the <tt>for</tt> expression.
13015         It takes on each value successively
13016         in the specified range as an integer value
13017         if no step size is specified, or
13018         as a floating point value when a step size is
13019         present.
13020 </p>
13021
13022 <b>example:</b>
13023 <blockquote>
13024 <pre>
13025 &gt; (for (x 1 10 2) (println x))
13026 <b>1
13027 3
13028 5
13029 7
13030 9</b>
13031
13032 &gt; (for (x 8 6 0.5) (println x))
13033 <b>8
13034 7.5
13035 7
13036 6.5
13037 6</b>
13038
13039 &gt; (for (x 1 100 2 (&gt; (* x x) 30)) (println x))
13040 <b>1
13041 3
13042 5
13043 true</b>
13044 &gt; _
13045 </pre>
13046 </blockquote>
13047
13048 <p>
13049         The second example uses
13050         a range of numbers
13051         from highest to lowest.
13052         Note that the step size
13053         is always a positive number.
13054         In the third example,
13055         a break condition is tested.
13056 </p>
13057
13058 <p>
13059         Use the <a HREF="#sequence">sequence</a> function
13060         to make a sequence of numbers.
13061 </p>
13062
13063 <br /><br />
13064
13065 <a NAME="for-all"></a>
13066 <h2><span class="function">for-all</span></h2>
13067
13068 <b>syntax: (for-all <em>func-condition</em> <em>list</em>)</b>
13069
13070 <p>Applies the function in <em>func-condition</em>
13071 to all elements in <em>list</em>.
13072 If all elements meet the condition in <em>func-condition</em>,
13073 the result is <tt>true</tt>;
13074 otherwise, <tt>nil</tt> is returned.</p>
13075
13076 <b>example:</b>
13077 <blockquote>
13078 <pre>
13079 (for-all number? '(2 3 4 6 7))                 <span class=arw>&rarr;</span> true
13080
13081 (for-all number? '(2 3 4 6 "hello" 7))         <span class=arw>&rarr;</span> nil
13082
13083 (for-all (fn (x) (= x 10)) '(10 10 10 10 10))  <span class=arw>&rarr;</span> true
13084 </pre>
13085 </blockquote>
13086
13087 <p>Use the <a href="#exists">exists</a> function
13088 to check if at least one element in a list
13089 meets a condition.</p>
13090
13091 <br /><br />
13092
13093 <a NAME="fork"></a>
13094 <h2><span class="function">fork</span></h2>
13095
13096 <b>syntax: (fork <em>exp</em>)</b>
13097
13098 <p>
13099         The expression in <em>exp</em> is launched
13100         as a newLISP child process thread
13101         of the platforms OS.
13102         The new process inherits
13103         the entire address space,
13104         but runs independently,
13105         so symbol or variable contents
13106         changed in the child thread
13107         will not affect the parent process
13108         or vice versa.
13109         The child process ends
13110         when the evaluation of <em>exp</em> finishes.
13111 </p>
13112
13113 <p>
13114         On success, <tt>fork</tt> returns with the child process ID;
13115         on failure, <tt>nil</tt> is returned.
13116         See also the <a href="#wait-pid">wait-pid</a> function,
13117         which waits for a child process to finish.
13118 </p>
13119
13120 <p>
13121         This function is only available
13122         on Linux/UNIX versions of newLISP
13123         and is based on the <tt>fork()</tt>
13124         implementation of the underlying OS. </p>
13125
13126 <b>example:</b>
13127 <blockquote>
13128 <pre>
13129 &gt; (set 'x 0)
13130 <b>0</b>
13131 &gt; (fork (while (&lt; x 20) (println (inc 'x)) (sleep 1000)))
13132 <b>176</b>
13133
13134 &gt; <b>1
13135 2
13136 3
13137 4
13138 5
13139 6</b>
13140 </pre>
13141 </blockquote>
13142
13143
13144 <p>
13145         The example illustrates
13146         how the child process thread
13147         inherits the symbol space
13148         and how it is independent of
13149         the parent process.
13150         The <tt>fork</tt> statement
13151         returns immediately with
13152         the process ID <tt>176</tt>.
13153         The child process increments
13154         the variable <tt>x</tt>
13155         by one each second and prints it
13156         to standard out (boldface).
13157         In the parent process,
13158         commands can still be entered.
13159         Type <tt>x</tt> to see that
13160         the symbol <tt>x</tt> still
13161         has the value <tt>0</tt> (zero)
13162         in the parent process.
13163         Although statements entered
13164         will mix with the display
13165         of the child process output,
13166         they will be correctly input
13167         to the parent process.
13168 </p>
13169
13170 <p>
13171         The second example illustrates
13172         how <a href="#pipe">pipe</a> can be used
13173         to communicate between threads.
13174 </p>
13175
13176 <b>example:</b>
13177 <blockquote>
13178 <pre>
13179 #!/usr/bin/newlisp
13180
13181 (define (count-down-thread x channel)
13182   (while (!= x 0)
13183     (begin
13184       (write-line (string x) channel)
13185       (dec 'x))))
13186
13187 (define (observer-thread channel)
13188   (do-until (= i "1")
13189     (println "thread " (setq i (read-line channel)))))
13190
13191 (map set '(in out) (pipe))
13192 (set 'observer (fork (observer-thread in)))
13193 (set 'counter (fork (count-down-thread 5 out)))
13194
13195 ; avoid zombies
13196 (wait-pid observer)
13197 (wait-pid counter)
13198
13199 (exit)
13200 </pre>
13201 </blockquote>
13202
13203 <p>The following output is generated by observer-thread</p>
13204
13205 <blockquote>
13206 <pre>
13207 thread 5
13208 thread 4
13209 thread 3
13210 thread 2
13211 thread 1
13212 </pre>
13213 </blockquote>
13214
13215 <p>
13216         The <tt>count-down-thread</tt> writes
13217         numbers to the communication pipe,
13218         where they are picked up by
13219         the <tt>observer-thread</tt>
13220         and displayed.
13221 </p>
13222
13223 <p>A forked process can either exit by itself or it can be destroyed using
13224 the <a href="#destroy">destroy</a> function.</p<
13225
13226 <blockquote>
13227 <pre>
13228 (define (fork-destroy-demo)
13229         (set 'pid (fork (dotimes (i 1000) (println i) (sleep 10))))
13230         (sleep 50)
13231         (destroy pid)
13232 )
13233
13234 &gt; (fork-destroy-demo)
13235 <b>0
13236 1
13237 2
13238 3
13239 4
13240 true</b>
13241 &gt;
13242 </pre>
13243 </blockquote>
13244
13245 <p>The process started by <tt>fork-destroy-demo</tt> will not finishe but is
13246 destroyed 50 milli seconds after start by a call to <a href="#destroy">destroy</a>.
13247 </p>
13248
13249 <p>
13250         Use the <a href="#semaphore">semaphore</a>
13251         function for synchronizing threads
13252         and <a href="#share">share</a>
13253         for sharing memory between threads.
13254 </p>
13255
13256 <br /><br />
13257
13258 <a NAME="format"></a>
13259 <h2><span class="function">format</span></h2>
13260 <b>syntax: (format <em>str-format exp-data-1</em> [<em>exp-data-i</em> ... ] )</b><br>
13261 <b>syntax: (format <em>str-format</em> <em>list-data</em>)</b>
13262
13263 <p>
13264         Constructs a formatted string
13265         from <em>exp-data-1</em>
13266         using the format specified
13267         in the evaluation of <em>str-format</em>.
13268         The format specified is identical
13269         to the format used for the <tt>printf()</tt>
13270         function in the ANSI C language.
13271         Two or more <em>exp-data</em> arguments
13272         can be specified for more than one
13273         format specifier in <em>str-format</em>.
13274 </p>
13275
13276 <p>
13277         In an alternative syntax,
13278         the data to be formatted
13279         can be passed inside a list
13280         in <em>list-data</em>.
13281 </p>
13282
13283 <p>
13284         <tt>format</tt> checks for a valid format string,
13285         matching data type, and the correct number of arguments.
13286         Wrong formats or data types result in error messages.
13287         <a href="#int">int</a>, <a href="#float">float</a>,
13288         or <a href="#string">string</a> can be used
13289         to ensure correct data types and to avoid error messages.
13290 </p>
13291
13292 <p>
13293         The format string has the following general format:
13294 </p>
13295
13296 <blockquote>
13297
13298 <pre><font size="+1">"%w.pf"</font></pre>
13299 </blockquote>
13300
13301 <p>
13302         The <tt>%</tt> (percent sign)
13303         starts a format specification.
13304         To display a <tt>%</tt> inside a
13305         format string, double it: <tt>%%</tt></p>
13306
13307 <p>
13308         The <tt>w</tt> represents the width field.
13309         Data is right-aligned,
13310         except when preceded
13311         by a minus sign,
13312         in which case it is left-aligned.
13313         When preceded by a zero,
13314         the unused space is filled
13315         with leading zeroes.
13316         The width field is optional
13317         and serves all data types.
13318 </p>
13319
13320 <p>
13321         The <tt>p</tt> represents the precision number
13322         of decimals (floating point only)
13323         or strings and is separated
13324         from the width field by a period.
13325         Precision is optional.
13326         If preceded by a <tt>+</tt> (plus sign),
13327         positive numbers are displayed with a <tt>+</tt>.
13328         When using the precision field on strings,
13329         the number of characters displayed
13330         is limited to the number in <tt>p</tt>.
13331 </p>
13332
13333 <p>
13334         The <tt>f</tt> represents
13335         a type flag and is essential;
13336         it cannot be omitted.
13337 </p>
13338
13339 <p>
13340         Below are the types in <tt>f</tt>:
13341 </p>
13342
13343 <blockquote>
13344 <pre>
13345 s       text string
13346 c       character (value 1 - 255)
13347 d       decimal (32-bit)
13348 u       unsigned decimal (32-bit)
13349 x       hexadecimal lowercase
13350 X       hexadecimal uppercase
13351 o       octal (32-bits) (not supported on all compilers)
13352 f       floating point
13353 e       scientific floating point
13354 E       scientific floating point
13355 g       general floating point
13356 </pre>
13357 </blockquote>
13358
13359 <p>Formatting 64-bit numbers using 32-bit format specifiers will truncate and
13360 format the lower 32 bits of the number.
13361 </p>
13362
13363 <p>For 64-bit numbers (since version 8.9.7) use the following format
13364 strings on UNIX like operating systems:
13365 </p>
13366
13367 <blockquote>
13368 <pre>
13369 lld     decimal (64-bit)
13370 llu     unsigned decimal (64-bit)
13371 llx     hexadecimal (64-bit)
13372 llX     hexadecimal uppercase(64-bit)
13373 </pre>
13374 </blockquote>
13375
13376 <p>For 64-bit numbers (since version 8.9.7) use the following format
13377 strings on Tru64 UNIX:
13378 </p>
13379
13380 <blockquote>
13381 <pre>
13382 ld     decimal (64-bit)
13383 lu     unsigned decimal (64-bit)
13384 lx     hexadecimal (64-bit)
13385 lX     hexadecimal uppercase(64-bit)
13386 </pre>
13387 </blockquote>
13388
13389 <p>On Win32 platforms the following characters apply for 64 bit numbers:
13390 </p>
13391
13392 <blockquote>
13393 <pre>
13394 I64d    decimal (64-bit)
13395 I64u    unsigned decimal (64-bit)
13396 I64x    hexadecimal (64-bit)
13397 I64X    hexadecimal uppercase(64-bit)
13398 </pre>
13399 </blockquote>
13400
13401 <p>
13402         Other text may occur between,
13403         before, or after the format specs.
13404 </p>
13405
13406 <p>Note that on Tru64 UNIX the format character <tt>i</tt> can be used instead
13407 of <tt>d</tt>.
13408 </p>
13409
13410 <br /><br />
13411 <b>example:</b>
13412 <blockquote>
13413 <pre>
13414 (format "&gt;&gt;&gt;%6.2f&lt;&lt;&lt;" 1.2345)     <span class=arw>&rarr;</span> "&gt;&gt;&gt;  1.23&lt;&lt;&lt;"
13415 (format "&gt;&gt;&gt;%-6.2f&lt;&lt;&lt;" 1.2345)    <span class=arw>&rarr;</span> "&gt;&gt;&gt;1.23  &lt;&lt;&lt;"
13416 (format "&gt;&gt;&gt;%+6.2f&lt;&lt;&lt;" 1.2345)    <span class=arw>&rarr;</span> "&gt;&gt;&gt; +1.23&lt;&lt;&lt;"
13417 (format "&gt;&gt;&gt;%+6.2f&lt;&lt;&lt;" -1.2345)   <span class=arw>&rarr;</span> "&gt;&gt;&gt; -1.23&lt;&lt;&lt;"
13418 (format "&gt;&gt;&gt;%-+6.2f&lt;&lt;&lt;" -1.2345)  <span class=arw>&rarr;</span> "&gt;&gt;&gt;-1.23 &lt;&lt;&lt;"
13419
13420 (format "%e" 123456789)        <span class=arw>&rarr;</span> "1.234568e+08"
13421 (format "%12.10E" 123456789)   <span class=arw>&rarr;</span> "1.2345678900E+08"
13422
13423 (format "%10g" 1.23)   <span class=arw>&rarr;</span> "      1.23"
13424 (format "%10g" 1.234)  <span class=arw>&rarr;</span> "     1.234"
13425
13426 (format "Result = %05d" 2)  <span class=arw>&rarr;</span> "Result = 00002"
13427
13428 (format "%-15s" "hello")        <span class=arw>&rarr;</span> "hello          "
13429 (format "%15s %d" "hello" 123)  <span class=arw>&rarr;</span> "          hello 123"
13430 (format "%5.2s" "hello")        <span class=arw>&rarr;</span> "   he"
13431 (format "%-5.2s" "hello")       <span class=arw>&rarr;</span> "he   "
13432
13433 (format "%o" 80)    <span class=arw>&rarr;</span> "120"
13434
13435 (format "%x %X" -1 -1)  <span class=arw>&rarr;</span> "ffffffff FFFFFFFF"
13436
13437 (format "%c" 65)  <span class=arw>&rarr;</span> "A"
13438 </pre>
13439 </blockquote>
13440
13441 <p>
13442         The data to be formatted
13443         can be passed inside a list:
13444 </p>
13445
13446 <blockquote>
13447 <pre>
13448 (set 'L '("hello" 123))
13449 (format "%15s %d" L)  <span class=arw>&rarr;</span> "          hello 123"
13450 </pre>
13451 </blockquote>
13452
13453 <p>
13454         If the format string requires it,
13455         newLISP's <tt>format</tt> will
13456         automatically convert integers
13457         into floating points
13458         or floating points into integers:
13459 </p>
13460
13461 <blockquote>
13462 <pre>
13463 (format "%f" 123)      <span class=arw>&rarr;</span> 123.000000
13464
13465 (format "%d" 123.456)  <span class=arw>&rarr;</span> 123
13466 </pre>
13467 </blockquote>
13468
13469 <br /><br />
13470
13471 <a NAME="fv"></a>
13472 <h2><span class="function">fv</span></h2>
13473 <b>syntax: (fv <em>num-rate</em> <em>num-nper</em> <em>num-pmt</em> <em>num-pv</em> [<em>int-type</em>])</b>
13474
13475 <p>
13476         Calculates the future value of a loan
13477         with constant payment <em>num-pmt</em>
13478         and constant interest rate <em>num-rate</em>
13479         after <em>num-nper</em> period of time and
13480         a beginning principal value of <em>num-pv</em>.
13481         If payment is at the end of the period,
13482         <em>int-type</em> is 0 (zero); for payment
13483         at the end of each period, <em>int-type</em> is 1.
13484         If <em>num-type</em> is omitted, payment
13485         at the end of each period is assumed.
13486 </p>
13487
13488 <b>example:</b>
13489 <blockquote>
13490 <pre>
13491 (fv (div 0.07 12) 240 775.30 -100000)  <span class=arw>&rarr;</span> -0.5544645052
13492 </pre>
13493 </blockquote>
13494
13495 <p>
13496         The example illustrates
13497         how a loan of $100,000
13498         is paid down to a residual of $0.55
13499         after 240 monthly payments
13500         at a yearly interest rate of 7 percent.
13501 </p>
13502
13503 <p>
13504         See also the functions <a href="#irr">irr</a>,
13505         <a HREF="#nper">nper</a>, <a HREF="#npv">npv</a>,
13506         <a HREF="#pmt">pmt</a>, and <a HREF="#pv">pv</a>.
13507 </p>
13508
13509 <br /><br />
13510
13511 <a NAME="gammai"></a>
13512 <h2><span class="function">gammai</span></h2>
13513 <b>syntax: (gammai <em>num-a</em> <em>num-b</em>)</b>
13514
13515 <p>
13516         Calculates the incomplete Gamma function
13517         of values <em>a</em> and <em>b</em> in <em>num-a</em> and <em>num-b</em>,
13518         respectively.
13519 </p>
13520
13521 <b>example:</b>
13522 <blockquote>
13523 <pre>
13524 (gammai 4 5)  <span class=arw>&rarr;</span> 0.7349740847
13525 </pre>
13526 </blockquote>
13527
13528 <p>
13529         The incomplete Gamma function is used to derive
13530         the probability of Chi&sup2; to exceed a
13531         given value for a degree of freedom, df, as follows:
13532 </p>
13533
13534 <BLOCKQUOTE>
13535 <em><b>Q(Chi&sup2;|df) = Q(df/2, Chi&sup2;/2) = gammai(df/2, Chi&sup2;/2)</b></em>
13536 </BLOCKQUOTE>
13537
13538 <p>
13539         See also the <a HREF="#prob-chi2">prob-chi2</a> function.
13540 </p>
13541
13542 <br /><br />
13543
13544 <a NAME="gammaln"></a>
13545 <h2><span class="function">gammaln</span></h2>
13546 <b>syntax: (gammaln <em>num-x</em>)</b>
13547
13548 <p>
13549         Calculates the log Gamma function of the value <em>x</em> in <em>num-x</em>.
13550 </p>
13551
13552 <b>example:</b>
13553 <blockquote>
13554 <pre>
13555 (exp (gammaln 6))  <span class=arw>&rarr;</span> 120
13556 </pre>
13557 </blockquote>
13558
13559 <p>
13560         The example uses the equality of <em>n! = gamma(n + 1)</em>
13561         to calculate the factorial value of 5.
13562 </p>
13563
13564 <p>
13565         The log Gamma function is also related to the Beta function,
13566         which can be derived from it:
13567 </p>
13568
13569 <BLOCKQUOTE>
13570 <em><b>Beta(z,w) = Exp(Gammaln(z) + Gammaln(w) - Gammaln(z+w))</b></em>
13571
13572 </BLOCKQUOTE>
13573 <br /><br />
13574
13575
13576 <a NAME="gcd"></a>
13577 <h2><span class="function">gcd</span></h2>
13578 <b>syntax: (gcd <em>int_1</em> [<em>int-2 ...</em>])</b>
13579 <a NAME="gcd"></a>
13580
13581 <p>
13582         Calculates the greatest common divisor
13583         of a group of integers.
13584         The greatest common divisor of two integers
13585         that are not both zero
13586         is the largest integer that divides both numbers.
13587         <tt>gcd</tt> will calculate the greatest common divisor
13588         for the first two integers in <em>int-i</em>
13589         and then further reduce the argument list
13590         by calculating the greatest common divisor of the result
13591         and the next argument in the parameter list.
13592 </p>
13593
13594 <b>example:</b>
13595 <blockquote>
13596 <pre>
13597 (gcd 0)        <span class=arw>&rarr;</span> 0
13598 (gcd 0 0)      <span class=arw>&rarr;</span> 0
13599 (gcd 10)       <span class=arw>&rarr;</span> 10
13600 (gcd 12 36)    <span class=arw>&rarr;</span> 12
13601 (gcd 15 36 6)  <span class=arw>&rarr;</span> 3
13602 </pre>
13603 </blockquote>
13604
13605 <p>
13606         See
13607         <a href="http://en.wikipedia.org/wiki/Greatest_common_divisor">Wikipedia</a>
13608         for details and theory about gcd numbers in mathematics.
13609 </p>
13610
13611 <br /><br />
13612
13613 <a NAME="get-char"></a>
13614 <h2><span class="function">get-char</span></h2>
13615 <b>syntax: (get-char <em>int-address</em>)</b>
13616
13617 <p>
13618         Gets a character from an address
13619         specified in <em>int-address</em>.
13620         This function is useful when using
13621         imported shared library functions
13622         with <a HREF="#import">import</a>.
13623 </p>
13624
13625 <b>example:</b>
13626 <blockquote>
13627 <pre>
13628 char * foo(void)
13629         {
13630         char * result;
13631         result = "ABCDEFG";
13632         return(result);
13633         }
13634 </pre>
13635 </blockquote>
13636
13637 <p>
13638         Consider the above C function
13639         from a shared library, which returns a
13640         character pointer (address to a string).
13641 </p>
13642
13643 <blockquote>
13644 <pre>
13645 (import "mylib.so" "foo")
13646 (print (get-char (foo) ))       <span class=arw>&rarr;</span>  65
13647 (print (get-char (+ (foo) 1)))  <span class=arw>&rarr;</span>  66
13648 </pre>
13649
13650 </blockquote>
13651
13652 <p>
13653         Note that it is unsafe to use the <tt>get-char</tt> function
13654         with an incorrect address in <em>int-address</em>. Doing so
13655         could result in the system crashing or becoming unstable.
13656 </p>
13657
13658 <p>
13659         See also the <a href="#address">address</a>,
13660         <a HREF="#get-int">get-int</a>,
13661     <a HREF="#get-long">get-long</a>,
13662         <a HREF="#get-float">get-float</a>,
13663         <a HREF="#get-string">get-string</a>,
13664         <a HREF="#pack">pack</a>, and <a HREF="#unpack">unpack</a> functions.
13665 </p>
13666
13667 <br /><br />
13668
13669 <a NAME="get-float"></a>
13670 <h2><span class="function">get-float</span></h2>
13671 <b>syntax: (get-float <em>int-address</em>)</b>
13672
13673 <p>
13674         Gets a 64-bit double float from an address
13675         specified in <em>int-address</em>.
13676         This function is helpful when using
13677         imported shared library functions (with <tt>import</tt>)
13678         that return an address pointer to a double float
13679         or a pointer to a structure containing double floats.
13680 </p>
13681
13682 <b>example:</b>
13683 <blockquote>
13684 <pre>
13685 double float * foo(void)
13686         {
13687         double float * result;
13688         &hellip;
13689         *result = 123.456;
13690         return(result);
13691         }
13692 </pre>
13693 </blockquote>
13694
13695 <p>
13696         The previous C function is compiled
13697         into a shared library.
13698 </p>
13699
13700 <blockquote>
13701 <pre>
13702 (import "mylib.so" "foo")
13703 (get-float (foo))  <span class=arw>&rarr;</span> 123.456
13704 </pre>
13705 </blockquote>
13706
13707 <p>
13708         <tt>foo</tt> is imported and returns a pointer
13709         to a double float when called.
13710         Note that <tt>get-float</tt> is unsafe when used
13711         with an incorrect address in <em>int-address</em>
13712         and may result in the system crashing or becoming unstable.
13713 </p>
13714
13715 <p>
13716         See also the <a href="#address">address</a>,
13717         <a HREF="#get-int">get-int</a>,
13718     <a HREF="#get-long">get-long</a>,
13719         <a HREF="#get-char">get-char</a>,
13720         <a HREF="#get-string">get-string</a>,
13721         <a HREF="#pack">pack</a>,
13722         and <a HREF="#unpack">unpack</a> functions.
13723 </p>
13724
13725 <br /><br />
13726
13727 <a NAME="get-int"></a>
13728 <h2><span class="function">get-int</span></h2>
13729 <b>syntax: (get-int <em>int-address</em>)</b>
13730
13731 <p>
13732         Gets a 32-bit integer from
13733         the address specified in <em>int-address</em>.
13734         This function is handy when using
13735         imported shared library functions with <tt>import</tt>,
13736         a function returning an address pointer
13737         to an integer, or a pointer to a structure containing integers.
13738 </p>
13739
13740 <b>example:</b>
13741 <blockquote>
13742 <pre>
13743 int * foo(void)
13744         {
13745         int * result;
13746         &hellip;
13747         *result = 123;
13748         return(result);
13749         }
13750
13751 int foo-b(void)
13752         {
13753         int result;
13754         &hellip;
13755         result = 456;
13756         return(result);
13757         }
13758 </pre>
13759 </blockquote>
13760
13761 <p>
13762         Consider the C function <tt>foo</tt> (from a shared library),
13763         which returns an integer pointer (address of an integer).
13764 </p>
13765
13766 <blockquote>
13767 <pre>
13768 (import "mylib.so" "foo")
13769 (get-int (foo))  <span class=arw>&rarr;</span> 123
13770 (foo-b)          <span class=arw>&rarr;</span> 456
13771 </pre>
13772 </blockquote>
13773
13774 <p>
13775         Note that using <tt>get-int</tt> with an incorrect address
13776         in <em>int-address</em> is unsafe and could result
13777         in the system crashing or becoming unstable.
13778 </p>
13779
13780 <p>
13781         See also the <a href="#address">address</a>,
13782         <a HREF="#get-char">get-char</a>,
13783         <a HREF="#get-float">get-float</a>,
13784     <a HREF="#get-long">get-long</a>,
13785         <a HREF="#get-string">get-string</a>,
13786         <a HREF="#pack">pack</a>,
13787         and <a HREF="#unpack">unpack</a> functions.
13788 </p>
13789
13790 <br /><br />
13791
13792 <a NAME="get-long"></a>
13793 <h2><span class="function">get-long</span></h2>
13794 <b>syntax: (get-long <em>int-address</em>)</b>
13795
13796 <p>
13797         Gets a 64-bit integer from
13798         the address specified in <em>int-address</em>.
13799         This function is handy when using <tt>import</tt>
13800         to import shared library functions,
13801         a function returning an address pointer to a long integer,
13802         or a pointer to a structure containing long integers.
13803 </p>
13804
13805 <b>example:</b>
13806 <blockquote>
13807 <pre>
13808 long long int * foo(void)
13809         {
13810         int * result;
13811         &hellip;
13812         *result = 123;
13813         return(result);
13814         }
13815
13816 long long int foo-b(void)
13817         {
13818         int result;
13819         &hellip;
13820         result = 456;
13821         return(result);
13822         }
13823 </pre>
13824 </blockquote>
13825
13826 <p>
13827         Consider the C function <tt>foo</tt> (from a shared library),
13828         which returns an integer pointer (address of an integer).
13829 </p>
13830
13831 <blockquote>
13832 <pre>
13833 (import "mylib.so" "foo")
13834 (get-int (foo))  <span class=arw>&rarr;</span> 123
13835 (foo-b)          <span class=arw>&rarr;</span> 456
13836 </pre>
13837 </blockquote>
13838
13839 <p>
13840         Note that using <tt>get-long</tt> with an incorrect address
13841         in <em>int-address</em> is unsafe and could result
13842         in the system crashing or becoming unstable.
13843 </p>
13844
13845 <p>
13846         See also the <a href="#address">address</a>,
13847         <a HREF="#get-char">get-char</a>,
13848         <a HREF="#get-float">get-float</a>,
13849     <a HREF="#get-int">get-int</a>,
13850         <a HREF="#get-string">get-string</a>,
13851         <a HREF="#pack">pack</a>,
13852         and <a HREF="#unpack">unpack</a> functions.
13853 </p>
13854
13855 <br /><br />
13856
13857
13858 <a NAME="get-string"></a>
13859 <h2><span class="function">get-string</span></h2>
13860 <b>syntax: (get-string <em>int-address</em>)</b>
13861
13862 <p>
13863         Gets a character string from the address
13864         specified in <em>int-address</em>.
13865         This function is helpful when
13866         using imported shared library functions
13867         with <a HREF="#import">import</a>.
13868 </p>
13869
13870 <b>example:</b>
13871 <blockquote>
13872 <pre>
13873 char * foo(void)
13874         {
13875         char * result;
13876         result = "ABCDEFG";
13877         return(result);
13878         }
13879 </pre>
13880 </blockquote>
13881
13882 <p>
13883         Consider the above C function from a shared library,
13884         which returns a character pointer (address to a string).
13885 </p>
13886
13887 <blockquote>
13888 <pre>
13889 (import "mylib.so" "foo")
13890 (print (get-string (foo)))  <span class=arw>&rarr;</span> "ABCDEFG"
13891 </pre>
13892 </blockquote>
13893
13894 <p>
13895         When a string is passed as an argument,
13896         <tt>get-string</tt> will take its address as the argument.
13897         Because <tt>get-string</tt> always breaks off
13898         at the first first <tt>\000</tt> (null character) it encounters,
13899         it can be used to retrieve a string from a buffer:
13900 </p>
13901
13902 <b>example:</b>
13903 <blockquote>
13904 <pre>
13905 (set 'buff "ABC\000\000\000")  <span class=arw>&rarr;</span> "ABC\000\000\000"
13906
13907 (length buff)  <span class=arw>&rarr;</span> 6
13908
13909 (get-string buff)  <span class=arw>&rarr;</span> "ABC"
13910
13911 (length (get-string buff))  <span class=arw>&rarr;</span> 3
13912 </pre>
13913 </blockquote>
13914
13915 <p>
13916         See also the <a HREF="#get-char">get-char</a>,
13917         <a HREF="#get-int">get-int</a>,
13918         <a HREF="#get-float">get-float</a>,
13919         <a HREF="#pack">pack</a>,
13920         and <a HREF="#unpack">unpack</a> functions.
13921 </p>
13922
13923 <p>
13924         Note that <tt>get-string</tt> can crash the system
13925         or make it unstable if the wrong address is specified.
13926 </p>
13927
13928 <br /><br />
13929
13930 <a NAME="get-url"></a>
13931 <h2><span class="function">get-url</span></h2>
13932 <b>syntax: (get-url <em>str-url</em> [<em>str-option</em>] [<em>int-timeout</em> [<em>str-header</em>]])</b>
13933
13934 <p>Reads a web page or file specified by the URL in <em>str-url</em> using
13935 the HTTP GET protocol.  Both <tt>http://</tt> and <tt>file://</tt>
13936 URLs are handled.  <tt>"header"</tt> can be optionally specified
13937 to retrieve only the header.  An  option, <tt>"list"</tt>,
13938 causes header and page information to be returned as separate strings in a list. </p>
13939
13940 <p>A <tt>"debug"</tt> option can be specified either alone or after the
13941 <tt>"header"</tt> or <tt>"list"</tt> option separated by one character,
13942 i.e. <tt>"header debug"</tt> or <tt>"list debug"</tt>. This option
13943 outputs all outgoing information to the console window.</p>
13944
13945 <p>
13946         The optional argument <em>int-timeout</em>
13947         can specify a value in milliseconds.
13948         If no data is available from the host
13949         after the specified timeout,
13950         <tt>get-url</tt> returns the string <tt>ERR: timeout</tt>.
13951         When other error conditions occur,
13952         <tt>get-url</tt> returns a string starting with <tt>ERR:</tt>
13953         and the description of the error.
13954 </p>
13955
13956 <p><tt>get-url</tt> requests are also understood by newLISP server nodes.
13957 </p>
13958
13959 <b>example:</b>
13960 <blockquote>
13961 <pre>
13962 (get-url "http://www.nuevatec.com")
13963 (get-url "http://www.nuevatec.com" 3000)
13964 (get-url "http://www.nuevatec.com" "header")
13965 (get-url "http://www.nuevatec.com" "header" 5000)
13966 (get-url "http://www.nuevatec.com" "list")
13967
13968 (get-url "file:///home/db/data.txt") ; access local file system
13969
13970 (env "HTTP_PROXY" "http://ourproxy:8080")
13971 (get-url "http://www.nuevatec.com/newlisp/")
13972 </pre>
13973 </blockquote>
13974
13975 <p>
13976         The index page from the site specified
13977         in <em>str-url</em> is returned as a string.
13978         In the third line,
13979         only the HTTP header
13980         is returned in a string.
13981         Lines 2 and 4 show a
13982         timeout value being used.
13983 </p>
13984
13985 <p> The second example shows usage of a <tt>file://</tt> URL
13986 to acces <tt>/home/db/data.txt</tt> on the local file system.</p>
13987
13988 <p>
13989         The third example illustrates
13990         the use of a proxy server.
13991         The proxy server's URL must be
13992         in the operating system's environment.
13993         As shown in the example,
13994         this can be added using
13995         the <a HREF="#env">env</a>
13996         function.
13997 </p>
13998
13999 <p>
14000         The <em>int-timeout</em> can be followed
14001         by an optional custom header in <em>str-header</em>:
14002 </p>
14003
14004 <b>Custom header</b>
14005
14006         <p>The custom header may contain options
14007         for browser cookies or other directives to the server.
14008         When no <em>str-header</em> is specified,
14009         newLISP sends certain header information by default.
14010         After the following request:
14011 </p>
14012
14013 <blockquote>
14014 <pre>
14015 (get-url "http://somehost.com" 5000)
14016 </pre>
14017 </blockquote>
14018
14019 <p>
14020         newLISP will configure and send
14021         the request and header below:
14022 </p>
14023
14024 <blockquote>
14025 <pre>
14026 GET / HTTP/1.1
14027 Host: somehost.com
14028 User-Agent: newLISP v8800
14029 Connection: close
14030 </pre>
14031 </blockquote>
14032
14033 <p>
14034         As an alternative, the <em>str-header</em>
14035         option could be used:
14036 </p>
14037
14038 <blockquote>
14039 <pre>
14040 (get-url "http://somehost.com" 5000
14041     "User-Agent: Mozilla/4.0\r\nCookie: name=fred\r\n")
14042 </pre>
14043 </blockquote>
14044
14045 <p>
14046         newLISP will now send the
14047         following request and header:
14048 </p>
14049
14050 <blockquote>
14051 <pre>
14052 GET / HTTP/1.1
14053 Host: somehost.com
14054 User-Agent: Mozilla/4.o
14055 Cookie: name=fred
14056 Connection: close
14057 </pre>
14058 </blockquote>
14059
14060 <p>
14061         Note that when using a custom header,
14062         newLISP will only supply the <tt>GET</tt> request line,
14063         as well as the <tt>Host:</tt> and <tt>Connection:</tt> header entries.
14064         newLISP inserts all other entries supplied in the custom header
14065         between the <tt>Host:</tt> and <tt>Connection:</tt> entries.
14066         Each entry must end with a carriage return
14067         line-feed pair: <tt>\r\n</tt>.
14068
14069 </p>
14070
14071 <p>
14072         See an HTTP transactions reference
14073         for valid header entries.
14074 </p>
14075
14076 <p>
14077         Custom headers can also be used
14078         in the <a HREF="#put-url">put-url</a>
14079         and <a HREF="#post-url">post-url</a> functions.
14080 </p>
14081
14082 <br /><br />
14083
14084 <a NAME="global"></a>
14085 <h2><span class="function">global</span></h2>
14086
14087 <b>syntax: (global <em>sym-1</em> [<em>sym-2 ...</em>])</b>
14088
14089 <p>
14090         One or more symbols in <em>sym-1</em> [<em>sym-2 ...</em>]
14091         can be made globally accessible from contexts other than MAIN.
14092         The statement has to be executed in the MAIN context,
14093         and only symbols belonging to MAIN can be made global.
14094         <tt>global</tt> returns the last symbol made global.
14095 </p>
14096
14097 <b>example:</b>
14098 <blockquote>
14099 <pre>
14100 (global 'aVar 'x 'y 'z)  <span class=arw>&rarr;</span> z
14101
14102 (define (foo x)
14103   (&hellip;))
14104
14105 (constant (global 'foo))
14106 </pre>
14107 </blockquote>
14108
14109 <p>
14110         The second example shows how <a href="#constant">constant</a>
14111         and <tt>global</tt> can be combined into one statement,
14112         protecting and making a previous function definition global.
14113 </p>
14114
14115
14116 <br /><br />
14117
14118 <a NAME="globalp"></a>
14119 <h2><span class="function">global?</span></h2>
14120
14121 <b>syntax: (global? <em>sym</em>)</b>
14122
14123 <p>Checks if symbol in <em>sym</em> is global. Bult-in functions context
14124 symbols and all symbols made global using the function <a href="#global">global</a>
14125 are global:</p>
14126
14127 <b>example:</b>
14128 <blockquote>
14129 <pre>
14130 global? 'print)   <span class=arw>&rarr;</span> true
14131 (global 'var)     <span class=arw>&rarr;</span> var
14132 (global? 'var)    <span class=arw>&rarr;</span> true
14133
14134 (constant (global 'foo))
14135
14136 (global? 'foo)    <span class=arw>&rarr;</span> true
14137 </pre>
14138 </blockquote>
14139
14140 <br /><br />
14141
14142 <a NAME="if"></a>
14143 <h2><span class="function">if</span></h2>
14144
14145 <b>syntax: (if <em>exp-condition</em> <em>exp-1</em> [<em>exp-2</em>])</b><br />
14146
14147 <b>syntax: (if <em>exp-cond-1</em> <em>exp-1</em>  <em>exp-cond-2</em> <em>exp-2</em> [... ])</b>
14148 <p>
14149         If the value of <em>exp-condition</em> is not nil or an empty list,
14150         the result of evaluating <em>exp-1</em> is returned;
14151         otherwise, the value of <em>exp-2</em> is returned.
14152         If <em>exp-2</em> is absent, the value of
14153         <em>exp-condition</em> is returned.
14154 </p>
14155
14156 <b>example:</b>
14157 <blockquote>
14158 <pre>
14159 (set 'x 50)                   <span class=arw>&rarr;</span> 50
14160 (if (&lt; x 100) "small" "big")  <span class=arw>&rarr;</span> "small"
14161 (set 'x 1000)                 <span class=arw>&rarr;</span> 1000
14162 (if (&lt; x 100) "small" "big")  <span class=arw>&rarr;</span> "big"
14163 (if (&gt; x 2000) "big")         <span class=arw>&rarr;</span> nil
14164 </pre>
14165 </blockquote>
14166
14167 <p>
14168         The second form of <tt>if</tt> works similarly
14169         to <a href="#cond">cond</a>, except it does not take
14170         parentheses around the condition-body pair of expressions.
14171         In this form, <tt>if</tt> can have
14172         an unlimited number of arguments.
14173 </p>
14174
14175 <b>example:</b>
14176 <blockquote>
14177 <pre>
14178 (define (classify x)
14179     (if
14180         (&lt; x 0) "negative"
14181         (&lt; x 10) "small"
14182         (&lt; x 20) "medium"
14183         (&gt;= x 30) "big"
14184         "n/a"))
14185
14186 (classify 15)   <span class=arw>&rarr;</span> "medium"
14187 (classify 100)  <span class=arw>&rarr;</span> "big"
14188 (classify 22)   <span class=arw>&rarr;</span> "n/a"
14189 (classify -10)  <span class=arw>&rarr;</span> "negative"
14190 </pre>
14191 </blockquote>
14192
14193 <p>
14194         The last expression, <tt>"n/a"</tt>, is optional.
14195         When this option is omitted,
14196         the evaluation of <tt>(&gt;= x 30)</tt>
14197         is returned, behaving exactly like a traditional
14198         <a href="#cond">cond</a> but without requiring
14199         parentheses around the condition-expression pairs.
14200 </p>
14201
14202 <p>
14203         In any case, the whole <tt>if</tt> expression
14204         always returns the last expression or condition evaluated.
14205 </p>
14206
14207 <p>
14208         See also the <a HREF="#unless">unless</a> function.
14209 </p>
14210
14211 <br /><br />
14212
14213 <a NAME="ifft"></a>
14214 <h2><span class="function">ifft</span></h2>
14215 <b>syntax: (ifft <em>list-num</em>)</b>
14216
14217 <p>
14218         Calculates the inverse discrete Fourier transform
14219         on a list of complex numbers in <em>list-num</em>
14220         using the FFT method (Fast Fourier Transform).
14221         Each complex number is specified by its real part,
14222         followed by its imaginary part.
14223         In case only real numbers are used,
14224         the imaginary part is set to <tt>0.0</tt> (zero).
14225         When the number of elements in <em>list-num</em>
14226         is not an integer power of 2,
14227         <tt>ifft</tt> increases the number of elements
14228         by padding the list with zeroes.
14229         When complex numbers are 0 in the imaginary part,
14230         simple numbers can be used.
14231 </p>
14232
14233 <b>example:</b>
14234 <blockquote>
14235 <pre>
14236 (ifft (fft '((1 0) (2 0) (3 0) (4 0))))
14237 <span class=arw>&rarr;</span> ((1 0) (2 0) (3 0) (4 0))
14238
14239 ;; when imaginary part is 0, plain numbers work too
14240
14241 (ifft (fft '(1 2 3 4)))
14242 <span class=arw>&rarr;</span> ((1 0) (2 0) (3 0) (4 0))
14243 </pre>
14244 </blockquote>
14245
14246 <p>
14247         The inverse operation of <tt>ifft</tt>
14248         is the <a HREF="#fft">fft</a> function.
14249 </p>
14250
14251 <br /><br />
14252
14253 <a NAME="import"></a>
14254 <h2><span class="function">import</span></h2>
14255 <b>syntax: (import <em>str-lib-name</em> <em>str-function-name</em> ["cdecl"])</b>
14256
14257 <p>
14258         Imports the function specified in <em>str-function-name</em>
14259         from a shared library named in <em>str-lib-name</em>.
14260         The functions <a HREF="#address">address</a>,
14261         <a HREF="#get-char">get-char</a>,
14262         <a HREF="#get-int">get-int</a>,
14263         <a HREF="#get-float">get-float</a>,
14264         <a HREF="#get-string">get-string</a>,
14265         <a HREF="#pack">pack</a>, and
14266         <a HREF="#unpack">unpack</a>
14267         can be used to retrieve return values
14268         or to unpack data from returned structure addresses.
14269         If the library is not located
14270         in the normal library search path,
14271         <em>str-lib-name</em> must contain
14272         the full path name.
14273 </p>
14274
14275 <p>
14276         To transform newLISP data types into the data types
14277         needed by the imported function, use the functions
14278         <a href="#float">float</a> for 64-bit double floats,
14279         <a href="#flt">flt</a> for 32-bit floats,
14280         and <a href="#int">int</a> for 32-bit integers.
14281         By default, newLISP passes
14282         floating point numbers
14283         as 64-bit double floats,
14284         integers as 32-bit integers,
14285         and strings as 32-bit integers
14286         for string addresses.
14287 </p>
14288
14289 <b>example:</b>
14290 <blockquote>
14291 <pre>
14292 ;; import in Linux
14293
14294 (import "libc.so.6" "printf")  <span class=arw>&rarr;</span> printf &lt;400862A0&gt;
14295
14296 ;; import in Mac OS X
14297
14298 (import "libc.dylib" "printf")  <span class=arw>&rarr;</span> printf &lt;90022080&gt;
14299
14300 ;; import in CYGWIN
14301
14302 (import "cygwin1.dll" "printf")  <span class=arw>&rarr;</span> printf &lt;6106B108&gt;
14303
14304 (printf "%g %s %d %c\n" 1.23 "hello" 999 65)
14305 <b>1.23 hello 999 A</b>
14306 <span class=arw>&rarr;</span> 17 ; return value
14307
14308 ;; import Win32 DLLs in Win32 or CYGWIN version
14309
14310 (import "kernel32.dll" "GetTickCount")  <span class=arw>&rarr;</span> GetTickCount
14311 (import "user32.dll" "MessageBoxA")     <span class=arw>&rarr;</span> MessageBoxA
14312 (GetTickCount)                          <span class=arw>&rarr;</span> 3328896
14313 </pre>
14314 </blockquote>
14315
14316
14317 <p>
14318         In the first example,
14319         the string "1.23 hello 999 A"
14320         is printed as a side effect,
14321         and the value 17 (number of
14322         characters printed) is returned.
14323         Any C function can be imported
14324         from any shared library in this way.
14325 </p>
14326
14327 <p>
14328         The message box example pops up
14329         a Windows dialog box, which may be hidden
14330         behind the console window.
14331         The console prompt does not return until the
14332         'OK' button is pressed in the message box.
14333 </p>
14334
14335 <blockquote>
14336 <pre>
14337 ;;this pops up a message box
14338
14339 (MessageBoxA 0 "This is the body" "Caption" 1)
14340 </pre>
14341 </blockquote>
14342
14343
14344 <p>
14345         The other examples show several imports
14346         of Win32 DLL functions and the details of passing values
14347         <em>by value</em> or <em>by reference</em>.
14348         Whenever strings or numbers are passed by reference,
14349         space must be reserved beforehand.
14350 </p>
14351
14352 <blockquote>
14353 <pre>
14354 ;; allocating space for a string return value
14355
14356 (import "kernel32.dll" "GetWindowsDirectoryA")
14357 (set 'str (dup "\000" 64)  ; reserve space and initialize
14358
14359 (GetWindowsDirectoryA str (length str))
14360
14361 str  <span class=arw>&rarr;</span> "C:\\WINDOWS\000                     "
14362
14363 (slice str 0 (find "\000" str))  <span class=arw>&rarr;</span> "C:\\WINDOWS"
14364
14365 ;; or use trim
14366 (trim str)  <span class=arw>&rarr;</span> "C:\\WINDOWS"
14367
14368 ;; passing an integer parameter by reference
14369
14370 (import "kernel32.dll" "GetComputerNameA")
14371
14372 (set 'str (dup "\000" 64)  ; reserve space, initialize
14373
14374 ;; get size in a buffer lpNum
14375 (set 'lpNum (pack "lu" (length str)))
14376
14377 ;; call the function
14378 (GetComputerNameA str lpNum)
14379
14380 str  <span class=arw>&rarr;</span> "LUTZ-PC\000                        "
14381
14382 (slice str 0 (find "\000" str))  <span class=arw>&rarr;</span> "LUTZ-PC"
14383
14384 ;; or use trim
14385 (trim str)  <span class=arw>&rarr;</span> "LUTZ-PC"
14386 </pre>
14387 </blockquote>
14388
14389 <p>
14390         <tt>import</tt> returns the address of the function,
14391         which can be used to assign a different name
14392         to the imported function.
14393 </p>
14394
14395 <blockquote>
14396 <pre>
14397 (set 'imprime (import "libc.so.6" "printf"))
14398 <span class=arw>&rarr;</span> printf &lt;400862A0&gt;
14399
14400 (imprime "%s %d" "hola" 123)
14401 <span class=arw>&rarr;</span> "hola 123"
14402 </pre>
14403 </blockquote>
14404
14405 <p>
14406         Note that the Win32 version of newLISP
14407         uses standard call <em>stdcall</em> conventions
14408         to call DLL library routines.
14409         This is necessary for calling DLLs that belong
14410         to the Win32 operating system (e.g., odbc32.dll).
14411         Most third-party DLLs are compiled for
14412         C declaration <em>cdecl</em> calling conventions
14413         and may need to specify the string <tt>"cdecl"</tt>
14414         as an additional last argument when importing functions.
14415         newLISP compiled for Linux and other UNIX systems
14416         uses the <em>cdecl</em> calling conventions by default
14417         and ignores any additional string.
14418 </p>
14419
14420 <blockquote>
14421 <pre>
14422 ;; force cdecl calling conventions on Win32
14423 (import "sqlite.dll" "sqlite_open" "cdecl")  <span class=arw>&rarr;</span> sqlite_open &lt;673D4888&gt;
14424 </pre>
14425 </blockquote>
14426
14427
14428 <p>
14429         Imported functions may take up to fourteen arguments.
14430         Note that floating point arguments
14431         take up two spaces each
14432         (e.g., passing five floats takes up
14433         ten of the fourteen parameters).
14434 </p>
14435
14436
14437 <br /><br />
14438
14439 <a NAME="inc"></a>
14440 <h2><span class="function">inc</span></h2>
14441 <b>syntax: (inc <em>sym</em> [<em>num</em>])</b>
14442
14443 <p>
14444         Increments the number in <em>sym</em> by 1
14445         or by the optional number <em>num</em>
14446         and returns the result.
14447         <tt>inc</tt> performs mixed int
14448         and float arithmetic according
14449         to the rules outlined below.
14450 </p>
14451
14452 <p>
14453         If <em>num</em> is absent,
14454         <tt>inc</tt> always returns
14455         an integer in <em>sym</em>.
14456         If the input arguments are floats and <tt>num</tt> is absent,
14457         the input arguments are truncated to integers.
14458 </p>
14459
14460 <p>
14461         Integer calculations (without <em>num</em>)
14462         resulting in numbers greater than
14463         9,223,372,036,854,775,807 wrap around to negative numbers.
14464         Results smaller than -9,223,372,036,854,775,808
14465         wrap around to positive numbers.
14466 </p>
14467
14468 <p>
14469         If <em>num</em> is supplied,
14470         <tt>inc</tt> always returns
14471         the result as floating point,
14472         even for integer input arguments.
14473 </p>
14474
14475 <b>example:</b>
14476 <blockquote>
14477 <pre>
14478 (set 'x 0)     <span class=arw>&rarr;</span> 0
14479 (inc 'x)       <span class=arw>&rarr;</span> 1
14480 x              <span class=arw>&rarr;</span> 1
14481 (inc 'x 0.25)  <span class=arw>&rarr;</span> 1.25
14482 x              <span class=arw>&rarr;</span> 1.25
14483
14484 (inc 'x)  <span class=arw>&rarr;</span> 2  ; gets truncated
14485 </pre>
14486 </blockquote>
14487
14488 <p>
14489         Use the <a href="#dec">dec</a> function for decrementing.
14490 </p>
14491
14492
14493 <br /><br />
14494
14495 <a NAME="index"></a>
14496 <h2><span class="function">index</span></h2>
14497 <b>syntax: (index <em>exp-predicate</em> <em>exp-list</em>)</b>
14498
14499 <p>
14500         Applies the predicate <em>exp-predicate</em>
14501         to each element of the list <em>exp-list</em>
14502         and returns a list containing the indices of the elements
14503         for which <em>exp-predicate</em> is true.
14504 </p>
14505
14506 <b>example:</b>
14507 <blockquote>
14508 <pre>
14509 (index symbol? '(1 2 d 4 f g 5 h))  <span class=arw>&rarr;</span> (2 4 5 7)
14510
14511 (define (big? x) (&gt; x 5))  <span class=arw>&rarr;</span> (lambda (x) (&gt; x 5))
14512
14513 (index big? '(1 10 3 6 4 5 11))  <span class=arw>&rarr;</span> (1 3 6)
14514 </pre>
14515 </blockquote>
14516
14517 <p>
14518         The predicate may be a built-in predicate,
14519         a user-defined function, or a lambda expression.
14520 </p>
14521
14522 <p>
14523         Use the <a HREF="#filter">filter</a> function
14524         to return the elements themselves.
14525 </p>
14526
14527 <br /><br />
14528
14529 <a NAME="int"></a>
14530 <h2><span class="function">int</span></h2>
14531
14532 <b>syntax: (int <em>exp</em> [<em>exp-default</em>] [<em>int-base</em>])</b>
14533
14534 <p>
14535         If the expression in <em>exp</em> evaluates to a number or a string,
14536         the result is converted to an integer and returned.
14537         If <em>exp</em> cannot be converted to an integer,
14538         then <tt>nil</tt> or the evaluation of
14539         <em>exp-default</em> will be returned.
14540         This function is mostly used when translating strings
14541         from user input or from parsing text.
14542         If <em>exp</em> evaluates to a string,
14543         the string must start with a digit; one or more spaces;
14544         or the <tt>+</tt> or <tt>-</tt> sign.
14545         The string must begin with '<tt>0x</tt>'
14546         for hexadecimal strings or
14547         '<tt>0</tt>' (zero) for octal strings.
14548         If <em>str</em> is invalid,
14549         <tt>int</tt> returns <tt>nil</tt>
14550         as a default value if not otherwise specified.
14551 </p>
14552
14553 <p>
14554         A second optional parameter
14555         can be used to force the number base
14556         of conversion to a specific value.
14557 </p>
14558
14559 <p>
14560         Integers larger than 9,223,372,036,854,775,807
14561         are truncated to 9,223,372,036,854,775,807.
14562         Integers smaller than -9,223,372,036,854,775,808
14563         are truncated to -9,223,372,036,854,775,808.
14564 </p>
14565
14566 <p>
14567         When converting from a float
14568         (as in the second form of <tt>int</tt>),
14569         floating point values larger or smaller
14570         than the integer maximum or minimum
14571         are also truncated.
14572         A floating point expression evaluating to <tt>NaN</tt>
14573         is converted to 0 (zero).
14574 </p>
14575
14576
14577 <b>example:</b>
14578 <blockquote>
14579 <pre>
14580 (int "123")          <span class=arw>&rarr;</span> 123
14581 (int " 123")         <span class=arw>&rarr;</span> 123
14582 (int "a123" 0)       <span class=arw>&rarr;</span> 0
14583 (int (trim " 123"))  <span class=arw>&rarr;</span> 123
14584 (int "0xFF")         <span class=arw>&rarr;</span> 255
14585 (int "055")          <span class=arw>&rarr;</span> 45
14586 (int "1.567")        <span class=arw>&rarr;</span> 1
14587 (int 1.567)          <span class=arw>&rarr;</span> 1
14588
14589 (integer? 1.00)        <span class=arw>&rarr;</span> nil
14590 (integer? (int 1.00))  <span class=arw>&rarr;</span> true
14591
14592 (int "1111" 0 2)  <span class=arw>&rarr;</span> 15   ; base 2 conversion
14593 (int "0FF" 0 16)  <span class=arw>&rarr;</span> 255  ; base 16 conversion
14594
14595 (int 'xyz)     <span class=arw>&rarr;</span> nil
14596 (int 'xyz 0)   <span class=arw>&rarr;</span> 0
14597 (int nil 123)  <span class=arw>&rarr;</span> 123
14598
14599 (int "abc" "not a number")  <span class=arw>&rarr;</span> "not a number"
14600
14601 (print "Enter a num:")
14602 (set 'num (int (read-line)))
14603 </pre>
14604 </blockquote>
14605
14606 <p>
14607         Use the <a HREF="#float">float</a> function
14608         to convert arguments to floating point numbers.
14609 </p>
14610
14611 <br /><br />
14612
14613 <a NAME="integerp"></a>
14614 <h2><span class="function">integer?</span></h2>
14615 <b>syntax: (integer? <em>exp</em>)</b>
14616
14617 <p>
14618         Returns <tt>true</tt> only if the value
14619         of <em>exp</em> is an integer;
14620         otherwise, it returns <tt>nil</tt>.
14621 </p>
14622
14623 <b>example:</b>
14624 <blockquote>
14625 <pre>
14626 (set 'num 123)  <span class=arw>&rarr;</span> 123
14627 (integer? num)  <span class=arw>&rarr;</span> true
14628 </pre>
14629 </blockquote>
14630
14631 <br /><br />
14632
14633 <a NAME="intersect"></a>
14634 <h2><span class="function">intersect</span></h2>
14635 <b>syntax: (intersect <em>list-A</em> <em>list-B</em>)</b><br />
14636
14637 <b>syntax: (intersect <em>list-A</em> <em>list-B</em> <em>bool</em>)</b>
14638
14639 <p>
14640         In the first syntax,
14641         <tt>intersect</tt> returns a list
14642         containing one copy of each element
14643         found both in <em>list-A</em> and <em>list-B</em>.
14644 </p>
14645
14646 <b>example:</b>
14647 <blockquote>
14648 <pre>
14649 (intersect '(3 0 1 3 2 3 4 2 1) '(1 4 2 5))
14650 <span class=arw>&rarr;</span> (2 4 1)
14651 </pre>
14652 </blockquote>
14653
14654 <p>
14655         In the second syntax,
14656         <tt>intersect</tt> returns a list of all elements
14657         in <em>list-A</em> that are also in <em>list-B</em>,
14658         without eliminating duplicates in <em>list-A</em>.
14659         <em>bool</em> is an expression evaluating to <tt>true</tt>
14660         or any other value not <tt>nil</tt>.
14661 </p>
14662
14663 <b>example:</b>
14664 <blockquote>
14665 <pre>
14666 (intersect '(3 0 1 3 2 3 4 2 1) '(1 4 2 5) true)
14667 <span class=arw>&rarr;</span> (1 2 4 2 1)
14668 </pre>
14669 </blockquote>
14670
14671 <p>
14672         See also the set functions
14673         <a HREF="#difference">difference</a> and
14674         <a HREF="#unique">unique</a>.
14675 </p>
14676
14677 <br /><br />
14678
14679 <a NAME="invert"></a>
14680 <h2><span class="function">invert</span></h2>
14681 <b>syntax: (invert <em>matrix</em>)</b>
14682
14683 <p>
14684         Returns the inversion of a
14685         two-dimensional matrix in <em>matrix</em>.
14686         The matrix must be square, with the same number
14687         of rows and columns, and <em>non-singular</em> (invertible).
14688         Matrix inversion can be used
14689         to solve systems of linear equations
14690         (e.g., multiple regression in statistics).
14691         newLISP uses LU-decomposition of
14692         the matrix to find the inverse.
14693 </p>
14694
14695 <p>
14696         The dimensions of a matrix
14697         are defined by the number of rows
14698         times the number of elements
14699         in the first row.
14700         For missing elements in non-rectangular matrices,
14701         <tt>0.0</tt> (zero) is assumed.
14702         A matrix can either be a nested list
14703         or an <a href="#array">array</a>.
14704 </p>
14705
14706 <p>
14707         <tt>invert</tt> will return <tt>nil</tt>
14708         if the matrix is <i>singular</i> and cannot be inverted.
14709 </p>
14710
14711 <b>example:</b>
14712 <blockquote>
14713 <pre>
14714 (set 'A '((-1 1 1) (1 4 -5) (1 -2 0)))
14715 (invert A)  <span class=arw>&rarr;</span> ((10 2 9) (5 1 4) (6 1 5))
14716 </pre>
14717 </blockquote>
14718
14719 <p>
14720         All operations shown here on lists
14721         can be performed on arrays, as well.
14722 </p>
14723
14724 <p>
14725         See also the matrix functions <a href="#det">det</a>,
14726         <a href="#mat">mat</a>, <a HREF="#multiply">multiply</a>
14727     and <a HREF="#transpose">transpose</a>.
14728 </p>
14729
14730 <br /><br />
14731
14732
14733 <a NAME="irr"></a>
14734 <h2><span class="function">irr</span></h2>
14735 <b>syntax: (irr <em>list-amounts</em> [<em>list-times</em> [<em>num-guess</em>]])</b>
14736
14737 <p>
14738         Calculate the internal rate of return
14739         of a cash flow per time period.
14740         The internal rate of return is the interest rate
14741         that makes the present value of a cash flow equal to 0.0 (zero).
14742         In-flowing (negative values) and out-flowing (positive values)
14743         amounts are specified in  <em>list-amounts</em>.
14744         If no time periods are specified in <em>list-times</em>,
14745         amounts in <em>list-amounts</em> correspond to
14746         consecutive time periods increasing by 1 (1, 2, 3&mdash;).
14747         The algorithm used is iterative,
14748         with an initial guess of 0.5 (50 percent).
14749         Optionally, a different
14750         initial guess can be specified.
14751         The algorithm returns when a precision
14752         of 0.000001 (0.0001 percent) is reached.
14753         <tt>nil</tt> is returned if the algorithm
14754         cannot converge after 50 iterations.
14755 </p>
14756
14757 <p>
14758         <em>irr</em> is often used to decide
14759         between different types of investments.
14760 </p>
14761
14762 <b>example:</b>
14763 <blockquote>
14764 <pre>
14765 (irr '(-1000 500 400 300 200 100))
14766 <span class=arw>&rarr;</span> 0.2027
14767
14768 (npv 0.2027 '(500 400 300 200 100))
14769 <span class=arw>&rarr;</span> 1000.033848 ; ~ 1000
14770
14771 (irr '(-1000 500 400 300 200 100) '(0 3 4 5 6 7))
14772 <span class=arw>&rarr;</span> 0.0998
14773
14774 (irr '(-5000 -2000 5000 6000) '(0 3 12 18))
14775 <span class=arw>&rarr;</span> 0.0321
14776 </pre>
14777 </blockquote>
14778
14779 <p>
14780         If an initial investment of 1,000
14781         yields 500 after the first year,
14782         400 after two years, and so on,
14783         finally reaching 0.0 (zero) after five years,
14784         then that corresponds to a yearly return
14785         of about 20.2 percent.
14786         The next line demonstrates the relation
14787         between <tt>irr</tt> and <a href="#npv">npv</a>.
14788         Only 9.9 percent returns are necessary when making
14789         the first withdrawal after three years.
14790 </p>
14791
14792 <p>
14793         In the last example, securities
14794         were initially purchased for 5,000,
14795         then for another 2,000 three months later.
14796         After a year, securities for 5,000 are sold.
14797         Selling the remaining securities
14798         after 18 months renders 6,000.
14799         The internal rate of return is 3.2 percent per month,
14800         or about 57 percent in 18 months.
14801 </p>
14802
14803 <p>
14804         See also the <a HREF="#fv">fv</a>,
14805         <a HREF="#nper">nper</a>,
14806         <a HREF="#npv">npv</a>,
14807         <a HREF="#pmt">pmt</a>,
14808         and <a href="#pv">pv</a> functions.
14809 </p>
14810
14811 <br /><br />
14812
14813
14814
14815 <a NAME="join"></a>
14816 <h2><span class="function">join</span></h2>
14817 <b>syntax: (join <em>list-of-strings</em> [<em>str-joint</em> [<em>boool-trail-joint</em>]])</b>
14818
14819 <p>
14820         Concatenates the given
14821         list of strings
14822         in <em>list-of-strings</em>.
14823         If <em>str-joint</em> is present,
14824         it is inserted between each string in the join.
14825         If <em>bool-trail-joint</em> is <tt>true</tt>
14826         then a joint string is also appended to the last string.
14827 </p>
14828
14829 <b>example:</b>
14830 <blockquote>
14831 <pre>
14832 (set 'lst '("this" "is" "a" "sentence"))
14833
14834 (join lst " ")  <span class=arw>&rarr;</span> "this is a sentence"
14835
14836 (join (map string (slice (now) 0 3)) "-")  <span class=arw>&rarr;</span> "2003-11-26"
14837
14838 (join (explode "keep it together"))  <span class=arw>&rarr;</span> "keep it together"
14839
14840 (join '("A" "B" "C") "-")         <span class=arw>&rarr;</span> "A-B-C"
14841 (join '("A" "B" "C") "-" true)    <span class=arw>&rarr;</span> "A-B-C-"
14842 </pre>
14843 </blockquote>
14844
14845 <p>
14846         See also the <a HREF="#append">append</a>,
14847         <a HREF="#string">string</a>,
14848         and <a HREF="#explode">explode</a> functions,
14849         which are the inverse of the <tt>join</tt> operation.
14850 </p>
14851
14852 <br /><br />
14853
14854 <a NAME="lambda"></a>
14855
14856 <h2><span class="function">lambda</span></h2>
14857
14858 <p>See the description of <a href="#fn">fn</a> which is a shorter form of writing <tt>lambda</tt>.</p
14859
14860 <br /><br />
14861
14862 <a NAME="lambda-macro"></a>
14863
14864 <h2><span class="function">lambda-macro</span></h2>
14865
14866 <p>See the description of <a href="#define-macro">define-macro</a>.</p
14867
14868 <br /><br />
14869
14870 <a NAME="lambdap"></a>
14871 <h2><span class="function">lambda?</span></h2>
14872 <b>syntax: (lambda? <em>exp</em>)</b>
14873
14874 <p>Returns <tt>true</tt> only if the value of <em>exp</em> is a lambda expression
14875 and otherwise <tt>nil</tt>.
14876 </p>
14877
14878 <b>example:</b>
14879 <blockquote>
14880 <pre>
14881 (define (square x) (* x x))
14882 (lambda? square)  <span class=arw>&rarr;</span> true
14883 </pre>
14884 </blockquote>
14885
14886 <p>See <a href="#define">define</a> and <a href="#define-macro">define-macro</a> for
14887 more information about <em>lambda</em> expressions.
14888 </p>
14889 <br /><br />
14890
14891 <a NAME="last"></a>
14892
14893 <h2><span class="function">last</span></h2>
14894 <b>syntax: (last <em>list</em>)</b><br />
14895 <b>syntax: (last <em>array</em>)</b><br />
14896 <b>syntax: (last <em>str</em>)</b>
14897
14898 <p>Returns the last element of a list or a string.
14899 </p>
14900
14901 <b>example:</b>
14902 <blockquote>
14903 <pre>
14904 (last '(1 2 3 4 5))  <span class=arw>&rarr;</span> 5
14905 (last '(a b (c d)))  <span class=arw>&rarr;</span> (c d)
14906
14907 (set 'A (array 3 2 (sequence 1 6)))
14908 <span class=arw>&rarr;</span> ((1 2) (3 4) (5 6))
14909 (last A)             <span class=arw>&rarr;</span> (5 6)
14910 </pre>
14911 </blockquote>
14912
14913 <p>In the second version the last character in the string <em>str</em> is returned as a
14914 string.
14915 </p>
14916
14917 <b>example:</b>
14918 <blockquote>
14919 <pre>
14920 (last "newLISP")  <span class=arw>&rarr;</span> "P"
14921 </pre>
14922 </blockquote>
14923
14924 <p>
14925 Note that <a href="#last">last</a> works on character boundaries
14926 rather than byte boundaries
14927 when the UTF-8&ndash;enabled version of newLISP is used.
14928 See also <a HREF="#first">first</a>, <a HREF="#rest">rest</a> and <a href="#nth">nth</a>.
14929 </p>
14930
14931 <br /><br />
14932
14933 <a NAME="legalp"></a>
14934 <h2><span class="function">legal?</span></h2>
14935 <b>syntax: (legal? <em>str</em>)</b><br />
14936
14937 <p>
14938 The token in <em>str</em> is verified as a legal newLISP symbol.
14939 Non legal symbols can be created using the <a href="#sym">sym</a> function
14940 (e.g. symbols containing spaces, quotes, or other characters not normally allowed).
14941 Non legal symbols are created frequently
14942 when using them for associative data access:
14943 </p>
14944
14945 <b>example:</b>
14946 <blockquote>
14947 <pre>
14948 (symbol? (sym "one two"))  <span class=arw>&rarr;</span> true
14949
14950 (legal? "one two")  <span class=arw>&rarr;</span> nil  ; contains a space
14951
14952 (set (sym "one two") 123)  <span class=arw>&rarr;</span> 123
14953
14954 (eval (sym "one two"))  <span class=arw>&rarr;</span> 123
14955 </pre>
14956 </blockquote>
14957
14958 <p>The example shows that the string <tt>"one two"</tt> does not contain a legal
14959 symbol although a symbol can be created from this string and treated like a
14960 variable.
14961 </p>
14962
14963 <br /><br />
14964
14965 <a NAME="length"></a>
14966 <h2><span class="function">length</span></h2>
14967 <b>syntax: (length <em>expr</em>)</b><br />
14968
14969 <p>Returns the number of elements in a list, the number of rows in
14970 an array or the number of characters in a string.
14971 </p>
14972
14973 <p><tt>length</tt> applied to a symbol returns the length of the symbol name.
14974 Applied to a number, <tt>length</tt> returns the number of
14975 bytes needed in memory to store that number: 4 for integers and 8 for floating point numbers.
14976 </p>
14977
14978 <b>example:</b>
14979 <blockquote>
14980 <pre>
14981 (length '(a b (c d) e))         <span class=arw>&rarr;</span> 4
14982 (length '())                    <span class=arw>&rarr;</span> 0
14983 (set 'someList '(q w e r t y))  <span class=arw>&rarr;</span> (q w e r t y)
14984 (length someList)               <span class=arw>&rarr;</span> 6
14985
14986 (set 'ary (array 2 4 '(0)))  <span class=arw>&rarr;</span> ((1 2 3 4) (5 6 7 8))
14987 (length ary)                 <span class=arw>&rarr;</span> 2
14988
14989 (length "Hello World")  <span class=arw>&rarr;</span> 11
14990 (length "")             <span class=arw>&rarr;</span> 0
14991
14992 (length 'someVar)  <span class=arw>&rarr;</span> 7
14993 (length 123)       <span class=arw>&rarr;</span> 8
14994 (length 1.23)      <span class=arw>&rarr;</span> 8
14995 </pre>
14996 </blockquote>
14997
14998 <br /><br />
14999
15000 <a NAME="let"></a>
15001 <h2><span class="function">let</span></h2>
15002 <b>syntax: (let ((<em>sym1</em> <em>exp-init1</em>) [ (<em>sym2</em> <em>exp-init2</em>) ... ] ) <em>body</em>)</b><br />
15003 <b>syntax: (let (<em>sym1</em> <em>exp-init1</em> [<em>sym2</em> <em>exp-init2</em> ... ] ) <em>body</em>)</b>
15004
15005 <p>One or more variables <em>sym1</em>, <em>sym2</em>, ... are declared locally and
15006 initialized with expressions in <em>exp-init1</em>, <em>exp-init2</em>, etc.
15007 When the local variables are initialized the initializer expressions evaluate
15008 using symbol bindings as before the <tt>let</tt> statement. To incrementally use
15009 symbol bindings as evaluated during the initialization of locals in <tt>let</tt>,
15010 use <a href="#letn">letn</a>.
15011 One or more expressions in <em>exp-body</em> are evaluated using the local
15012 definitions of <em>sym1</em>, <em>sym2</em> etc. <tt>let</tt> is useful for
15013 breaking up complex expressions by defining local variables close to the
15014 place where they are used. The second form omits the parenthesis around the
15015 variable expression pairs but functions identical.
15016 </p>
15017
15018 <b>example:</b>
15019 <blockquote>
15020 <pre>
15021 (define (sum-sq a b)
15022 (let ((x (* a a)) (y (* b b)))
15023 (+ x y)))
15024
15025 (sum-sq 3 4) <span class=arw>&rarr;</span> 25
15026
15027 (define (sum-sq a b)           ; alternative syntax
15028 (let (x (* a a) y (* b b))
15029 (+ x y)))
15030 </pre>
15031 </blockquote>
15032
15033 <p>The variables <tt>x</tt> and <tt>y</tt> are initialized, then the expression
15034
15035 <tt>(+ x y)</tt> is evaluated. The let form is just an optimized version and syntactic
15036 convenience for writing:
15037 </p>
15038
15039 <blockquote>
15040 <pre>
15041 ((lambda (<em>sym1</em> [<em>sym2</em> ... ]) <em>exp-body</em> ) <em>exp-init1</em> [ <em>exp-init2</em> ])
15042 </pre>
15043 </blockquote>
15044
15045 <p>See also <a href="#letn">letn</a> for an incremental or nested form of
15046 <tt>let</tt>.
15047 </p>
15048
15049 <br /><br />
15050
15051 <a NAME="letex"></a>
15052 <h2><span class="function">letex</span></h2>
15053 <b>syntax: (letex ((<em>sym1</em> <em>exp-init1</em>) [ (<em>sym2</em> <em>exp-init2</em>) ... ] ) <em>body</em>)</b><br />
15054
15055 <b>syntax: (letex (<em>sym1</em> <em>exp-init1</em> [<em>sym2</em> <em>exp-init2</em> ... ] ) <em>body</em>)</b>
15056
15057 <p>This functions combines <a href="#let">let</a> and <a href="#expand">expand</a> to
15058 expand local variables into an expression before evaluating it.
15059 </p>
15060
15061 <p>Both forms provide the same functionality, but in the second form the parentheses around the initializers can be omitted.
15062 </p>
15063
15064 <b>example:</b>
15065 <blockquote>
15066 <pre>
15067 (letex '(x 1 y 2 z 3) '(x y z))    <span class=arw>&rarr;</span> (1 2 3)
15068 </pre>
15069 </blockquote>
15070
15071 <p>Before the expression <tt>'(x y z)</tt> gets evaluated, <tt>x, y</tt> and <tt>z</tt>
15072
15073 are literally replaced with the initializers from the <tt>letex</tt> initializer list.
15074 The final expression which gets evaluated is <tt>'(1 2 3)</tt>.
15075 </p>
15076
15077 <p>The following is a more complex realistic example. <tt>letex</tt> and
15078 <a href="#define-macro">define-macro</a> are used together to define a <tt>dolist-while</tt>,
15079 which loops through a list while certain condition is true:
15080 </p>
15081
15082 <b>example:</b>
15083 <blockquote>
15084 <pre>
15085 (define-macro (dolist-while)
15086 (letex (var (args 0 0)
15087 lst (args 0 1)
15088 cnd (args 0 2)
15089 body (cons 'begin (1 (args))))
15090 (let (res)
15091 (catch (dolist (var lst)
15092 (if (set 'res cnd) body (throw res)))))))
15093
15094 &gt; (dolist-while (x '(a b c d e f) (!= x 'd)) (println x))
15095 a
15096 b
15097 c
15098 nil
15099 &gt;
15100 </pre>
15101 </blockquote>
15102
15103 <p>The <a href="#args">args</a> function is used to access the unevaluated argument list from
15104 <a href="#define-macro">define-macro</a>.
15105 </p>
15106
15107 <br /><br />
15108
15109 <a NAME="letn"></a>
15110 <h2><span class="function">letn</span></h2>
15111 <b>syntax: (letn ((<em>sym1</em> <em>exp-init1</em>) [ (<em>sym2</em> <em>exp-init2</em>) ... ] ) <em>body</em>)</b><br />
15112 <b>syntax: (letn (<em>sym1</em> <em>exp-init1</em> [<em>sym2</em> <em>exp-init2</em> ... ] ) <em>body</em>)</b>
15113
15114 <p><tt>letn</tt> is like a <em>nested let</em> and works similar to <a href="#let">let</a>, but will
15115 incrementally use the new symbol bindings when evaluating the initializer expressions as
15116 if several <a href="#let">let</a> were nested. The following comparison
15117 of <a href="#let">let</a> and <tt>letn</tt> show the difference:
15118 </p>
15119
15120 <b>example:</b>
15121 <blockquote>
15122 <pre>
15123 (set 'x 10)
15124 (let ((x 1) (y (+ x 1)))
15125 (list x y))           <span class=arw>&rarr;</span> (1 11)
15126
15127 (letn ((x 1) (y (+ x 1)))
15128 (list x y))          <span class=arw>&rarr;</span> (1 2)
15129 </pre>
15130 </blockquote>
15131
15132 <p>While in the first example using <a href="#let">let</a> the variable <tt>y</tt> is
15133 calculated using the binding of <tt>x</tt> before the <a href="#let">let</a> expression,
15134 in the second example using <tt>letn</tt> the variable <tt>y</tt> is calculated using
15135 the new local binding of <tt>x</tt>.
15136 </p>
15137
15138 <blockquote>
15139 <pre>
15140 (letn  (x 1 y x)
15141 (+ x y))             <span class=arw>&rarr;</span>  2
15142
15143 ;; same as nested let's
15144
15145 (let (x 1)
15146 (let (y x)
15147 (+ x y)))       <span class=arw>&rarr;</span>  2
15148 </pre>
15149 </blockquote>
15150
15151 <p><tt>letn</tt> works like several <em>nested</em> <a href="#let">let</a>. The parenthesis
15152 around the initializer expressions can be omitted.
15153 </p>
15154
15155 <br /><br />
15156
15157 <a NAME="list"></a>
15158 <h2><span class="function">list</span></h2>
15159 <b>syntax: (list <em>exp-1</em> [<em>exp-2</em> ... ])</b>
15160
15161 <p>The <em>exp</em> are evaluated and the values used to construct a new list.
15162 </p>
15163
15164 <b>example:</b>
15165 <blockquote>
15166 <pre>
15167 (list 1 2 3 4 5)                <span class=arw>&rarr;</span> (1 2 3 4 5)
15168 (list 'a '(b c) (+ 3 4) '() '*) <span class=arw>&rarr;</span> (a (b c) 7 () *)
15169 </pre>
15170 </blockquote>
15171
15172 <p>See also <a href="#cons">cons</a> and <a href="#push">push</a> for other
15173 forms of building lists.
15174 </p>
15175
15176 <br /><br />
15177
15178 <a NAME="listp"></a>
15179 <h2><span class="function">list?</span></h2>
15180 <b>syntax: (list? <em>exp</em>)</b>
15181
15182 <p>Returns <tt>true</tt> only if the value of <em>exp</em> is a list; otherwise
15183 returns <tt>nil</tt>.  Note that lambda and lambda-macro
15184 expressions are also recognized as special instances of a list expression.
15185 </p>
15186
15187 <b>example:</b>
15188 <blockquote>
15189 <pre>
15190 (set 'var '(1 2 3 4))    <span class=arw>&rarr;</span> (1 2 3 4)
15191 (list? var)              <span class=arw>&rarr;</span> true
15192
15193 (define (double x) (+ x x))
15194
15195 (list? double)           <span class=arw>&rarr;</span> true
15196 </pre>
15197 </blockquote>
15198 <br /><br />
15199
15200 <a NAME="load"></a>
15201
15202 <h2><span class="function">load</span></h2>
15203 <b>syntax: (load <em>str-file-name</em> [<em>str-file-name-2 ...</em>] [<em>sym-context</em>])</b>
15204
15205 <p>Loads and translates newLISP from a source file specified in one or more <em>str-file-name</em>
15206 and evaluates the expressions contained in the file(s). When loading is successful
15207 <tt>load</tt> returns the result of the last expression in the last file evaluated. If a file
15208 cannot be loaded <tt>load</tt> throws an error.
15209 </p>
15210
15211 <p>
15212 An optional <em>sym-context</em> can be specified,
15213 which becomes the context of evaluation,
15214 unless such a context switch is already present
15215 in the file being loaded.
15216 By default,
15217 files which do not contain <a href="#context">context</a> switches
15218 will be loaded into the <tt>MAIN</tt> context.
15219 </p>
15220
15221 <p>The <em>str-file-name</em> specs can contain URLs. Both <tt>http://</tt> and <tt> file://</tt>
15222 URLs are supported.
15223 </p>
15224
15225 <b>example:</b>
15226 <blockquote>
15227 <pre>
15228 (load "myfile.lsp")
15229
15230 (load "a-file.lsp" "b-file.lsp")
15231
15232 (load "file.lsp" "http://mysite.org/mypro")
15233
15234 (load "http://192.168.0.21:6000//home/test/program.lsp")
15235
15236 (load "a-file.lsp" "b-file.lsp" 'MyCTX)
15237
15238 (load "file:///usr/share/newlisp/mysql5.lsp")
15239 </pre>
15240 </blockquote>
15241
15242 <p>In case expressions evaluated during the <tt>load</tt> are changing the
15243 <a href="#context">context</a>, this will not influence the programming
15244 module doing the <tt>load</tt>. The current <a href="#context">context</a>
15245 after the <tt>load</tt> statement will always be the same as before in the
15246 <tt>load</tt>.
15247 </p>
15248
15249 <p>Normal file specs and URLs can be mixed in the same load command.
15250 </p>
15251
15252 <p><tt>load</tt> with <tt>HTTP</tt> URLs can also be used to load code
15253 remotely from newLISP server nodes running on UNIX like operating system.
15254 In this mode, <tt>load</tt> will issue
15255 an HTTP GET request to the target URL. Note that a double backslash is required
15256 when path names are specified relative to the root directory. <tt>load</tt>
15257 in <tt>HTTP</tt> mode will observe a 60-second timeout.</p>
15258 </p></p>
15259
15260 <p>The second to last line causes the files to be loaded in to the context <tt>MyCTX</tt>.
15261 The quote forces the context to be created if it did not exist.
15262 </p>
15263
15264 <p>The <tt>file://</tt> URL is followed by a third <tt>/</tt> for the directory spec.
15265 </p>
15266
15267 <br /><br />
15268
15269 <a NAME="local"></a>
15270 <h2><span class="function">local</span></h2>
15271 <b>syntax: (local (<em>sym-1</em> [<em>sym-2 ...</em>]) <em>body</em>)</b>
15272
15273 <p>
15274 Initializes one or more symbols
15275 in <em>sym-1&mdash;</em> to <tt>nil</tt>,
15276 evaluates the expressions in <em>body</em>,
15277 and returns the result of the last evaluation.
15278 </p>
15279
15280 <p>
15281 <tt>local</tt> works similarly to <a href="#let">let</a>,
15282 but local variables are all initialized to <tt>nil</tt>.
15283 </p>
15284
15285 <p>
15286 <tt>local</tt> provides a simple way
15287 to localize variables
15288 without explicit initialization.
15289 </p>
15290
15291
15292 <br>
15293
15294 <a NAME="log"></a>
15295 <h2><span class="function">log</span></h2>
15296 <b>syntax: (log <em>num</em>)</b><br />
15297
15298 <b>syntax: (log <em>num</em> <em>num-base</em>)</b>
15299
15300 <p>In the first syntax the expression in <em>num</em> is evaluated and the natural
15301 logarithmic function is calculated from the result.
15302 </p>
15303
15304 <b>example:</b>
15305 <blockquote>
15306 <pre>
15307 (log 1)         <span class=arw>&rarr;</span> 0
15308 (log (exp 1))   <span class=arw>&rarr;</span> 1
15309 </pre>
15310 </blockquote>
15311
15312 <p>In the second syntax an arbitrary base can be specified in <em>num-base</em>.
15313 </p>
15314
15315 <b>example:</b>
15316 <blockquote>
15317 <pre>
15318 (log 1024 2)             <span class=arw>&rarr;</span> 10
15319 (log (exp 1) (exp 1))    <span class=arw>&rarr;</span>  1
15320 </pre>
15321 </blockquote>
15322
15323 <p>See also <a HREF="#exp">exp</a>, which is the inverse function to <tt>log</tt> with
15324 base <b><em>e</em></b>.
15325 </p>
15326
15327 <br /><br />
15328
15329 <a NAME="lookup"></a>
15330 <h2><span class="function">lookup</span></h2>
15331 <b>syntax: (lookup <em>exp</em> <em>assoc-list</em> [<em>int-index</em>])</b>
15332
15333 <p>Finds in <em>assoc-list</em> an <em>association</em> the <em>key</em> element of which
15334 has the same value as <em>exp</em> and returns the <em>int-index</em> element of
15335
15336 <em>association</em> (or the last element if <em>int-index</em> is absent).
15337 See also <a HREF="#indexing">Indexing elements of strings and lists</a>.
15338 </p>
15339
15340 <p><tt>lookup</tt> is similar to <a href="#assoc">assoc</a> but goes one step further
15341 by extracting specific element found in the list.
15342 </p>
15343
15344 <b>example:</b>
15345 <blockquote>
15346 <pre>
15347 (set 'params '(
15348 (name "John Doe")
15349 (age 35)
15350 (gender "M")
15351 (balance 12.34)))
15352
15353 (lookup 'age params)    <span class=arw>&rarr;</span> 35
15354
15355 (set 'persons '(
15356 ("John Doe" 35 "M" 12.34)
15357 ("Mickey Mouse" 65 "N" 12345678)))
15358
15359 (lookup "Mickey Mouse" persons 2)    <span class=arw>&rarr;</span> "N"
15360 (lookup "Mickey Mouse" persons -3)   <span class=arw>&rarr;</span> 65
15361 (lookup "John Doe" persons 1)        <span class=arw>&rarr;</span> 35
15362 (lookup "John Doe" persons -2)       <span class=arw>&rarr;</span> "M"
15363 </pre>
15364 </blockquote>
15365
15366 <p>See also <a href="#assoc">assoc</a></p>
15367 <br /><br />
15368
15369
15370 <a NAME="lower-case"></a>
15371 <h2><span class="function">lower-case</span></h2>
15372 <b>syntax: (lower-case <em>str</em>)</b>
15373
15374 <p>
15375 Converts the characters of the string
15376 in <em>str</em> to lowercase.
15377 A new string is created,
15378 and the original is left untouched.
15379 </p>
15380
15381
15382 <b>example:</b>
15383 <blockquote>
15384 <pre>
15385 (lower-case "HELLO WORLD")  <span class=arw>&rarr;</span> "hello world"
15386 (set 'Str "ABC")
15387 (lower-case Str)  <span class=arw>&rarr;</span> "abc"
15388 Str               <span class=arw>&rarr;</span> "ABC"
15389 </pre>
15390 </blockquote>
15391
15392 <p>
15393 See also the <a HREF="#upper-case">upper-case</a> and
15394 <a href="#title-case">title-case</a> functions.
15395 </p>
15396
15397 <br /><br />
15398
15399
15400 <a NAME="macrop"></a>
15401 <h2><span class="function">macro?</span></h2>
15402 <b>syntax: (macro? <em>exp</em>)</b>
15403
15404 <p>
15405 returns <tt>true</tt> if <em>exp</em> evaluates
15406 to a lambda-macro expression;
15407 otherwise, <tt>nil</tt> is returned.
15408 </p>
15409
15410 <b>example:</b>
15411 <blockquote>
15412 <pre>
15413 (define-macro (mysetq lv rv) (set lv (eval rv)))
15414 (macro? mysetq)  <span class=arw>&rarr;</span> true
15415 </pre>
15416 </blockquote>
15417
15418 <br /><br />
15419
15420 <a NAME="main-args"></a>
15421 <h2><span class="function">main-args</span></h2>
15422 <b>syntax: (main-args)</b><br />
15423
15424 <b>syntax: (main-args <em>int-index</em>)</b>
15425
15426 <p>
15427 <tt>main-args</tt> returns a list
15428 with several string members,
15429 one for program invocation
15430 and one for each of
15431 the command-line arguments.
15432 </p>
15433
15434 <b>example:</b>
15435 <blockquote>
15436 <pre>
15437 newlisp 1 2 3
15438
15439 &gt; (main-args)
15440 <b>("/usr/bin/newlisp" "1" "2" "3")</b>
15441 </pre>
15442 </blockquote>
15443
15444 <p>
15445 After <tt>newlisp 1 2 3</tt> is executed at the command prompt,
15446 <tt>main-args</tt> returns a list containing the name of
15447 the invoking program and three command-line arguments.
15448 </p>
15449
15450 <p>
15451 Optionally, <tt>main-args</tt> can take
15452 an <em>int-index</em> for indexing into the list.
15453 Note that an index out of range will cause <tt>nil</tt>
15454 to be returned, not the last elements of the list like
15455 in list-indexing.
15456 </p>
15457
15458 <blockquote>
15459 <pre>
15460 newlisp a b c
15461
15462 &gt; (main-args 0)
15463 <b>"/usr/bin/newlisp"</b>
15464 &gt; (main-args -1)
15465 <b>"c"</b>
15466 &gt; (main-args 2)
15467 <b>"b"</b>
15468 &gt; (main-args 10)
15469 <b>nil</b>
15470 </pre>
15471 </blockquote>
15472
15473 <p>
15474 Note that when newLISP is executed from a script,
15475 <tt>main-args</tt> also returns the <em>name</em>
15476 of the script as the second argument:
15477 </p>
15478
15479 <blockquote>
15480 <pre>
15481 #!/usr/bin/newlisp
15482 #
15483 # script to show the effect of 'main-args' in script file
15484
15485 (print (main-args) "\n")
15486 (exit)
15487
15488 # end of script file
15489
15490 ;; execute script in the OS shell:
15491
15492 script 1 2 3
15493
15494 <b>("/usr/bin/newlisp" "./script" "1" "2" "3")</b>
15495 </pre>
15496 </blockquote>
15497
15498 <p>
15499 Try executing this script with different
15500 command-line parameters.
15501 </p>
15502
15503 <br /><br />
15504
15505 <a NAME="make-dir"></a>
15506 <h2><span class="function">make-dir</span></h2>
15507 <b>syntax: (make-dir <em>str-dir-name</em> [<em>int-mode</em>])</b>
15508
15509 <p>
15510 Creates a directory as specified in <em>str-dir-name</em>,
15511 with the optional access mode <em>int-mode</em>.
15512 Returns <tt>true</tt> or <tt>nil</tt>
15513 depending on the outcome.
15514 If no access mode is specified,
15515 most UNIX systems default to <tt>drwxr-xr-x</tt>.
15516 </p>
15517
15518 <p>
15519 On UNIX systems, the access mode specified
15520 will also be masked by the OS's <em>user-mask</em>
15521 set by the system administrator.
15522 The <em>user-mask</em> can be retrieved
15523 on UNIX systems using the command <tt>umask</tt>
15524 and is usually <tt>0022</tt> (octal),
15525 which masks write (and creation) permission
15526 for non-owners of the file.
15527 </p>
15528
15529 <b>example:</b>
15530 <blockquote>
15531 <pre>
15532 ;; 0 (zero) in front of 750 makes it an octal number
15533
15534 (make-dir "adir" 0750)
15535 </pre>
15536 </blockquote>
15537
15538 <p>
15539 This example creates a directory named <tt>adir</tt>
15540 in the current directory with an access mode of
15541 <tt>0750</tt> (octal 750 = <tt>drwxr-x---</tt>).
15542 </p>
15543 <br /><br />
15544
15545 <a NAME="map"></a>
15546
15547 <h2><span class="function">map</span></h2>
15548 <b>syntax: (map <em>exp-functor</em> <em>list-args-1</em> [<em>list-args-2</em> ... ])</b>
15549
15550 <p>
15551 Successively applies the primitive function,
15552 defined function, or lambda expression
15553 <em>exp-functor</em> to the arguments specified in
15554 <em>list-args-1, list-args-2&mdash;</em>,
15555 returning all results in a list. </p>
15556
15557 <b>example:</b>
15558 <blockquote>
15559 <pre>
15560 (map + '(1 2 3) '(50 60 70))  <span class=arw>&rarr;</span> (51 62 73)
15561
15562 (map if '(true nil true nil true) '(1 2 3 4 5) '(6 7 8 9 10))
15563 <span class=arw>&rarr;</span> '(1 7 3 9 5)
15564
15565 (map (fn (x y) (* x y)) '(3 4) '(20 10))
15566 <span class=arw>&rarr;</span> (60 40)
15567 </pre>
15568
15569 </blockquote>
15570
15571 <p>
15572 The second example shows how to dynamically
15573 create a function for <tt>map</tt>:
15574 </p>
15575
15576 <blockquote>
15577 <pre>
15578 (define (foo op p)
15579 (append (lambda (x)) (list (list op p 'x))))
15580 </pre>
15581 </blockquote>
15582
15583 <p>We can also use the shorter <tt>fn</tt>:</p>
15584
15585 <blockquote>
15586 <pre>
15587 (define (foo op p)
15588 (append (fn (x)) (list (list op p 'x))))
15589 </pre>
15590 </blockquote>
15591
15592 <p><tt>foo</tt> now works like a function-maker:</p>
15593
15594 <blockquote>
15595 <pre>
15596 (foo 'add 2)  <span class=arw>&rarr;</span> (lambda (x) (add 2 x))
15597
15598 (map (foo add 2) '(1 2 3 4 5))  <span class=arw>&rarr;</span> (3 4 5 6 7 8)
15599
15600 (map (foo mul 3) '(1 2 3 4 5))  <span class=arw>&rarr;</span> (3 6 9 12 15)
15601 </pre>
15602 </blockquote>
15603
15604 <p>
15605 Note that the quote before the operand can be omitted,
15606 since primitives evaluate to themselves in newLISP.
15607 </p>
15608
15609 <p>
15610 By incorporating <tt>map</tt>
15611 into the function definition,
15612 we can do the following:
15613 </p>
15614
15615 <blockquote>
15616 <pre>
15617 (define (list-map op p lst)
15618 (map (lambda (x) (op p x)) lst))
15619
15620 (list-map + 2 '(1 2 3 4))  <span class=arw>&rarr;</span> (3 4 5 6)
15621
15622 (list-map mul 1.5 '(1 2 3 4))  <span class=arw>&rarr;</span> (1.5 3 4.5 6)
15623 </pre>
15624 </blockquote>
15625
15626 <p>
15627 The number of arguments used is determined
15628 by the length of the first argument list.
15629 Arguments missing in other argument lists
15630 cause an error message.
15631 If an argument list contains too many elements,
15632 the extra ones will be ignored.
15633 </p>
15634
15635 <p>
15636 Note that only functions with <em>applicative
15637 order of evaluation</em> can be mapped.
15638 Functions with conditional or delayed evaluation
15639 of their arguments (e.g., <a href="#if">if</a>
15640 or <a href="#case">case</a>) cannot be mapped.
15641 </p>
15642
15643 <br /><br />
15644
15645 <a NAME="mat"></a>
15646 <h2><span class="function">mat</span></h2>
15647 <b>syntax: (mat <em>+</em>|<em>-</em>|<em>*</em>|<em>/</em> <em>matrix-A matrix-B</em>)</b><br />
15648 <b>syntax: (mat <em>+</em>|<em>-</em>|<em>*</em>|<em>/</em> <em>matrix-A number</em>)</b>
15649
15650 <p>Using the first syntax,
15651 this function performs fast floating point
15652 scalar operations on two-dimensional matrices
15653 in <em>matrix-A</em> or <em>matrix-B</em>.
15654 The type of operation is specified
15655 by one of the four arithmetic operators
15656 <tt>+</tt>, <tt>-</tt>, <tt>*</tt>, or <tt>/</tt>.
15657 This type of arithmetic operator is typically used for integer
15658 operations in newLISP. In the case of <tt>mat</tt>, however,
15659 all operations will be performed as floating point operations
15660 (<tt>add</tt>, <tt>sub</tt>, <tt>mul</tt>, <tt>div</tt>).</p>
15661
15662 <p>Matrices in newLISP are two-dimensional lists or arrays.
15663 Internally, newLISP translates lists and arrays into fast, accessible
15664 C-language data objects.
15665 This makes matrix operations in newLISP
15666 as fast as those coded directly in C.
15667 The same is true for the matrix operations
15668 <a href="#multiply">multiply</a> and <a href="#invert">invert</a>.</p>
15669
15670 <b>example:</b>
15671 <blockquote>
15672 <pre>
15673 (set 'A '((1 2 3) (4 5 6)))
15674 (set 'B A)
15675
15676 (mat + A B)    <span class=arw>&rarr;</span> ((2 4 6) (8 10 12))
15677 (mat - A B)    <span class=arw>&rarr;</span> ((0 0 0) (0 0 0))
15678 (mat * A B)    <span class=arw>&rarr;</span> ((1 4 9) (16 25 36))
15679 (mat / A B)    <span class=arw>&rarr;</span> ((1 1 1) (1 1 1))
15680
15681 ; specify the operator in a variable
15682
15683 (set 'op +)
15684 (mat op A B)    <span class=arw>&rarr;</span> ((2 4 6) (8 10 12))
15685 </pre>
15686 </blockquote>
15687
15688 <p>Using the second syntax,
15689 all cells in <em>matrix-A</em>
15690 are multiplied with a scalar
15691 in <em>number</em>:</p>
15692
15693 <blockquote>
15694 <pre>
15695 (mat + A 5)    <span class=arw>&rarr;</span> ((6 7 8) (9 10 11))
15696 (mat - A 2)    <span class=arw>&rarr;</span> ((-1 0 1) (2 3 4))
15697 (mat * A 3)    <span class=arw>&rarr;</span> ((3 6 9) (12 15 18))
15698 (mat / A 10)   <span class=arw>&rarr;</span> ((.1 .2 .3) (.4 .5 .6))
15699 </pre>
15700 </blockquote>
15701
15702 <p>See also the other matrix operations <a href="#det">det</a>,
15703 <a href="#invert">invert</a>, <a href="#multiply">multiply</a>,
15704 and <a href="#transpose">transpose</a>.</p>
15705
15706 <br /><br />
15707
15708 <a NAME="match"></a>
15709 <h2><span class="function">match</span></h2>
15710 <b>syntax: (match <em>list-pattern</em> <em>list-match</em> [<em>bool</em>])</b>
15711
15712 <p>
15713 The pattern in <em>list-pattern</em> is matched
15714 against the list in <em>list-match</em>,
15715 and the matching expressions are returned in a list.
15716 The three wildcard characters <tt>?</tt>, <tt>+</tt>,
15717 and <tt>*</tt> can be used in <em>list-pattern</em>.
15718 </p>
15719
15720 <p>
15721 Wildcard characters may be nested.
15722 <tt>match</tt> returns a
15723 list of matched expressions.
15724 For each <tt>?</tt> (question mark),
15725 a matching expression element is returned.
15726 For each <tt>+</tt> (plus sign) or
15727 <tt>*</tt> (asterisk), a list containing
15728 the matched elements is returned.
15729 If the pattern cannot be matched
15730 against the list in <em>list-match</em>,
15731 <tt>match</tt> returns <tt>nil</tt>.
15732 If no wildcard characters are present
15733 in the pattern an empty list is returned.
15734 </p>
15735
15736 <p>
15737 Optionally, the boolean value <tt>true</tt>
15738 (or any other expression not evaluating to <tt>nil</tt>)
15739 can be supplied as a third argument.
15740 This causes <tt>match</tt> work as it did in
15741 versions prior to 8.2.3, showing all list
15742 elements in the returned result.
15743 </p>
15744
15745 <p>
15746 <tt>match</tt> is frequently employed as a functor parameter
15747 in <a href="#find">find</a>, <a href="#ref">ref</a>,
15748 <a href="#ref-all">ref-all</a> and <a href="#replace">replace</a> and
15749 is internally used by <a href="#find-all">find-all</a> for lists.</p>
15750 </p>
15751
15752 <b>example:</b>
15753 <blockquote>
15754 <pre>
15755 (match '(a ? c) '(a b c))  <span class=arw>&rarr;</span> (b)
15756
15757 (match '(a ? ?) '(a b c))  <span class=arw>&rarr;</span> (b c)
15758
15759 (match '(a ? c) '(a (x y z) c))  <span class=arw>&rarr;</span> ((x y z))
15760
15761 (match '(a ? c) '(a x y z c))  <span class=arw>&rarr;</span> nil
15762
15763
15764 (match '(a * c) '(a x y z c))  <span class=arw>&rarr;</span> ((x y z))
15765
15766 (match '(a (b c ?) x y z) '(a (b c d) x y z))  <span class=arw>&rarr;</span> (d)
15767
15768 (match '(a (*) x ? z) '(a (b c d) x y z))  <span class=arw>&rarr;</span> ((b c d) y)
15769
15770 (match '(+) '())  <span class=arw>&rarr;</span> nil
15771
15772 (match '(+) '(a))  <span class=arw>&rarr;</span> ((a))
15773
15774 (match '(+) '(a b))  <span class=arw>&rarr;</span> ((a b))
15775
15776 (match '(a (*) x ? z) '(a () x y z))  <span class=arw>&rarr;</span> (() y)
15777 (match '(a (+) x ? z) '(a () x y z))  <span class=arw>&rarr;</span> nil
15778 </pre>
15779 </blockquote>
15780
15781 <p>
15782 Note that the <tt>*</tt> operator tries to grab
15783 the fewest number of elements possible,
15784 but <tt>match</tt> backtracks and grabs more elements
15785 if a match cannot be found.
15786 </p>
15787
15788 <p>
15789 The <tt>+</tt> operator works similarly
15790 to the <tt>*</tt> operator,
15791 but it requires at least one list element.
15792 </p>
15793
15794 <p>
15795 The following example shows
15796 how the matched expressions
15797 can be bound to variables.
15798 </p>
15799
15800 <blockquote>
15801 <pre>
15802 (map set '(x y) (match '(a (? c) d *) '(a (b c) d e f)))
15803
15804 x  <span class=arw>&rarr;</span> b
15805 y  <span class=arw>&rarr;</span> (e f)
15806 </pre>
15807 </blockquote>
15808
15809 <p>
15810 Note that <tt>match</tt> for strings has been eliminated.
15811 For more powerful string matching, use <a href="#regex">regex</a>,
15812 <a href="#find">find</a>, <a href="#find-all">find-all</a>
15813 or <a href="#parse">parse</a>.
15814 </p>
15815
15816 <p> <a href="#unify">unify</a> is another function for matching
15817 expressions in a PROLOG like manner.</p>
15818
15819 <br /><br />
15820
15821 <a NAME="max"></a>
15822 <h2><span class="function">max</span></h2>
15823 <b>syntax: (max <em>num-1</em> [<em>num-2</em> ... ])</b>
15824
15825 <p>
15826 Evaluates the expressions <em>num-1</em>&mdash;
15827 and returns the largest number.
15828 </p>
15829
15830 <b>example:</b>
15831 <blockquote>
15832 <pre>
15833 (max 4 6 2 3.54 7.1)  <span class=arw>&rarr;</span> 7.1
15834 </pre>
15835 </blockquote>
15836
15837 <p>
15838 See also the <a HREF="#min">min</a> function.
15839 </p>
15840
15841 <br /><br />
15842
15843 <a NAME="member"></a>
15844 <h2><span class="function">member</span></h2>
15845 <b>syntax: (member <em>exp</em> <em>list</em>)</b><br />
15846 <b>syntax: (member <em>str</em> <em>str-key</em> [<em>num-option</em>])</b>
15847 <p>
15848 In the first syntax,
15849 <tt>member</tt> searches
15850 for the element <em>exp</em>
15851 in the list <em>list</em>.
15852 If the element is a member of the list,
15853 a new list starting with the element found
15854 and the rest of the original list
15855 is constructed and returned.
15856 If nothing is found,
15857 <tt>nil</tt> is returned.
15858 When specifying <em>num-option</em>
15859 <tt>member</tt> performs a regular expression search.
15860 </p>
15861
15862 <b>example:</b>
15863 <blockquote>
15864 <pre>
15865 (set 'aList '(a b c d e f g h))  <span class=arw>&rarr;</span> (a b c d e f g h)
15866 (member 'd aList)                <span class=arw>&rarr;</span> (d e f g h)
15867 (member 55 aList)                <span class=arw>&rarr;</span> nil
15868 </pre>
15869 </blockquote>
15870
15871 <p>
15872 In the second syntax,
15873 <tt>member</tt> searches
15874 for <em>str-key</em> in <em>str</em>.
15875 If <em>str-key</em> is found, all of <em>str</em>
15876 (starting with <em>str-key</em>) is returned.
15877 <tt>nil</tt> is returned if nothing is found.
15878 </p>
15879
15880 <b>example:</b>
15881 <blockquote>
15882 <pre>
15883 (member "LISP" "newLISP")  <span class=arw>&rarr;</span> "LISP"
15884 (member "LI" "newLISP")    <span class=arw>&rarr;</span> "LISP"
15885 (member "" "newLISP")      <span class=arw>&rarr;</span> "newLISP"
15886 (member "xyz" "newLISP")   <span class=arw>&rarr;</span> nil
15887 (member "li" "newLISP" 1)  <span class=arw>&rarr;</span> "LISP"
15888 </pre>
15889 </blockquote>
15890
15891 <p>
15892 See also the related functions
15893 <a href="#slice">slice</a> and
15894 <a href="#find">find</a>.
15895 </p>
15896
15897 <br /><br />
15898
15899 <a NAME="min"></a>
15900 <h2><span class="function">min</span></h2>
15901 <b>syntax: (min <em>num-1</em> [<em>num-2</em> ... ])</b>
15902
15903 <p>
15904 Evaluates the expressions <em>num-1</em>&mdash;
15905 and returns the smallest number.
15906 </p>
15907
15908 <b>example:</b>
15909 <blockquote>
15910 <pre>
15911 (min 4 6 2 3.54 7.1)  <span class=arw>&rarr;</span> 2
15912 </pre>
15913 </blockquote>
15914
15915 <p>
15916 See also the <a HREF="#max">max</a> function.
15917 </p>
15918 <br /><br />
15919
15920 <a NAME="mod"></a>
15921 <h2><span class="function">mod</span></h2>
15922 <b>syntax: (mod <em>num-1</em> <em>num-2</em> [<em>num-3</em> ... ])</b>
15923
15924 <p>
15925 Calculates the modular value of the
15926 numbers in <em>num-1</em> and <em>num-2</em>.
15927 <tt>mod</tt> computes the remainder
15928 from the division of the numerator <em>num-i</em>
15929 by the denominator <em>num-i + 1</em>.
15930 Specifically, the return value is
15931 <em>numerator - n * denominator</em>,
15932 where <tt>n</tt> is the quotient
15933 of the numerator divided by the denominator,
15934 rounded towards zero to an integer.
15935 The result has the same sign as
15936 the numerator and its magnitude
15937 is less than the magnitude
15938 of the denominator.
15939 </p>
15940
15941 <b>example:</b>
15942 <blockquote>
15943 <pre>
15944 (mod 10.5 3.3)   <span class=arw>&rarr;</span>  0.6
15945 (mod -10.5 3.3)  <span class=arw>&rarr;</span> -0.6
15946 </pre>
15947 </blockquote>
15948
15949 <p>
15950 Use the <a HREF="#arithmetic">%</a> (percent sign)
15951 function when working with integers only.
15952 </p>
15953
15954 <br /><br />
15955
15956 <a NAME="mul"></a>
15957 <h2><span class="function">mul</span></h2>
15958 <b>syntax: (mul <em>num-1</em> <em>num-2</em> [<em>num-3</em> ... ])</b>
15959
15960 <p>
15961 Evaluates all expressions <em>num-1</em>&mdash;,
15962 calculating and returning the product.
15963 <tt>mul</tt> can perform mixed-type arithmetic,
15964 but it always returns floating point numbers.
15965 Any floating point calculation with
15966 <tt>NaN</tt> also returns <tt>NaN</tt>.
15967 </p>
15968
15969 <b>example:</b>
15970
15971 <blockquote>
15972 <pre>
15973 (mul 1 2 3 4 5 1.1)  <span class=arw>&rarr;</span> 132
15974 (mul 0.5 0.5)        <span class=arw>&rarr;</span> 0.25
15975 </pre>
15976 </blockquote>
15977
15978 <br /><br />
15979
15980 <a NAME="multiply"></a>
15981 <h2><span class="function">multiply</span></h2>
15982 <b>syntax: (multiply <em>matrix-A</em> <em>matrix-B</em>)</b>
15983
15984 <p>
15985 Returns the matrix multiplication of matrices
15986 in <em>matrix-A</em> and <em>matrix-B</em>.
15987 If <em>matrix-A</em> has the dimensions <em>n</em> by <em>m</em>
15988 and <em>matrix-B</em> the dimensions <em>k</em> by <em>l</em>
15989 (<em>m</em> and <em>k</em> must be equal),
15990 the result is an <em>n</em> by <em>l</em> matrix.
15991 <tt> multiply</tt> can perform mixed-type arithmetic,
15992 but the results are always double precision floating points,
15993 even if all input values are integers.
15994 </p>
15995
15996 <p>
15997 The dimensions of a matrix are determined
15998 by the number of rows and the number
15999 of elements in the first row.
16000 For missing elements
16001 in non-rectangular matrices,
16002 <tt>0.0</tt> is assumed.
16003 A matrix can either be a nested list
16004 or <a href="#array">array</a>.
16005 </p>
16006
16007 <b>example:</b>
16008 <blockquote>
16009 <pre>
16010 (set 'A '((1 2 3) (4 5 6)))
16011 (set 'B '((1 2) (1 2) (1 2)))
16012 (multiply A B)  <span class=arw>&rarr;</span> ((6 12) (15 30))
16013 </pre>
16014 </blockquote>
16015
16016 <p>
16017 All operations shown here on lists
16018 can be performed on arrays, as well.
16019 </p>
16020
16021 <p>
16022 See also the matrix operations <a href="#det">det</a>,
16023 <a HREF="#invert">invert</a>, <a HREF="#mat">mat</a>
16024 and <a HREF="#transpose">transpose</a>.
16025 </p>
16026
16027 <br /><br />
16028
16029 <a NAME="name"></a>
16030 <h2><span class="function">name</span></h2>
16031 <b>syntax: (name <em>symbol</em> [<em>bool</em>])</b><br />
16032 <b>syntax: (name <em>context</em>)</b>
16033
16034 <p>
16035 Returns as a string, the name of a <em>symbol</em>
16036 without the context prefix.
16037 If the expression in <em>bool</em>
16038 evaluates to anything other than <tt>nil</tt>,
16039 the name of the symbol's context is returned instead.
16040 </p>
16041
16042 <p>
16043 When <em>context</em> is supplied,
16044 then <tt>name</tt> returns the name of the context.
16045 </p>
16046
16047 <b>example:</b>
16048 <blockquote>
16049 <pre>
16050 (set 'ACTX:var 123)
16051 (set 'sm 'ACTX:var)
16052 (string sm)     <span class=arw>&rarr;</span> "ACTX:var"
16053 (name sm)       <span class=arw>&rarr;</span> "var"
16054 (name sm true)  <span class=arw>&rarr;</span> "ACTX"
16055
16056 ; name from context
16057
16058 (set 'ctx ACTX)
16059 (name ctx)      <span class=arw>&rarr;</span> "ACTX"
16060 </pre>
16061 </blockquote>
16062
16063 <br /><br />
16064 <a NAME="NaNp"></a>
16065 <h2><span class="function">NaN?</span></h2>
16066 <b>syntax: (NaN? <em>number</em> )</b>
16067
16068 <p>
16069 Tests if the result of a
16070 floating point math operation
16071 is a <tt>NaN</tt>.
16072 Certain floating point operations
16073 return a special IEEE 754 number format
16074 called a <tt>NaN</tt> for 'Not a Number'.
16075 </p>
16076
16077 <b>example:</b>
16078 <blockquote>
16079 <pre>
16080 (set 'x (sqrt -1))  <span class=arw>&rarr;</span> NaN
16081 (add x 123)         <span class=arw>&rarr;</span> NaN
16082 (mul x 123)         <span class=arw>&rarr;</span> NaN
16083
16084 (+ x 123)  <span class=arw>&rarr;</span> 123
16085 (* x 123)  <span class=arw>&rarr;</span> 0
16086
16087 (&gt; x 0)   <span class=arw>&rarr;</span> nil
16088 (&lt;= x 0)  <span class=arw>&rarr;</span> nil
16089 (= x x)   <span class=arw>&rarr;</span> true
16090 (NaN? x)  <span class=arw>&rarr;</span> true
16091 </pre>
16092 </blockquote>
16093
16094 <p>
16095 Note that all floating point arithmetic operations
16096 with a <tt>NaN</tt> yield a <tt>NaN</tt>.
16097 All comparisons with <tt>NaN</tt> return <tt>nil</tt>,
16098 but <tt>true</tt> when comparing to itself.
16099 Comparison with itself, however,
16100 would result in <em>not</em> <tt>true</tt> when using ANSI C.
16101 </p>
16102
16103 <p>
16104 Integer operations treat <tt>NaN</tt> as <tt>0</tt> (zero) values.
16105 </p>
16106
16107 <br /><br />
16108
16109 <a NAME="net-accept"></a>
16110 <h2><span class="function">net-accept</span></h2>
16111 <b>syntax: (net-accept <em>int-socket</em>)</b>
16112
16113 <p>
16114 Accepts a connection on a socket
16115 previously put into listening mode.
16116 Returns a newly created socket handle
16117 for receiving and sending data
16118 on this connection.
16119 </p>
16120
16121 <b>example:</b>
16122 <blockquote>
16123 <pre>
16124 (set 'socket (net-listen 1234))
16125 (net-accept socket)
16126 </pre>
16127 </blockquote>
16128
16129 <p>
16130 Note that for ports less than 1024,
16131 newLISP must be started in superuser mode
16132 on UNIX-like operating systems.
16133 </p>
16134
16135 <p>
16136 See also the <a HREF="#example_server_tcp">server</a>
16137 and <a HREF="#example_client_tcp">client</a> examples
16138 in the <tt>examples/</tt> directory of the source
16139 distribution.
16140 </p>
16141
16142 <br /><br />
16143
16144 <a NAME="net-close"></a>
16145 <h2><span class="function">net-close</span></h2>
16146 <b>syntax: (net-close <em>int-socket</em> [<em>true</em>)</b>
16147
16148 <p>
16149 Closes a network socket in <em>int-socket</em> that
16150 was previously created by a
16151 <a HREF="#net-connect">net-connect</a>
16152 or <a HREF="#net-accept">net-accept</a> function.
16153 Returns <tt>true</tt> on success and
16154 <tt>nil</tt> on failure.
16155 </p>
16156
16157 <b>example:</b>
16158 <blockquote>
16159 <pre>
16160 (net-close aSock)
16161 </pre>
16162 </blockquote>
16163
16164 <p>The optional <em>true</em> flag suppresses immediate shutdown
16165 of sockets waiting for pending data transmissions to finish.</p>
16166
16167 <br /><br />
16168
16169
16170 <a NAME="net-connect"></a>
16171 <h2><span class="function">net-connect</span></h2>
16172 <b>syntax: (net-connect <em>str-remote-host</em> <em>int-port</em> [<em>str-mode</em> [<em> int-ttl</em>] ])</b><br />
16173 <b>syntax: (net-connect <em>str-file-path</em>)</b>
16174
16175 <p>
16176 In the first syntax connects to a remote host computer
16177 specified in <em>str-remote-host</em>
16178 and a port specified in <em>int-port</em>.
16179 Returns a socket handle
16180 after having connected successfully;
16181 else it returns <tt>nil</tt>.
16182 </p>
16183
16184 <b>example:</b>
16185 <blockquote>
16186 <pre>
16187 (define (finger nameSite , socket buffer user site)
16188 (set 'user ((parse nameSite "@") 0))
16189 (set 'site ((parse nameSite "@") 1))
16190 (set 'socket (net-connect site 79))
16191 (if socket
16192 (net-send socket (append user "\r\n"))
16193 "no connection")
16194 (net-receive socket 'str 512)
16195 (print "\n" str "\n"))
16196 </pre>
16197 </blockquote>
16198
16199 <p>
16200 The above program
16201 uses the <em>finger</em> service
16202 on a remote computer.
16203 This service returns information
16204 about an account holder
16205 on this computer.
16206 Some ISP and UNIX installations
16207 provide this service.
16208 </p>
16209
16210 <p>When executing:</p>
16211
16212 <blockquote>
16213 <pre>
16214 (finger "johnDoe@someSite.com")
16215 </pre>
16216 </blockquote>
16217
16218 <p>
16219 the program tries to connect
16220 to a server named "someSite.com"
16221 and sends the string "johnDoe".
16222 If "someSite.com" is running a finger service,
16223 it sends back information about the account
16224 "johnDoe" on this server.
16225 In case a connection cannot be made,
16226 the function returns the string "no connection."
16227 </p>
16228
16229 <p>
16230 <tt>nameSite</tt> is split up into
16231 the account name and host name parts.
16232 <tt>net-connect</tt> is used to
16233 connect to <tt>someSite.com</tt>
16234 and returns the socket handle,
16235 which processes incoming data.
16236 </p>
16237
16238 <h3>Local domain UNIX sockets</h3>
16239
16240 <p>In the second syntax <tt>net-connect</tt> connects to a server on the
16241 local file system via a <em>local domain UNIX socket</em> named using
16242 <em>str-file-path</em>. Returns a socket handle after having connected
16243 successfully; else it returns <tt>nil</tt>.
16244 </p>
16245
16246 <b>example:</b>
16247 <blockquote>
16248 <pre>
16249 (net-connect "/tmp/mysocket")  <span class=arw>&rarr;</span> 3
16250
16251 ; on OS/2 use "\\socket\\" prefix
16252
16253 (net-connect "\\socket\\mysocket")
16254
16255 </pre>
16256 </blockquote>
16257
16258 <p>A <em>local domain</em> file system socket is created and returned.
16259 On the server side <em>local domain</em> sockets have been created
16260 using <a href="#net-listen">net-listen</a> and <a href="#net-accept">net-accept</a>.
16261 After the connection has been established the functions <a href="#net-select">net-select</a>,
16262 <a href="#net-send">net-send</a> and <a href="#net-receive">net-receive</a> can be used
16263 as usual for TCP/IP stream communications. This type of connnection can be used as a fast
16264 bi-directional communications channel between processes on the same file system.
16265 This type of connection is not available on Win32 platforms.</p>
16266
16267 <h3>UDP communications</h3>
16268
16269 <p>
16270 As a third parameter,
16271 the string <tt>"udp"</tt>
16272 or <tt>"u"</tt> can be specified
16273 in the optional <em>str-mode</em>
16274 to create a socket suited for
16275 UDP (User Datagram Protocol) communications.
16276 In UDP mode, <tt>net-connect</tt>
16277 does <em>not</em> try to connect
16278 to the remote host,
16279 but only binds the socket
16280 to the remote address.
16281 A subsequent <a href="#net-send">net-send</a>
16282 will send a UDP packet
16283 containing that target address.
16284 Using <a href="#net-send-to">net-send-to</a>
16285 causes that address to be overwritten.
16286 </p>
16287
16288 <p>
16289 The functions <a href="#net-receive">net-receive</a>
16290 and <a href="#net-receive-from">net-receive-from</a>
16291 can also be used
16292 and will perform UDP communications.
16293 <a href="#net-select">net-select</a>
16294 and <a href="#net-peek">net-peek</a>
16295 can be used to check
16296 for received data
16297 in a non-blocking fashion.
16298 </p>
16299
16300 <p>
16301 If data is never received when
16302 opening a client connection
16303 using <tt>net-connect</tt>,
16304 then calling <a href="#net-listen">net-listen</a>
16305 with the <tt>"udp"</tt> option
16306 may be preferable for starting
16307 the client side of the connection.
16308 <a href="#net-listen">net-listen</a> binds a specific
16309 local address and port to the socket.
16310 When <tt>net-connect</tt> is used,
16311 the local address and port
16312 will be picked by the socket-stack
16313 functions of the host OS.
16314 </p>
16315
16316 <h3>UDP multicast communications</h3>
16317 <p>
16318 When specifying <tt>"multi"</tt>
16319 or <tt>"m"</tt> as a third parameter for <em>str-mode</em>,
16320 a socket for UDP multicast communications
16321 will be created.
16322 Optionally, the fourth parameter
16323 <tt>int-ttl</tt> can be specified
16324 as a TTL (time to live) value.
16325 If no <em>int-ttl</em> value is specified,
16326 a value of 3 is assumed.
16327 </p>
16328
16329 <p>
16330 Note that specifying UDP multicast mode
16331 in <tt>net-connect</tt> does not actually establish
16332 a connection to the target multicast address
16333 but only puts the socket into UDP multicasting mode.
16334 On the receiving side,
16335 use <a href="#net-listen">net-listen</a>
16336 together with the UDP multicast option.
16337 </p>
16338
16339 <b>example:</b>
16340 <blockquote>
16341 <pre>
16342 ;; example client
16343
16344 (net-connect "226.0.0.1" 4096 "multi")  <span class=arw>&rarr;</span> 3
16345
16346 (net-send-to "226.0.0.1" 4096 "hello" 3)
16347
16348 ;; example server
16349
16350 (net-listen 4096 "226.0.0.1" "multi")  <span class=arw>&rarr;</span> 5
16351
16352 (net-receive-from 5 20)
16353 <span class=arw>&rarr;</span> ("hello" "192.168.1.94" 32769)
16354 </pre>
16355 </blockquote>
16356
16357 <p>
16358 On the server side,
16359 <a href="#net-peek">net-peek</a> or <a href="#net-select">net-select</a>
16360 can be used for non-blocking communications.
16361 In the above example, the server would block
16362 until a datagram is received.
16363 </p>
16364
16365 <p>
16366 The address <tt>226.0.0.1</tt>
16367 is just one multicast address
16368 in the Class D range of multicast addresses
16369 from <tt>224.0.0.0</tt> to <tt>239.255.255.255</tt>.
16370 </p>
16371
16372 <p>
16373 The <a href="#net-send">net-send</a> and
16374 <a href="#net-receive">net-receive</a> functions
16375 can also be used instead of <a href="#net-send-to">net-send-to</a>
16376 and <a href="#net-receive-from">net-receive-from</a>.
16377 </p>
16378
16379
16380 <h3>UDP broadcast communications</h3>
16381
16382 <p>
16383 Specifying the string <tt>"broadcast"</tt> or <tt>"b"</tt>
16384 in the third parameter, <em>str-mode</em>, causes
16385 UDP broadcast communications to be set up.
16386 In this case, the broadcast address
16387 ending in 255 is used.
16388 </p>
16389
16390 <b>example:</b>
16391 <blockquote>
16392 <pre>
16393 ;; example client
16394
16395 (net-connect "192.168.2.255" 3000 "broadcast")  <span class=arw>&rarr;</span> 3
16396
16397 (net-send 3 "hello")
16398
16399 ;; example server
16400
16401 (net-listen 3000 "" "udp")  <span class=arw>&rarr;</span> 5
16402
16403 (net-receive 5 'buff 10)
16404
16405 buff  <span class=arw>&rarr;</span> "hello"
16406
16407 ;; or
16408
16409 (net-receive-from 5 10)
16410 <span class=arw>&rarr;</span> ("hello" "192.168.2.1" 46620)
16411 </pre>
16412 </blockquote>
16413
16414 <p>
16415 Note that on the receiving side,
16416 <a href="#net-listen">net-listen</a> should be used
16417 with the default address
16418 specified with an <tt>""</tt> (empty string).
16419 Broadcasts will not be received
16420 when specifying an address.
16421 As with all UDP communications,
16422 <a href="#net-listen">net-listen</a> does not actually put
16423 the receiving side in listen mode,
16424 but rather sets up the sockets
16425 for the specific UDP mode.
16426 </p>
16427
16428 <p>
16429 The <a href="#net-select">net-select</a>
16430 or <a href="#net-peek">net-peek</a> functions
16431 can be used to check for
16432 incoming communications
16433 in a non-blocking fashion.
16434 </p>
16435
16436 <br /><br />
16437
16438 <a NAME="net-error"></a>
16439 <h2><span class="function">net-error</span></h2>
16440 <b>syntax: (net-error)</b>
16441
16442 <p>
16443 Retrieves the last error that occurred
16444 when calling a <a HREF="#socket_tcpip">net-*</a> function.
16445 When any of the following functions return <tt>nil</tt>,
16446 <tt>net-error</tt> can be called to get more information:
16447 <a HREF="#net-accept">net-accept</a>,
16448 <a HREF="#net-connect">net-connect</a>,
16449 <a HREF="#net-eval">net-eval</a>,
16450 <a HREF="#net-listen">net-listen</a>,
16451 <a HREF="#net-lookup">net-lookup</a>,
16452 <a HREF="#net-receive">net-receive</a>,
16453 <a HREF="#net-receive-udp">net-receive-udp</a>,
16454 <a HREF="#net-select">net-select</a>,
16455 <a HREF="#net-send">net-send</a>,
16456 <a HREF="#net-send-udp">net-send-udp</a>,
16457 and <a HREF="#net-service">net-service</a>.
16458 Functions that communicate using sockets
16459 close the socket automatically
16460 and remove it from the
16461 <a HREF="#net-sessions">net-sessions</a> list.
16462 This makes for a very robust API
16463 in situations of unreliable net connections.
16464 Calling any of these functions
16465 successfully clears the last error.
16466 </p>
16467
16468 <p>The following messages are returned:</p>
16469
16470 <blockquote>
16471 <pre> 1: Cannot open socket
16472 2: Host name not known
16473 3: Not a valid service
16474 4: Connection failed
16475 5: Accept failed
16476 6: Connection closed
16477 7: Connection broken
16478 8: Socket send() failed
16479 9: Socket recv() failed
16480 10: Cannot bind socket
16481 11: Too many sockets in net-select
16482 12: Listen failed
16483 13: Badly formed IP
16484 14: Select failed
16485 15: Peek failed
16486 16: Not a valid socket
16487 </pre>
16488 </blockquote>
16489
16490 <b>example:</b>
16491 <blockquote>
16492 <pre>
16493 (net-connect "jhghjgkjhg" 80)  <span class=arw>&rarr;</span>  nil
16494
16495 (net-error)  <span class=arw>&rarr;</span>  (2 "ERR: Host name not known")
16496 </pre>
16497 </blockquote>
16498
16499 <br /><br />
16500
16501 <a NAME="net-eval"></a>
16502 <h2><span class="function">net-eval</span></h2>
16503 <b>syntax: (net-eval <em>str-host</em> <em>int-port</em> <em>str-expr</em> [<em>int-timeout</em> [<em>func-handler</em>] ])</b><br />
16504 <b>syntax: (net-eval '((<em>str-host</em> <em>int-port</em> <em>str-expr</em>) [( ... ) ... ]) [<em>int-timeout</em>])</b><br />
16505 <b>syntax: (net-eval '((<em>str-host</em> <em>int-port</em> <em>str-expr</em>) ...)  <em>int-timeout</em> <em>func-handler</em>)</b>
16506
16507 <p>
16508 Can be used to evaluate source remotely
16509 on one or more newLISP servers.
16510 This function handles all communications necessary
16511 to connect to the remote servers,
16512 send source for evaluation, and
16513 wait and collect responses.
16514 </p>
16515
16516 <p>
16517 Beginning with version 8.9.8,
16518 <em>str-host</em>, <em>int-port</em>, and
16519 <em>str-expr</em> are evaluated.
16520 It is no longer necessary to specify them as constant.
16521 <tt>net-eval</tt> will evaluate
16522 these arguments.
16523 </p>
16524
16525 <p>
16526 The remote TCP/IP servers
16527 are started in the following way:
16528 </p>
16529
16530 <blockquote>
16531 <pre>
16532 newlisp -c -d 4711 &amp;
16533
16534 ;; or with logging connections
16535
16536 newlisp -l -c -d 4711 &amp;
16537 </pre>
16538 </blockquote>
16539
16540 <p>
16541 Instead of <tt>4711</tt>,
16542 any other port number can be used.
16543 Multiple nodes can be started on different hosts
16544 and with the same or different port numbers.
16545 The <tt>-l</tt> or <tt>-L</tt> logging options
16546 can be specified to log connections
16547 and remote commands.
16548 </p>
16549
16550 <p>
16551 The <tt>-d</tt> daemon mode
16552 allows newLISP to maintain state between connections.
16553 When keeping state between connections is not desired,
16554 the <a href="#inetd_daemon">inetd daemon mode</a>
16555 offers more advantages.
16556 The Internet <tt>inetd</tt> or <tt>xinetd</tt> services daemon
16557 will start a new newLISP process
16558 for each client connection.
16559 This makes for much faster servicing
16560 of multiple connections.
16561 In <tt>-d</tt> daemon mode,
16562 each new client request
16563 would have to wait for the previous request to be finished.
16564 See the chapter <a href="#inetd_daemon">inetd daemon mode</a>
16565 on how to configure this mode correctly.
16566 </p>
16567
16568 <p>
16569 In the first syntax,
16570 <tt>net-eval</tt> talks to only one
16571 remote newLISP server node,
16572 sending the host in <em>str-host</em>
16573 on port <em>int-port</em>
16574 a request to evaluate the expression
16575 <em>str-expr</em>.
16576 If <em>int-timeout</em> is not given,
16577 <tt>net-eval</tt> will wait indefinitely for a response.
16578 Otherwise, if the timeout in milliseconds has expired,
16579 <tt>nil</tt> is returned;
16580 else, the evaluation result of <em>str-expr</em>
16581 is returned.
16582 </p>
16583
16584 <b>example:</b>
16585 <blockquote>
16586 <pre>
16587 (net-eval "192.168.1.94" 4711 "(+ 3 4)")       <span class=arw>&rarr;</span> 7
16588 (net-eval "192.168.1.94" 4711 "(+ 3 4)" 1)     <span class=arw>&rarr;</span> nil  ; timeout to short
16589 (net-eval "192.168.1.94" 4711 "(+ 3 4)" 1000)  <span class=arw>&rarr;</span> 7
16590
16591 ; specify a local-domain UNIX socket (not on Win32)
16592 (net-eval "/tmp/mysocket" 0 "(+ 3 4)")    <span class=arw>&rarr;</span> 7
16593 </pre>
16594 </blockquote>
16595
16596 <p>
16597 The second syntax of <tt>net-eval</tt>
16598 returns a list of the results
16599 after all of the responses are collected
16600 or timeout occurs.
16601 Responses that time out
16602 return <tt>nil</tt>.
16603 The last example line shows how to specify
16604 a local-domain UNIX socket specifying the socket path
16605 and a port number of <tt>0</tt>.
16606 Connection errors or errors
16607 that occur when sending information to nodes
16608 are returned as a list of error numbers
16609 and descriptive error strings.
16610 See the function <a href="#net-error">net-error</a>
16611 for a list of potential error messages.
16612 </p>
16613
16614 <b>example:</b>
16615 <blockquote>
16616 <pre>
16617 (net-eval '(
16618 ("192.168.1.94" 4711 "(+ 3 4)")
16619 ("192.168.1.95" 4711 "(+ 5 6)")
16620 ) 5000)
16621 <span class=arw>&rarr;</span> (7 11)
16622
16623 (net-eval '(
16624 ("localhost" 8081 {(foo "abc")})
16625 ("localhost" 8082 "(myfunc 123)")
16626 ) 3000)
16627
16628 ;; inetd or xinetd nodes on the same server and port
16629
16630 (net-eval '(
16631 ("localhost" 2000 {(foo "abc")})
16632 ("localhost" 2000 "(myfunc 123)")
16633 ) 3000)
16634 </pre>
16635 </blockquote>
16636
16637 <p>
16638 The first example shows two expressions
16639 evaluated on two different remote nodes.
16640 In the second example,
16641 both nodes run on the local computer.
16642 This may be useful when debugging
16643 or taking advantage of multiple CPUs
16644 on the same computer.
16645 When specifying <tt>0</tt> for the portnumber
16646 <tt>net-eval</tt> takes the hostname as
16647 file path to the local-domain UNIX socket.
16648 </p>
16649
16650 <p>
16651 When nodes are inetd or xinetd-controlled,
16652 several nodes may have the same node
16653 for the IP address and port number.
16654 In this case, the UNIX daemon inetd or xinetd
16655 will start multiple newLISP servers.
16656 This is useful when testing distributed programs
16657 on just one machine.
16658 The last example illustrates this case.
16659 </p>
16660
16661 <p>
16662 The source sent for evaluation
16663 can consist of entire multiline programs.
16664 This way, remote nodes can be loaded with programs first,
16665 then specific functions can be called.
16666 For large program files, the functions
16667 <a href="#put-url">put-url</a> or
16668 <a href="#save">save</a> (with a URL file name)
16669 can be used to transfer programs.
16670 </p>
16671
16672 <p>
16673 Optionally, a handler function can be specified.
16674 This function will be repeatedly called while waiting
16675 and once for every remote evaluation completion.
16676 </p>
16677
16678 <b>example:</b>
16679 <blockquote>
16680 <pre>
16681 (define (myhandler param)
16682 (if param
16683 (println param))
16684 )
16685
16686 (set 'Nodes '(
16687 ("192.168.1.94" 4711)
16688 ("192.168.1.95" 4711)
16689 ))
16690
16691 (set 'Progs '(
16692 {(+ 3 4)}
16693 {(+ 5 6)}
16694 ))
16695
16696 (net-eval (map (fn (n p) (list (n 0) (n 1) p)) Nodes Progs)
16697 5000 myhandler)
16698 <span class=arw>&rarr;</span>
16699 ("192.168.1.94" 4711 7)
16700 ("192.168.1.95" 4711 11)
16701 </pre>
16702 </blockquote>
16703
16704 <p>
16705 The example shows how the list of node specs
16706 can be assembled from a list of nodes
16707 and sources to evaluate.
16708 This may be useful
16709 when connecting to a larger number of remote nodes.
16710 Since version 8.9.7, <tt>net-eval</tt>
16711 has also been able to evaluate
16712 the spec given in the node lists.
16713 This allows the following code:
16714 </p>
16715
16716 <blockquote>
16717 <pre>
16718 (net-eval '(
16719 ((Nodes 0 0) (Nodes 0 1) (Progs 0))
16720 ((Nodes 1 0) (Nodes 1 1) (Progs 1))
16721 ) 3000 myhandler)
16722 </pre>
16723 </blockquote>
16724
16725 <p>
16726 While waiting for input from remote hosts,
16727 <tt>myhandler</tt> will be called with <tt>nil</tt>
16728 as the argument to <tt>param</tt>.
16729 When a remote node result is completely received,
16730 <tt>myhandler</tt> will be called with <tt>param</tt>
16731 set to a list containing the remote host name
16732 or IP number, the port, and the resulting expression.
16733 <tt>net-eval</tt> will return <tt>true</tt> before a timeout
16734 or <tt>nil</tt> if the timeout was reached or exceeded.
16735 All remote hosts that exceeded the timeout limit
16736 will contain a <tt>nil</tt>
16737 in their results list.
16738 </p>
16739
16740 <p>
16741 Unless operating in raw mode,
16742 each piece of code sent to a remote node
16743 for evaluation should be one expression.
16744 This can be achieved by putting several statements
16745 into a <a href="#begin">begin</a> block.
16746 </p>
16747
16748 <h3>Raw mode</h3>
16749 <p>
16750 An additional parameter in each node specification
16751 can control whether the returned result
16752 is evaluated (the default behavior) or returned as a string
16753 as it comes over the communications channel.
16754 The following example
16755 illustrates the difference between
16756 the default <em>evaluated</em> and <em>raw</em> modes
16757 of <tt>net-eval</tt>:
16758 </p>
16759
16760 <blockquote>
16761 <pre>
16762 (net-eval '(("localhost" 4711 {(+ 3 4)})) 1000)  <span class=arw>&rarr;</span> (7)
16763
16764 (net-eval '(("localhost" 4711 {(+ 3 4)} true)) 1000)  <span class=arw>&rarr;</span> ("7\n")
16765
16766 (net-eval '(("localhost" 4711 {(+ 3 4) (+ 5 6)})) 1000)  <span class=arw>&rarr;</span> (11)
16767
16768 (net-eval '(("localhost" 4711 {(+ 3 4) (+ 5 6)} true)) 1000)  <span class=arw>&rarr;</span> ("7\n11\n")
16769 </pre>
16770 </blockquote>
16771
16772 <p>
16773 While the evaluated mode
16774 always returns an evaluated expression,
16775 raw mode returns a string
16776 terminated by a line-feed.
16777 The last two statements reveal
16778 that in the default evaluated mode,
16779 only the result of the last expression evaluation
16780 is returned,
16781 while in raw mode,
16782 both results are visible,
16783 each terminated by a line-feed.
16784 </p>
16785
16786 <p>
16787 Raw mode returns the same string
16788 as would be observed when entering expressions
16789 on the command line,
16790 while the evaluated mode returns LISP expressions
16791 ready for further newLISP processing.
16792 newLISP's <tt>net-eval</tt>
16793 protects the expression returned
16794 with a single quote before evaluating,
16795 thus ensuring that the expression string received
16796 is parsed in the receiving environment,
16797 but the resulting expression itself
16798 stays in the original form
16799 sent by the remote node.
16800 Only one quote gets prepended.
16801 For that reason,
16802 only one expression should be sent back
16803 when working in non-raw mode.
16804 </p>
16805
16806 <p>The following example shows this effect:</p>
16807
16808 <blockquote>
16809 <pre>
16810 (set 'prog [text]
16811 (list 1 2 3 4)
16812 (list 'a 'b 'c)
16813 [/text])
16814
16815 ; raw mode
16816 (net-eval '((host port prog true) ...))
16817 <span class=arw>&rarr;</span> ("(1 2 3 4)\n(a b c)\n")
16818
16819 ; normal mode
16820 (net-eval '((host port prog) ...))
16821 <span class=err>invalid function in function net-eval : (a b c)</span>
16822
16823 ; brace statments with (begin ...)
16824 (set 'prog [text]
16825 (begin
16826 (list 1 2 3 4)
16827 (list 'a 'b 'c))
16828 [/text])
16829
16830 ; normal mode
16831 (net-eval '((host port prog) ...))
16832 <span class=arw>&rarr;</span> ((a b c))
16833 </pre>
16834 </blockquote>
16835
16836 <p>
16837 The <tt>begin</tt> in the definition of <tt>prog</tt>
16838 forces the return of only one expression,
16839 which then gets converted correctly
16840 by the receiving <tt>net-eval</tt>.
16841 </p>
16842
16843 <p>
16844 Note that <em>raw</em> mode
16845 has always been part of <tt>net-eval</tt>,
16846 but it was not documented
16847 prior to version 8.7.5.
16848 </p>
16849
16850 <br /><br />
16851
16852
16853 <a NAME="net-listen"></a>
16854 <h2><span class="function">net-listen</span></h2>
16855 <b>syntax: (net-listen <em>int-port</em> [<em>str-ip-addr</em>] [<em>str-mode</em>])</b><br />
16856 <b>syntax: (net-listen <em>str-file-path</em>)</b>
16857
16858 <p>
16859 Listens on a port specified in <em>int-port</em>.
16860 A call to <tt>net-listen</tt>
16861 returns immediately with a socket number,
16862 which is then used by
16863 the blocking <a HREF="#net-accept">net-accept</a> function
16864 to wait for a connection.
16865 As soon as a connection is accepted,
16866 <a href="#net-accept">net-accept</a> returns a socket number
16867 that can be used to communicate with
16868 the connecting client.
16869 </p>
16870
16871
16872 <b>example:</b>
16873 <blockquote>
16874 <pre>
16875 (set 'port 1234)
16876 (set 'listen (net-listen port))
16877 (unless listen (begin
16878 (print "listening failed\n")
16879 (exit)))
16880 (print "Waiting for connection on: " port "\n")
16881 (set 'connection (net-accept listen))
16882 (if connection
16883 (while (net-receive connection 'buff 1024 "\n")
16884 (print buff)
16885 (if (= buff "\r\n") (exit)))
16886 (print "Could not connect\n"))
16887 </pre>
16888 </blockquote>
16889
16890 <p>
16891 The example waits for a connection on port 1234,
16892 then reads incoming lines until
16893 an empty line is received.
16894 Note that listening on ports lower than 1024
16895 may require superuser access on UNIX systems.
16896 </p>
16897
16898 <p>
16899 On computers with more than one interface card,
16900 specifying an optional interface IP address or name
16901 in <em>str-ip-addr</em> directs <tt>net-listen</tt>
16902 to listen on the specified address.
16903 </p>
16904
16905 <blockquote>
16906 <pre>
16907 ;; listen on a specific address
16908 (net-listen port "192.168.1.54")
16909 </pre>
16910 </blockquote>
16911
16912 <h3>Local domain UNIX sockets</h3>
16913
16914 <p>In the second syntax <tt>net-listen</tt> listens for a client on the
16915 local file system via a <em>local domain UNIX socket</em> named using
16916 <em>str-file-path</em>. If successful returns a socket handle which can be used with
16917 <a href="#net-accept">net-accept</a> to accept a client connection; else it returns <tt>nil</tt>.
16918 </p>
16919
16920 <b>example:</b>
16921 <blockquote>
16922 <pre>
16923 (net-listen "/tmp/mysocket")  <span class=arw>&rarr;</span> 5
16924
16925 ; on OS/2 use "\\socket\\" prefix
16926
16927 (net-listen "\\socket\\mysocket")
16928
16929 (net-accept 5)
16930 </pre>
16931 </blockquote>
16932
16933 <p>A <em>local domain</em> file system socket is created and listened on.
16934 A client will try to connect using the same <em>str-file-path</em>.
16935 After a connection has been accepted the functions <a href="#net-select">net-select</a>,
16936 <a href="#net-send">net-send</a> and <a href="#net-receive">net-receive</a> can be used
16937 as usual for TCP/IP stream communications. This type of connnection can be used as a fast
16938 bi-directional communications channel between processes on the same file system.
16939 This type of connection is not available on Win32 platforms.</p>
16940
16941
16942 <h3>UDP communications</h3>
16943
16944 <p>
16945 As a third parameter,
16946 the optional string <tt>"udp"</tt> or <tt>"u"</tt>
16947 can be specified in <em>str-mode</em>
16948 to create a socket suited for UDP
16949 (User Datagram Protocol) communications.
16950 A socket created in this way
16951 can be used directly with
16952 <a href="#net-receive-from">net-receive-from</a>
16953 to await incoming UDP data
16954 <em>without</em> using <tt>net-accept</tt>,
16955 which is only used in TCP communications.
16956 The <a href="#net-receive-from">net-receive-from</a> call
16957 will block until a UDP data packet is received.
16958 Alternatively, <a href="#net-select">net-select</a>
16959 or <a href="#net-peek">net-peek</a> can be used
16960 to check for ready data in a non-blocking fashion.
16961 To send data back to the address and port received
16962 with <a href="#net-receive-from">net-receive-from</a>,
16963 use <a href="#net-send-to">net-send-to</a>.
16964 </p>
16965
16966 <p>
16967 Note that <a href="#net-peer">net-peer</a> will not work,
16968 as UDP communications do not maintain
16969 a connected socket with address information.
16970 </p>
16971
16972 <blockquote>
16973 <pre>
16974 (net-listen 1002 "192.168.1.120" "udp")
16975
16976 (net-listen 1002 "" "udp")
16977 </pre>
16978 </blockquote>
16979
16980 <p>
16981 The first example listens on a specific network adapter,
16982 while the second example listens on the default adapter.
16983 Both calls return a socket number
16984 that can be used in subsequent <a href="#net-receive">net-receive</a>,
16985 <a href="#net-receive-from">net-receive-from</a>,
16986 <a href="#net-send-to">net-send-to</a>,
16987 <a href="#net-select">net-select</a>,
16988 or <a href="#net-peek">net-peek</a> function calls.
16989 </p>
16990
16991 <p>
16992 Both a UDP server <em>and</em> UDP client
16993 can be set up using <tt>net-listen</tt>
16994 with the <tt>"udp"</tt> option.
16995 In this mode, <tt>net-listen</tt>
16996 does not really <em>listen</em>
16997 as in TCP/IP communications;
16998 it just binds the socket
16999 to the local interface address and port.
17000 </p>
17001
17002 <p>
17003 For a working example, see the files
17004 <tt>examples/client</tt> and <tt>examples/server</tt>
17005 in the newLISP source distribution.
17006 </p>
17007
17008 <p>
17009 Instead of <tt>net-listen</tt>
17010 and the <tt>"udp"</tt> option,
17011 the functions <a href="#net-receive-udp">net-receive-udp</a>
17012 and <a href="#net-send-udp">net-send-udp</a>
17013 can be used for short transactions
17014 consisting only of one data packet.
17015 </p>
17016
17017 <p>
17018 <tt>net-listen</tt>, <a href="#net-select">net-select</a>,
17019 and <a href="#net-peek">net-peek</a> can be used
17020 to facilitate non-blocking reading.
17021 The listening/reading socket is not closed
17022 but is used again for subsequent reads.
17023 In contrast, when the
17024 <a href="#net-receive-udp">net-receive-udp</a>
17025 and <a href="#net-send-udp">net-send-udp</a> pair is used,
17026 both sides close the sockets after sending and receiving.
17027 </p>
17028
17029
17030 <h3>UDP multicast communications</h3>
17031
17032 <p>
17033 If the optional string <em>str-mode</em> is specified as
17034 <tt>"multi"</tt> or <tt>"m"</tt>,
17035 <tt>net-listen</tt> returns a socket suitable for multicasting.
17036 In this case, <em>str-ip-addr</em> contains one
17037 of the multicast addresses in the range <tt>224.0.0.0</tt>
17038 to <tt>239.255.255.255</tt>.
17039 <tt>net-listen</tt> will register <em>str-ip-addr</em>
17040 as an address on which to receive multicast transmissions.
17041 This address should not be confused with the IP address
17042 of the server host.
17043 </p>
17044
17045
17046 <b>example:</b>
17047 <blockquote>
17048 <pre>
17049 ;; example client
17050
17051 (net-connect "226.0.0.1" 4096 "multi")  <span class=arw>&rarr;</span> 3
17052
17053 (net-send-to "226.0.0.1" 4096 "hello" 3)
17054
17055
17056 ;; example server
17057
17058 (net-listen 4096 "226.0.0.1" "multi")  <span class=arw>&rarr;</span> 5
17059
17060 (net-receive-from 5 20)
17061 <span class=arw>&rarr;</span> ("hello" "192.168.1.94" 32769)
17062 </pre>
17063 </blockquote>
17064
17065 <p>
17066 On the server side,
17067 <a href="#net-peek">net-peek</a>
17068 or <a href="#net-select">net-select</a>
17069 can be used for non-blocking communications.
17070 In the example above,
17071 the server would block
17072 until a datagram is received.
17073 </p>
17074
17075 <p>
17076 The <a href="#net-send">net-send</a>
17077 and <a href="#net-receive">net-receive</a> functions
17078 can be used instead of <a href="#net-send-to">net-send-to</a>
17079 and <a href="#net-receive-from">net-receive-from</a>.
17080 </p>
17081
17082 <br /><br />
17083
17084 <a NAME="net-local"></a>
17085 <h2><span class="function">net-local</span></h2>
17086 <b>syntax: (net-local <em>int-socket</em>)</b>
17087
17088 <p>
17089 Returns the IP number and port
17090 of the local computer
17091 for a connection on
17092 a specific <em>int-socket</em>.
17093 </p>
17094
17095 <b>example:</b>
17096
17097 <blockquote>
17098 <pre>
17099 (net-local 16)  <span class=arw>&rarr;</span> ("204.179.131.73" 1689)
17100 </pre>
17101 </blockquote>
17102 <p>
17103 Use the <a HREF="#net-peer">net-peer</a>
17104 function to access the remote computer's
17105 IP number and port.
17106 </p>
17107 <br /><br />
17108
17109 <a NAME="net-lookup"></a>
17110 <h2><span class="function">net-lookup</span></h2>
17111
17112 <b>syntax: (net-lookup <em>str-ip-number</em>)</b><br />
17113 <b>syntax: (net-lookup <em>str-hostname</em> [<em>bool</em>])</b>
17114
17115
17116 <p>
17117 Returns either a hostname string
17118 from <em>str-ip-number</em>
17119 in IP dot format or the IP number
17120 in dot format from <em>str-hostname</em>:
17121 </p>
17122
17123 <b>example:</b>
17124 <blockquote>
17125 <pre>
17126 (net-lookup "209.24.120.224")    <span class=arw>&rarr;</span> "www.nuevatec.com"
17127 (net-lookup "www.nuevatec.com")  <span class=arw>&rarr;</span> "209.24.120.224"
17128
17129 (net-lookup "216.16.84.66.sbl-xbl.spamhaus.org" true)
17130 <span class=arw>&rarr;</span> "127.0.0.2"
17131 </pre>
17132 </blockquote>
17133
17134 <p>
17135 Optionally,     a <em>bool</em> flag
17136 can be specified in the second syntax.
17137 If the expression in <em>bool</em>
17138 evaluates to anything other than <tt>nil</tt>,
17139 host-by-name lookup will be forced,
17140 even if the name string starts
17141 with an IP number.
17142 </p>
17143
17144 <br /><br />
17145
17146 <a NAME="net-peek"></a>
17147 <h2><span class="function">net-peek</span></h2>
17148 <b>syntax: (net-peek <em>int-socket</em>)</b>
17149
17150 <p>
17151 Returns the number of bytes
17152 ready for reading
17153 on the network socket <em>int-socket</em>.
17154 If an error occurs
17155 or the connection is closed,
17156 <tt>nil</tt> is Returned.
17157 </p>
17158
17159 <b>example:</b>
17160 <blockquote>
17161 <pre>
17162 (set 'aSock (net-connect "aserver.com" 123))
17163 (while ( = (net-peek aSock) 0) (do-something-else))
17164 (net-receive aSock 'buff 1024)
17165 </pre>
17166 </blockquote>
17167
17168 <p>
17169 After connecting, the program
17170 waits in a while loop
17171 until <tt>aSock</tt> can be read.
17172 </p>
17173
17174 <p>
17175 Use the <a href="#peek">peek</a> function
17176 to check file descriptors and <tt>stdin</tt>.
17177 </p>
17178
17179 <br /><br />
17180
17181 <a NAME="net-peer"></a>
17182 <h2><span class="function">net-peer</span></h2>
17183 <b>syntax: (net-peer <em>int-socket</em>)</b>
17184
17185 <p>
17186 Returns the IP number and port
17187 of the remote computer
17188 for a connection on <em>int-socket</em>.
17189 </p>
17190
17191 <b>example:</b>
17192 <blockquote>
17193 <pre>
17194 (net-peer 16)  <span class=arw>&rarr;</span> ("192.100.81.100" 13)
17195 </pre>
17196 </blockquote>
17197
17198 <p>
17199 Use the <a HREF="#net-local">net-local</a> function
17200 to access the local computer's IP number and port.
17201 </p>
17202
17203 <br /><br />
17204
17205 <a NAME="net-ping"></a>
17206
17207 <h2><span class="function">net-ping</span></h2>
17208 <b>syntax: (net-ping <em>str-address</em> [<em>int-timeout</em> [<em>int-count</em>]])</b><br />
17209 <b>syntax: (net-ping <em>list-addresses</em> [<em>int-timeout</em> [<em>int-count</em>]])</b>
17210
17211 <p> This function is only available on UNIX-based systems
17212 and must be run in superuser mode, i.e. using: <tt>sudo newlisp</tt> to
17213 start newLISP on Mac OS X or other BSD's, or as the root user on Linux.
17214 Broadcast mode and specifying ranges with with the <tt>-</tt> (hyphen) or
17215 <em>*</em> (star) are not available on IPv6 address mode.</p>
17216
17217 <p> In the first syntax, <tt>net-ping</tt> sends a ping
17218 ICMP 64-byte echo request to the address specified in <em>str-address</em>.
17219 If it is a broadcast address, the ICMP packet will be received
17220 by all addresses on the subnet.  Note that for security reasons,
17221 many computers do not answer ICMP broadcast ping (ICMP_ECHO) requests.
17222 An optional timeout parameter can be specified in <em>int-timeout</em>.
17223 If no timeout is specified, a waiting time of 1000 milliseconds
17224 (one second) is assumed.</p>
17225
17226 <p> <tt>net-ping</tt> returns either a list of lists of IP strings
17227 and round-trip time in micro seconds for which a response was received
17228 or an empty list if no response was received.</p>
17229
17230 <p>
17231 A return value of <tt>nil</tt>
17232 indicates a failure.
17233 Use the <a href="#net-error">net-error</a> function
17234 to retrieve the error message.  If the message reads <tt>Cannot open socket</tt>,
17235 it is probably because newLISP is running without root permissions.
17236 newLISP can be started using:
17237 </p>
17238 <blockquote>
17239 <pre>
17240 sudo newlisp
17241 </pre>
17242 </blockquote>
17243 <p>
17244 Alternatively, newLISP can be installed
17245 with the set-user-ID bit set to run
17246 in superuser mode.
17247 </p>
17248
17249 <b>example:</b>
17250 <blockquote>
17251 <pre>
17252 (net-ping "newlisp.org")     <span class=arw>&rarr;</span> (("66.235.209.72" 634080))
17253 (net-ping "127.0.0.1")       <span class=arw>&rarr;</span> (("127.0.0.1" 115))
17254 (net-ping "yahoo.com" 3000)  <span class=arw>&rarr;</span> nil
17255 </pre>
17256 </blockquote>
17257
17258 <p>
17259 In the second syntax, <tt>net-ping</tt> is run in <em>batch mode</em>.
17260 Only one socket is opened in this mode, but multiple ICMP packets are sent out&mdash;one
17261 each to multiple addresses specified in a list or specified by range.
17262 Packets are sent out as fast as possible.  In this case, multiple answers can be received.
17263 If the same address is specified multiple times, thr receiving IP address will be flooded
17264 with ICMP packets.</p>
17265
17266 <p>
17267 To limit the number of responses to be waited for in broadcast or batch mode,
17268 an additional argument indicating the maximum number of responses to receive
17269 can be specified in <em>int-count</em>.  Usage of this parameter can cause
17270 the function to return sooner than the specified timeout.
17271 When a given number of responses has been received, <tt>net-ping</tt> will return
17272 before the timeout has occurred. Not specifying <em>int-count</em> or specifying <tt>0</tt>
17273 assumes an <em>int-count</em> equal to the number of packets sent out.</p>
17274
17275 <b>example:</b>
17276 <blockquote>
17277 <pre>
17278 (net-ping '("newlisp.org" "192.168.1.255") 2000 20)
17279 <span class=arw>&rarr;</span> (("66.235.209.72" 826420) ("192.168.1.1" 124) ("192.168.1.254" 210))
17280
17281 (net-ping "192.168.1.*" 500) ; from 1 to 254
17282 <span class=arw>&rarr;</span> (("192.168.1.1" 120) ("192.168.1.2" 245) ("192.168.2.3" 180) ("192.168.2.254" 234))
17283
17284 (net-ping "192.168.1.*" 500 2) ; returns after 2 responses
17285 <span class=arw>&rarr;</span> (("192.168.1.3" 115) ("192.168.1.1" 145))
17286
17287 (net-ping "192.168.1.1-10" 1000) ; returns after 1 second
17288 <span class=arw>&rarr;</span> (("192.168.1.3" 196) ("192.168.1.1" 205))
17289
17290 (net-ping '("192.168.1.100-120" "192.168.1.124-132") 2000) ; returns after 2 seconds
17291 <span class=arw>&rarr;</span> ()
17292 </pre>
17293 </blockquote>
17294
17295
17296 <p>
17297 Broadcast or batch mode&mdash;as well as normal addresses
17298 and IP numbers or hostnames&mdash; can be mixed in one <tt>net-ping</tt> statement by
17299 putting all of the IP specs into a list.</p>
17300
17301 <p>
17302 The second and third line show how the batch mode of <tt>net-ping</tt>
17303 can be initiated by specifying the <tt>*</tt> (asterisk)
17304 as a wildcard character for the last subnet octet
17305 in the IP number. The fourth and fifth line show how an IP
17306 range can be specified for the last subnet octet in the IP number.
17307 <tt>net-ping</tt> will iterate through all numbers
17308 from either 1 to 254 for the star <tt>*</tt> or the range specified,
17309 sending an ICMP packet to each address.
17310 Note that this is different from the <em>broadcast</em> mode
17311 specified with an IP octet of <tt>255</tt>.
17312 While in broadcast mode, <tt>net-ping</tt> sends out only one packet,
17313 which is received by multiple addresses.  Batch mode explicitly generates
17314 multiple packets, one for each target address. When specifying broadcast
17315 mode, <em>int-count</em> should be specified too.</p>
17316
17317 <p>
17318 When sending larger lists of IPs in batch mode over one socket,
17319 a longer timeout may be necessary to allow enough time for all of the packets
17320 to be sent out over one socket.  If the timeout is too short,
17321 the function <tt>net-ping</tt> may return an incomplete list or the empty list <tt>()</tt>.
17322 In this case <a href="#net-error">net-error</a> will return a timeout error.
17323 On error <tt>nil</tt> is returned and  <a href="#net-error">net-error</a>
17324 can be used to retrieve an error message.</p>
17325
17326 <p>
17327 On some systems only lists up to a specific length can be handled
17328 regardless of the timeout specified. In this case the range should
17329 be broken up in subranges used with multiple <tt>net-ping</tt>
17330 invocations. In any case, <tt>net-ping</tt> will send out packages
17331 as quickly as possible.
17332 </p>
17333
17334 <br /><br />
17335
17336 <a NAME="net-receive"></a>
17337 <h2><span class="function">net-receive</span></h2>
17338 <b>syntax: (net-receive <em>int-socket</em> <em>sym-buffer</em> <em>int-max-bytes</em> [<em>wait-string</em>])</b>
17339
17340 <p>
17341 Receives data on the socket <em>int-socket</em>
17342 into a string contained in <em>sym-buffer</em>.
17343 A maximum of <em>int-max-bytes</em> is received.
17344 <tt>net-receive</tt> returns the number of bytes read.
17345 If there is a break in the connection,
17346 <tt>nil</tt> is returned.
17347 The space reserved in <em>sym-buffer</em>
17348 is exactly the size of bytes read.
17349 </p>
17350
17351 <p>
17352 Note that <tt>net-receive</tt> is a blocking call
17353 and does not return until the data arrives at <em>int-socket</em>.
17354 Use <a HREF="#net-peek">net-peek</a>
17355 or <a HREF="#net-select">net-select</a> to find out
17356 if a socket is ready for reading.
17357 </p>
17358
17359 <p>
17360 Optionally, a <em>wait-string</em>
17361 can be specified
17362 as a fourth parameter.
17363 <tt>net-receive</tt> then returns after
17364 a character or string of characters
17365 matching <em>wait-string</em>
17366 is received.
17367 The <em>wait-string</em> will be part
17368 of the data contained in <em>sym-buffer</em>.
17369 </p>
17370
17371 <b>example:</b>
17372 <blockquote>
17373 <pre>
17374 (define (gettime)
17375 (net-connect "netcom.com" 13)
17376 (net-receive socket 'buf 256)
17377 (print buf "\n")
17378 (net-close socket))
17379 </pre>
17380 </blockquote>
17381
17382 <p>
17383 When calling <tt>gettime</tt>,
17384 the program connects to port 13
17385 of the server netcom.com.
17386 Port 13 is a date-time service
17387 on most server installations.
17388 Upon connection, the server sends
17389 a string containing the date and time of day.
17390 </p>
17391
17392 <blockquote>
17393 <pre>
17394 (define (net-receive-line socket sBuff)
17395 (net-receive socket sBuff 256 "\n"))
17396
17397 (set 'bytesReceived (net-receive-line socket 'sm))
17398 </pre>
17399 </blockquote>
17400
17401 <p>
17402 The second example defines a new function
17403 <tt>net-receive-line</tt>,
17404 which returns after receiving a newline character
17405 (a string containing one character in this example)
17406 or 256 characters.
17407 The "\n" string is part of the contents of sBuff.
17408 </p>
17409
17410 <p>
17411 Note that when the fourth parameter is specified,
17412 <tt>net-receive</tt> is slower than the normal version
17413 because information is read character by character.
17414 In most situations, the speed difference can be neglected.
17415 </p>
17416
17417 <br /><br />
17418
17419 <A NAME="net-receive-from"></a>
17420 <h2><span class="function">net-receive-from</span></h2>
17421 <b>syntax: (net-receive-from <em>int-socket</em> <em>int-max-size</em>)</b>
17422
17423 <p>
17424 <tt>net-receive-from</tt> can be used to set up
17425 non-blocking UDP communications.
17426 The socket in <em>int-socket</em>
17427 must previously have been opened
17428 by either <a href="#net-listen">net-listen</a>
17429 or <a href="#net-connect">net-connect</a>
17430 (both using the <tt>"udp"</tt> option).
17431 <em>int-max-size</em> specifies
17432 the maximum number of bytes that will be received.
17433 On Linux/BSD, if more bytes are received,
17434 those will be discarded.
17435 On Win32, <tt>net-receive-from</tt> will return <tt>nil</tt>
17436 and close the socket.
17437 </p>
17438
17439 <b>example:</b>
17440 <blockquote>
17441 <pre>
17442 ;; listen on port 1001 on the default address
17443 (net-listen 1001 "" "udp")  <span class=arw>&rarr;</span> 1980
17444
17445 ;; optionally poll for arriving data with 100ms timeout
17446 (while (not (net-select 1980 "r" 100000)) (do-something ...))
17447
17448 (net-receive-from 1980 20)  <span class=arw>&rarr;</span> ("hello" "192.168.0.5" 3240)
17449
17450 ;; send answer back to sender
17451 (net-send-to "192.168.0.5" 3240 "hello to you" 1980)
17452
17453 (net-close 1980) ; close socket
17454 </pre>
17455 </blockquote>
17456
17457 <p>
17458 The second line in this example is optional.
17459 Without it, the <tt>net-receive-from</tt> call
17460 would block until data arrives.
17461 A UDP server could be set up
17462 by listening and polling several ports
17463 serving them as they receive data.
17464 </p>
17465
17466 <p>
17467 Note that <tt>net-receive</tt>
17468 could not be used in this case
17469 because it does not return
17470 the sender's address and port information,
17471 which are required to talk back.
17472 In UDP communications,
17473 the data packet itself
17474 contains the address of the sender,
17475 <em>not</em> the socket over which
17476 communication takes place.
17477 </p>
17478
17479 <p>
17480 See also the <a href="#net-connect">net-connect</a> function
17481 with the <tt>"udp"</tt> option and the
17482 <a href="#net-send-to">net-send-to</a> function
17483 for sending UDP data packets over open connections.
17484 </p>
17485
17486 <p>
17487 For blocking short UDP transactions,
17488 see the <a href="#net-send-udp">net-send-udp</a>
17489 and <a href="#net-receive-udp">net-receive-udp</a> functions.
17490 </p>
17491
17492 <br /><br />
17493
17494
17495 <a NAME="net-receive-udp"></a>
17496 <h2><span class="function">net-receive-udp</span></h2>
17497 <b>syntax: (net-receive-udp <em>int-port</em> <em>int-maxsize</em> [<em>int-microsec</em> [<em>str-addr-if</em>]])</b>
17498
17499 <p>
17500 Receives a User Datagram Protocol (UDP) packet on port <em>int-port</em>,
17501 reading <em>int-maxsize</em> bytes.
17502 If more than <em>int-maxsize</em> bytes are received,
17503 bytes over <em>int-maxsize</em> are discarded on Linux/BSD;
17504 on Win32, <tt>net-receive-udp</tt> returns <tt>nil</tt>.
17505 <tt>net-receive-udp</tt> blocks until a datagram arrives
17506 or the optional timeout value in <em>int-microsec</em> expires.
17507 When setting up communications between datagram sender and receiver,
17508 the <tt>net-receive-udp</tt> statement must be set up first.
17509 </p>
17510
17511
17512 <p>
17513 No previous setup using <tt>net-listen</tt>
17514 or <tt>net-connect</tt> is necessary.
17515 </p>
17516
17517 <p>
17518 <tt>net-receive-udp</tt> returns a list
17519 containing a string of the UDP packet
17520 followed by a string containing
17521 the sender's IP number and the port used.
17522 </p>
17523
17524 <b>example:</b>
17525 <blockquote>
17526 <pre>
17527 ;; wait for datagram with maximum 20 bytes
17528 (net-receive-udp 1001 20)
17529
17530 ;; or
17531 (net-receive-udp 1001 20 5000000)  ; wait for max 5 seconds
17532
17533 ;; executed on remote computer
17534 (net-send-udp "nuevatec.com" 1001 "Hello")  <span class=arw>&rarr;</span> 4
17535
17536 ;; returned from the net-receive-udp statement
17537 <span class=arw>&rarr;</span> ("Hello" "128.121.96.1" 3312)
17538
17539 ;; sending binary information
17540 (net-send-udp "ahost.com" 2222 (pack "c c c c" 0 1 2 3))
17541 <span class=arw>&rarr;</span> 4
17542
17543 ;; extracting the received info
17544 (set 'buff (first (net-receive-udp 2222 10)))
17545
17546 (print (unpack "c c c c" buff))  <span class=arw>&rarr;</span> (0 1 2 3)
17547 </pre>
17548 </blockquote>
17549
17550 <p>
17551 See also the <a href="#net-send-udp">net-send-udp</a>
17552 function for sending datagrams and
17553 the <a href="#pack">pack</a> and <a href="#unpack">unpack</a>
17554 functions for packing and unpacking binary information.
17555 </p>
17556
17557 <p>
17558 To listen on a specified address
17559 on computers with more than one interface card,
17560 an interface IP address or name can be
17561 optionally specified in <em>str-addr-if</em>.
17562 When specifying <em>str-addr-if</em>,
17563 a timeout must also be specified
17564 in <em>int-wait</em>.
17565 </p>
17566
17567 <p>
17568 As an alternative, UDP communication
17569 can be set up using <a href="#net-listen">net-listen</a>,
17570 or <a href="#net-connect">net-connect</a>
17571 together with the <tt>"udp"</tt> option
17572 to make non-blocking data exchange possible
17573 with <a href="#net-receive-from">net-receive-from</a>
17574 and <a href="#net-send-to">net-send-to</a>.
17575 </p>
17576
17577 <br /><br />
17578
17579
17580 <a NAME="net-select"></a>
17581 <h2><span class="function">net-select</span></h2>
17582 <b>syntax: (net-select <em>int-socket</em> <em>str-mode</em> <em>int-micro-seconds</em>)</b><br />
17583 <b>syntax: (net-select <em>list-sockets</em> <em>str-mode</em> <em>int-micro-seconds</em>)</b>
17584
17585 <p>
17586 In the first form,
17587 <tt>net-select</tt> finds out about the status
17588 of one socket specified in  <em>int-socket</em>.
17589 Depending on <em>str-mode</em>,
17590 the socket can be checked
17591 if it is ready for reading or writing,
17592 or if the socket has an error condition.
17593 A timeout value is specified in <em>int-micro-seconds</em>.
17594 </p>
17595
17596 <p>
17597 In the second syntax,
17598 <tt>net-select</tt> can check for a list of sockets
17599 in <em>list-sockets</em>.
17600 </p>
17601
17602 <p>
17603 The following value can be given for <em>str-mode</em>:
17604 </p>
17605
17606 <blockquote>
17607 <tt>"read"</tt> or <tt>"r"</tt> to check if ready for reading or accepting.<br />
17608
17609 <tt>"write"</tt> or <tt>"w"</tt> to check if ready for writing.<br />
17610 <tt>"exception"</tt> or <tt>"e"</tt> to check for an error condition.<br />
17611 </blockquote>
17612
17613 <p>
17614 Read, send, or accept operations
17615 can be handled without blocking
17616 by using the <tt>net-select</tt> function.
17617 <tt>net-select</tt> waits
17618 for a socket to be ready
17619 for the value given in <em>int-micro-seconds</em>,
17620 then returns <tt>true</tt> or <tt>nil</tt>
17621 depending on the readiness of the socket.
17622 During the select loop,
17623 other portions of the program can run.
17624 On error,
17625 <a href="#net-error">net-error</a> is set.
17626 When <tt>-1</tt> is specified for <em>int-micro-seconds</em>,
17627 <tt>net-select</tt> will never time out.
17628 </p>
17629
17630 <b>example:</b>
17631 <blockquote>
17632 <pre>
17633 (set 'listen-socket (net-listen 1001))
17634
17635 ;; wait for connection
17636 (while (not (net-select listen-socket "read" 1000))
17637 (if (net-error) (print (net-error))))
17638 (set 'connection (net-accept listen-socket))
17639 (net-send connection "hello")
17640
17641 ;; wait for incoming message
17642 (while (not (net-select connection "read" 1000))
17643 (do-something))
17644 (net-receive connection 'buff 1024)
17645 </pre>
17646 </blockquote>
17647
17648 <p>
17649 When <tt>net-select</tt> is used,
17650 several listen and connection sockets can be watched,
17651 and multiple connections can be handled.
17652 When used with a list of sockets,
17653 <tt>net-select</tt> will return a list of ready sockets.
17654 The following example would listen on two sockets
17655 and continue accepting and servicing connections:
17656 </p>
17657
17658 <b>example:</b>
17659 <blockquote>
17660 <pre>
17661 (set 'listen-list '(1001 1002))
17662
17663 (while (not (net-error))
17664 (dolist (conn (net-select listen-list "r" 1000))
17665 (accept-connection conn))  ; build and accept-list
17666
17667 (dolist (conn (net-select accept-list "r" 1000))
17668 (read-connection conn))    ; read on conn socket
17669
17670 (dolist (conn (net-select accept-list "w" 1000))
17671 (write-connection conn)))  ; write on conn socket
17672 </pre>
17673 </blockquote>
17674
17675 <p>
17676 In the second syntax,
17677 a list  is returned
17678 containing all the sockets
17679 that passed the test;
17680 if timeout occurred,
17681 an empty list is returned.
17682 An error causes
17683 <a href="#net-error">net-error</a> to be set.
17684 </p>
17685
17686 <p>
17687 Note that supplying a nonexistent socket to <tt>net-select</tt>
17688 will cause an error to be set in <a href="#net-error">net-error</a>.
17689 </p>
17690
17691 <br /><br />
17692
17693 <a NAME="net-send"></a>
17694 <h2><span class="function">net-send</span></h2>
17695 <b>syntax: (net-send <em>int-socket</em> <em>str-buffer</em> [<em>int-num-bytes</em>])</b>
17696
17697 <p>
17698 Sends the contents of <em>str-buffer</em> on the connection specified by <em>int-socket</em>.
17699 If <em>int-num-bytes</em> is specified, up to <em>int-num-bytes</em> are sent.
17700 If <em>int-num-bytes</em> is not specified, the entire contents will be sent.
17701 <tt>net-send</tt> returns the number of bytes sent or <tt>nil</tt> on failure.
17702 </p>
17703
17704 <tt>On failure use <a href="#net-error">net-error</a> to get more error information.</p>
17705
17706 <b>example:</b>
17707 <blockquote>
17708 <pre>
17709 (set 'buf "hello there")
17710
17711 (net-send sock buf)       <span class=arw>&rarr;</span> 11
17712 (net-send sock buf 5)     <span class=arw>&rarr;</span> 5
17713
17714 (net-send sock "bye bye") <span class=arw>&rarr;</span> 7
17715 </pre>
17716 </blockquote>
17717
17718 <p>
17719 The first <tt>net-send</tt> sends the string <tt>"hello there"</tt>, while
17720 the second <tt>net-send</tt> sends only the string <tt>"hello"</tt>.
17721 </p>
17722
17723 <br /><br />
17724
17725 <a NAME="net-send-to"></a>
17726 <h2><span class="function">net-send-to</span></h2>
17727 <b>syntax: (net-send-to <em>str-remotehost</em> <em>int-remoteport</em> <em>str-buffer</em> <em>int-socket</em>)</b>
17728
17729 <p>
17730 Sends UDP data packets on open connections.
17731 The socket in <em>int-socket</em>
17732 must have previously been opened with a <a href="#net-connect">net-connect</a>
17733 or <a href="#net-listen">net-listen</a> function.
17734 Both functions must be opened
17735 with their <tt>"udp"</tt> option.
17736 The host in <em>str-remotehost</em>
17737 can be specified either as a hostname
17738 or as an IP-number string.
17739 </p>
17740
17741 <b>example:</b>
17742 <blockquote>
17743 <pre>
17744 (net-connect "asite.com" 1010 "udp")
17745 <span class=arw>&rarr;</span> 2058  ; get a UDP socket
17746
17747 (net-send-to "asite.com" 1010 "hello" 2058)
17748
17749 ;; optionally poll for answer
17750 (while (not (net-select 2058 "r" 100000))
17751 (do-something &hellip;))
17752
17753 ;; receive answering data from UDP server
17754 (net-receive-from 2058 20)
17755 <span class=arw>&rarr;</span> ("hello to you" "10.20.30.40" 1010)
17756
17757 (net-close 2058)
17758 </pre>
17759 </blockquote>
17760
17761 <p>
17762 The second line in the example is optional.
17763 Without it,
17764 the <a href="#net-receive-from"> net-receive-from</a> call
17765 would block until data arrives.
17766 Using polling,
17767 a client could maintain conversations with several UDP servers
17768 at the same time.
17769 </p>
17770
17771 <p>
17772 See also the <a href="#net-receive-from">net-receive-from</a> function
17773 and the <a href="#net-listen">net-listen</a> function
17774 with the <tt>"udp"</tt> option.
17775 </p>
17776
17777 <p>
17778 For blocking short UDP transactions,
17779 see <a href="#net-send-udp">net-send-udp"</a>
17780 and <a href="#net-receive-udp">net-receive-udp</a>.
17781 </p>
17782
17783 <br /><br />
17784
17785 <a NAME="net-send-udp"></a>
17786 <h2><span class="function">net-send-udp</span></h2>
17787 <b>syntax: (net-send-udp <em>str-remotehost</em> <em>int-remoteport</em> <em>str-buffer</em> [<em>bool</em>])</b>
17788
17789 <p>
17790 Sends a User Datagram Protocol (UDP)
17791 to the host specified in <em>str-remotehost</em>
17792 and to the port in <em>int-remoteport</em>.
17793 The data sent is in <em>str-buffer</em>.
17794 </p>
17795
17796 <p>
17797 No previous setup using <tt>net-connect</tt>
17798 or <tt>net-listen</tt> is necessary.
17799 <tt>net-send-udp</tt> returns immediately
17800 with the number of bytes sent
17801 and closes the socket used.
17802 If no <tt>net-receive-udp</tt> statement
17803 is waiting at the receiving side,
17804 the datagram sent is lost.
17805 When using datagram communications over insecure connections,
17806 setting up a simple protocol between sender and receiver
17807 is recommended for ensuring delivery.
17808 UDP communication by itself
17809 does not guarantee reliable delivery
17810 as TCP/IP does.
17811 </p>
17812
17813 <b>example:</b>
17814 <blockquote>
17815 <pre>
17816 (net-send-udp "somehost.com" 3333 "Hello")  <span class=arw>&rarr;</span> 5
17817 </pre>
17818 </blockquote>
17819
17820 <p>
17821 <tt>net-send-udp</tt> is also suitable
17822 for sending binary information
17823 (e.g., the zero character or other nonvisible bytes).
17824 For a more comprehensive example,
17825 see <a href="#net-receive-udp">net-receive-udp</a>.
17826 </p>
17827
17828 <p>
17829 Optionally, the sending socket
17830 can be put in broadcast mode
17831 by specifying <tt>true</tt>
17832 or any expression
17833 not evaluating to <tt>nil</tt>
17834 in <em>bool</em>:
17835 </p>
17836
17837 <blockquote>
17838 <pre>
17839 (net-send-udp "192.168.1.255" 2000 "Hello" true)  <span class=arw>&rarr;</span> 5
17840 </pre>
17841 </blockquote>
17842
17843 <p>
17844 The UDP will be sent to all nodes
17845 on the <tt>192.168.1</tt> network.
17846 Note that on some operating systems,
17847 sending the network mask <tt>255</tt>
17848 without the <em>bool</em> <tt>true</tt> option
17849 will enable broadcast mode.
17850 </p>
17851
17852 <p>
17853 As an alternative,
17854 the <a href="#net-connect">net-connect</a> function
17855 using the <tt>"udp"</tt> option&mdash;together with
17856 the <a href="#net-send-to">net-send-to</a> function&mdash;can
17857 be used to talk to a UDP listener
17858 in a non-blocking fashion.
17859 </p>
17860
17861 <br /><br />
17862
17863 <a NAME="net-service"></a>
17864 <h2><span class="function">net-service</span></h2>
17865 <b>syntax: (net-service <em>str-service</em> <em>str-protocol</em>)</b>
17866
17867 <p>
17868 Makes a lookup in the <em>services</em> database
17869 and returns the standard port number for this service.
17870 Returns <tt>nil</tt> on failure.
17871 </p>
17872
17873 <b>example:</b>
17874 <blockquote>
17875 <pre>
17876 (net-service "ftp" "tcp")       <span class=arw>&rarr;</span> 21
17877 (net-service "finger" "tcp")    <span class=arw>&rarr;</span> 79
17878 (net-service "net-eval" "tcp")  <span class=arw>&rarr;</span> 4711  ; if configured
17879 </pre>
17880 </blockquote>
17881
17882 <br /><br />
17883
17884 <a NAME="net-sessions"></a>
17885 <h2><span class="function">net-sessions</span></h2>
17886 <b>syntax: (net-sessions)</b>
17887
17888 <p>
17889 Returns a list of active listening and connection sockets.
17890 </p>
17891
17892 <br /><br />
17893
17894 <a name="new"></a>
17895 <h2><span class="function">new</span></h2>
17896 <b>syntax: (new <em>context-source</em> <em>sym-context-target</em> [<em>bool</em>])</b><br />
17897 <b>syntax: (new <em>context-source</em>)</b>
17898
17899 <p>
17900 In the first syntax,
17901 <em>context-source</em> is the name of an existing context,
17902 and <em>sym-context-target</em> is the name of a new context
17903 to be created just like the original,
17904 with the same variable names and user-defined functions.
17905 If the context in <em>sym-context-target</em> already exists,
17906 then new symbols and definitions are added.
17907 Existing symbols are overwritten
17908 when the expression in <em>bool</em>
17909 evaluates to anything besides <tt>nil</tt>;
17910 otherwise, the content of existing symbols
17911 will remain.
17912 This makes <em>mixins</em> of context objects possible.
17913 <tt>new</tt> returns the target context,
17914 which cannot be MAIN.
17915 </p>
17916
17917 <p>
17918 In the second syntax,
17919 the existing context in <em>context-source</em>
17920 gets copied into the current context
17921 as the target context.
17922 </p>
17923
17924 <p>
17925 All references to symbols in the originating context
17926 will be translated to references in the target context.
17927 This way, all functions and data structures referring to symbols
17928 in the original context will now refer to symbols in the target context.
17929 </p>
17930
17931 <b>example:</b>
17932 <blockquote>
17933 <pre>
17934 (new CTX 'CTX-2)  <span class=arw>&rarr;</span> CTX-2
17935
17936 ;; force overwrite of existing symbols
17937 (new CTX MyCTX true)  <span class=arw>&rarr;</span> MyCTX
17938
17939 (set 'CTX:x 123)
17940 (new CTX)  <span class=arw>&rarr;</span> MAIN  ; copies x into MAIN
17941 x          <span class=arw>&rarr;</span> 123
17942
17943 (map new '(Ct-a Ct-b Ct-c))  ; merge into current context
17944 </pre>
17945 </blockquote>
17946
17947 <p>
17948 The first line in the example creates a new context
17949 called <tt>CTX-2</tt> that has the exact same structure
17950 as the original one.
17951 Note that <tt>CTX</tt> is not quoted
17952 because contexts evaluate to themselves,
17953 but CTX-2 must be quoted because it does not exist yet.
17954 </p>
17955
17956 <p>
17957 The second line merges the context <tt>CTX</tt> into <tt>MyCTX</tt>.
17958 Any existing symbols of same name in <tt>MyCTX</tt>
17959 will be overwritten.
17960 Because <tt>MyCTX</tt> already exists,
17961 the quote before the context symbol can be omitted.
17962 </p>
17963
17964 <p>
17965 The last lines show how a foreign context
17966 gets merged into the current one
17967 and how <a href="#map">map</a> can be used
17968 to merge a list of contexts.
17969 </p>
17970
17971 <p>
17972 Context symbols need not be mentioned explicitly,
17973 but they can be contained in variables:
17974 </p>
17975
17976 <b>example:</b>
17977 <blockquote>
17978 <pre>
17979 (set 'foo:x 123)
17980 (set 'bar:y 999)
17981
17982 (set 'ctxa foo)
17983 (set 'ctxb bar)
17984
17985 (new ctxa ctxb)  ; from foo to bar
17986
17987 bar:x  <span class=arw>&rarr;</span> 123  ; x has been added to bar
17988 bar:y  <span class=arw>&rarr;</span> 999)
17989 </pre>
17990 </blockquote>
17991
17992 <p>
17993 The example refers to contexts in variables
17994 and merges context <tt>foo</tt> into <tt>bar</tt>.
17995 </p>
17996
17997
17998 <p>
17999 See also the function <a href="#def-new">def-new</a>
18000 for moving and merging single functions
18001 instead of entire contexts.
18002 See the <a href="#context">context</a> function
18003 for a more comprehensive example of <tt>new</tt>.
18004 </p>
18005
18006 <br /><br />
18007
18008 <a name="nilp"></a>
18009 <h2><span class="function">nil?</span></h2>
18010 <b>syntax: (nil? <em>expr</em>)</b>
18011
18012 <p>
18013 If the expression in <em>expr</em> evaluates to <tt>nil</tt>,
18014 then <tt>nil?</tt> returns <tt>true</tt>;
18015 otherwise, it returns <tt>nil</tt>.
18016 </p>
18017
18018 <b>example:</b>
18019 <blockquote>
18020 <pre>
18021 (map nil? '(x nil  1 nil "hi" ()))
18022 <span class=arw>&rarr;</span> (nil true nil true nil nil)
18023
18024 (nil? nil)  <span class=arw>&rarr;</span> true
18025 (nil? '())  <span class=arw>&rarr;</span> nil
18026
18027 ; nil? means strictly nil
18028 (nil? (not '()))  <span class=arw>&rarr;</span> nil
18029 </pre>
18030 </blockquote>
18031
18032 <p>
18033 The <tt>nil?</tt> predicate
18034 is useful for distinguishing between
18035 <tt>nil</tt> and the empty list <tt>()</tt>.
18036 </p>
18037
18038 <p>Note that <tt>nil?</tt> means <em>strictly</em> <tt>nil</tt>
18039 while <tt>true?</tt> means everything not <tt>nil</tt> or the
18040 empty list <tt>()</tt>.</p>
18041
18042 <br /><br />
18043
18044 <a NAME="not"></a>
18045 <h2><span class="function">not</span></h2>
18046
18047 <b>syntax: (not <em>exp</em>)</b>
18048
18049 <p>
18050 If <em>exp</em> evaluates to <tt>nil</tt>,
18051 then <tt>true</tt> is returned;
18052 otherwise, <tt>nil</tt> is returned.
18053 </p>
18054
18055 <b>example:</b>
18056 <blockquote>
18057 <pre>
18058 (not true)            <span class=arw>&rarr;</span> nil
18059 (not nil)             <span class=arw>&rarr;</span> true
18060 (not '())             <span class=arw>&rarr;</span> true
18061 (not (&lt; 1 10))        <span class=arw>&rarr;</span> nil
18062 (not (not (&lt; 1 10)))  <span class=arw>&rarr;</span> true
18063 </pre>
18064 </blockquote>
18065 <br /><br />
18066
18067 <a NAME="normal"></a>
18068 <h2><span class="function">normal</span></h2>
18069 <b>syntax: (normal <em>float-mean</em> <em>float-stdev</em> <em>int-n</em>)</b><br />
18070 <b>syntax: (normal <em>float-mean</em> <em>float-stdev</em>)</b>
18071
18072 <p>
18073 In the first form, <tt>normal</tt> returns a list of length <em>int-n</em>
18074 of random, continuously distributed floating point numbers
18075 with a mean of <em>float-mean</em>
18076 and a standard deviation of <em>float-stdev</em>.
18077 The random generator used internally
18078 can be seeded using the <a HREF="#seed">seed</a> function.
18079 </p>
18080
18081 <b>example:</b>
18082 <blockquote>
18083 <pre>
18084 (normal 10 3 10)
18085 <span class=arw>&rarr;</span> (7 6.563476562 11.93945312 6.153320312 9.98828125
18086 7.984375 10.17871094 6.58984375 9.42578125 12.11230469)
18087 </pre>
18088 </blockquote>
18089
18090 <p>
18091 In the second form,
18092 <tt>normal</tt> returns a single
18093 normal distributed floating point number:
18094 </p>
18095
18096 <blockquote>
18097 <pre>
18098 (normal 0 1)  <span class=arw>&rarr;</span> 0.6630859375
18099 </pre>
18100 </blockquote>
18101
18102 <p>
18103 See also the <a HREF="#random">random</a>
18104 and <a href="#rand">rand</a> functions
18105 for evenly distributed numbers,
18106 <a href="#amb">amb</a> for randomizing evaluation
18107 in a list of expressions,
18108 and <a href="#seed">seed</a> for setting a different start point
18109 for pseudo random number generation.
18110 </p>
18111
18112 <br /><br />
18113
18114 <a NAME="now"></a>
18115 <h2><span class="function">now</span></h2>
18116 <b>syntax: (now [<em>int-offset</em>])</b>
18117 <p>
18118 Returns information about
18119 the current date and time
18120 as a list of integers.
18121 An optional time-zone offset
18122 can be specified in minutes in <em>int-offset</em>.
18123 This causes the time to be shifted
18124 forward or backward in time,
18125 before being split into separate date values.
18126 </p>
18127
18128 <b>example:</b>
18129 <blockquote>
18130 <pre>
18131 (now)  <span class=arw>&rarr;</span> (2002 2 27 18 21 30 140000 57 3 300 0)
18132
18133 (apply date-value (now))  <span class=arw>&rarr;</span> 1014834090
18134 </pre>
18135 </blockquote>
18136
18137 <p>
18138 The numbers represent the following date-time fields:
18139 </p>
18140 <br />
18141 <blockquote>
18142 <table border="0" cellpadding="1" width="90%" summary="date formatting">
18143 <tr align="left"><th>format</th><th>description</th></tr>
18144
18145 <tr><td>year</td><td>Gregorian calendar</td></tr>
18146 <tr><td>month</td><td>               (1&ndash;12)</td></tr>
18147 <tr><td>day</td><td>                 (1&ndash;31)</td></tr>
18148 <tr><td>hour</td><td>                (0&ndash;23) UCT</td></tr>
18149 <tr><td>minute</td><td>              (0&ndash;59)</td></tr>
18150 <tr><td>second</td><td>              (0&ndash;59)</td></tr>
18151 <tr><td>microsecond</td><td>         (0&ndash;999999)
18152                 OS-specific, millisecond resolution</td></tr>
18153
18154 <tr><td>day of current year</td><td>Jan 1st is 1</td></tr>
18155 <tr><td>day of current week</td><td> (1&ndash;7) starting Sunday</td></tr>
18156 <tr><td>time zone offset in minutes</td><td> west of GMT</td></tr>
18157 <tr><td>daylight savings time flag</td><td> (0&ndash;1) on Linux/UNIX
18158                                 bias and in minutes on Win32</td></tr>
18159 </table>
18160 </blockquote>
18161
18162 <br />
18163
18164 <p>
18165 The second example returns the UCT time value of seconds
18166 after January 1, 1970.
18167 </p>
18168
18169 <p>
18170 Ranging from 0 to 23,
18171 hours are given in Coordinated Universal Time (UCT)
18172 and are not adjusted for the local time zone.
18173 The resolution of the microsecond field
18174 depends on the operating system and platform.
18175 On some platforms,
18176 the last three digits of the <tt>microseconds</tt> field
18177 are always 0 (zero).
18178 </p>
18179
18180 <p>
18181 See also the <a HREF="#date">date</a>,
18182 <a href="#date-value">date-value</a>,
18183 <a href="#time">time</a>,
18184 and <a href="#time-of-day">time-of-day</a> functions.
18185 </p>
18186
18187 <p>
18188 Note that on Solaris,
18189 the returned time offset value
18190 is not working correctly in some versions/platforms
18191 and may contain garbage values.
18192 </p>
18193
18194 <p>
18195 On many platforms,
18196 the daylight savings flag
18197 is not active
18198 and returns 0 (zero)
18199 even during daylight savings time.
18200 </p>
18201
18202 <br /><br />
18203
18204 <a name="nullp"></a>
18205 <h2><span class="function">null?</span></h2>
18206 <b>syntax: (null? <em>expr</em>)</b>
18207
18208 <p>
18209 Checks if an expression evaluates to <tt>nil</tt>,
18210 the empty list <tt>()</tt>,
18211 the empty string <tt>""</tt>,
18212 <tt>NaN</tt> (not a number),
18213 or 0 (zero),
18214 in which case it returns <tt>true</tt>.
18215 In all other cases,
18216 <tt>null?</tt> returns <tt>nil</tt>.
18217 The predicate <tt>null?</tt> is useful in conjunction with the functions <a href="#filter">filter</a> or <a href="#clean">clean</a> to check the outcome of other newLISP operations.
18218 </p>
18219
18220 <b>example:</b>
18221 <blockquote>
18222 <pre>
18223 (map null? '(1 0 0.0 2 NaN "hello" "" (a b c) () nil true))
18224 <span class=arw>&rarr;</span> (nil true true true nil true nil true nil true true nil)
18225
18226 (filter null? '(1 0 2 0.0 NaN "hello" "" (a b c) () nil true))
18227 <span class=arw>&rarr;</span> (0 0 NaN "" () nil)
18228
18229 (clean null? '(1 0 2 0.0 NaN "hello" "" (a b c) () nil true))
18230 <span class=arw>&rarr;</span> (1 2 "hello" (a b c) true)
18231 </pre>
18232 </blockquote>
18233
18234 <p>
18235 See also the predicates <a href="#emptyp">empty?</a>,
18236 <a href="#nilp">nil?</a>
18237 and <a href="#zerop">zero?</a>.
18238 </p>
18239
18240 <br /><br />
18241
18242 <a NAME="nper"></a>
18243 <h2><span class="function">nper</span></h2>
18244 <b>syntax: (nper <em>num-interest</em> <em>num-pmt</em> <em>num-pv</em> [<em>num-fv</em> <em>int-type</em>])</b>
18245
18246 <p>
18247 Calculates the number of payments required to pay a loan of <em>num-pv</em> with a constant interest rate of <em>num-interest</em> and payment <em>num-pmt</em>.
18248 If <em>num-fv</em> is omitted,
18249 the future value of the loan is assumed to be 0.0.
18250 If payment is at the end of the period,
18251 <em>int-type</em> is 0;
18252 else it is 1.
18253 If <em>int-type</em> is omitted,
18254 0 is assumed.
18255 </p>
18256
18257 <b>example:</b>
18258 <blockquote>
18259 <pre>
18260 (nper (div 0.07 12) 775.30 -100000)  <span class=arw>&rarr;</span> 239.9992828
18261 </pre>
18262 </blockquote>
18263
18264 <p>
18265 The example calculates the number of monthly payments required to pay a loan of $100,000 at a yearly interest rate of 7 percent with payments of $775.30.
18266 </p>
18267
18268 <p>
18269 See also the <a HREF="#fv">fv</a>,
18270 <a href="#irr">irr</a>,
18271 <a HREF="#npv">npv</a>,
18272 <a HREF="#pmt">pmt</a>,
18273 and <a HREF="#pv">pv</a> functions.
18274 </p>
18275 <br /><br />
18276
18277 <a NAME="npv"></a>
18278 <h2><span class="function">npv</span></h2>
18279 <b>syntax: (npv <em>num-interest</em> <em>list-values</em>)</b>
18280
18281 <p>
18282 Calculates the net present value of an investment with a fixed interest rate <em>num-interest</em> and a series of future payments and income in <em>list-values</em>.
18283 Payments are represented by negative values in <em>list-values</em>,
18284 while income is represented by positive values in <em>list-values</em>.
18285 </p>
18286
18287 <b>example:</b>
18288 <blockquote>
18289 <pre>
18290 (npv 0.1 '(1000 1000 1000))
18291 <span class=arw>&rarr;</span> 2486.851991
18292
18293 (npv 0.1 '(-2486.851991 1000 1000 1000))
18294 <span class=arw>&rarr;</span> -1.434386832e-08  ; ~ 0.0 (zero)
18295 </pre>
18296 </blockquote>
18297
18298 <p>
18299 In the example,
18300 an initial investment of $2,481.85 would allow for an income of $1,000 after the end of the first,
18301 second,
18302 and third years.
18303 </p>
18304
18305 <p>
18306 See also the <a HREF="#fv">fv</a>,
18307 <a href="#irr">irr</a>,
18308 <a HREF="#nper">nper</a>,
18309 <a HREF="#pmt">pmt</a>,
18310 and <a HREF="#pv">pv</a> functions.
18311 </p>
18312
18313
18314 <br /><br />
18315
18316
18317 <a NAME="nth"></a>
18318 <h2><span class="function">nth</span></h2>
18319 <b>syntax: (nth int-index <em>list</em>)</b><br /><br />
18320 <b>syntax: (nth (<em>list</em> <em>int-index-1</em> [<em>int-index-2 ...</em>]))</b><br /><br />
18321 <b>syntax: (nth (<em>array</em> <em>int-index-1</em> [<em>int-index-2 ...</em>]))</b><br /><br />
18322 <b>syntax: (nth (<em>str</em> <em>int-offset</em>))</b>
18323
18324 <p>
18325 In the first version,
18326 <tt>nth</tt> evaluates <em>int-index</em>
18327 and uses it as an index
18328 into <em>list</em>,
18329 returning the element found
18330 at that index.
18331 See also <a HREF="#indexing">Indexing elements of strings and lists</a>.
18332 Multiple indices may be specified
18333 to recursively access elements in nested lists.
18334 If there are more indices than nesting levels,
18335 the extra indices are ignored.
18336 </p>
18337
18338 <b>example:</b>
18339 <blockquote>
18340 <pre>
18341 (set 'L '(a b c))
18342 (nth 0 L)    <span class=arw>&rarr;</span> a
18343 (nth (L 0))  <span class=arw>&rarr;</span> a
18344 ; or simply
18345 (L 0) <span class=arw>&rarr;</span> a
18346
18347 (set 'names '(john martha robert alex))
18348 <span class=arw>&rarr;</span> (john martha robert alex)
18349
18350 (nth (names 2))  <span class=arw>&rarr;</span> robert
18351 ; or simpy
18352 (names 2) <span class=arw>&rarr;</span> robert
18353
18354 (names -1)  <span class=arw>&rarr;</span> alex
18355
18356 (set 'persons '((john 30) (martha 120) ((john doe) 17)))
18357
18358 (persons 1 1)  <span class=arw>&rarr;</span> 120
18359
18360 (nth (persons 2 0 1))  <span class=arw>&rarr;</span> doe
18361 ; or simply
18362 (persons 2 0 1)  <span class=arw>&rarr;</span> doe
18363
18364 ; multiple indices in a vector
18365 (set 'v '(2 0 1))
18366 (persons v)      <span class=arw>&rarr;</span> doe
18367
18368 (persons -2 0)  <span class=arw>&rarr;</span> martha
18369
18370 (persons 10)  <span class=arw>&rarr;</span> ((john doe) 17))  ; out of bounds
18371 (person -5)  <span class=arw>&rarr;</span> (john 30)          ; out of bounds
18372 </pre>
18373 </blockquote>
18374
18375 <p>When using a syntax with parenthesized list and indices <tt>(L idx)</tt> then
18376 <tt>L</tt> can be the context of the default functor <tt>L:L</tt>. This allows lists
18377 passed by reference:</p>
18378
18379 <blockquote><pre>
18380 (set 'L:L '(a b c d e f g))
18381
18382 (define (second ctx)
18383         (nth (ctx 1)))
18384
18385 ;; passing the list in L:L by reference
18386 (second L)   <span class=arw>&rarr;</span> b
18387
18388 ;; passing the list in L:L by value
18389 (second L:L) <span class=arw>&rarr;</span> b
18390 </pre></blockquote>
18391
18392 <p>Reference passing is faster and uses less memory in big lists and should
18393 be used on lists with more than a few hundred items.</p>
18394
18395 <p>Note that the <i>implicit indexing</i> version of <tt>nth</tt> is not breaking Lisp
18396 syntax rules but should be understood as a logical expansion of Lisp syntax rules to
18397 other data types than built-in functions or lambda expressions. A list in the functor
18398 position of an s-expression assumes self-indexing functionality using the index
18399 arguments following.</p>
18400
18401 <p>
18402 The implicit indexed syntax forms are faster but the other form with an explicit
18403 <tt>nth</tt> may be more readable in some situations.
18404 </p>
18405
18406 <p>
18407 In the second version,
18408 <tt>nth</tt> works on <a href="#array">arrays</a> just like it does on lists,
18409 but out-of-bounds indices will cause an error message.
18410 </p>
18411
18412 <b>example:</b>
18413 <blockquote>
18414 <pre>
18415 (set 'aArray (array 2 3 '(a b c d e f)))
18416 <span class=arw>&rarr;</span> ((a b c) (d e f))
18417 (nth (aArray 1))    <span class=arw>&rarr;</span>  (d e f)
18418 (aArray 1)          <span class=arw>&rarr;</span>  (d e f)
18419
18420 (nth (aArray 1 0))     <span class=arw>&rarr;</span> d
18421 (nth (aArray '(1 0)))  <span class=arw>&rarr;</span> d
18422
18423 (aArray 1 0)           <span class=arw>&rarr;</span> d
18424 (aArray '(1 0))        <span class=arw>&rarr;</span> d
18425 </pre>
18426 </blockquote>
18427
18428 <p>
18429 In the third version,
18430 <tt>nth</tt> returns the character found at the position <em>int-index</em> in <em>str</em> and returns it as a string.
18431 </p>
18432
18433 <b>example:</b>
18434 <blockquote>
18435 <pre>
18436 (nth ("newLISP" 0)) <span class=arw>&rarr;</span> "n"
18437
18438 ("newLISP" 0)       <span class=arw>&rarr;</span> "n"
18439 `
18440 ("newLISP" -1)      <span class=arw>&rarr;</span> "P"
18441 </pre>
18442 </blockquote>
18443
18444 <p>
18445 See also the <a HREF="#set-nth">set-nth</a> function for accessing multidimensional nested lists and arrays.
18446 See the <a href="#push">push</a> and <a href="#pop">pop</a> functions for accessing multidimensional lists.
18447 </p>
18448
18449 <p>
18450 Note also that <a href="#nth">nth</a> works on character boundaries rather than byte boundaries when using the UTF-8&ndash;enabled version of newLISP.
18451 </p>
18452
18453
18454 <br /><br />
18455
18456 <a NAME="nth-set"></a>
18457
18458 <h2><span class="function">nth-set</span></h2>
18459 <b>syntax: (nth-set <em>int-index</em> <em>list</em> <em>exp-replacement</em>)</b><br /><br />
18460 <b>syntax: (nth-set (<em>list</em> <em>int-nth-1</em> [ <em>int-nth-2 ...</em>]) <em>exp-replacement</em>)</b><br /><br />
18461 <b>syntax: (nth-set (<em>array</em> <em>int-nth-1</em> [ <em>int-nth-2 ...</em>]) <em>exp-replacement</em>)</b><br /><br />
18462 <b>syntax: (nth-set (<em>str</em> <em>int-nth-1</em>) <em>str</em> <em> str-replacement</em>)</b>
18463
18464 <p>
18465 Sets the <em>int-nth</em> element of a list or array with the evaluation of <em>exp-replacement</em>
18466 and returns the old element. As shown in the last two syntax lines,
18467 <a href="#implicit_indexing">implicit indexing</a> syntax can be used
18468 for specifying indices. Implicit indexing is the preferred form in
18469 <tt>nth-set</tt> and <a href="#set-nth">set-nth</a>, but both forms remain valid.
18470 </p>
18471
18472 <p>
18473 <tt>nth-set</tt> performs a destructive operation, changing the original list or array.
18474 More than one index can be specified to recursively traverse nested list structures
18475 or multidimensional arrays. An out-of-bounds index always returns the last or first element
18476 when indexing a list, but it causes an out-of-bound error when indexing an array.
18477 </p>
18478
18479 <p>
18480 When replacing in lists, the old element is also contained in the system variable $0 and
18481 can be used in the replacement expression itself.
18482 </p>
18483
18484 <blockquote>
18485 <pre>
18486 (set 'aList '(a b c d e f g))
18487
18488 ;; plain syntax for on level index
18489 (nth-set 4 aList (list $0 'z))     <span class=arw>&rarr;</span> e ; old value
18490
18491 ;; modern syntax and preferred for multiple indices
18492 (nth-set (aList 4) (list $0 'z))   <span class=arw>&rarr;</span> e ; old value
18493
18494 aList <span class=arw>&rarr;</span> (a b c d (e z) f g)
18495 </pre>
18496 </blockquote>
18497
18498 <p>
18499 <P>In the second form,
18500 the <em>int-nth</em> character in <em>str</em> is replaced with the string in <em>str-replacement</em>.
18501 Out-of-bounds indices will pick the first or last character for replacement,
18502 and the system variable <tt>$0</tt> is set to the old, replaced character.
18503 </p>
18504
18505 <b>example:</b>
18506 <blockquote>
18507 <pre>
18508 ;;;;;;;;;;; usage on lists ;;;;;;;;;;;;
18509
18510 (set 'aList '(a b c d e f g))
18511
18512 (nth-set (aList 2) "I am the replacement")  <span class=arw>&rarr;</span> c  ; new syntax
18513
18514 aList  <span class=arw>&rarr;</span> (a b "I am the replacement" d e f g)
18515
18516 $0  <span class=arw>&rarr;</span> c
18517
18518 (set 'aList '(a b (c d (e f g) h) i))
18519 (nth-set (aList 2 2 0) 'x)  <span class=arw>&rarr;</span> e
18520
18521 aList  <span class=arw>&rarr;</span> (a b (c d (x f g) h) i)
18522 $0     <span class=arw>&rarr;</span> e
18523
18524 (nth-set (aList -2 2 -1) 99)  <span class=arw>&rarr;</span> g
18525
18526 aList  <span class=arw>&rarr;</span> (a b (c d (x f 99) h) i)
18527
18528 ;; use indices in a vector
18529
18530 (set 'aList '(a b (c d (e f g) h) i))
18531
18532 (set 'vec (ref 'f aList))  <span class=arw>&rarr;</span> (2 2 1)
18533
18534 (nth-set (aList vec) 'Z)  <span class=arw>&rarr;</span> f ; old value
18535
18536 aList  <span class=arw>&rarr;</span> (a b (c d (e Z g) h) i)
18537
18538 ;; usage on default functors
18539
18540 (set 'db:db '(a b c d e f g))
18541
18542 (nth-set (db 3) 99)  <span class=arw>&rarr;</span> d
18543
18544 db:db  <span class=arw>&rarr;</span> (a b c 99 e f g)
18545 </pre>
18546 </blockquote>
18547
18548 <p>
18549 The following examples use <tt>nth-set</tt> to change the contents of <a href="#array">arrays</a>.
18550 </p>
18551
18552 <b>example:</b>
18553 <blockquote>
18554 <pre>
18555 ;;;;;;;;;;; usage on arrays ;;;;;;;;;;;;
18556
18557 (set 'myarray (array 3 4 (sequence 1 12)))
18558 <span class=arw>&rarr;</span> ((1 2 3 4) (5 6 7 8) (9 10 11 12))
18559
18560 (nth-set (myarray 2 3) 99)  <span class=arw>&rarr;</span> 12
18561 myarray
18562 <span class=arw>&rarr;</span> ((1 2 3 4) (5 6 7 8) (9 10 11 99))
18563
18564 (nth-set (myarray -2 1) "hello")  <span class=arw>&rarr;</span> 6
18565 myarray
18566 <span class=arw>&rarr;</span> ((1 2 3 4) (5 "hello" 7 8) (9 10 11 99))
18567
18568 (nth-set (myarray 1) (array 4 '(a b c d)))
18569 <span class=arw>&rarr;</span> (5 "hello" 7 8)
18570 myarray
18571 <span class=arw>&rarr;</span> ((1 2 3 4) (a b c d) (9 10 11 99))
18572
18573 ;; usage on default functors
18574 (set 'myarray:myarray (array 7 '(a b c d e f g)))
18575
18576 (nth-set (myarray 3) 99)  <span class=arw>&rarr;</span> d
18577 myarray:myarray           <span class=arw>&rarr;</span> (a b c 99 e f g)
18578 </pre>
18579 </blockquote>
18580
18581 <p>
18582 <P>When replacing whole rows as in the third example,
18583 care must be taken to replace it as an array.
18584 See also the array functions <a href="#array">array</a>,
18585 <a href="#arrayp">array?</a>,
18586 and <a href="#array-list">array-list</a>.
18587 </p>
18588
18589 <p>
18590 <P>In second form,
18591 the <em>int-nth</em> character in <em>str</em> is replaced with the string in <em>str-replacement</em>.
18592 </p>
18593
18594 <b>example:</b>
18595 <blockquote>
18596 <pre>
18597 ;;;;;;;;;;; usage on strings ;;;;;;;;;;;;
18598 (set 's "abcd")
18599
18600 (nth-set (s 0) "xyz")  <span class=arw>&rarr;</span> "a"
18601 s   <span class=arw>&rarr;</span> "xyzbcd"
18602 $0  <span class=arw>&rarr;</span> "a"
18603 </pre>
18604 </blockquote>
18605
18606
18607 <p>
18608 <tt>nth-set</tt> uses the system variable <tt>$0</tt> for the element found in lists and strings.
18609 This can be used in the replacement expression:
18610 </p>
18611
18612 <blockquote>
18613 <pre>
18614 (set 'lst '(1 2 3 4))
18615
18616 (nth-set (lst 1) (+ $0 1))  <span class=arw>&rarr;</span> 2
18617
18618 lst  <span class=arw>&rarr;</span> '(1 3 3 4)
18619 </pre>
18620 </blockquote>
18621
18622 <p>
18623 See the <a href="#set-nth">set-nth</a> function,
18624 which works like <tt>nth-set</tt>
18625 but returns the whole changed expression
18626 instead of the replaced element.
18627 <tt>set-nth</tt> is also slower when doing replacements
18628 in larger lists or string buffers.
18629 </p>
18630
18631 <P>
18632 Use the <A HREF="#nth">nth</A>,
18633 <a href="#push">push</a>,
18634 and <a href="#pop">pop</a> functions
18635 to access multidimensional nested lists.
18636 The <A HREF="#nth">nth</A> function
18637 will also work
18638 with multidimensional nested arrays.
18639 </p>
18640
18641
18642 <p>
18643 <tt>nth-set</tt> works exactly like <a HREF="#set-nth">set-nth</a> but returns the replaced element instead of the whole changed list expression.
18644 <tt>nth-set</tt> is much faster when replacing elements in larger lists or arrays.
18645 </p>
18646
18647 <br /><br />
18648
18649 <a NAME="numberp"></a>
18650 <h2><span class="function">number?</span></h2>
18651 <b>syntax: (number? <em>exp</em>)</b>
18652
18653 <p>
18654 <tt>true</tt> is returned only if <em>exp</em> evaluates to a floating point number or an integer;
18655 otherwise,
18656 <tt>nil</tt> is returned.
18657 </p>
18658
18659 <b>example:</b>
18660 <blockquote>
18661 <pre>
18662 (set 'x 1.23)
18663 (set 'y 456)
18664 (number? x)      <span class=arw>&rarr;</span> true
18665 (number? y)      <span class=arw>&rarr;</span> true
18666 (number? "678")  <span class=arw>&rarr;</span> nil
18667 </pre>
18668 </blockquote>
18669
18670 <p>
18671 See the functions <a href="#floatp">float?</a> and <a href="#integerp">integer?</a> to test for a specific number type.
18672 </p>
18673
18674 <br /><br />
18675
18676 <a NAME="open"></a>
18677 <h2><span class="function">open</span></h2>
18678
18679 <b>syntax: (open <em>str-path-file</em> <em>str-access-mode</em> [<em>str-option</em>])</b>
18680
18681 <p>
18682 The <em>str-path-file</em> is a file name,
18683 and <em>str-access-mode</em> is a string specifying the file access mode.
18684 <tt>open</tt> returns an integer,
18685 which is a file handle to be used on subsequent read or write operations on the file.
18686 On failure,
18687 <tt>open</tt> returns <tt>nil</tt>.
18688 The access mode <tt>"write"</tt> creates the file if it doesn't exist,
18689 or it truncates an existing file to 0 (zero) bytes in length.
18690 </p>
18691
18692 <p>
18693 The following strings are legal access modes:
18694 </p>
18695
18696 <blockquote>
18697 <tt>"read"</tt> or <tt>"r"</tt> for read only access<br />
18698
18699 <tt>"write"</tt> or <tt>"w"</tt> for write only access<br />
18700 <tt>"update"</tt> or <tt>"u"</tt> for read/write access<br />
18701 <tt>"append"</tt> or <tt>"a"</tt> for append read/write access<br />
18702
18703 </blockquote>
18704
18705 <b>example:</b>
18706 <blockquote>
18707 <pre>
18708 (device (open "newfile.data" "write"))  <span class=arw>&rarr;</span> 5
18709 (print "hello world\n")  <span class=arw>&rarr;</span> "hello world"
18710 (close (device))         <span class=arw>&rarr;</span> 5
18711
18712 (set 'aFile (open "newfile.data" "read"))
18713 (seek aFile 6)
18714 (set 'inChar (read-char aFile))
18715 (print inChar "\n")
18716 (close aFile)
18717 </pre>
18718 </blockquote>
18719
18720 <p>
18721 The first example uses <tt>open</tt> to set the device for <a HREF="#print">print</a> and writes the word <tt>"hello world"</tt> into the file <tt>newfile.data</tt>.
18722 The second example reads a byte value at offset 6 in the same file (the ASCII value of <tt>'w'</tt> is 119).
18723 Note that using <tt>close</tt> on <a HREF="#device">(device)</a> automatically resets <a HREF="#device">device</a> to 0 (zero).
18724 </p>
18725
18726 <p>
18727 As an additional <em>str-option</em>,
18728 <tt>"non-block"</tt> or <tt>"n"</tt> can be specified after the <tt>"read"</tt> or <tt>"write"</tt> option.
18729 Only available on UNIX systems,
18730 non-blocking mode can be useful when opening <em>named pipes</em> but is not required to perform I/O on named pipes.
18731 </p>
18732
18733 <p>
18734 To create a named pipe in newLISP,
18735 use the <a href="#exec">exec</a> or <a href="#import">import</a> function:
18736 </p>
18737
18738 <b>example:</b>
18739 <blockquote>
18740 <pre>
18741 (exec "mkfifo myfifo")
18742
18743 ;; or alternatively
18744
18745 (import "/lib/libc.so.6" "mkfifo")
18746 (mkfifo "/tmp/myfifo" 0777)
18747 </pre>
18748
18749 </blockquote>
18750
18751 <p>
18752 The named pipe can now be used like a file with <a href="#open">open</a>,
18753 <a href="#read-buffer">read-buffer</a>,
18754 and <a href="#write-buffer">write-buffer</a>.
18755 </p>
18756
18757 <br /><br />
18758
18759 <a NAME="or"></a>
18760 <h2><span class="function">or</span></h2>
18761
18762 <b>syntax: (or <em>exp-1</em> [<em>exp-2</em> ... ])</b>
18763
18764 <p>
18765 Evaluates expressions <em>exp-x</em> from left to right until finding a result that does not evaluate to <tt>nil</tt> or the empty list <tt>()</tt>.
18766 The result is the return value of the <tt>or</tt> expression.
18767 </p>
18768
18769 <b>example:</b>
18770 <blockquote>
18771 <pre>
18772 (set 'x 10)
18773 (or (&gt; x 100) (= x 10))          <span class=arw>&rarr;</span> true
18774 (or "hello" (&gt; x 100) (= x 10))  <span class=arw>&rarr;</span> "hello"
18775 (or '())                         <span class=arw>&rarr;</span> nil
18776 (or true)                        <span class=arw>&rarr;</span> true
18777 (or)                             <span class=arw>&rarr;</span> nil
18778 </pre>
18779 </blockquote>
18780 <br /><br />
18781
18782 <a NAME="ostype"></a>
18783 <h2><span class="function">ostype</span></h2>
18784 <b>syntax: ostype</b>
18785
18786 <p><tt>ostype</tt> is a built-in system constant
18787 containing the name of the operating system
18788 newLISP is running on.</p>
18789
18790 <b>example:</b>
18791 <blockquote>
18792 <pre>
18793 ostype  <span class=arw>&rarr;</span> "Win32"
18794 </pre>
18795 </blockquote>
18796
18797 <p>One of the following strings is returned: <tt>"Linux", "BSD", "OSX", "Tru64Unix", "Solaris", "Win32", or "OS/2"</tt>.
18798 </p>
18799
18800
18801 <p><tt>ostype</tt> can be used to write platform-independent code:</p>
18802 <blockquote>
18803 <pre>
18804 (if
18805 (= ostype "Linux") (import "libz.so")
18806 (= ostype "BSD") (import "libz.so")
18807 (= ostype "OSX") (import "libz.dylib")
18808 ...
18809 (println "cannot import libz on this platform")
18810 )
18811 </pre>
18812 </blockquote>
18813
18814 <p>Use <a href="#sys-info">sys-info</a> to learn more
18815 about the current flavor of newLISP running.</p>
18816
18817 <br /><br />
18818
18819 <a NAME="pack"></a>
18820 <h2><span class="function">pack</span></h2>
18821 <b>syntax: (pack <em>str-format</em> <em>exp-1</em> [<em>exp-2</em> ... ])</b><br />
18822 <b>syntax: (pack <em>str-format</em> <em>list-expr</em>)</b>
18823
18824 <p>
18825 Packs one or more expressions (<em>exp-1</em> to <em>exp-n</em>)
18826 into a binary format specified in the format string <em>str-format</em>,
18827 returning the binary structure in a string buffer.
18828 The symmetrical <a HREF="#unpack">unpack</a> function is used
18829 for unpacking. The expression arguments can also be given in a list.
18830 <tt>pack</tt> and <tt>unpack</tt> are useful
18831 when reading and writing binary files
18832 (see <a HREF="#read-buffer">read-buffer</a> and
18833 <a HREF="#write-buffer">write-buffer</a>)
18834 or when unpacking binary structures
18835 from return values of imported C functions
18836 using <tt>import</tt>.
18837 </p>
18838
18839 <p>
18840 The following characters are used in <em>str-format</em>:
18841 </p>
18842
18843 <blockquote>
18844 <br />
18845 <table border="0" cellpadding="1" width="95%" summary="format characters">
18846 <tr align="left"><th>format</th><th>description</th></tr>
18847
18848 <tr>
18849 <td WIDTH="20%"><tt>c </tt></td>
18850
18851 <td WIDTH="80%">a signed 8-bit number</td>
18852 </tr>
18853
18854 <tr>
18855 <td><tt>b </tt></td>
18856 <td>an unsigned 8-bit number</td>
18857 </tr>
18858
18859 <tr>
18860 <td><tt>d </tt></td>
18861 <td>a signed 16-bit short number</td>
18862 </tr>
18863
18864 <tr>
18865 <td><tt>u </tt></td>
18866 <td>an unsigned 16-bit short number</td>
18867 </tr>
18868
18869 <tr>
18870 <td><tt>ld</tt></td>
18871 <td>a signed 32-bit long number</td>
18872 </tr>
18873
18874 <tr>
18875 <td><tt>lu</tt></td>
18876 <td>an unsigned 32-bit long number</td>
18877 </tr>
18878
18879 <tr>
18880 <td><tt>Ld</tt></td>
18881 <td>a signed 64-bit long number</td>
18882 </tr>
18883
18884 <tr>
18885 <td><tt>Lu</tt></td>
18886 <td>an unsigned 64-bit long number</td>
18887 </tr>
18888
18889 <tr>
18890 <td><tt>f </tt></td>
18891 <td>a float in 32-bit representation</td>
18892 </tr>
18893
18894 <tr>
18895 <td><tt>lf</tt></td>
18896 <td>a double float in 64-bit representation</td>
18897 </tr>
18898
18899 <tr>
18900 <td><tt>sn</tt></td>
18901 <td>a string of <em>n</em> null padded ASCII characters</td>
18902 </tr>
18903
18904 <tr>
18905 <td><tt>nn</tt></td>
18906 <td><em>n</em> null characters</td>
18907 </tr>
18908
18909 <tr>
18910 <td><tt>&gt;</tt></td>
18911
18912 <td>switch to big endian byte order</td>
18913 </tr>
18914
18915 <tr>
18916 <td><tt>&lt;</tt></td>
18917 <td>switch to little endian byte order</td>
18918 </tr>
18919
18920 </table>
18921 </blockquote>
18922 <br />
18923
18924 <p>
18925 Note that newLISP only supports 32-bit, signed integers
18926 and treats <tt>lu</tt> and <tt>ld</tt> the same way internally.
18927 </p>
18928
18929 <p>
18930 <tt>pack</tt> will convert all floats into integers
18931 when passed to <tt>b</tt>, <tt>c</tt>, <tt>d</tt>, <tt>ld</tt>,
18932 or <tt>lu</tt> formats.
18933 It will also convert integers into floats
18934 when passing them to <tt>f</tt> and <tt>lf</tt> formats.
18935 </p>
18936
18937 <b>example:</b>
18938 <blockquote>
18939 <pre>
18940 (pack "c c c" 65 66 67)  <span class=arw>&rarr;</span> "ABC"
18941 (unpack "c c c" "ABC")   <span class=arw>&rarr;</span> (65 66 67)
18942
18943 (pack "c c c" 0 1 2)             <span class=arw>&rarr;</span> "\000\001\002"
18944 (unpack "c c c" "\000\001\002")  <span class=arw>&rarr;</span> (0 1 2)
18945
18946 (set 's (pack "c d u" 10 12345 56789))
18947 (unpack "c d u" s)  <span class=arw>&rarr;</span> (10 12345 56789)
18948
18949 (set 's (pack "s10 f" "result" 1.23))
18950 (unpack "s10 f" s)
18951 <span class=arw>&rarr;</span> ("result\000\000\000\000" 1.230000019)
18952
18953 (set 's (pack "s3 lf" "result" 1.23))
18954 (unpack "s3 f" s)  <span class=arw>&rarr;</span> ("res" 1.23)
18955
18956 (set 's (pack "c n7 c" 11 22))
18957 (unpack "c n7 c" s)  <span class=arw>&rarr;</span> (11 22))
18958
18959 (unpack "b" (pack "b" -1.0))  <span class=arw>&rarr;</span> (255)
18960 (unpack "f" (pack "f" 123))   <span class=arw>&rarr;</span> (123)
18961 </pre>
18962 </blockquote>
18963
18964 <p>
18965 The last two statements show
18966 how floating point numbers are converted
18967 into integers when required by the format specification.
18968 </p>
18969
18970 <p>The expressions to pack can also be given in a list:</p>
18971
18972 <blockquote>
18973 <pre>
18974 (set 'lst '("A" "B" "C"))
18975 (set 'adr (pack "lululu" lst))
18976 (map get-string (unpack "lululu" adr))    <span class=arw>&rarr;</span> ("A" "B" "C")
18977 </pre>
18978 </blockquote>
18979
18980 <p>Note that the list should be referenced directly in <tt>pack</tt>,
18981 so the pointers passed by <tt>adr</tt> are valid. <tt>adr</tt> would be written
18982 as <tt>char * adr[]</tt> in the C-programming language and represents a 32-bit pointer to an
18983 array of 32-bit string pointers.
18984 </p>
18985
18986 <p>
18987 The <tt>&gt;</tt> and <tt>&lt;</tt> specifiers
18988 can be used to switch between <em>little endian</em>
18989 and <em>big endian</em> byte order
18990 when packing or unpacking:
18991 </p>
18992
18993 <blockquote>
18994 <pre>
18995 (pack "d" 1)   <span class=arw>&rarr;</span> "\001\000"  ;; on little endian CPU
18996 (pack "&gt;d" 1)  <span class=arw>&rarr;</span> "\000\001"  ;; force big endian
18997
18998 (pack "ld" 1)   <span class=arw>&rarr;</span> "\001\000\000\000" ;; on little endian CPU
18999 (pack "&lt;ld" 1)  <span class=arw>&rarr;</span> "\000\000\000\001" ;; force big endian
19000 </pre>
19001 </blockquote>
19002
19003 <p>
19004 Switching the byte order will affect all number formats with 16-,
19005 32-,
19006 or 64-bit sizes.
19007 </p>
19008
19009 <p>
19010 The pack and unpack format need not be the same:
19011 </p>
19012
19013 <blockquote>
19014 <pre>
19015 (set 's (pack "s3" "ABC"))
19016 (unpack "c c c" s)  <span class=arw>&rarr;</span> (65 66 67)
19017 </pre>
19018 </blockquote>
19019
19020 <p>
19021 The examples show spaces between the format specifiers.
19022 These are not required but can be used to improve readability.
19023 </p>
19024
19025 <p>
19026 See also the <a href="#address">address</a>,
19027 <a HREF="#get-int">get-int</a>,
19028 <a HREF="#get-long">get-long</a>
19029 <a HREF="#get-char">get-char</a>,
19030 <a HREF="#get-string">get-string</a>,
19031 and <a HREF="#unpack">unpack</a> functions.
19032 </p>
19033
19034 <br /><br />
19035
19036 <a NAME="parse"></a>
19037
19038 <h2><span class="function">parse</span></h2>
19039 <b>syntax: (parse <em>str-data</em> [<em>str-break</em>  [<em>int-option</em>]])</b>
19040
19041 <p>
19042 Breaks the string that results from evaluating <em>str-data</em> into string tokens,
19043 which are then returned in a list.
19044 When no <em>str-break</em> is given,
19045 <tt>parse</tt> tokenizes according to newLISP's internal parsing rules.
19046 A string may be specified in <em>str-break</em> for tokenizing only at the occurrence of a string.
19047 If an <em>int-option</em> number is specified,
19048 a regular expression pattern may be used in <em>str-break</em>.
19049 </p>
19050
19051 <p>
19052 When <em>str-break</em> is not specified,
19053 the maximum token size is 2048 for quoted strings and 256 for identifiers.
19054 In this case,
19055 newLISP uses the same faster tokenizer it uses for parsing LISP source.
19056 If <em>str-data</em> is specified,
19057 there is no limitation on the length of tokens.
19058 A different algorithm is used that splits the source string <em>str-data</em> at the string in <em>str-break</em>.
19059 </p>
19060
19061 <b>example:</b>
19062 <blockquote>
19063 <pre>
19064 (parse "hello how are you")  <span class=arw>&rarr;</span> ("hello" "how" "are" "you")
19065
19066 (parse "one:two:three" ":")  <span class=arw>&rarr;</span> ("one" "two" "three")
19067
19068 (parse "one--two--three" "--")
19069 <span class=arw>&rarr;</span> ("one" "two" "three")
19070
19071 (parse "one-two--three---four" "-+" 0)
19072 <span class=arw>&rarr;</span> ("one" "two" "three" "four")
19073
19074 (parse "hello regular   expression 1, 2, 3" {,\s*|\s+} 0)
19075 <span class=arw>&rarr;</span> ("hello" "regular" "expression" "1" "2" "3")
19076 </pre>
19077 </blockquote>
19078
19079 <p>
19080 The last two examples show a regular expression
19081 as the break string with the default option <tt>0</tt> (zero).
19082 Instead of <tt>{</tt> and <tt>}</tt> (left and right curly brackets),
19083 quotes can be used to limit the pattern.
19084 In this case,
19085 double backslashes must be used
19086 inside the pattern.
19087 The last pattern could be used
19088 for parsing CVS files.
19089 For the regular expression option numbers,
19090 see <a HREF="#regex">regex</a>.
19091 </p>
19092
19093 <p>
19094 <tt>parse</tt> will return empty fields
19095 around separators
19096 as empty strings:
19097 </p>
19098
19099 <blockquote>
19100 <pre>
19101 (parse "1,2,3," ",") <span class=arw>&rarr;</span> ("1" "2" "3" "")
19102 (parse "1,,,4" ",")  <span class=arw>&rarr;</span> ("1" "" "" "4")
19103 (parse "," ",")      <span class=arw>&rarr;</span> ("" "")
19104
19105 (parse "")      <span class=arw>&rarr;</span> ()
19106 (parse "" " ")  <span class=arw>&rarr;</span> ()
19107 </pre>
19108 </blockquote>
19109
19110 <p>
19111 This behavior is needed
19112 when parsing records
19113 with empty fields.
19114 </p>
19115
19116 <p>
19117 Parsing an empty string
19118 will always result
19119 in an empty list.
19120 </p>
19121
19122 <p>
19123 Use the <a HREF="#regex">regex</a> function
19124 to break strings up
19125 and the <a href="#directory">directory</a>,
19126 <a href="#find">find</a>,
19127 <a href="#find-all">find-all</a>,
19128 <a href="#regex">regex</a>,
19129 <a href="#replace">replace</a>,
19130 and <a href="#search">search</a> functions
19131 for using regular expressions.
19132 </p>
19133
19134 <br /><br />
19135
19136 <a NAME="parse-date"></a>
19137 <h2><span class="function">parse-date</span></h2>
19138 <b>syntax: (parse-date <em>str-date</em> <em>str-format</em>)</b>
19139
19140 <p>Parses a date from a text string in <em>str-date</em>
19141 using a format as defined in <em>str-format</em>, which uses
19142 the same formatting rules found in <a href="#date">date</a>.
19143 The function <tt>parse-date</tt> returns the number of seconds passed
19144 since January 1, 1900.</p>
19145
19146 <p>This function is not available on Win32 platforms.</p>
19147
19148 <b>example:</b>
19149 <blockquote>
19150 <pre>
19151 (parse-date "2007.1.3" "%Y.%m.%d")    <span class=arw>&rarr;</span> 1167782400
19152 (parse-date "January 10, 07" "%B %d, %y")    <span class=arw>&rarr;</span> 1168387200
19153 </pre>
19154 </blockquote>
19155
19156 <p>See the <a href="#date">date</a> function for all possible format descriptors.</p>
19157
19158 <br /><br />
19159
19160 <a NAME="peek"></a>
19161 <h2><span class="function">peek</span></h2>
19162 <b>syntax: (peek <em>int-handle</em>)</b>
19163
19164 <p>
19165 Returns the number of bytes ready to be read on a file descriptor;
19166 otherwise,
19167 it returns <tt>nil</tt> if the file descriptor is invalid.
19168 <tt>peek</tt> can also be used to check <tt>stdin</tt>.
19169 This function is only available on UNIX-like operating systems.
19170 </p>
19171
19172 <b>example:</b>
19173 <blockquote>
19174 <pre>
19175 (peek 0)  ; check # of bytes ready on stdin
19176 </pre>
19177 </blockquote>
19178
19179 <p>
19180 Use the <a href="#net-peek">net-peek</a> function
19181 to check for network sockets,
19182 or for the number of available bytes on them.
19183 On UNIX systems,
19184 <a href="#net-peek">net-peek</a> can be used
19185 to check file descriptors.
19186 The difference is that
19187 <a href="#net-peek">net-peek</a> also sets
19188 <a href="#net-error">net-error</a>.
19189 </p>
19190
19191 <br /><br />
19192
19193 <a NAME="pipe"></a>
19194 <h2><span class="function">pipe</span></h2>
19195 <b>syntax: (pipe)</b>
19196
19197 <p>
19198 Creates an inter-process communications pipe and returns the <tt>read</tt> and <tt>write</tt> handles to it within a list.
19199 </p>
19200
19201 <b>example:</b>
19202 <blockquote>
19203 <pre>
19204 (pipe)  <span class=arw>&rarr;</span> (3 4)  ; 3 for read, 4 for writing
19205 </pre>
19206 </blockquote>
19207
19208 <p>
19209 The pipe handles can be passed to a child process or thread launched via <a href="#process"> process</a> or to <a href="#fork">fork</a> for inter-process communications.
19210 </p>
19211
19212 <p>
19213 Note that the pipe does not block when being written to,
19214 but it does block reading until bytes are available.
19215 A <a href="#read-line">read-line</a> blocks until a newline character is received.
19216 A <a href="#read-buffer"> read-buffer</a> blocks when fewer characters than specified are available from a pipe that has not had the writing end closed by all processes.
19217 </p>
19218
19219 <p>
19220 More than one pipe can be opened if required.
19221 </p>
19222
19223 <p>
19224 newLISP can also use <em>named pipes</em>.
19225 See the <a href="#open">open</a> function for further information.
19226 </p>
19227
19228 <br /><br />
19229
19230 <a NAME="pmt"></a>
19231 <h2><span class="function">pmt</span></h2>
19232
19233 <b>syntax: (pmt <em>num-interest</em> <em>num-periods</em> <em>num-principal</em> [<em>num-future-value</em> <em>int-type</em>])</b>
19234
19235 <p>
19236 Calculates the payment for a loan based on a constant interest of <em>num-interest</em> and constant payments over <em>num-periods</em> of time.
19237 <em>num-future-value</em> is the value of the loan at the end (typically 0.0).
19238 When paying at the end of each period,
19239 <em>num-type</em> is 0 (zero);
19240 otherwise,
19241 it is 1.
19242 If omitted,
19243 <em>int-type</em> is assumed to be 0 (zero) for payment at the end of a period.
19244 </p>
19245
19246 <b>example:</b>
19247 <blockquote>
19248 <pre>
19249 (pmt (div 0.07 12) 240 100000)  <span class=arw>&rarr;</span> -775.2989356
19250 </pre>
19251 </blockquote>
19252
19253 <p>
19254 The above example calculates a payment of $775.30 for a loan of $100,000 at a yearly interest rate of 7 percent.
19255 It is calculated monthly and paid over 20 years (20 * 12 = 240 monthly periods).
19256 This illustrates the typical way payment is calculated for mortgages.
19257 </p>
19258
19259 <p>
19260 See also the <a HREF="#fv">fv</a>,
19261 <a href="#irr">irr</a>,
19262 <a HREF="#nper">nper</a>,
19263 <a HREF="#npv">npv</a>,
19264 and <a HREF="#pv">pv</a> functions.
19265 </p>
19266
19267 <br /><br />
19268
19269 <a NAME="pop"></a>
19270 <h2><span class="function">pop</span></h2>
19271 <b>syntax: (pop <em>list</em> [<em>int-index-1</em> [<em>int-index-2</em> ... ]])</b><br />
19272 <b>syntax: (pop <em>list</em> [<em>list-indexes</em>])</b><br /><br />
19273
19274 <b>syntax: (pop <em>str</em>&nbsp;[<em>int-index</em> [<em>int-length</em>]])</b>
19275
19276 <p>Using <tt>pop</tt> elements can be removed from lists and characters from strings.</p>
19277
19278 <p>
19279 In the first syntax <tt>pop</tt> extracts an element from the list found
19280 by evaluating <em>list</em>.
19281 If a second parameter is present,
19282 the element at <em>int-index</em> is extracted and returned.
19283 See also <a HREF="#indexing">Indexing elements of strings and lists</a>.
19284 </p>
19285
19286 <p>
19287 In the second version,
19288 indices are specified in the list <em>list-indexes</em>.
19289 This way,
19290 <tt>pop</tt> works easily together with <a href="#ref">ref</a>
19291 and <a href="#ref-all">ref-all</a>,
19292 which return lists of indices.
19293 </p>
19294
19295 <p>
19296 <tt>pop</tt> changes the contents of the target list.
19297 The popped element is returned.
19298 </p>
19299
19300 <b>example:</b>
19301 <blockquote>
19302 <pre>
19303 (set 'pList '((f g) a b c "hello" d e 10))
19304
19305 (pop pList)  <span class=arw>&rarr;</span> (f g)
19306 (pop pList)  <span class=arw>&rarr;</span> a
19307 plist        <span class=arw>&rarr;</span> (b c "hello" d e 10)
19308
19309 (pop pList 3)    <span class=arw>&rarr;</span> d
19310 (pop pList 100)  <span class=arw>&rarr;</span> 10
19311 pList            <span class=arw>&rarr;</span> (b c "hello" e)
19312
19313 (pop pList -1)  <span class=arw>&rarr;</span> e
19314 pList           <span class=arw>&rarr;</span> (b c "hello")
19315
19316 (pop pList -2)  <span class=arw>&rarr;</span> c
19317 pList           <span class=arw>&rarr;</span> (b "hello")
19318
19319 (set 'pList '(a 2 (x y (p q) z)))
19320
19321 (pop pList -1 2 0)  <span class=arw>&rarr;</span> p
19322
19323 ;; use indices in a list
19324 (set 'pList '(a b (c d () e)))
19325
19326 (push 'x pList '(2 2 0))  <span class=arw>&rarr;</span> x
19327 pList
19328 <span class=arw>&rarr;</span> (a b (c d (x) e))
19329
19330 (ref 'x pList)  <span class=arw>&rarr;</span> (2 2 0)
19331
19332 (pop pList '(2 2 0))  <span class=arw>&rarr;</span> x
19333 </pre>
19334 </blockquote>
19335
19336 <p><tt>pop</tt> can also be used on strings with one index:</p>
19337
19338 <b>example:</b>
19339 <blockquote>
19340 <pre>
19341 ;; use pop on strings
19342
19343 (set 'str "newLISP")
19344
19345 (pop str -4 4)  <span class=arw>&rarr;</span> "LISP"
19346
19347 str  <span class=arw>&rarr;</span> "new"
19348
19349 (pop str 1)  <span class=arw>&rarr;</span> "e"
19350
19351 str  <span class=arw>&rarr;</span> "nw"
19352
19353 (set 'str "x")
19354
19355 (pop str)  <span class=arw>&rarr;</span> "x"
19356 (pop str)  <span class=arw>&rarr;</span> ""
19357 </pre>
19358 </blockquote>
19359
19360 <p>Popping an empty string will return an empty string.</p>
19361
19362 <p>
19363 See also the <a HREF="#push">push</a> function,
19364 the inverse operation to <tt>pop</tt>,
19365 and the <a href="#set-nth">set-nth</a> and <a href="#nth">nth</a> functions,
19366 which can take multidimensional indices into lists.
19367 </p>
19368
19369 <br /><br />
19370
19371 <a NAME="pop-assoc"></a>
19372 <h2><span class="function">pop-assoc</span></h2>
19373 <b>syntax: (pop (<em>list-alist</em> <em>expr-key-1</em> [<em>expr-key-2</em> ... ])</b>
19374
19375 <p>Removes and association referred to by the key in <em>expr-key</em> from
19376 th association list in <em>list-alist</em>.</p>
19377
19378 <b>example:</b>
19379 <blockquote>
19380 <pre>
19381 (set 'L '((a (b 1) (c (d 2)))))
19382 (pop-assoc (L 'a)) <span class=arw>&rarr;</span> (a (b 1) (c (d 2)))
19383 L <span class=arw>&rarr;</span> '()
19384
19385 (set 'L '((a (b 1) (c (d 2)))))
19386 (pop-assoc (L 'a 'b))  <span class=arw>&rarr;</span> (b 1)
19387 L <span class=arw>&rarr;</span>  '((a (c (d 2))))
19388
19389 (set 'L '((a (b 1) (c (d 2)))))
19390 (pop-assoc (L 'a 'c))  <span class=arw>&rarr;</span> (c (d 2))
19391 L <span class=arw>&rarr;</span> '((a (b 1))))
19392 </pre>
19393 </blockquote>
19394
19395 <p>See also <a href="#assoc">assoc</a> for retrieving associations and <a href="#set-assoc">set-assoc</a>
19396 ans <a href="#assoc-set">assoc-set</a> for changing associations.</p>
19397
19398 <br /><br />
19399
19400 <a NAME="post-url"></a>
19401 <h2><span class="function">post-url</span></h2>
19402 <b>syntax: (post-url <em>str-url</em> <em>str-content</em> [<em>str-content-type</em> [<em>str-option</em>] [<em>int-timeout</em> [ <em>str-header</em>]]])</b>
19403
19404 <p>
19405 Sends an HTTP POST request to the URL in <em>str-url</em>.
19406 POST requests are used to post information collected from web entry forms to a web site.
19407 Most of the time,
19408 the function <tt>post-url</tt> mimics what a web browser would do when sending information collected in an HTML form to a server,
19409 but it can also be used to upload files (see an HTTP reference).
19410 The function returns the page returned from the server in a string.
19411 </p>
19412
19413 <p>
19414 When <tt>post-url</tt> encounters an error,
19415 it returns a string description of the error beginning with <tt>ERR:</tt>.
19416 </p>
19417
19418 <p>
19419 The last parameter,
19420 <em>int-timeout</em>,
19421 is for an optional timeout value,
19422 which is specified in milliseconds.
19423 When no response from the host is received before the timeout has expired,
19424 the string <tt>ERR:
19425 timeout</tt> is returned.
19426 </p>
19427 <b>example:</b>
19428 <blockquote>
19429 <pre>
19430 (post-url "http://somesite.com/form.pl"
19431 "name=johnDoe&amp;city=New%20York"
19432 "application/x-www-form-urlencoded")
19433
19434 (post-url "http://somesite.com/form.pl"
19435 "name=johnDoe&amp;city=New%20York"
19436 "application/x-www-form-urlencoded" 8000)
19437
19438 ;; assumes default content type
19439 (post-url "http://somesite.com/form.pl"
19440 "name=johnDoe&amp;city=New%20York"
19441 </pre>
19442 </blockquote>
19443
19444 <p>
19445 The above example uploads a user name and city using a special format called <tt>application/x-www-form-urlencoded</tt>.
19446 <tt>post-url</tt> can be used to post other content types such as files or binary data.
19447 See an HTTP reference for other content-type specifications and data encoding formats.
19448 When the content-type parameter is omitted,
19449 <tt>post-url</tt> assumes <tt>application/x-www-form-urlencoded</tt> as the default content type.
19450 </p>
19451
19452 <h3>Additional parameters</h3>
19453 <p>
19454 When <em>str-content-type</em> is specified,
19455 the <em>str-option</em> <tt>"header"</tt> or <tt>"list"</tt> can be specified as the return page.
19456 If the <em>int-timeout</em> option is specified,
19457 the custom header option <em>str-header</em> can be specified,
19458 as well.
19459 See the function <a href="#get-url">get-url</a> for details on both of these options.
19460 </p>
19461
19462 <p>
19463 See also the <a HREF="#get-url">get-url</a> and <a HREF="#put-url">put-url</a> functions.
19464 </p>
19465
19466 <br /><br />
19467
19468 <a NAME="pow"></a>
19469 <h2><span class="function">pow</span></h2>
19470 <b>syntax: (pow <em>num-1</em> <em>num-2 </em> [<em>num-3</em> ... ])</b><br>
19471 <b>syntax: (pow <em>num-1</em>)</b>
19472
19473 <p>
19474 Calculates <em>num-1</em> to the power of <em>num-2</em> and so forth.
19475 </p>
19476
19477 <b>example:</b>
19478 <blockquote>
19479 <pre>
19480 (pow 100 2)      <span class=arw>&rarr;</span> 10000
19481 (pow 100 0.5)    <span class=arw>&rarr;</span> 10
19482 (pow 100 0.5 3)  <span class=arw>&rarr;</span> 1000
19483
19484 (pow 3)  <span class=arw>&rarr;</span> 9
19485 </pre>
19486 </blockquote>
19487
19488 <p>
19489 When <em>num-1</em> is the only argument,
19490 <tt>pow</tt> assumes 2 for the exponent.
19491 </p>
19492 <br /><br />
19493
19494 <a NAME="pretty-print"></a>
19495
19496 <h2><span class="function">pretty-print</span></h2>
19497 <b>syntax: (pretty-print [<em>int-length</em> [<em>str-tab</em>]])</b>
19498
19499 <p>
19500 Reformats expressions for <a href="#print">print</a>,
19501 <a href="#save">save</a>,
19502 or <a href="#source">source</a>.
19503 The first parameter,
19504 <em>int-length</em>,
19505 specifies the maximum line length,
19506 and <em>str-tab</em> specifies the string used to indent lines.
19507 All parameters are optional.
19508 <tt>pretty-print</tt> returns the current settings or the new settings when one or both parameters are specified.
19509 </p>
19510
19511 <b>example:</b>
19512 <blockquote>
19513 <pre>
19514 (pretty-print)  <span class=arw>&rarr;</span> (64 " ")  ; default setting
19515
19516 (pretty-print 90 "\t")  <span class=arw>&rarr;</span> (90 "\t")
19517
19518 (pretty-print 100)  <span class=arw>&rarr;</span> (100 "\t")
19519 </pre>
19520 </blockquote>
19521
19522 <p>
19523 The first example reports the default settings of 64 for the maximum line length and a <tt>TAB</tt> character for indenting.
19524 The third example changes the line length only.
19525 </p>
19526
19527 <p>
19528 Note that <tt>pretty-print</tt> cannot be used to prevent line breaks from being printed.
19529 To completely suppress pretty printing,
19530 use the function <a href="#string">string</a> to convert the expression to a raw unformatted string as follows:
19531 </p>
19532
19533 <b>example:</b>
19534 <blockquote>
19535 <pre>
19536 ;; print without formatting
19537
19538 (print (string my-expression))
19539 </pre>
19540 </blockquote>
19541
19542 <br /><br />
19543
19544
19545 <a NAME="primitivep"></a>
19546 <h2><span class="function">primitive?</span></h2>
19547 <b>syntax: (primitive? <em>exp</em>)</b>
19548
19549 <p>
19550 Evaluates and tests if <em>exp</em> is a primitive symbol and returns <tt>true</tt> or <tt>nil</tt> depending on the result.
19551 </p>
19552
19553 <b>example:</b>
19554 <blockquote>
19555 <pre>
19556 (set 'var define)
19557 (primitive? var)  <span class=arw>&rarr;</span> true
19558 </pre>
19559 </blockquote>
19560
19561 <br /><br />
19562
19563 <a NAME="print"></a>
19564 <h2><span class="function">print</span></h2>
19565 <b>syntax: (print <em>exp-1</em> [<em>exp-2</em> ... ])</b>
19566
19567 <p>
19568 Evaluates and prints <em>exp-1</em>&mdash;
19569 to the current I/O device,
19570 which defaults to the console window.
19571 See the built-in function <a HREF="#device">device</a> for details on how to specify a different I/O device.
19572 </p>
19573
19574 <p>
19575 List expressions are indented by the nesting levels of their opening parentheses.
19576 </p>
19577
19578 <p>
19579 Several special characters may be included in strings encoded with the escape character <tt>\</tt>:
19580 </p>
19581 <br />
19582 <blockquote>
19583 <table border="0" cellpadding="1" width="95%" summary="escape characters in print">
19584 <tr align="left" valign="bottom"><th>escaped<br />character</th><th>description</th></tr>
19585
19586 <tr>
19587 <td><tt>\n</tt></td>
19588 <td>the line-feed character (ASCII 10)</td>
19589
19590 </tr>
19591
19592 <tr>
19593 <td><tt>\r</tt></td>
19594 <td>the carriage-return character (ASCII 13)</td>
19595 </tr>
19596
19597 <tr>
19598 <td><tt>\t</tt></td>
19599 <td>the tab character (ASCII 9)</td>
19600 </tr>
19601
19602 <tr>
19603
19604 <td><tt>\nnn</tt></td>
19605 <td>where <em>nnn</em> is a decimal ASCII code between 000 and 255</td>
19606 </tr>
19607
19608 </table>
19609 </blockquote>
19610
19611 <br />
19612
19613 <b>example:</b>
19614 <blockquote>
19615 <pre>
19616 (print (set 'res (+ 1 2 3)))
19617 (print "the result is" res "\n")
19618
19619 "\065\066\067"  <span class=arw>&rarr;</span> "ABC"
19620 </pre>
19621 </blockquote>
19622
19623 <p>
19624         To finish printing with a line feed,
19625         use <a HREF="#println">println</a>.
19626 </p>
19627
19628 <br /><br />
19629
19630 <a NAME="println"></a>
19631 <h2><span class="function">println</span></h2>
19632 <b>syntax: (println <em>exp-1</em> [<em>exp-2</em> ... ])</b>
19633
19634 <p>
19635         Evaluates and prints <em>exp-1</em>&mdash;
19636         to the current I/O device,
19637         which defaults to the console window.
19638         A line feed is printed at the end.
19639         See the built-in function <a HREF="#device">device</a> for details on how to specify a different I/O device.
19640         <tt>println</tt> works exactly like <a HREF="#print">print</a> but emits a line-feed character at the end.
19641 </p>
19642
19643 <p>
19644         See also the <a HREF="#write-line">write-line</a> and <a HREF="#print">print</a> functions.
19645 </p>
19646
19647 <br /><br />
19648
19649 <a NAME="prob-chi2"></a>
19650 <h2><span class="function">prob-chi2</span></h2>
19651 <b>syntax: (prob-chi2 <em>num-chi2</em> <em>num-df</em>)</b>
19652
19653 <p>
19654         Returns the probability Q of an observed Chi&sup2;
19655         statistic in <em>num-chi2</em> with <em>num-df</em> degrees of freedom to be equal to or greater than.
19656         <tt>prob-chi2</tt> is derived from the incomplete Gamma function <a HREF="#gammai">gammai</a>.
19657 </p>
19658
19659 <b>example:</b>
19660 <blockquote>
19661 <pre>
19662 (prob-chi2 10 6)  <span class=arw>&rarr;</span> 0.1246520195
19663 </pre>
19664 </blockquote>
19665
19666 <p>
19667         See also the inverse function <a href="#crit-chi2">crit-chi2</a>.
19668 </p>
19669
19670 <br /><br />
19671
19672 <a NAME="prob-z"></a>
19673 <h2><span class="function">prob-z</span></h2>
19674 <b>syntax: (prob-z <em>num-z</em>)</b>
19675
19676 <p>
19677         Returns the probability of <em>num-z</em>,
19678         not to exceed the observed value where <em>num-z</em> is a normal distributed value with a mean of 0.0 and a standard deviation of 1.0.
19679 </p>
19680
19681 <b>example:</b>
19682 <blockquote>
19683 <pre>
19684 (prob-z 0.0)  <span class=arw>&rarr;</span> 0.5
19685 </pre>
19686 </blockquote>
19687
19688
19689 <p>
19690         See also the inverse function <a href="#crit-z">crit-z</a>.
19691 </p>
19692
19693 <br /><br />
19694
19695 <a NAME="process"></a>
19696 <h2><span class="function">process</span></h2>
19697 <b>syntax: (process <em>str-command</em>)</b><br />
19698 <b>syntax: (process <em>str-command</em> <em>int-pipe-in</em> <em>int-pipe-out</em> [<em>int-win32-option</em>])</b><br />
19699 <b>syntax: (process <em>str-command</em> <em>int-pipe-in</em> <em>int-pipe-out</em> [<em>int-pipe-error</em>])</b>
19700
19701 <p>
19702         In the first syntax,
19703         <tt>process</tt> launches a  process specified in <em>str-command</em> and immediately returns with the
19704     process ID or <tt>nil</tt> if a the process could not be created. On Mac OS X and other UNIX, the application
19705     or script must be specified with its full path-name. The new process inherits the OS envrionment from the
19706     parent process.
19707 </p>
19708
19709 <p> Command line arguments are parsed out at spaces. Arguments containing spaces must be delimited using
19710     single quotes on Mac OS X and other UNIX. On Win32 double quotes are used. The process id returned
19711     can be used to destroy the running process using <a href="#destroy">destroy</a>, if the process does
19712         not exit by itself.
19713 </p>
19714
19715 <b>example:</b>
19716 <blockquote>
19717 <pre>
19718 (process "notepad")  <span class=arw>&rarr;</span> 1894 ; on Win32
19719 </pre>
19720 </blockquote>
19721
19722 <p>
19723         In the second syntax,
19724         standard input and output of the created process can be redirected to pipe handles.
19725         When remapping standard I/O of the launched application to a pipe,
19726         it is possible to communicate with the other application via <a href="#write-line">write-line</a> and <a href="#read-line">read-line</a>  or <a href="#write-buffer">write-buffer</a> and <a href="#read-buffer">read-buffer</a> statements:
19727 </p>
19728
19729 <b>example:</b>
19730 <blockquote>
19731 <pre>
19732 ;; Linux/UNIX
19733 ;; create pipes
19734 (map set '(myin bcout) (pipe))
19735 (map set '(bcin myout) (pipe))
19736
19737 ;; launch UNIX 'bc' calculator application
19738 (process "/usr/bin/bc" bcin bcout) <span class=arw>&rarr;</span> 7916
19739
19740 (write-buffer myout "3 + 4\n")  ; bc expects a linefeed
19741
19742 (read-line myin)  <span class=arw>&rarr;</span> "7"
19743
19744
19745 ;; bc can use bignums with arbitrary precision
19746
19747 (write-buffer myout "123456789012345 * 123456789012345\n")
19748
19749 (read-line myin)  <span class=arw>&rarr;</span> "15241578753238669120562399025"
19750
19751 ;; destroy the process
19752 (destroy 7916)
19753
19754 ;; Win32
19755 (map set '(myin cmdout) (pipe))
19756 (map set '(cmdin myout) (pipe))
19757
19758 (process "cmd" cmdin cmdout)  ; Win32 command shell
19759
19760 (write-line "dir c:\\*.bat" myout)
19761
19762 (read-buffer myin 'buff 2000)
19763
19764 (println buff)  ; directory listing
19765 </pre>
19766 </blockquote>
19767
19768 <p>
19769         On Win32 versions of newLISP,
19770         a fourth optional parameter of <em>int-win32-option</em> can be specified to control the display status of the application.
19771         This option defaults to <tt>1</tt> for showing the application's window,
19772         <tt>0</tt> for hiding it,
19773         and <tt>2</tt> for showing it minimized on the Windows launch bar.
19774 </p>
19775
19776 <p>
19777         On both Win32 and Linux/UNIX systems,
19778         standard error will be redirected to standard out by default.
19779         On Linux/UNIX,
19780         an optional pipe handle for standard error output can be defined.
19781         In this case,
19782         <a href="#peek">peek</a> can be used to check for information on the pipe handles:
19783 </p>
19784
19785 <blockquote>
19786 <pre>
19787 ;; create pipes
19788 (map set '(myin bcout) (pipe))
19789 (map set '(bcin myout) (pipe))
19790 (map set '(errin errout) (pipe))
19791
19792 ;; launch UNIX 'bc' calculator application
19793 (process "bc" bcin bcout errout)
19794
19795 (write-buffer myout command)
19796
19797 ;; wait for bc sending result or error info
19798 (while (and (= (peek myin) 0)
19799             (= (peek errin) 0)) (sleep 10))
19800
19801 (if (&gt; (peek errin) 0)
19802         (println (read-line errin)))
19803
19804 (if (&gt; (peek myin) 0)
19805         (println (read-line myin)))
19806 </pre>
19807 </blockquote>
19808
19809 <p>
19810          Not all interactive console applications can have their standard I/O channels remapped.
19811         Sometimes only one channel,
19812         <em>in</em> or <em>out</em>,
19813         can be remapped.
19814         In this case,
19815         specify <tt>0</tt> (zero) for the unused channel.
19816         The following statement uses only the launched application's output:
19817 </p>
19818
19819 <blockquote>
19820 <pre>
19821 (process "app" 0 myout)
19822 </pre>
19823 </blockquote>
19824
19825 <p>
19826         Normally,
19827         two pipes are used:
19828         one for communications to the child process and the other one for communications from the child process.
19829 </p>
19830
19831 <p>
19832         See also the <a href="#pipe">pipe</a> and <a href="#share">share</a> functions for inter-process communications and the <a href="#semaphore">semaphore</a> function for synchronization of several processes.
19833         See the <a href="#fork">fork</a> function for starting separate newLISP threads on Linux/UNIX.
19834 </p>
19835
19836 <br /><br />
19837
19838 <a NAME="protectedp"></a>
19839 <h2><span class="function">protected?</span></h2>
19840
19841 <b>syntax: (protected? <em>sym</em>)</b>
19842
19843 <p>Checks checks if a symbol in <em>sym</em> is protected. Protected symbols are built-in
19844 functions, context symbols and all symbols made constant using the <a href="#constant">constant</a>
19845 function:</p>
19846
19847 <blockquote>
19848 <pre>
19849 (protected? 'println)    <span class=arw>&rarr;</span> true
19850 (constant 'aVar 123)
19851 (protected? 'aVar)       <span class=arw>&rarr;</span> true
19852 </pre>
19853 </blockquote>
19854
19855 <br /><br />
19856
19857 <a NAME="push"></a>
19858 <h2><span class="function">push</span></h2>
19859 <b>syntax: (push <em>exp</em>i <em>list</em> [<em>int-index-1</em> [<em>int-index-2 ...</em>]])</b><br />
19860 <b>syntax: (push <em>exp</em> <em>list</em> [<em>list-indexes</em>])</b><br /><br />
19861
19862 <b>syntax: (push <em>str-1</em> <em>str-2</em> [<em>int-index</em>])</b>
19863
19864 <p>
19865         Inserts the value of <em>exp</em> into the list <em>list</em>.
19866         If <em>int-index</em> is present,
19867         the element is inserted at that index.
19868         If the index is absent,
19869         the element is inserted at index 0 (zero),
19870         the first element.
19871         <tt>push</tt> is a destructive operation that changes the contents of the target list.
19872         The element inserted is returned.
19873         See also <a HREF="#indexing">Indexing elements of strings and lists</a>.
19874 </p>
19875
19876 <p>
19877         If more than one <em>int-index</em> is present,
19878         the indices are used to access a nested list structure.
19879         Improper indices (those not matching list elements) are discarded.
19880 </p>
19881
19882 <p>
19883         The second version takes a list of <em>list-indexes</em> but is otherwise identical to the first.
19884         In this way,
19885         <tt>push</tt> works easily together with <a href="#ref">ref</a>
19886         and <a href="#ref-all">ref-all</a>,
19887         which return lists of indices.
19888 </p>
19889
19890 <p>
19891         If <em>list</em> does not contain a list,
19892         <em>list</em> must contain a <tt>nil</tt> and will be initialized to the empty list.
19893 </p>
19894
19895 <p>
19896         Repeatedly using <tt>push</tt> to the end of a list
19897         using <tt>-1</tt> as the <em>int-index</em>
19898         is optimized and as fast as pushing
19899         to the front of a list
19900         with no index at all.
19901         This can be used to efficiently grow a list.
19902 </p>
19903
19904 <b>example:</b>
19905 <blockquote>
19906 <pre>
19907 ; inserting in front
19908 (set 'pList '(b c))  <span class=arw>&rarr;</span> (b c)
19909 (push 'a pList)      <span class=arw>&rarr;</span> a
19910 pList                <span class=arw>&rarr;</span> (a b c)
19911
19912 ; insert at index
19913 (push "hello" pList 2)  <span class=arw>&rarr;</span> "hello"
19914 pList                   <span class=arw>&rarr;</span> (a b "hello" c)
19915
19916 ; optimized appending at the end
19917 (push 'z pList -1)  <span class=arw>&rarr;</span> z
19918 pList               <span class=arw>&rarr;</span> (a b "hello" c z)
19919
19920 ; inserting lists in lists
19921 (push '(f g) pList)  <span class=arw>&rarr;</span> (f g)
19922 pList                <span class=arw>&rarr;</span> ((f g) a b "hello" c z)
19923
19924 ; inserting at negative index
19925 (push 'x pList -3)  <span class=arw>&rarr;</span> x
19926 pList               <span class=arw>&rarr;</span> ((f g) a b "hello" x c z)
19927
19928 ; using multiple indices
19929 (push 'h pList 0 -1)  <span class=arw>&rarr;</span> h
19930 pList                 <span class=arw>&rarr;</span> ((f g h) a b "hello" x c z)
19931
19932 ; use indices in a list
19933 (set 'pList '(a b (c d () e)))
19934
19935 (push 'x pList '(2 2 0))  <span class=arw>&rarr;</span> x
19936 pList                     <span class=arw>&rarr;</span> (a b (c d (x) e))
19937
19938 (ref 'x pList)  <span class=arw>&rarr;</span> (2 2 0)
19939
19940 (pop pList '(2 2 0))  <span class=arw>&rarr;</span> x
19941
19942 ;; push on strings
19943
19944 (set 'str "abcdefg")
19945
19946 (push "hijk" str -1)  <span class=arw>&rarr;</span> "hijk"
19947 str                   <span class=arw>&rarr;</span> "abcdefghijk"
19948
19949 (push "123" str)  <span class=arw>&rarr;</span> "123"
19950 str               <span class=arw>&rarr;</span> "123abcdefghijk"
19951
19952 (push "4" str 3)  <span class=arw>&rarr;</span> "4"
19953 str               <span class=arw>&rarr;</span> "1234abcdefghijk"
19954
19955 ; push on uninitialized symbol
19956 aVar  <span class=arw>&rarr;</span> nil
19957
19958 (push 999 aVar)  <span class=arw>&rarr;</span> 999
19959
19960 aVar  <span class=arw>&rarr;</span> (999)
19961 </pre>
19962 </blockquote>
19963
19964 <p>
19965         See also the <a HREF="#pop">pop</a> function,
19966         which is the inverse operation to <tt>push</tt>,
19967         and the <a href="#set-nth">set-nth</a>,
19968         <a href="#nth-set">nth-set</a>,
19969         and <a href="#nth">nth</a> functions,
19970         which can all take multidimensional indices into lists.
19971 </p>
19972
19973 <br /><br />
19974
19975 <a NAME="put-url"></a>
19976 <h2><span class="function">put-url</span></h2>
19977 <b>syntax: (put-url <em>str-url</em> <em>str-content</em> [<em>str-option</em>] [<em>int-timeout</em> [<em>str-header</em>]])</b>
19978
19979 <p>
19980         The HTTP PUT protocol is used to transfer information in <em>str-content</em> to a file specified in <em>str-url</em>.
19981         The lesser-known HTTP PUT mode is frequently used for transferring web pages from HTML editors to Web servers.
19982         In order to use PUT mode,
19983         the web server's software must be configured correctly.
19984         On the Apache web server,
19985         use the <tt>'Script PUT'</tt> directive in the section where directory access rights are configured.
19986 </p>
19987
19988 <p>
19989         Optionally,
19990         an <em>int-timeout</em> value can be specified in milliseconds as the last parameter.
19991         <tt>put-url</tt> will return <tt>ERR:
19992         timeout</tt> when the host gives no response and the timeout expires.
19993         On other error conditions,
19994         <tt>put-url</tt> returns a string starting with <tt>ERR:</tt> and the description of the error.
19995 </p>
19996
19997 <p>
19998         <tt>put-url</tt> requests are also understood by newLISP server nodes.
19999 </p>
20000
20001 <b>example:</b>
20002 <blockquote>
20003 <pre>
20004 (put-url "http://asite.com/myFile.txt" "Hi there")
20005 (put-url "http://asite.com/myFile.txt" "Hi there" 2000)
20006
20007 (put-url "http://asite.com/webpage.html"
20008     (read-file "webpage.html"))
20009 </pre>
20010 </blockquote>
20011
20012 <p>
20013         The first example creates a file called <tt>myFile.txt</tt> on the target server and stores the text string <tt>'Hi there'</tt> in it.
20014         In the second example,
20015         the local file <tt>webpage.html</tt> is transferred to <tt>asite.com</tt>.
20016 </p>
20017
20018 <p>
20019         On an Apache web server,
20020         the following could be configured in <tt>httpd.conf</tt>.
20021 </p>
20022
20023 <b>example:</b>
20024 <blockquote>
20025 <pre>
20026 &lt;directory /www/htdocs&gt;
20027 Options All
20028 Script PUT /cgi-bin/put.cgi
20029 &lt;/directory&gt;
20030 </pre>
20031 </blockquote>
20032
20033 <p>
20034          The script <tt>put.cgi</tt> would contain code to receive content from the web server via STDIN.
20035         The following is a working <tt>put.cgi</tt> written in newLISP for the Apache web server:
20036 </p>
20037
20038 <b>example:</b>
20039 <pre>
20040 #!/usr/home/johndoe/bin/newlisp
20041 #
20042 #
20043 # get PUT method data from CGI STDIN
20044 # and write data to a file specified
20045 # int the PUT request
20046 #
20047 #
20048
20049
20050 (print "Content-type: text/html\n\n")
20051
20052 (set 'cnt 0)
20053 (set 'result "")
20054
20055 (if (= "PUT" (env "REQUEST_METHOD"))
20056     (begin
20057       (set 'len (integer (env "CONTENT_LENGTH")))
20058
20059       (while (&lt; cnt len)
20060           (set 'n (read-buffer (device) 'buffer len))
20061           (if (not n)
20062             (set 'cnt len)
20063             (begin
20064               (inc 'cnt n)
20065               (write-buffer result buffer))))
20066
20067       (set 'path (append
20068               "/usr/home/johndoe"
20069               (env "PATH_TRANSLATED")))
20070
20071       (write-file path result)
20072     )
20073 )
20074
20075 (exit)
20076 </pre>
20077
20078
20079 <p>
20080         Note that the script appends ".txt" to the path to avoid the CGI execution of uploaded malicious scripts.
20081         Note also that the two lines where the file path is composed may work differently in your web server environment.
20082         Check environment variables passed by your web server for composition of the right file path.
20083 </p>
20084
20085 <p>
20086         <tt>put-url</tt> returns content returned by the <tt>put.cgi</tt> script.
20087 </p>
20088
20089 <h3>Additional parameters</h3>
20090 <p>
20091         In <em>str-option</em>,
20092         <tt>"header"</tt> or <tt>"list"</tt> can be specified for the returned page.
20093         If the <em>int-timeout</em> option is specified,
20094         the custom header option <em>str-header</em> can be specified,
20095         as well.
20096         See the function <a href="#get-url">get-url</a> for details on both of these options.
20097 </p>
20098
20099 <p>
20100         See also the functions <a HREF="#get-url">get-url</a> and <a HREF="#post-url">post-url</a>,
20101         which can be used to upload files when formatting form data as <tt>multipart/form-data</tt>.
20102 </p>
20103
20104 <br /><br />
20105
20106
20107 <a NAME="pv"></a>
20108 <h2><span class="function">pv</span></h2>
20109 <b>syntax: (pv <em>num-int</em> <em>num-nper</em> <em>num-pmt</em> [<em>num-fv int-type</em>])</b>
20110
20111 <p>
20112         Calculates the present value of a loan with the constant interest rate <em>num-interest</em> and the constant payment <em>num-pmt</em> after <em>num-nper</em> number of payments.
20113         The future value <em>num-pmt</em> is assumed to be 0.0 if omitted.
20114         If payment is at the end of each period,
20115         0 (zero) is assumed for <em>int-type</em>;
20116         otherwise 1 is assumed.
20117 </p>
20118
20119 <b>example:</b>
20120 <blockquote>
20121 <pre>
20122 (pv (div 0.07 12) 240 775.30)  <span class=arw>&rarr;</span> -100000.1373
20123 </pre>
20124 </blockquote>
20125 <p>
20126         In the example,
20127         a loan that would be paid off (future value = 0.0) in 240 payments of $775.30 at a constant interest rate of 7 percent per year would start out at $100,000.14.
20128 </p>
20129
20130 <p>
20131         See also the <a HREF="#fv">fv</a>,
20132         <a href="#irr">irr</a>,
20133         <a HREF="#nper">nper</a>,
20134         <a HREF="#npv">npv</a>,
20135         and <a HREF="#pmt">pmt</a> functions.
20136 </p>
20137
20138 <br /><br />
20139
20140
20141 <a NAME="quote"></a>
20142 <h2><span class="function">quote</span></h2>
20143 <b>syntax: (quote <em>exp</em>)</b>
20144
20145 <p>
20146         Returns <em>exp</em> without evaluating it.
20147         The same effect can be obtained by prepending a <tt>'</tt> (single quote) to <em>exp</em>.
20148 </p>
20149
20150 <b>example:</b>
20151 <blockquote>
20152 <pre>
20153 (quote x)         <span class=arw>&rarr;</span> x
20154 (quote 123)       <span class=arw>&rarr;</span> 123
20155 (quote (a b c))   <span class=arw>&rarr;</span> (a b c)
20156 (= (quote x) 'x)  <span class=arw>&rarr;</span> true
20157 </pre>
20158 </blockquote>
20159 <br /><br />
20160
20161 <a NAME="quotep"></a>
20162 <h2><span class="function">quote?</span></h2>
20163 <b>syntax: (quote? <em>exp</em>)</b>
20164
20165 <p>
20166          Evaluates and tests whether <em>exp</em> is quoted.
20167         Returns <tt>true</tt> or <tt>nil</tt> depending on the result.
20168 </p>
20169
20170 <b>example:</b>
20171 <blockquote>
20172 <pre>
20173 (set 'var ''x)  <span class=arw>&rarr;</span> 'x
20174 (quote? var)    <span class=arw>&rarr;</span> true
20175 </pre>
20176 </blockquote>
20177 <p>
20178          Note that in the <tt>set</tt> statement,
20179         <tt> ''x</tt> is quoted twice because the first quote is lost during the evaluation of the <tt>set</tt> assignment.
20180 </p>
20181
20182 <br /><br />
20183
20184 <a NAME="rand"></a>
20185 <h2><span class="function">rand</span></h2>
20186 <b>syntax: (rand <em>int-range</em> [<em>int-N</em>])</b>
20187
20188 <p>
20189         Evaluates the expression in <em>int-range</em>
20190         and generates a random number in the range of
20191         0 (zero) to (<em>int-range</em> - 1).
20192         When <tt>0</tt> (zero) is passed,
20193         the internal random generator
20194         is initialized using
20195         the current value returned by
20196         the C <tt>time()</tt> function.
20197         Optionally, a second parameter
20198         can be specified to return
20199         a list of length <em>int-N</em>
20200         of random numbers.
20201 </p>
20202
20203 <b>example:</b>
20204 <blockquote>
20205 <pre>
20206 (dotimes (x 100) (print (rand 2))) =&gt;
20207 11100000110100111100111101 ... 10111101011101111101001100001000
20208
20209 (rand 3 100)  <span class=arw>&rarr;</span> (2 0 1 1 2 0 &hellip;)
20210 </pre>
20211 </blockquote>
20212
20213 <p>
20214         The first line in the example
20215         prints equally distributed <tt>0</tt>'s and <tt>1</tt>'s,
20216         while the second line produces a list
20217         of 100 integers with
20218         <tt>0</tt>, <tt>1</tt>, and <tt>2</tt> equally distributed.
20219         Use the <a HREF="#random">random</a>
20220         and <a HREF="#normal">normal</a> functions
20221         to generate floating point
20222         random numbers,
20223         and use <a href="#seed">seed</a> to vary
20224         the initial seed
20225         for random number generation.
20226 </p>
20227
20228 <br /><br />
20229
20230 <a NAME="random"></a>
20231 <h2><span class="function">random</span></h2>
20232 <b>syntax: (random <em>float-offset</em> <em>float-scale</em> <em>int-n</em>)</b><br />
20233 <b>syntax: (random <em>float-offset</em> <em>float-scale</em>)</b>
20234
20235 <p>
20236         In the first form,
20237         <tt>random</tt> returns a list of <em>int-n</em>
20238         evenly distributed floating point numbers
20239         scaled (multiplied) by <em>float-scale</em>,
20240         with an added offset of <em>float-offset</em>.
20241         The starting point of the internal random generator
20242         can be seeded using <a HREF="#seed">seed</a>.
20243 </p>
20244
20245 <b>example:</b>
20246 <blockquote>
20247 <pre>
20248 (random 0 1 10)
20249 <span class=arw>&rarr;</span> (0.10898973 0.69823783 0.56434872 0.041507289 0.16516733
20250     0.81540917 0.68553784 0.76471068 0.82314585 0.95924564)
20251 </pre>
20252 </blockquote>
20253
20254 <p>
20255         When used in the second form,
20256         <tt>random</tt> returns a single
20257         evenly distributed number:
20258 </p>
20259
20260 <blockquote>
20261 <pre>
20262 (random 10 5)  <span class=arw>&rarr;</span> 11.0971
20263 </pre>
20264 </blockquote>
20265
20266 <p>
20267         See also the <a HREF="#normal">normal</a>
20268         and <a HREF="#rand">rand</a> functions.
20269 </p>
20270 <br /><br />
20271
20272 <a NAME="randomize"></a>
20273 <h2><span class="function">randomize</span></h2>
20274 <b>syntax: (randomize <em>list</em> [<em>bool</em>])</b>
20275
20276 <p>
20277         Rearranges the order of elements in <em>list</em>
20278         into a random order.
20279 </p>
20280
20281 <b>example:</b>
20282 <blockquote>
20283 <pre>
20284 (randomize '(a b c d e f g))  <span class=arw>&rarr;</span> (b a c g d e f)
20285 (randomize (sequence 1 5))    <span class=arw>&rarr;</span> (3 5 4 1 2)
20286 </pre>
20287 </blockquote>
20288
20289 <p>
20290         <tt>randomize</tt> will always return
20291         a sequence different from the previous one
20292         without the optional <em>bool</em> flag.
20293         This may require the function to calculate
20294         several sets of reordered elements,
20295         which in turn may lead to different processing times
20296         with different invocations of the function
20297         on the same input list length.
20298         To allow for the output to be equal
20299         to the input, <tt>true</tt>
20300         or any expression evaluating to
20301         not <tt>nil</tt>
20302         must be specified in <em>bool</em>.
20303 </p>
20304
20305 <p>
20306         <tt>randomize</tt> uses
20307         an internal <em>pseudo random sequence</em> generator
20308         that returns the same series of results
20309         each time newLISP is started.
20310         Use the <a href="#seed">seed</a> function to
20311         change this sequence.
20312 </p>
20313
20314 <br /><br />
20315
20316
20317 <a NAME="read-buffer"></a>
20318 <h2><span class="function">read-buffer</span></h2>
20319
20320 <b>syntax: (read-buffer <em>int-file</em> <em>sym-buffer</em> <em>int-size</em> [<em>str-wait</em>])</b>
20321
20322 <p>
20323         Reads a maximum of <em>int-size</em> bytes
20324         from a file specified in <em>int-file</em>
20325         into a buffer in <em>sym-buffer</em>.
20326         Any data referenced by the symbol <em>sym-buffer</em>
20327         prior to the reading is deleted.
20328         The handle in <em>int-file</em>
20329         is obtained from a previous <a HREF="#open">open</a> statement.
20330         The symbol <em>sym-buffer</em> contains data
20331         of type string after the read operation.
20332 </p>
20333
20334 <p>
20335         Optionally,
20336         a string to be waited for
20337         can be specified in <em>str-wait</em>.
20338         <tt>read-buffer</tt> will read
20339         a maximum amount of bytes
20340         specified in <em>int-size</em>
20341         or return earlier
20342         if <em>str-wait</em> was found
20343         in the data.
20344         The wait-string is part
20345         of the returned data and must
20346     not contain binary <tt>0</tt> (zero)
20347     characters.
20348 </p>
20349
20350 <p>
20351         Returns the number of bytes read or <tt>nil</tt>
20352         when the wait-string was not found.
20353         In any case,
20354         the bytes read are put into the buffer
20355         pointed to by <em>sym-buffer</em>,
20356         and the file pointer of the file read
20357         is moved forward.
20358         If no new bytes have been read,
20359         <em>sym-buffer</em> will contain <tt>nil</tt>.
20360 </p>
20361
20362 <b>example:</b>
20363 <blockquote>
20364 <pre>
20365 (set 'handle (open "aFile.ext" "read"))
20366 (read-buffer handle 'buff 200)
20367 </pre>
20368 </blockquote>
20369
20370 <p>
20371         Reads 200 bytes into the symbol <tt>buff</tt>
20372         from the file <tt>aFile.ext</tt>.
20373 </p>
20374
20375 <blockquote>
20376 <pre>
20377 (read-buffer handle 'buff 1000 "password:")
20378 </pre>
20379 </blockquote>
20380
20381 <p>
20382         Reads 1000 bytes or until
20383         the string <tt>password:</tt> is encountered.
20384         The string <tt>password:</tt>
20385         will be part of the data returned.
20386 </p>
20387
20388 <p>
20389         See also the <a HREF="#write-buffer">write-buffer</a> function.
20390 </p>
20391
20392 <br /><br />
20393
20394 <a NAME="read-char"></a>
20395 <h2><span class="function">read-char</span></h2>
20396
20397 <b>syntax: (read-char <em>int-file</em>)</b>
20398
20399 <p>
20400         Reads a byte from a file specified
20401         by the file handle in <em>int-file</em>.
20402         The file handle is obtained from
20403         a previous <a HREF="#open">open</a> operation.
20404         Each <tt>read-char</tt> advances
20405         the file pointer by one byte.
20406         Once the end of the file is reached,
20407         <tt>nil</tt> is returned.
20408 </p>
20409
20410 <b>example:</b>
20411 <blockquote>
20412 <pre>
20413 (define (slow-file-copy from-file to-file)
20414 (set 'in-file (open from-file "read"))
20415 (set 'out-file (open to-file "write"))
20416 (while (set 'chr (read-char in-file))
20417     (write-char out-file chr))
20418     (close in-file)
20419     (close out-file)
20420     "finished")
20421 </pre>
20422 </blockquote>
20423
20424 <p>
20425         Use <a HREF="#read-line">read-line</a>
20426         and <a HREF="#device">device</a> to read
20427         whole text lines at a time.
20428         Note that newLISP supplies
20429         a fast built-in function
20430         called <a HREF="#copy-file">copy-file</a>
20431         for copying files.
20432 </p>
20433
20434 <p>
20435         See also the <a HREF="#write-char">write-char</a> function.
20436 </p>
20437
20438 <br /><br />
20439
20440 <a NAME="read-file"></a>
20441 <h2><span class="function">read-file</span></h2>
20442 <b>syntax: (read-file <em>str-file-name</em>)</b>
20443
20444 <p>
20445         Reads a file in <em>str-file-name</em>
20446         in one swoop and returns a string buffer
20447         containing the data.
20448 </p>
20449
20450 <b>example:</b>
20451 <blockquote>
20452 <pre>
20453 (write-file "myfile.enc"
20454     (encrypt (read-file "/home/lisp/myFile") "secret"))
20455 </pre>
20456 </blockquote>
20457
20458 <p>
20459         The file <tt>myfile</tt> is read,
20460         then encrypted using the password <tt>"secret"</tt>
20461         before being written back into a new file titled <tt>"myfile.enc"</tt>
20462         in the current directory.
20463 </p>
20464
20465 <p>
20466         <tt>read-file</tt> can take an <tt>http://</tt>
20467         or <tt>file://</tt> URL in <em>str-file-name</em>.
20468         In this case, <tt>read-file</tt> works exactly like
20469         <a href="#get-url">get-url</a> and can take
20470         the same additional parameters.
20471 </p>
20472
20473 <b>example:</b>
20474 <blockquote>
20475 <pre>
20476 (read-file "http://asite.com/somefile.tgz" 10000)
20477 </pre>
20478 </blockquote>
20479
20480 <p>
20481         The file <tt>somefile.tgz</tt> is retrieved from
20482         the remote location <tt>http://asite.com</tt>.
20483         The file transfer will time out after 10 seconds
20484         if it is not finished.
20485         In this mode, <tt>read-file</tt> can also be used
20486         to transfer files from remote newLISP server nodes.</p>
20487
20488 <p>See also the <a HREF="#write-file">write-file</a> and
20489 <a HREF="#append-file">append-file</a> functions.
20490 </p>
20491
20492 <br /><br />
20493
20494 <a NAME="read-key"></a>
20495 <h2><span class="function">read-key</span></h2>
20496 <b>syntax: (read-key)</b>
20497
20498 <p>
20499         Reads a key from the keyboard
20500         and returns an integer value.
20501         For navigation keys,
20502         more than one <tt>read-key</tt> call
20503         must be made.
20504         For keys representing ASCII characters,
20505         the return value is the same
20506         on all OSes, except for navigation keys
20507         and other control sequences like function keys,
20508         in which case the return values may vary
20509         on different OSes and configurations.
20510 </p>
20511
20512
20513 <b>example:</b>
20514 <blockquote>
20515 <pre>
20516 (read-key)  <span class=arw>&rarr;</span> 97  ; after hitting the A key
20517 (read-key)  <span class=arw>&rarr;</span> 65  ; after hitting the shifted A key
20518 (read-key)  <span class=arw>&rarr;</span> 10  ; after hitting [enter] on Linux
20519 (read-key)  <span class=arw>&rarr;</span> 13  ; after hitting [enter] on Win32
20520
20521 (while (!= (set 'c (read-key)) 1) (println c))
20522 </pre>
20523 </blockquote>
20524
20525 <p>
20526         The last example can be used
20527         to check return sequences
20528         from navigation and function keys.
20529         To break out of the loop,
20530         press <tt>Ctrl-A</tt>.
20531 </p>
20532
20533 <p>
20534         Note that <tt>read-key</tt> will not work
20535         from the newLISP-GS front-end
20536         or any other application running
20537         newLISP over a TCP/IP port connection.
20538 </p>
20539
20540 <br /><br />
20541
20542 <a NAME="read-line"></a>
20543
20544 <h2><span class="function">read-line</span></h2>
20545 <b>syntax: (read-line [<em>int-file</em>])</b>
20546
20547 <p>
20548         Reads from the current I/O device a string
20549         delimited by a line-feed character (ASCII 10).
20550         There is no limit
20551         to the length of the string
20552         that can be read.
20553         The line-feed character is not part of the returned string.
20554         The line always breaks on a line feed,
20555         which is then swallowed.
20556         A line breaks on a carriage return (ASCII 13)
20557         only if followed by a line feed,
20558         in which case both characters are discarded.
20559         A carriage return alone only breaks and is swallowed
20560         if it is the last character in the stream.
20561 </p>
20562
20563 <p>
20564         By default,
20565         the current <a HREF="#device">device</a>
20566         is the keyboard (<a HREF="#device">device</a> 0).
20567         Use the built-in function <a HREF="#device">device</a>
20568         to specify a different I/O device (e.g., a file).
20569         Optionally,
20570         a file handle can be specified
20571         in the <em>int-file</em> obtained
20572         from a previous <a HREF="#open">open</a> statement.
20573 </p>
20574
20575 <p>
20576         The last buffer contents
20577         from a read-line operation
20578         can be retrieved using <a HREF="#current-line">current-line</a>.
20579 </p>
20580
20581 <b>example:</b>
20582 <blockquote>
20583 <pre>
20584 (print "Enter a num:")
20585 (set 'num (integer (read-line)))
20586
20587 (set 'in-file (open "afile.dat" "read"))
20588 (while (read-line in-file)
20589         (write-line))
20590 (close in-file)
20591 </pre>
20592 </blockquote>
20593
20594 <p>
20595         The first example reads input from the keyboard
20596         and converts it to a number.
20597         In the second example,
20598         a file is read line by line
20599         and displayed on the screen.
20600         The <tt>write-line</tt> statement
20601         takes advantage of the fact
20602         that the result from the last
20603         <tt>read-line</tt> operation
20604         is stored in a system internal buffer.
20605         When <a HREF="#write-line">write-line</a>
20606         is used without argument,
20607         it writes the contents
20608         of the last <tt>read-line</tt> buffer
20609         to the screen.
20610 </p>
20611
20612 <p>
20613         See also the <a HREF="#current-line">current-line</a> function
20614         for retrieving this buffer.
20615 </p>
20616
20617 <br /><br />
20618 <a NAME="real-path"></a>
20619 <h2><span class="function">real-path</span></h2>
20620 <b>syntax: (real-path [<em>str-path</em>])</b>
20621
20622 <p>
20623         Returns the full path
20624         from the relative file path
20625         given in <em>str-path</em>.
20626         If a path is not given,
20627         <tt>"."</tt> (the current directory) is assumed.
20628 </p>
20629
20630 <b>example:</b>
20631 <blockquote>
20632 <pre>
20633 (real-path)  <span class=arw>&rarr;</span> "/usr/home/fred"  ; current directory
20634 (real-path "./somefile.txt")
20635 <span class=arw>&rarr;</span> "/usr/home/fred/somefile.txt"
20636 </pre>
20637 </blockquote>
20638
20639 <p>
20640         The output length is limited
20641         by the OS's maximum allowed path length.
20642         If <tt>real-path</tt> fails
20643         (e.g., because of a nonexistent path),
20644         <tt>nil</tt> is returned.
20645 </p>
20646
20647
20648
20649 <br /><br />
20650
20651 <a NAME="ref"></a>
20652 <h2><span class="function">ref</span></h2>
20653 <b>syntax: (ref <em>exp-key</em> <em>list</em> [<em>func-compare</em>])</b>
20654 <b>syntax: (ref (<em>list</em> <em>exp-key</em>) [<em>func-compare</em>])</b>
20655
20656 <p>
20657         <tt>ref</tt> searches for the key expression <em>exp-key</em>
20658         in <em>list</em> and returns a list of integer indices
20659         or an empty list if <em>exp-key</em> cannot be found.
20660         <tt>ref</tt> can work together with <a href="#push">push</a>
20661         and <a href="pop">pop</a>,
20662         both of which can also take lists of indices.
20663 </p>
20664
20665 </p>
20666 The optional <em>func-compare</em>
20667 contains a comparison operator
20668 or function. In this case the system variable <tt>$0</tt> contains
20669 the last expression found.</p>
20670
20671 <b>example:</b>
20672 <blockquote>
20673 <pre>
20674 (set 'pList '(a b (c d () e)))
20675
20676 (push 'x pList '(2 2 0))  <span class=arw>&rarr;</span> x
20677
20678 pList  <span class=arw>&rarr;</span> (a b (c d (x) e))
20679
20680 (ref 'x pList)    <span class=arw>&rarr;</span> (2 2 0)
20681
20682 ; or form suitable for context default functors
20683 (ref (pList 'x)    <span class=arw>&rarr;</span> (2 2 0)
20684
20685 (ref '(x) pList)  <span class=arw>&rarr;</span> (2 2)
20686
20687 (set 'v (ref '(x) pList)) <span class=arw>&rarr;</span> (2 2)
20688
20689 (pList v) <span class=arw>&rarr;</span> (x)
20690
20691 (ref '(c d (x) e) pList)  <span class=arw>&rarr;</span> (2)
20692
20693 (ref 'foo pList)  <span class=arw>&rarr;</span> ()
20694
20695 (pop pList '(2 2 0))  <span class=arw>&rarr;</span> x
20696
20697 ; with optional comparison function
20698
20699 (ref 'e '(a b (c d (e) f)))    <span class=arw>&rarr;</span> (2 2 0)
20700
20701 (ref 'e '(a b (c d (e) f)) =)  <span class=arw>&rarr;</span> (2 2 0)
20702 $0 <span class=arw>&rarr;</span> e
20703
20704 (ref 'e '(a b (c d (e) f)) &gt;)  <span class=arw>&rarr;</span> (0)
20705 $0 <span class=arw>&rarr;</span> a
20706
20707 (ref 'e '(a b (c d (e) f)) (fn (x y) (or (= x y) (= y 'd)))) <span class=arw>&rarr;</span> (2 1)
20708 $0 <span class=arw>&rarr;</span> d
20709
20710 ; define the comparison function first
20711 (define (is-it-or-d x y) (or (= x y) (= y 'd)))
20712
20713 (ref 'e '(a b (c d (e) f)) is-it-or-d)  <span class=arw>&rarr;</span> (2 1)
20714 $0 <span class=arw>&rarr;</span> d
20715 </pre>
20716 </blockquote>
20717
20718 <p>
20719 The following example shows the use of
20720 <a href="#match">match</a> and <a href="#unify">unify</a>
20721 to formulate searches that are as powerful as regular expressions are
20722 for strings:
20723 </p>
20724
20725 <blockquote>
20726 <pre>
20727 (ref '(a ?) '((l 3) (a 12) (k 5) (a 10) (z 22)) match) <span class=arw>&rarr;</span> (1)
20728 $0 <span class=arw>&rarr;</span> (a 12)
20729
20730 (ref '(X X) '( ((a b) (c d)) ((e e) (f g)) ) unify) <span class=arw>&rarr;</span> (1 0)
20731 $0 <span class=arw>&rarr;</span> (e e)
20732
20733 (ref '(X g) '( ((a b) (c d)) ((e e) (f g)) ) unify) <span class=arw>&rarr;</span> (1 1)
20734 $0 <span class=arw>&rarr;</span> (f g)
20735 </pre>
20736 </blockquote>
20737
20738 <p>
20739 The first line searches for a list pair
20740 where the two elements are equal.
20741 The second searches for a list pair
20742 with the symbol <tt>g</tt> as the second member.
20743 </p>
20744
20745 <p>When using the second syntax, the list can be passed by a context
20746 identifying a default functor:</p>
20747
20748 <blockquote>
20749 <pre>
20750 (set 'L:L '(a b (c d) e f))
20751
20752 (ref (L 'd))  <span class=arw>&rarr;</span> (2 1)
20753 </pre>
20754 </blockquote>
20755
20756 <p>This is suitable when passing lists by reference using a context.</p>
20757 <p>
20758 See also the <a href="#ref-all">ref-all</a> function.
20759 </p>
20760
20761 <br /><br />
20762
20763 <a NAME="ref-all"></a>
20764 <h2><span class="function">ref-all</span></h2>
20765 <b>syntax: (ref-all <em>exp list</em> [<em>func-compare</em>])</b>
20766
20767 <p>
20768         Works similarly to <a href="#ref">ref</a>,
20769         but returns a list of all index vectors found
20770         for <em>exp</em> in <em>list</em>.
20771 </p>
20772
20773 <p>
20774 By default, <tt>ref-all</tt> checks if expressions are equal.
20775 With <em>func-compare</em>, more complex comparison functions
20776 can be defined.
20777 </p>
20778
20779 <b>example:</b>
20780 <blockquote>
20781 <pre>
20782 (set 'L '(a b c (d a f (a h a)) (k a (m n a) (x))))
20783
20784 (ref-all 'a L) <span class=arw>&rarr;</span> ((0) (3 1) (3 3 0) (3 3 2) (4 1) (4 2 2))
20785
20786 (L '(3 1)) <span class=arw>&rarr;</span> a
20787
20788 (map 'L (ref-all 'a L)) <span class=arw>&rarr;</span> (a a a a a a)
20789
20790 ; with comparison operator
20791
20792 (set 'L '(a b c (d f (h l a)) (k a (m n) (x))))
20793
20794 (ref-all 'c L)    <span class=arw>&rarr;</span> ((2))
20795
20796 (ref-all 'c L &gt;)  <span class=arw>&rarr;</span> ((0) (1) (3 2 2) (4 1))
20797
20798 (ref-all 'a L (fn (x y) (or (= x y) (= y 'k))))
20799 <span class=arw>&rarr;</span> ((0) (3 2 2) (4 0) (4 1))
20800
20801 (ref-all nil L (fn (x y) (&gt; (length y) 2)))
20802 <span class=arw>&rarr;</span> ((3) (3 2) (4))
20803
20804 ; define the comparison functions first
20805 (define (is-long? x y) (&gt; (length y) 2)) ; the x gets occupied by 'nil
20806
20807 (ref-all nil L is-long?) <span class=arw>&rarr;</span>  ((3) (3 2) (4))
20808
20809 (define (is-it-or-d x y) (or (= x y) (= y 'd)))
20810
20811 (ref-all 'e '(a b (c d (e) f)) is-it-or-d)  <span class=arw>&rarr;</span> ((2 1) (2 2 0))
20812 </pre>
20813 </blockquote>
20814
20815 <p>
20816 The comparison function can be a previously defined function.
20817 Note that the comparison function always takes two arguments,
20818 even if only the second argument is used
20819 inside the function (as in the example using <tt>long?</tt>).
20820 </p>
20821
20822 <p>
20823 Using the <a href="#match">match</a>
20824 and <a href="#unify">unify</a> functions,
20825 list searches can be formulated that are as powerful
20826 as regular expression searches are for strings.
20827 </p>
20828
20829 <blockquote>
20830 <pre>
20831 (ref-all '(a ?) '((l 3) (a 12) (k 5) (a 10) (z 22)) match)
20832 <span class=arw>&rarr;</span> ((1) (3))
20833
20834 (ref-all '(X X) '( ((a b) (c d)) ((e e) (f g)) ((z) (z))) unify)
20835 <span class=arw>&rarr;</span> ((1 0) (2))
20836
20837 (ref-all '(X g) '( ((x y z) g) ((a b) (c d)) ((e e) (f g))) unify)
20838 <span class=arw>&rarr;</span> ((0) (2 1))
20839 </pre>
20840 </blockquote>
20841
20842 <p>
20843         See also the <a href="#ref">ref</a> function.
20844 </p>
20845
20846 <br /><br />
20847
20848 <a NAME="ref-set"></a>
20849 <h2><span class="function">ref-set</span></h2>
20850 <b>syntax: (ref-set (<em>list</em> <em>exp-key</em>) <em>exp-replacement</em> [<em>func-compare</em>])</b><br />
20851
20852 <p>Searches for <em>exp-key</em> in <em>list</em> and replaces the found element with <em>exp-replacement</em>.
20853 The <em>list</em> can be nested. The system variable <tt>$0</tt> contains the expression found
20854 and can be used in <em>exp-replacement</em>. The function returns the old replaced element.</p>
20855
20856
20857 <b>example:</b>
20858 <blockquote>
20859 <pre>
20860 (set 'data '(fruits (apples 123 44) (oranges 1 5 3)))
20861
20862 (ref-set (data 'apples) 'Apples)  <span class=arw>&rarr;</span> apples
20863 </pre>
20864 </blockquote>
20865
20866 <p><tt>data</tt> could be the context identifier of a default function for passing lists by reference:</p>
20867
20868 <blockquote>
20869 <pre>
20870 (set 'data:data '(fruits (apples 123 44) (oranges 1 5 3)))
20871
20872 (define (update ct key value)
20873         (ref-set (ct key) value))
20874
20875 (update data 'apples 'Apples)  <span class=arw>&rarr;</span> apples
20876 (update data 'oranges 'Oranges)  <span class=arw>&rarr;</span> oranges
20877
20878 data:data <span class=arw>&rarr;</span> (fruits (Apples 123 44) (oranges 1 5 3))
20879 </pre>
20880 </blockquote>
20881
20882 <p>For examples on how to use <em>func-compare</em> see <a href="#set-ref-all">set-ref-all</a></p>
20883
20884 <p>See also <a href="#set-ref">set-ref</a> which returns the whole changed list
20885 instead of the old element, but else works identical. For changing all
20886 occurences of an element in a list use <a href="#set-ref-all">set-ref-all</a>.</p>
20887
20888 <br /><br />
20889
20890 <a NAME="regex"></a>
20891
20892 <h2><span class="function">regex</span></h2>
20893 <b>syntax: (regex <em>str-pattern</em> <em>str-text</em> [<em>int-option</em>])</b>
20894
20895 <p>
20896         Performs a Perl Compatible Regular Expression (PCRE) search
20897         on <em>str-text</em> with the pattern specified in <em>str-pattern</em>.
20898         The same regular expression pattern matching
20899         is also supported in the functions <a href="#directory">directory</a>,
20900         <a HREF="#find">find</a>, <a href="#find-all">find-all</a>,
20901         <a href="#parse">parse</a>, <a HREF="#replace">replace</a>,
20902         and <a HREF="#search">search</a> when using these functions on strings.
20903 </p>
20904
20905 <p>
20906         <tt>regex</tt> returns a list with the matched strings and substrings
20907         and the beginning and length of each string inside the text.
20908         If no match is found, it returns <tt>nil</tt>.
20909         The offset numbers can be used for subsequent processing.
20910 </p>
20911
20912 <p>
20913         <tt>regex</tt> also sets the variables <tt>$0, $1,</tt>
20914         and <tt>$2&mdash;</tt>
20915         to the expression and subexpressions found.
20916         Just like any other symbol in newLISP,
20917         these variables or their equivalent expressions
20918         <tt>$0, $1,</tt> and <tt>$2&mdash;</tt> can be used in other
20919         LISP expressions for further processing.
20920 </p>
20921
20922 <b>example:</b>
20923 <blockquote>
20924 <pre>
20925 (regex "b+" "aaaabbbaaaa")  <span class=arw>&rarr;</span> ("bbb" 4 3)
20926
20927 ; case-insensitive search option 1
20928 (regex "b+" "AAAABBBAAAA" 1)  <span class=arw>&rarr;</span> ("BBB" 4 3)
20929
20930 (regex "[bB]+" "AAAABbBAAAA" )  <span class=arw>&rarr;</span> ("BbB" 4 3)
20931
20932 (regex "http://(.*):(.*)" "http://nuevatec.com:80")
20933 <span class=arw>&rarr;</span> ("http://nuevatec.com:80" 0 22 "nuevatec.com" 7 12 "80" 20 2)
20934
20935 $0  <span class=arw>&rarr;</span> "http://nuevatec.com:80"
20936 $1  <span class=arw>&rarr;</span> "nuevatec.com"
20937 $2  <span class=arw>&rarr;</span> "80"
20938
20939 (dotimes (i 3) (println ($ i)))
20940 <b>http://nuevatec.com:80
20941 nuevatec.com
20942 80</b>
20943 <span class=arw>&rarr;</span> "80"
20944 </pre>
20945 </blockquote>
20946
20947 <p>
20948          The second example shows the usage of extra options,
20949         while the third example demonstrates more complex parsing of two subexpressions,
20950         which where marked by parentheses in the search pattern.
20951         In the last example,
20952         the expression and subexpressions are retrieved using the system variables <tt>$0</tt> to <tt>$2</tt> or their equivalent expression <tt>($ 0)</tt> to <tt>($ 2)</tt>.
20953 </p>
20954
20955 <p>
20956         When <tt>""</tt> (quotes) are used
20957         to delimit strings
20958         that include literal backslashes,
20959         the backslash must be doubled in the regular expression pattern.
20960         As an alternative, <tt>{ }</tt> (curly brackets)
20961         or <tt>[text]</tt> and <tt>[/text]</tt> (text tags)
20962         can be used to delimit text strings.
20963         In these cases, no extra backslashes are required.
20964 </p>
20965
20966 <p>
20967         Characters escaped by a backslash in newLISP
20968         (e.g., the quote <tt>\"</tt> or <tt>\n</tt>)
20969         need not to be doubled in a regular expression pattern,
20970         which itself is delimited by quotes.
20971 </p>
20972
20973 <blockquote>
20974 <pre>
20975 ;; double backslash for parentheses (special char in regex)
20976 (regex "\\(abc\\)" "xyz(abc)xyz")  <span class=arw>&rarr;</span> ("(abc)" 3 5)
20977
20978 ;; one backslash for quotes (special char in newLISP)
20979 (regex "\"" "abc\"def")  <span class=arw>&rarr;</span> ("\"" 3 1)
20980
20981 ;; brackets as delimiters
20982 (regex {\(abc\)} "xyz(abc)xyz")  <span class=arw>&rarr;</span> ("(abc)" 3 5)
20983
20984 ;; brackets as delimiters and quote in pattern
20985 (regex {"} "abc\"def")  <span class=arw>&rarr;</span> ("\"" 3 1)
20986
20987 ;; text tags as delimiters, good for multiline text in CGI
20988 (regex [text]\(abc\)[/text] "xyz(abc)xyz")  <span class=arw>&rarr;</span> ("(abc)" 3 5)
20989 (regex [text]"[/text] "abc\"def")           <span class=arw>&rarr;</span> ("\"" 3 1)
20990 </pre>
20991 </blockquote>
20992
20993 <p>
20994         When curly brackets or text tags
20995         are used to delimit the pattern string
20996         instead of quotes,
20997         a simple backslash is sufficient.
20998         The pattern and string are then passed in raw form
20999         to the regular expression routines.
21000         When curly brackets are used inside a pattern
21001         itself delimited by curly brackets,
21002         the inner brackets must be balanced, as follows:
21003 </p>
21004
21005 <blockquote>
21006 <pre>
21007 ;; brackets inside brackets are balanced
21008 (regex {\d{1,3}} "qwerty567asdfg")  <span class=arw>&rarr;</span> ("567" 6 3)
21009 </pre>
21010 </blockquote>
21011
21012
21013 <p>
21014          The following constants can be used for <em>int-option</em>.
21015         Several options can be combined using a binary or <tt>|</tt> (pipe).
21016         The uppercase names are used in the PCRE regex documentation and could be predefined in <tt>init.lsp</tt>.
21017         The last option is a newLISP custom option only to be used in <a href="#replace">replace</a>;
21018         it can be combined with PCRE options.
21019 </p>
21020
21021 <pre>
21022   PCRE_CASELESS        1   ; treat uppercase like lowercase
21023   PCRE_MULTILINE       2   ; limit search at a newline like Perl's /m
21024   PCRE_DOTALL          4   ; . (dot) also matches newline
21025   PCRE_EXTENDED        8   ; ignore whitespace except inside char class
21026   PCRE_ANCHORED       16   ; anchor at the start
21027   PCRE_DOLLAR_ENDONLY 32   ; $ matches at end of string, not before newline
21028   PCRE_EXTRA          64   ; additional functionality currently not used
21029   PCRE_NOTBOL        128   ; first ch, not start of line; ^ shouldn't match
21030   PCRE_NOTEOL        256   ; last char, not end of line; $ shouldn't match
21031   PCRE_UNGREEDY      512   ; invert greediness of quantifiers
21032   PCRE_NOTEMPTY     1024   ; empty string considered invalid
21033   PCRE_UTF8         2048   ; pattern and strings as UTF-8 characters
21034
21035   REPLACE_ONCE    0x8000   ; replace only one occurrence
21036                            ; only for use in <a href="#replace">replace</a>
21037 </pre>
21038
21039 <p>
21040         Note that regular expression syntax is very complex
21041         and feature-rich with many special characters and forms.
21042         Please consult a book or the PCRE manual pages for more detail.
21043         Most PERL books or introductions to Linux or UNIX
21044         also contain chapters about regular expressions.
21045         See also <a HREF="http://www.pcre.org">http://www.pcre.org</a>
21046         for further references and manual pages.
21047 </p>
21048
21049 <br /><br />
21050
21051
21052 <a NAME="remove-dir"></a>
21053 <h2><span class="function">remove-dir</span></h2>
21054 <b>syntax: (remove-dir <em>str-path</em>)</b>
21055
21056 <p>
21057         Removes the directory
21058         whose path name is specified in <em>str-path</em>.
21059         The directory must be empty for <tt>remove-dir</tt> to succeed.
21060         Returns <tt>nil</tt> on failure.
21061 </p>
21062
21063 <b>example:</b>
21064 <blockquote>
21065 <pre>
21066 (remove-dir "temp")
21067 </pre>
21068 </blockquote>
21069
21070 <p>
21071         Removes the directory <tt>temp</tt>
21072         in the current directory.
21073 </p>
21074
21075 <br /><br />
21076
21077 <a NAME="rename-file"></a>
21078 <h2><span class="function">rename-file</span></h2>
21079 <b>syntax: (rename-file <em>str-path-old</em> <em>str-path-new</em>)</b>
21080
21081 <p>
21082         Renames a file or directory entry
21083         given in the path name <em>str-path-old</em>
21084         to the name given in <em>str-path-new</em>.
21085         Returns <tt>nil</tt> or <tt>true</tt>
21086         depending on the operation's success.
21087 </p>
21088
21089 <b>example:</b>
21090 <blockquote>
21091 <pre>
21092 (rename-file "data.lisp" "data.backup")
21093 </pre>
21094 </blockquote>
21095 <br /><br />
21096
21097 <a NAME="replace"></a>
21098 <h2><span class="function">replace</span></h2>
21099 <b>syntax: (replace <em>exp-key</em> <em>list</em> <em>exp-replacement</em> [<em>func-compare</em>])</b><br />
21100 <b>syntax: (replace <em>exp list</em>)</b><br /><br />
21101
21102 <b>syntax: (replace <em>str-key</em> <em>str-data</em> <em>exp-replacement</em>)</b><br />
21103 <b>syntax: (replace <em>str-pattern</em> <em>str-data</em> <em>exp-replacement</em> <em>int-option</em>)</b><br />
21104
21105 <h4>List replacement</h4>
21106 <p>
21107         If the second argument is a list,
21108         <tt>replace</tt> replaces all elements in the list <em>list</em>
21109         that are equal to the expression in <em>exp-key</em>.
21110         The element is replaced with <em>exp-replacement</em>.
21111         Note that <tt>replace</tt> is destructive. It
21112         changes the list passed to it and
21113         returns the changed list.
21114         The number of replacements made
21115         is contained in the system variable $0 when the function returns.
21116   During executions of the replacement expression,
21117   the system variable $0
21118   is set to the expression to be replaced.
21119 </p>
21120
21121 <p>
21122 Optionally, <em>func-compare</em> can specify a comparison operator
21123 or user-defined function.
21124 By default, <em>func-compare</em> is the <tt>=</tt> (equals sign).
21125 </p>
21126
21127 <b>example:</b>
21128 <blockquote>
21129 <pre>
21130 ;; list replacement
21131
21132 (set 'aList '(a b c d e a b c d))
21133
21134 (replace 'b aList 'B)  <span class=arw>&rarr;</span> (a B c d e a B c d)
21135 aList  <span class=arw>&rarr;</span> (a B c d e a B c d)
21136 $0     <span class=arw>&rarr;</span> 2  ; number of replacements
21137
21138 ;; list replacement with special compare functor/function
21139
21140 ; replace all numbers where 10 &lt; number
21141 (set 'L '(1 4 22 5 6 89 2 3 24))
21142
21143 (replace 10 L 10 &lt;) <span class=arw>&rarr;</span> (1 4 10 5 6 10 2 3 10)
21144
21145 ; same as:
21146
21147 (replace 10 L 10 (fn (x y) (&lt; x y))) <span class=arw>&rarr;</span> (1 4 10 5 6 10 2 3 10)
21148
21149 ; change name-string to symbol, x is ignored as nil
21150
21151 (set 'AL '((john 5 6 4) ("mary" 3 4 7) (bob 4 2 7 9) ("jane" 3)))
21152
21153 (replace nil AL (cons (sym ($0 0)) (rest $0))
21154                 (fn (x y) (string? (y 0))))
21155 <span class=arw>&rarr;</span> ((john 5 6 4) (mary 3 4 7) (bob 4 2 7 9) (jane 3))
21156 </pre>
21157 </blockquote>
21158
21159 <p>
21160 Using the <a href="#match">match</a> and <a href="#unify">unify</a> functions,
21161 list searches can be formulated that are as powerful as regular expression string searches:</p>
21162
21163 <blockquote>
21164 <pre>
21165 ; calculate the sum in all associations with 'mary
21166
21167 (set 'AL '((john 5 6 4) (mary 3 4 7) (bob 4 2 7 9) (jane 3)))
21168
21169 (replace '(mary *)  AL (list 'mary (apply + (rest $0))) match)
21170 <span class=arw>&rarr;</span> ((john 5 6 4) (mary 14) (bob 4 2 7 9) (jane 3))
21171
21172 ; make sum in all expressions
21173
21174 (set 'AL '((john 5 6 4) (mary 3 4 7) (bob 4 2 7 9) (jane 3)))
21175
21176 (replace '(*) AL (list ($0 0) (apply + (rest $0))) match)
21177 <span class=arw>&rarr;</span> ((john 15) (mary 14) (bob 22) (jane 3))
21178
21179 ; using unify
21180
21181 (replace '(X X) '((3 10) (2 5) (4 4) (6 7) (8 8)) (list ($0 0) 'double ($0 1)) unify)
21182 <span class=arw>&rarr;</span> ((3 10) (2 5) (4 double 4) (6 7) (8 double 8))
21183 </pre>
21184 </blockquote>
21185
21186 <br />
21187
21188 <h4>List removal</h4>
21189 <p>
21190         The last form of <tt>replace</tt> has only two arguments:
21191         the expression <em>expr</em> and <em>list</em>.
21192         This form removes all <em>expr</em>s found in <em>list</em>.
21193 </p>
21194
21195 <b>example:</b>
21196 <blockquote>
21197 <pre>
21198 ;; removing elements from a list
21199
21200 (set 'lst '(a b a a c d a f g))
21201 (replace 'a lst)  <span class=arw>&rarr;</span> (b c d f g)
21202 lst               <span class=arw>&rarr;</span> (b c d f g)
21203
21204 $0  <span class=arw>&rarr;</span> 4
21205 </pre>
21206 </blockquote>
21207
21208 <br />
21209
21210 <h4>String replacement without regular expression</h4>
21211 <p>
21212         If all arguments are strings,
21213         <tt>replace</tt> replaces all occurrences
21214         of <em>str-key</em> in <em>str-data</em>
21215         with the evaluated <em>exp-replacement</em>,
21216         returning the changed string.
21217         The expression in <em>exp-replacement</em>
21218         is evaluated for every replacement.
21219         The number of replacements made
21220         is contained in the system variable $0.
21221   This form of <tt>replace</tt>
21222   can also process binary <tt>0</tt>s (zeros).
21223 </p>
21224
21225 <b>example:</b>
21226 <blockquote>
21227 <pre>
21228 ;; string replacement
21229 (set 'str "this isa sentence")
21230 (replace "isa" str "is a")  <span class=arw>&rarr;</span> "this is a sentence"
21231 </pre>
21232 </blockquote>
21233
21234 <br />
21235
21236 <h4>Regular expression replacement</h4>
21237 <p>
21238         The presence of a fourth parameter
21239         indicates that a regular expression search
21240         should be performed with a regular expression pattern
21241         specified in <em>str-pattern</em>
21242         and an option number specified in <em>int-option</em>
21243         (e.g., <tt>1</tt> (one) for case-insensitive searching
21244         or <tt>0</tt> (zero) for a standard
21245         Perl Compatible Regular Expression (PCRE) search).
21246         See <a HREF="#regex">regex</a> above for details.
21247 </p>
21248
21249 <p>
21250         By default, <tt>replace</tt> replaces all occurrences
21251         of a search string even if a beginning-of-line specification
21252         is included in the search pattern.
21253         After each replace,
21254         a new search is started at a new position in <em>str-data</em>.
21255         Setting the option bit to <tt>0x8000</tt> in <em>int-option</em>
21256         will force <tt>replace</tt> to replace only the first occurrence.
21257         The changed string is returned.
21258 </p>
21259
21260 <p>
21261         <tt>replace</tt> with regular expressions
21262         also sets the internal variables
21263         <tt>$0, $1,</tt> and <tt>$2&mdash;</tt>
21264         with the contents of the expressions
21265         and subexpressions found.
21266         These can be used to perform replacements
21267         that depend on the content found during replacement.
21268         The symbols <tt>$0, $1,</tt> and <tt>$2&mdash;</tt> can be used
21269         in expressions just like any other symbols.
21270         If the replacement expression
21271         evaluates to something other than a string,
21272         no replacement is made.
21273         As an alternative,
21274         the contents of these variables can also be accessed
21275         by using <tt>($ 0), ($ 1), ($ 2),</tt> and so forth.
21276         This method allows indexed access
21277         (e.g., <tt>($ i)</tt>,
21278         where <tt>i</tt> is an integer).
21279 </p>
21280
21281 <p>After all replacements are made, the number of replacements
21282 is contained in the system variable <tt>$0</tt>.</p>
21283
21284
21285 <b>example:</b>
21286 <blockquote>
21287 <pre>
21288 ;; using the option parameter to employ regular expressions
21289
21290 (set 'str "ZZZZZxZZZZyy")     <span class=arw>&rarr;</span> "ZZZZZxZZZZyy"
21291 (replace "[x|y]" str "PP" 0)  <span class=arw>&rarr;</span> "ZZZZZPPZZZZPPPP"
21292 str                           <span class=arw>&rarr;</span> "ZZZZZPPZZZZPPPP"
21293
21294 ;; using system variables for dynamic replacement
21295
21296 (set 'str "---axb---ayb---")
21297 (replace "(a)(.)(b)" str (append $3 $2 $1) 0)
21298 <span class=arw>&rarr;</span> "---bxa---bya---"
21299
21300 str  <span class=arw>&rarr;</span> "---bxa---bya---"
21301
21302 ;; using the 'replace once' option bit 0x8000
21303
21304 (replace "a" "aaa" "X" 0)  <span class=arw>&rarr;</span> "XXX"
21305
21306 (replace "a" "aaa" "X" 0x8000)  <span class=arw>&rarr;</span> "Xaa"
21307
21308 ;; URL translation of hex codes with dynamic replacement
21309
21310 (set 'str "xxx%41xxx%42")
21311 (replace "%([0-9A-F][0-9A-F])" str
21312                (char (integer (append "0x" $1))) 1)
21313
21314 str  <span class=arw>&rarr;</span> "xxxAxxxB"
21315
21316 $0   <span class=arw>&rarr;</span> 2
21317 </pre>
21318 </blockquote>
21319
21320 <p>
21321         The <a HREF="#set-nth">set-nth</a> and
21322         <a HREF="#set-assoc">set-assoc</a> functions
21323         can also be used to change an element in a list.
21324 </p>
21325
21326 <p>
21327         See <a href="#directory">directory</a>,
21328         <a href="#find">find</a>,
21329         <a href="#find-all">find-all</a>,
21330         <a href="#parse">parse</a>,
21331         <a href="#regex">regex</a>,
21332         and <a href="#search">search</a>
21333         for other functions using regular expressions.
21334 </p>
21335
21336 <br /><br />
21337
21338 <a NAME="set-assoc"></a>
21339 <h2><span class="function">set-assoc</span></h2>
21340 <b>syntax: (set-assoc (<em>list-assoc</em> <em>exp-key-1</em> [<em>exp-key2</em> ...]) <em>exp-replacement</em>)</b>
21341
21342 <p>The function <tt>set-assoc</tt> behaves like the older <tt>replace-assoc</tt>
21343 replacing an association with <em>exp-key</em> in the association list <em>list-assoc</em>
21344 with <em>exp-replacement</em>.  An association list is a list
21345 whose elements are in turn lists, the first element serving as a key.</p>
21346
21347 <b>example:</b>
21348 <blockquote>
21349 <pre>
21350 (set 'aList '((a 1 2 3) (b 4 5 6) (c 7 8 9)))
21351
21352 (set-assoc (aList 'b) '(q "the replacement"))
21353 <span class=arw>&rarr;</span> ((a 1 2 3) (q "the replacement") (c 7 8 9))
21354
21355 aList  <span class=arw>&rarr;</span> ((a 1 2 3) (q "I am the replacement") (c 7 8 9))
21356 </pre>
21357 </blockquote>
21358
21359 <p><tt>set-assoc</tt> uses the system variable <tt>$0</tt> for the association found.
21360 This can be used in the replacement expression: </p>
21361
21362 <blockquote>
21363 <pre>
21364 (set 'lst '((a 1)(b 2)(c 3)))
21365
21366 (set-assoc (lst 'b) (list 'b (+ 1 (last $0))))
21367
21368 lst <span class=arw>&rarr;</span> ((a 1)(b 3)(c 3))
21369 </pre>
21370 </blockquote>
21371
21372 <p>
21373
21374 <p><tt>set-assoc</tt> returns the changed list or <tt>nil</tt> if no association is found.
21375 A destructive operation, <tt>set-assoc</tt> changes the contents of the list.</p>
21376
21377 <p>Like with <a href="#assoc">assoc</a>, association lists can be nested and multiple
21378 keys can be used for access.</p>
21379
21380 <blockquote>
21381 <pre>
21382 (set 'aList '((a 1) (b (c 2)) (d 3)))
21383
21384 (set-assoc (aList 'b 'c) '(c 3))
21385 <span class=arw>&rarr;</span> ((a 1) (b (c 3)) (d 3))
21386 </pre>
21387 </blockquote>
21388
21389 <p>
21390 See also the <a HREF="#assoc">assoc</a> function
21391 for accessing association lists. <a href="#assoc-set">assoc-set</a>  works like <tt>set-assoc</tt>
21392 but returns the old association element instead of the entire list. To remove associations
21393 use <a href="#pop-assoc">pop-assoc</a>.
21394 </p>
21395
21396 <br /><br />
21397
21398 <a NAME="replace-assoc"></a>
21399 <h2><span class="function">replace-assoc</span></h2>
21400 <b>syntax: (replace-assoc <em>exp-key</em> <em>list-assoc</em> <em>exp-replacement</em>)</b><br />
21401
21402 <b>syntax: (replace-assoc <em>exp-key</em> <em>list-assoc</em>)</b>
21403
21404 <p>Note that this function is deprecated and will be removed in a future version. Use
21405 <a href="#set-assoc">set-assoc</a> or <a href="#pop-assoc">pop-assoc</a> instead. This
21406 new functions also handle multiple keys for accessing elements in nested association
21407 lists.</p>
21408
21409 <p>
21410 In the first syntax, <tt>replace-assoc</tt> replaces an association element with <em>exp-key</em>
21411 in the association <em>list-assoc</em> with <em>exp-replacement</em>.
21412 In the second syntax, <tt>replace-assoc</tt> removes an association from the list and returns it.
21413 </p>
21414
21415 <br /><br />
21416
21417 <a NAME="reset"></a>
21418 <h2><span class="function">reset</span></h2>
21419 <b>syntax: (reset)</b><br />
21420 <b>syntax: (reset true)</b>
21421
21422 <p>
21423         In the first syntax,
21424         <tt>reset</tt> returns to the top level of evaluation,
21425         switches the <a HREF="#trace">trace</a> mode off,
21426         turns the <a HREF="#command-line">command-line</a> mode on,
21427         and switches to the MAIN context/namespace.
21428         <tt>reset</tt> restores the top-level variable environment
21429         using the saved variable environments on the stack.
21430         It also fires an error "user reset - no error".
21431         This behavior can be used when writing error handlers.
21432 </p>
21433
21434 <p>
21435         <tt>reset</tt> may return memory
21436         that was claimed by newLISP
21437         to the operating system.
21438         <tt>reset</tt> walks through the entire cell space,
21439         which may take a few seconds in a heavily loaded system.
21440 </p>
21441
21442 <p>
21443         <tt>reset</tt> occurs automatically after an error condition.
21444 </p>
21445
21446 <p>
21447         In the second syntax,
21448         <tt>reset</tt> will stop the current process
21449         and start a new clean newLISP process
21450         with the same command-line parameters.
21451         This mode will only work when newLISP was started
21452         using its full path-name, e.g. <tt>/usr/bin/newlisp</tt>
21453     instead of only <tt>newlisp</tt>.
21454         This mode is not available on Win32.
21455 </p>
21456
21457 <br /><br />
21458
21459 <a NAME="rest"></a>
21460 <h2><span class="function">rest</span></h2>
21461
21462 <b>syntax: (rest <em>list</em>)</b><br />
21463 <b>syntax: (rest <em>array</em>)</b><br />
21464 <b>syntax: (rest <em>str</em>)</b>
21465
21466 <p>
21467         Returns all of the items in a list or a string,
21468         except for the first.
21469         <tt>rest</tt> is equivalent to <em>cdr</em>
21470         or <em>tail</em> in other LISP dialects.
21471 </p>
21472
21473 <b>example:</b>
21474 <blockquote>
21475 <pre>
21476 (rest '(1 2 3 4))            <span class=arw>&rarr;</span> (2 3 4)
21477 (rest '((a b) c d))          <span class=arw>&rarr;</span> (c d)
21478 (set 'aList '(a b c d e))    <span class=arw>&rarr;</span> (a b c d e)
21479 (rest aList)                 <span class=arw>&rarr;</span> (b c d e)
21480 (first (rest aList))         <span class=arw>&rarr;</span> b
21481 (rest (rest aList))          <span class=arw>&rarr;</span> (d e)
21482 (rest (first '((a b) c d)))  <span class=arw>&rarr;</span> (b)
21483
21484 (set 'A (array 2 3 (sequence 1 6)))
21485 <span class=arw>&rarr;</span> ((1 2) (3 4) (5 6))
21486
21487 (rest A)  <span class=arw>&rarr;</span> ((3 4) (5 6))
21488 </pre>
21489 </blockquote>
21490
21491 <p>
21492         In the second version,
21493         <tt>rest</tt> returns all but the first character
21494         of the string <em>str</em> in a string.
21495 </p>
21496
21497 <b>example:</b>
21498 <blockquote>
21499 <pre>
21500 (rest "newLISP")          <span class=arw>&rarr;</span> "ewLISP"
21501 (first (rest "newLISP"))  <span class=arw>&rarr;</span> "e"
21502 </pre>
21503 </blockquote>
21504
21505
21506 <p>
21507         See also the <a HREF="#first">first</a>
21508         and <a HREF="#last">last</a> functions.
21509 </p>
21510
21511 <p>
21512         Note that an <em>implicit rest</em>
21513         is available for lists.
21514         See the chapter <a href="#implicit_rest_slice">Implicit rest and slice</a>.
21515 </p>
21516
21517 <p>
21518         Note that <a href="#rest">rest</a> works on character boundaries
21519         rather than byte boundaries
21520         when the UTF-8&ndash;enabled version of newLISP is used.
21521 </p>
21522
21523
21524 <br /><br />
21525
21526 <a NAME="reverse"></a>
21527 <h2><span class="function">reverse</span></h2>
21528 <b>syntax: (reverse <em>list</em>)</b><br />
21529
21530 <b>syntax: (reverse <em>string</em>)</b>
21531
21532 <p>
21533         In the first form,
21534         <tt>reverse</tt> reverses and returns the <em>list</em>.
21535         Note that <tt>reverse</tt> is destructive and
21536         changes the original list.
21537 </p>
21538
21539 <b>example:</b>
21540 <blockquote>
21541 <pre>
21542 (set 'l '(1 2 3 4 5 6 7 8 9))
21543
21544 (reverse l)  <span class=arw>&rarr;</span> (9 8 7 6 5 4 3 2 1)
21545 l            <span class=arw>&rarr;</span> (9 8 7 6 5 4 3 2 1)
21546 </pre>
21547 </blockquote>
21548
21549 <p>
21550         In the second form,
21551         <tt>reverse</tt> is used to reverse the order
21552         of characters in a string.
21553 </p>
21554
21555 <b>example:</b>
21556 <blockquote>
21557 <pre>
21558 (set 'str "newLISP")
21559
21560 (reverse str)  <span class=arw>&rarr;</span> "PSILwen"
21561 str            <span class=arw>&rarr;</span> "PSILwen"
21562 </pre>
21563 </blockquote>
21564
21565 <p>
21566         See also the <a HREF="#sort">sort</a> function.
21567 </p>
21568
21569 <br /><br />
21570
21571 <a NAME="rotate"></a>
21572 <h2><span class="function">rotate</span></h2>
21573 <b>syntax: (rotate <em>list</em> [<em>int-count</em>])</b><br />
21574 <b>syntax: (rotate <em>str</em> [<em>int-count</em>])</b>
21575
21576 <p>
21577         Rotates and returns
21578         the <em>list</em> or string in <em>str</em>.
21579         A count can be optionally specified in <em>int-count</em>
21580         to rotate more than one position.
21581         If <em>int-count</em> is positive,
21582         the rotation is to the right;
21583         if <em>int-count</em> is negative,
21584         the rotation is to the left.
21585         If no <em>int-count</em> is specified,
21586         <tt>rotate</tt> rotates 1 to the right.
21587         <tt>rotate</tt> is a destructive function
21588         that changes the contents of
21589         the original list or string.
21590 </p>
21591
21592 <b>example:</b>
21593 <blockquote>
21594 <pre>
21595 (set 'l '(1 2 3 4 5 6 7 8 9))
21596
21597 (rotate l)    <span class=arw>&rarr;</span> (9 1 2 3 4 5 6 7 8)
21598 (rotate l 2)  <span class=arw>&rarr;</span> (7 8 9 1 2 3 4 5 6)
21599
21600 l  <span class=arw>&rarr;</span> (7 8 9 1 2 3 4 5 6)
21601
21602 (rotate l -3)  <span class=arw>&rarr;</span> (1 2 3 4 5 6 7 8 9)
21603
21604 (set 'str "newLISP")
21605
21606 (rotate str)     <span class=arw>&rarr;</span> "PnewLIS"
21607 (rotate str 3)   <span class=arw>&rarr;</span> "LISPnew"
21608 (rotate str -4)  <span class=arw>&rarr;</span> "newLISP"
21609 </pre>
21610 </blockquote>
21611
21612 <p>
21613         When working on a string,
21614         <tt>rotate</tt> works on byte boundaries
21615         rather than character boundaries.
21616 </p>
21617
21618 <br /><br />
21619
21620 <a NAME="round"></a>
21621 <h2><span class="function">round</span></h2>
21622 <b>syntax: (round <em>number</em> [<em>int-digits</em>])</b>
21623
21624 <p>Rounds the number in <em>number</em>
21625 to the number of digits given in <em>int-digits</em>.
21626 When decimals are being rounded, <em>int-digits</em> is negative.
21627 It is positive when the integer part of a number is being rounded.</p>
21628
21629 <p>If <em>int-digits</em> is omitted, the function rounds to <tt>0</tt> decimal
21630 digits.</p>
21631
21632 <b>example:</b>
21633 <blockquote>
21634 <pre>
21635 (round 123.49 2)    <span class=arw>&rarr;</span> 100
21636 (round 123.49 1)    <span class=arw>&rarr;</span> 120
21637 (round 123.49 0)    <span class=arw>&rarr;</span> 123
21638 (round 123.49)      <span class=arw>&rarr;</span> 123
21639 (round 123.49 -1)   <span class=arw>&rarr;</span> 123.5
21640 (round 123.49 -2)   <span class=arw>&rarr;</span> 123.49
21641 </pre>
21642 </blockquote>
21643
21644 <p>Note that rounding for display purposes is better accomplished using
21645 <a href="#format">format</a>.</p>
21646
21647
21648 <br /><br />
21649
21650 <a NAME="save"></a>
21651 <h2><span class="function">save</span></h2>
21652 <b>syntax: (save <em>str-file</em>)</b><br />
21653 <b>syntax: (save <em>str-file</em> <em>sym-1</em> [<em>sym-2</em> ... ])</b>
21654
21655 <p>
21656         In the first syntax,
21657         the <tt>save</tt> function writes
21658         the contents of the newLISP workspace
21659         (in textual form) to the file <em>str-file</em>.
21660         <tt>save</tt> is the inverse function of <tt>load</tt>.
21661         Using <tt>load</tt> on files
21662         created with <tt>save</tt> causes
21663         newLISP to return to the same state
21664         as when <tt>save</tt> was originally invoked.
21665         System symbols starting with the <tt>$</tt> character
21666         (e.g., <tt>$0</tt> from regular expressions
21667         or <tt>$main-args</tt> from the command line)
21668         are not saved.
21669 </p>
21670
21671 <p>
21672         In the second syntax,
21673         symbols can be supplied as arguments.
21674         If <em>sym-n</em> is supplied,
21675         only the definition of that symbol is saved.
21676         If <em>sym-n</em> evaluates to a context,
21677         all symbols in that context are saved.
21678         More than one symbol can be specified,
21679         and symbols and context symbols can be mixed.
21680         When contexts are saved,
21681         system variables and symbols starting with the <tt>$</tt> character
21682         are not saved.
21683         Specifying system symbols explicitly
21684         causes them to be saved.
21685 </p>
21686
21687 <p>
21688         Each symbol is saved
21689         by means of a <a HREF="#set">set</a> statement or&mdash;if
21690         the symbol contains a lambda or lambda-macro function&mdash;by
21691         means of <a HREF="#define">define</a>
21692         or <a HREF="#define-macro">define-macro</a> statements.
21693 </p>
21694
21695 <p>
21696         Symbols containing <tt>nil</tt> will not be saved.
21697 </p>
21698
21699 <p>
21700         <tt>save</tt> returns <tt>true</tt> on completion.
21701 </p>
21702
21703 <b>example:</b>
21704 <blockquote>
21705 <pre>
21706 (save "save.lsp")
21707
21708 (save "/home/myself/myfunc.LSP" 'my-func)
21709 (save "file:///home/myself/myfunc.LSP" 'my-func)
21710
21711 (save "http://asite.com:8080//home/myself/myfunc.LSP" 'my-func)
21712
21713 (save "mycontext.lsp" 'mycontext)
21714
21715 ;; multiple args
21716 (save "stuff.lsp" 'aContext 'myFunc '$main-args 'Acontext)
21717 </pre>
21718 </blockquote>
21719
21720 <p>
21721         Since all context symbols are part of the context <tt>MAIN</tt>,
21722         saving <tt>MAIN</tt> saves all contexts.
21723 </p>
21724
21725 <p>
21726         Saving to a URL
21727         will cause an HTTP PUT request send to the URL.
21728         In this mode,
21729         <tt>save</tt> can also be used
21730         to push program source
21731         to remote newLISP server nodes.
21732         Note that a double backslash is required
21733         when path names are specified
21734         relative to the root directory.
21735         <tt>save</tt> in <tt>HTTP</tt>  mode will
21736         observe a 60-second timeout.</p>
21737 </p>
21738
21739 <p>
21740         Symbols made using <a href="#sym">sym</a>
21741         that are incompatible with the normal syntax rules for symbols
21742         are serialized using a <a href="#sym">sym</a> statement
21743         instead of a <a href="#set">set</a> statement.
21744 </p>
21745
21746 <p>
21747         <tt>save</tt> serializes contexts and symbols
21748         as if the current context is <tt>MAIN</tt>.
21749         Regardless of the current context,
21750         <tt>save</tt> will always generate the same output.
21751 </p>
21752
21753 <p>
21754         See also the functions <a HREF="#load">load</a>
21755         (the inverse operation of <tt>save</tt>)
21756         and <a href="#source">source</a>,
21757         which saves symbols and contexts to a string
21758         instead of a file.
21759 </p>
21760
21761 <br /><br />
21762
21763 <a NAME="search"></a>
21764 <h2><span class="function">search</span></h2>
21765 <b>syntax: (search <em>int-file</em> <em>str-search</em> [<em>bool-flag</em>] [<em>int-options</em>])</b>
21766
21767 <p>
21768 Searches a file specified by its handle in <em>int-file</em> for a string in <em>str-search</em>.
21769 <em>int-file</em> can be obtained from a previous <a HREF="#open">open</a> file.  After the search,
21770 the file pointer is positioned at the beginning  or the end of the searched string or at the end
21771 of the file if nothing is found.</p>
21772
21773 <p> If <em>bool-flag</em> evaluates to <tt>nil</tt> or if <em>bool-flag</em> is missing,
21774 then the filepointer is positioned at the beginning of the searched string, else at the end
21775 of the searched string.</p>
21776 <p> In <em>int-options</em>,  the options flags can be specified to perform
21777 a PCRE regular expression search.  See the function <a href="#regex">regex</a> for details.
21778 If <em>int-options</em> is mot specified a faster, plain string search is performed.
21779 <tt>search</tt> returns the new file position or <tt>nil</tt> if nothing is found.
21780 </p>
21781
21782 <p> When using the regular expression options flag, patterns found are stored in the system variables
21783 <tt>$0</tt> to <tt>$15</tt>.  </p>
21784
21785 <b>example:</b>
21786 <blockquote>
21787 <pre>
21788 (set 'file (open "init.lsp" "read"))
21789 (search file "define")
21790 (print (read-line file) "\n")
21791 (close file)
21792
21793
21794 (set 'file (open "program.c" "r"))
21795 (while (search file "#define (.*)" true 0) (println $1))
21796 (close file)
21797 </pre>
21798 </blockquote>
21799
21800 <p> The file <tt>init.lsp</tt> is opened and searched for the string <tt>define</tt> and the
21801 line in which the string occurs is printed. </p>
21802
21803 <p>The second example looks for all lines in the file <tt>program.c</tt> which start with
21804 the string <tt>#define</tt> and prints the rest of the line after the string "#define ".</p>
21805
21806 <p>
21807         For other functions using regular expressions,
21808         see <a href="#directory">directory</a>,
21809         <a href="#find">find</a>,
21810         <a href="#find-all">find-all</a>,
21811         <a href="#parse">parse</a>,
21812         <a HREF="#regex">regex</a>,
21813         and <a href="#replace">replace</a>.
21814 </p>
21815
21816 <br /><br />
21817
21818 <a NAME="seed"></a>
21819 <h2><span class="function">seed</span></h2>
21820 <b>syntax: (seed <em>int-seed</em>)</b>
21821
21822 <p>
21823         Seeds the internal random generator
21824         that generates numbers for <a href="#amb">amb</a>,
21825         <a href="#normal">normal</a>,
21826         <a HREF="#rand">rand</a>,
21827         and <a HREF="#random">random</a>
21828         with the number specified in <em>int-seed</em>.
21829         Note that the random generator used in newLISP
21830         is the C-library function <em>rand()</em>.
21831         All randomizing functions in newLISP
21832         are based on this function.
21833 </p>
21834
21835 <p>
21836         Note that the maximum value for <em>int-seed</em>
21837         is limited to 16 or 32 bits,
21838         depending on the operating system used.
21839         Internally,
21840         only the 32 least significant bits are passed
21841         to the random seed function of the OS.
21842 </p>
21843
21844 <b>example:</b>
21845 <blockquote>
21846 <pre>
21847 (seed 12345)
21848
21849 (seed (date-value))
21850 </pre>
21851 </blockquote>
21852
21853 <p>
21854         After using <tt>seed</tt> with the same number,
21855         the random generator starts the same sequence of numbers.
21856         This facilitates debugging
21857         when randomized data are involved.
21858         Using <tt>seed</tt>,
21859         the same random sequences can be generated
21860         over and over again.
21861 </p>
21862
21863 <p>
21864         The second example is useful for guaranteeing
21865         a different seed any time the program starts.
21866 </p>
21867
21868 <br /><br />
21869
21870 <a NAME="seek"></a>
21871 <h2><span class="function">seek</span></h2>
21872 <b>syntax: (seek <em>int-file</em> [<em>int-position</em>])</b>
21873
21874 <p>
21875         Sets the file pointer to the new position <em>int-position</em>
21876         in the file specified by <em>int-file</em>.
21877         The new position is expressed as an offset from
21878         the beginning of the file,
21879         0 (zero) meaning the beginning of the file.
21880         If no <em>int-position</em> is specified,
21881         <tt>seek</tt> returns the current position in the file.
21882         If <em>int-file</em> is 0 (zero),
21883         on BSD, <tt>seek</tt> will return
21884         the number of characters
21885         printed to <tt>STDOUT</tt>,
21886         and on Linux and Win32,
21887         it will return <tt>-1</tt>.
21888         On failure,
21889         <tt>seek</tt> returns <tt>nil</tt>.
21890         When <em>int-position</em> is set to <tt>-1</tt>,
21891         <tt>seek</tt> sets the file pointer
21892         to the end of the file.
21893 </p>
21894
21895 <p><tt>seek</tt> can set the file position past the current end of the file. Subsequent
21896 writing to this position will extend the file and fill unused positions with zero's.
21897 The blocks of zeros are not actually allocated on disk, so the file takes up less
21898 space and is called a <em>sparse file</em>.</p>
21899
21900 <b>example:</b>
21901 <blockquote>
21902 <pre>
21903 (set 'file (open "myfile" "read"))  <span class=arw>&rarr;</span> 5
21904 (seek file 100)                     <span class=arw>&rarr;</span> 100
21905 (seek file)                         <span class=arw>&rarr;</span> 100
21906
21907 (open "newlisp_manual.html" "read")
21908 (seek file -1)  ; seek to EOF
21909 <span class=arw>&rarr;</span> 593816
21910
21911 (set 'fle (open "large-file" "read")
21912 (seek file 30000000000)  <span class=arw>&rarr;</span> 30000000000
21913 </pre>
21914 </blockquote>
21915
21916 <p>
21917         newLISP supports file position numbers up to
21918         9,223,372,036,854,775,807.
21919 </p>
21920
21921 <br /><br />
21922
21923 <a NAME="select"></a>
21924 <h2><span class="function">select</span></h2>
21925
21926 <b>syntax: (select <em>list</em> <em>list-selection</em>)</b><br />
21927 <b>syntax: (select <em>list</em> [<em>int-index_i</em> ... ])</b><br /><br />
21928
21929 <b>syntax: (select <em>string</em> <em>list-selection</em>)</b><br />
21930
21931 <b>syntax: (select <em>string</em> [<em>int-index_i</em> ... ])</b>
21932
21933 <p>
21934         In the first two forms,
21935         <tt>select</tt> picks one or more elements
21936         from <em>list</em> using one or more indices
21937         specified in <em>list-selection</em> or the <em>int-index_i</em>.
21938 </p>
21939
21940 <b>example:</b>
21941 <blockquote>
21942 <pre>
21943 (set 'lst '(a b c d e f g))
21944
21945 (select lst '(0 3 2 5 3))  <span class=arw>&rarr;</span> (a d c f d)
21946
21947 (select lst '(-2 -1 0))  <span class=arw>&rarr;</span> (f g a)
21948
21949 (select lst -2 -1 0)  <span class=arw>&rarr;</span> (f g a)
21950 </pre>
21951 </blockquote>
21952
21953 <p>
21954         In the second two forms,
21955         <tt>select</tt> picks one or more characters
21956         from <em>string</em>
21957         using one or more indices specified in <em>list-selection</em>
21958         or the <em>int-index_i</em>.
21959 </p>
21960
21961 <b>example:</b>
21962 <blockquote>
21963 <pre>
21964 (set 'str "abcdefg")
21965
21966 (select str '(0 3 2 5 3))  <span class=arw>&rarr;</span> "adcfd"
21967
21968 (select str '(-2 -1 0))  <span class=arw>&rarr;</span> "fga"
21969
21970 (select str -2 -1 0)  <span class=arw>&rarr;</span> "fga"
21971 </pre>
21972 </blockquote>
21973
21974 <p>
21975         Selected elements can be repeated and do not have to appear in order,
21976         although this speeds up processing.
21977         The order in <em>list-selection</em> or <em>int-index_i</em>
21978         can be changed to rearrange elements.
21979 </p>
21980
21981 <br /><br />
21982
21983
21984 <a NAME="semaphore"></a>
21985 <h2><span class="function">semaphore</span></h2>
21986
21987 <b>syntax: (semaphore)</b><br />
21988 <b>syntax: (semaphore <em>int-id</em>)</b><br />
21989 <b>syntax: (semaphore <em>int-id</em> <em>int-wait</em>)</b><br />
21990 <b>syntax: (semaphore <em>int-id</em> <em>int-signal</em>)</b><br />
21991
21992 <b>syntax: (semaphore <em>int-id</em> <em>0</em>)</b>
21993
21994 <p>
21995         A semaphore is an interprocess synchronization object
21996         that maintains a count between 0 (zero) and some maximum value.
21997         Useful in controlling
21998         access to a shared resource,
21999         a semaphore is set to signaled
22000         when its count is greater than zero
22001         and to non-signaled
22002         when its count is zero.
22003 </p>
22004
22005 <p>
22006         A semaphore is created using the first syntax.
22007         This returns the semaphore ID,
22008         an integer used subsequently as <em>int-id</em>
22009         when the <em>semaphore</em> function is called.
22010         Initially, the semaphore has a value of zero, which
22011         represents the non-signaled state.
22012 </p>
22013
22014 <p>
22015         If calling <tt>semaphore</tt> with a negative value in <em>int-wait</em>
22016         causes it to be decremented below zero,
22017         the function call will block until another process or thread
22018         signals the semaphore with a positive value in <em>int-signal</em>.
22019         Calls to the semaphore with <em>int-wait</em> or <em>int-signal</em>
22020         effectively try to increment or decrement the semaphore value
22021         by a positive or negative value specified in <em>int-signal</em>
22022         or <em>int-wait</em>.
22023         Because the value of a semaphore must never fall below zero,
22024         the function call will block when this is attempted
22025         (i.e., a semaphore with a value of zero
22026         will block until another process or thread
22027         increases the value with a positive <em>int-signal</em>).
22028 </p>
22029
22030 <p>
22031         The second syntax is used to inquire about the value of a semaphore
22032         by calling <tt>semaphore</tt> with the <em>int-id</em> only.
22033         This form is not available on Win32.
22034 </p>
22035
22036 <p>
22037         Supplying <tt>0</tt> (zero) as the last argument
22038         will release system resources for the semaphore,
22039         which then becomes unavailable.
22040         Any pending waits on this semaphore
22041         in other child threads or processes
22042         will be released.
22043 </p>
22044
22045 <p>
22046         On Win32, only parent and child processes can share a semaphore.
22047         On Linux/UNIX, independent processes can share a semaphore.
22048 </p>
22049
22050 <p>
22051         The following code examples summarize the different syntax forms:
22052 </p>
22053
22054 <blockquote>
22055 <pre>
22056 ;; init semaphores
22057 (semaphore)
22058
22059 ;; assign a semaphore to sid
22060 (set 'sid (semaphore))
22061
22062 ;; inquire the state of a semaphore (not on Win32)
22063 (semaphore sid)
22064
22065 ;; put sid semaphore in wait state (-1)
22066 (semaphore sid -1)
22067
22068 ;; run sid semaphore previously put in wait (always 1)
22069 (semaphore sid 1)
22070
22071 ;; run sid semaphore with X times a skip (backward or forward) on the function
22072 (semaphore sid X)
22073
22074 ;; release sid semaphore systemwide (always 0)
22075 (semaphore sid 0)
22076 </pre>
22077 </blockquote>
22078
22079 <p>
22080         The following example shows semaphores controlling a child process:
22081 </p>
22082
22083 <b>example:</b>
22084 <blockquote>
22085 <pre>
22086 ;; counter thread output in bold
22087
22088 (define (counter n)
22089         (println "counter started")
22090         (dotimes (x n)
22091                 (semaphore sid -1)
22092                 (println x)))
22093
22094 ;; hit extra &lt;enter&gt; to make the prompt come back
22095 ;; after output to the console from counter thread
22096
22097 &gt; (set 'sid (semaphore))
22098
22099 &gt; (semaphore sid)
22100 <b>0</b>
22101
22102 &gt; (fork (counter 100))
22103
22104 <b>counter started</b>
22105 &gt; (semaphore sid 1)
22106 <b>0</b>
22107 &gt; (semaphore sid 3)
22108 <b>1</b>
22109 <b>2</b>
22110 <b>3</b>
22111 &gt; (semaphore sid 2)
22112 <b>4</b>
22113
22114 <b>5</b>
22115 &gt; _
22116 </pre>
22117 </blockquote>
22118
22119 <p>
22120         After the semaphore is acquired in <tt>sid</tt>,
22121         it has a value of <tt>0</tt>
22122         (the non-signaled state).
22123         When starting the thread <tt>counter</tt>,
22124         the semaphore will block after the initial start message
22125         and will wait in the semaphore call.
22126         The <tt>-1</tt> is trying to decrement the semaphore,
22127         which is not possible because its value is already zero.
22128         In the interactive, main parent process,
22129         the semaphore is signaled by raising its value by <tt>1</tt>.
22130         This unblocks the semaphore call in the <tt>counter</tt> thread,
22131         which can now decrement the semaphore from <tt>1</tt> to <tt>0</tt>
22132         and execute the <tt>print</tt> statement.
22133         When the semaphore call is reached again,
22134         it will block because the semaphore is already in the wait
22135         (<tt>0</tt>) state.
22136 </p>
22137
22138 <p>
22139         Subsequent calls to <tt>semaphore</tt>
22140         with numbers greater than <tt>1</tt>
22141         give the <tt>counter</tt> thread an opportunity
22142         to decrement the semaphore several times before blocking.
22143 </p>
22144
22145 <p>
22146         More than one thread can participate in controlling the semaphore,
22147         just as more than one semaphore can be created.
22148         The maximum number of semaphores is controlled
22149         by a systemwide kernel setting on UNIX-like operating systems.
22150 </p>
22151
22152 <p>
22153         Use the <a href="#fork">fork</a> function
22154         to start a new thread
22155         and the <a href="#share">share</a> function
22156         to share information between threads.
22157         For a more comprehensive example of
22158         using <tt>semaphore</tt> to synchronize threads,
22159         see the <a href="#example_prodcons">prodcons.lsp</a> example
22160         in the <tt>examples/</tt> directory
22161         in the source distribution,
22162         as well as the examples and modules
22163         distributed with newLISP.
22164 </p>
22165
22166 <br /><br />
22167
22168 <a NAME="sequence"></a>
22169 <h2><span class="function">sequence</span></h2>
22170 <b>syntax: (sequence <em>num-start</em> <em>num-end</em> [<em>num-step</em>])</b>
22171
22172 <p>
22173         Generates a sequence of numbers
22174         from <em>num-start</em> to <em>num-end</em>
22175         with an optional step size of <em>num-step</em>.
22176         When <em>num-step</em> is omitted,
22177         the value <tt>1</tt> (one) is assumed.
22178         The generated numbers are of type integer
22179         (when no optional step size is specified)
22180         or floating point
22181         (when the optional step size is present).
22182 </p>
22183
22184 <b>example:</b>
22185 <blockquote>
22186 <pre>
22187 (sequence 10 5)     <span class=arw>&rarr;</span> (10 9 8 7 6 5)
22188 (sequence 0 1 0.2)  <span class=arw>&rarr;</span> (0 0.2 0.4 0.6 0.8 1)
22189 (sequence 2 0 0.3)  <span class=arw>&rarr;</span> (2 1.7 1.4 1.1 0.8 0.5 0.2)
22190 </pre>
22191 </blockquote>
22192
22193 <p>
22194         Note that the step size must be a positive number,
22195         even if sequencing from a higher to a lower number.
22196 </p>
22197
22198 <p>
22199         Use the <a HREF="#series">series</a> function
22200         to generate geometric sequences.
22201 </p>
22202
22203 <br /><br />
22204
22205 <a NAME="series"></a>
22206 <h2><span class="function">series</span></h2>
22207
22208 <b>syntax: (series <em>num-start</em> <em>num-factor</em> <em>num-count</em>)</b>
22209
22210 <p>
22211         Creates a geometric sequence
22212         with <em>num-count</em> elements
22213         starting with the element in <em>num-start</em>.
22214         Each subsequent element
22215         is multiplied by <em>num-factor</em>.
22216         The generated numbers
22217         are always floating point numbers.
22218 </p>
22219
22220 <p>When <em>num-count</em> is less then <tt>1</tt> then <tt>series</tt>
22221 returns an empty list.</p>
22222
22223 <b>example:</b>
22224 <blockquote>
22225 <pre>
22226 (series 2 2 5)     <span class=arw>&rarr;</span> (2 4 8 16 32)
22227 (series 1 1.2 6)   <span class=arw>&rarr;</span> (1 1.2 1.44 1.728 2.0736 2.48832)
22228 (series 10 0.9 4)  <span class=arw>&rarr;</span> (10 9 8.1 7.29)
22229 (series 0 0 10)    <span class=arw>&rarr;</span> (0 0 0 0 0 0 0 0 0 0)
22230 (series 99 1 5)    <span class=arw>&rarr;</span> (99 99 99 99 99)
22231 </pre>
22232 </blockquote>
22233
22234 <p>
22235         Use the <a HREF="#sequence">sequence</a> function
22236         to generate arithmetic sequences.
22237 </p>
22238
22239 <br /><br />
22240
22241 <a NAME="set"></a>
22242 <h2><span class="function">set</span></h2>
22243 <b>syntax: (set <em>sym-1</em> <em>exp-1</em> [<em>sym-2</em> <em>exp-2</em> ... ])</b>
22244
22245 <p>
22246         Evaluates both arguments and
22247         then assigns the result of <em>exp</em>
22248         to the symbol found in <em>sym</em>.
22249         The <tt>set</tt> expression
22250         returns the result of the assignment.
22251         The assignment is performed by copying
22252         the contents of the right side
22253         into the symbol.
22254         The old contents of the symbol
22255         are deleted.
22256         An error message results
22257         when trying to change the contents
22258         of the symbols <tt>nil</tt>, <tt>true</tt>,
22259         or a context symbol.
22260         <tt>set</tt> can take multiple argument pairs.
22261 </p>
22262
22263 <b>example:</b>
22264 <blockquote>
22265 <pre>
22266 (set 'x 123)     <span class=arw>&rarr;</span> 123
22267 (set 'x 'y)      <span class=arw>&rarr;</span> y
22268 (set x "hello")  <span class=arw>&rarr;</span> "hello"
22269
22270 y  <span class=arw>&rarr;</span> "hello"
22271
22272 (set 'alist '(1 2 3))  <span class=arw>&rarr;</span> (1 2 3)
22273
22274
22275 (set 'x 1 'y "hello")  <span class=arw>&rarr;</span> "hello"  ; multiple arguments
22276
22277 x  <span class=arw>&rarr;</span> 1
22278 y  <span class=arw>&rarr;</span> "hello"
22279 </pre>
22280 </blockquote>
22281
22282 <p>
22283         The symbol for assignment
22284         could be the result
22285         from another newLISP expression:
22286 </p>
22287
22288 <blockquote>
22289 <pre>
22290 (set 'lst '(x y z))  <span class=arw>&rarr;</span> (x y z)
22291
22292 (set (first lst) 123)  <span class=arw>&rarr;</span> 123
22293
22294 x  <span class=arw>&rarr;</span> 123
22295 </pre>
22296 </blockquote>
22297
22298 <p>
22299         Symbols can be set to
22300         lambda or lambda-macro expressions.
22301         This operation is equivalent
22302         to using <a HREF="#define">define</a>
22303         or <a HREF="#define-macro">define-macro</a>.
22304 </p>
22305
22306 <blockquote>
22307 <pre>
22308 (set 'double (lambda (x) (+ x x)))
22309 <span class=arw>&rarr;</span> (lambda (x) (+ x x))
22310 </pre>
22311 </blockquote>
22312
22313 <p>
22314         is equivalent to:
22315 </p>
22316
22317 <blockquote>
22318 <pre>
22319 (define (double x) (+ x x))
22320 <span class=arw>&rarr;</span> (lambda (x) (+ x x))
22321 </pre>
22322 </blockquote>
22323
22324 <p>
22325         is equivalent to:
22326 </p>
22327
22328 <blockquote>
22329 <pre>
22330 (define double (lambda (x) (+ x x)))
22331 <span class=arw>&rarr;</span> (lambda (x) (+ x x))
22332 </pre>
22333 </blockquote>
22334
22335 <p>
22336         Use the <a href="#constant">constant</a> function
22337         (which works like <tt>set</tt>)
22338         to protect the symbol from subsequent alteration.
22339         Using the <a href="#setq">setq</a> function
22340         eliminates the need to quote the variable symbol.
22341 </p>
22342
22343 <br /><br />
22344
22345 <a NAME="setq"></a>
22346 <h2><span class="function">setq</span></h2>
22347 <b>syntax: (setq <em>sym-1</em> <em>exp-1</em>&nbsp;[<em>sym-2</em> <em>exp-2</em> ... ])</b>
22348
22349 <p>
22350         Works just like <a href="#set">set</a>,
22351         except the symbol in <em>sym</em>
22352         is not quoted.
22353         Like <a href="#set">set</a>,
22354         <tt>setq</tt> can take multiple arguments.
22355 </p>
22356
22357 <b>example:</b>
22358 <blockquote>
22359 <pre>
22360 (setq x 123)  <span class=arw>&rarr;</span> 123
22361
22362 ; multiple args
22363
22364 (setq x 1 y 2 z 3)  <span class=arw>&rarr;</span> 3
22365
22366 x  <span class=arw>&rarr;</span> 1
22367 y  <span class=arw>&rarr;</span> 2
22368 z  <span class=arw>&rarr;</span> 3
22369 </pre>
22370 </blockquote>
22371
22372 <br /><br />
22373
22374
22375 <a NAME="set-locale"></a>
22376 <h2><span class="function">set-locale</span></h2>
22377 <b>syntax: (set-locale [<em>str-locale</em> [<em>int-category</em>]])</b>
22378
22379 <p>
22380         Reports or switches to a different locale
22381         on your operating system or platform.
22382         When used without arguments,
22383         <em>set-locale</em> reports
22384         the current locale being used.
22385         When <em>str-locale</em> is specified,
22386         <em>set-locale</em> switches to the locale
22387         with all category options turned on
22388         (<tt>LC_ALL</tt>).
22389         Placing an empty string in <em>str-locale</em>
22390         switches to the default locale
22391         used on the current platform.
22392         <tt>set-locale</tt> returns either the current settings
22393         or <tt>nil</tt> if the requested change
22394         could not be performed.
22395 </p>
22396
22397 <b>example:</b>
22398 <blockquote>
22399 <pre>
22400 (set-locale)     ; report current locale
22401
22402 (set-locale "")  ; set default locale of your platform
22403 </pre>
22404 </blockquote>
22405
22406 <p>
22407         By default,
22408         newLISP starts up with the POSIX C default locale.
22409         This guarantees that newLISP's behavior will be identical
22410         on any platform locale:
22411 </p>
22412
22413 <blockquote>
22414 <pre>
22415 ;; after newLISP start up
22416
22417 (set-locale)  <span class=arw>&rarr;</span> "C"
22418 </pre>
22419 </blockquote>
22420
22421 <p>
22422         In <em>int-category</em>,
22423         integer numbers may be specified
22424         as <em>category options</em>
22425         for fine-tuning certain aspects
22426         of the locale,
22427         such as number display,
22428         date display, and so forth.
22429         The numbers used vary from system to system.
22430         The options valid on your platform
22431         can be found in the C include file <tt>locale.h</tt>.
22432         This file defines constants like
22433         <tt>LC_ALL, LC_NUMERIC,</tt> and <tt>LC_MONETARY</tt>.
22434         When <tt>set-locale</tt> is used without the option number,
22435         it assumes the <tt>LC_ALL</tt> option,
22436         which turns on all options for that locale.
22437 </p>
22438
22439 <p>
22440         Note that the locale also controls
22441         the decimal separator in numbers.
22442         The default C locale uses the decimal dot,
22443         but most others use a decimal comma.
22444         Since version 8.4.4,
22445         newLISP has been parsing decimal comma numbers correctly.
22446 </p>
22447
22448 <p>
22449         Note that using <tt>set-locale</tt>
22450         does not change the behavior
22451         of regular expressions in newLISP.
22452         To localize the behavior of PCRE
22453         (Perl Compatible Regular Expressions),
22454         newLISP must be compiled
22455         with different character tables.
22456         See the file, LOCALIZATION,
22457         in the newLISP source distribution
22458         for details.
22459 </p>
22460
22461 <p>
22462         See also the chapter <a href="#switching">Switching the locale</a>.
22463 </p>
22464
22465 <br /><br />
22466
22467
22468 <a NAME="set-nth"></a>
22469 <h2><span class="function">set-nth</span></h2>
22470
22471 <b>syntax: (set-nth <em>int-nth-1</em> [ <em>int-nth-2</em> ... ] <em>list</em>|<em>array</em> <em>exp-replacement</em>)</b><br />
22472
22473 <b>syntax: (set-nth <em>int-nth-1</em> <em>str</em> <em>str-replacement</em>)</b><br /><br />
22474
22475 <b>syntax: (set-nth (<em>list|array</em> <em>int-nth-1</em> [ <em>int-nth-2</em> ... ]) <em>exp-replacement</em>)</b><br />
22476
22477 <b>syntax: (set-nth (<em>str int-nth-1</em>) <em>str</em> <em>str-replacement</em>)</b>
22478
22479 <p>
22480         <tt>set-nth</tt> works like <a href="#nth-set">nth-set</a>,
22481         except instead of returning the replaced element,
22482         it returns the entire changed expression.
22483         For this reason,
22484         <tt>set-nth</tt> is slower on larger data objects.
22485
22486 </p>
22487
22488 <br /><br />
22489
22490
22491 <a NAME="set-ref"></a>
22492 <h2><span class="function">set-ref</span></h2>
22493 <b>syntax: (set-ref (<em>list</em> <em>exp-key</em>) <em>exp-replacement</em> [<em>func-compare</em>])</b><br />
22494
22495 <p>Searches for <em>exp-key</em> in <em>list</em> and replaces the found element with <em>exp-replacement</em>.
22496 The <em>list</em> can be nested. The system variable <tt>$0</tt> contains the expression found
22497 and can be used in <em>exp-replacement</em>. The function works like <a href="#ref-set">ref-set</a> but returns
22498 the whole list changed instead of the old element.</p>
22499
22500 <br /><br />
22501
22502
22503 <a NAME="set-ref-all"></a>
22504 <h2><span class="function">set-ref-all</span></h2>
22505 <b>syntax: (set-ref-all (<em>list</em> <em>exp-key</em>) <em>exp-replacement</em> [<em>func-compare</em>])</b><br />
22506
22507 <p>Searches for <em>exp-key</em> in <em>list</em> and replaces each instance of the found element with <em>exp-replacement</em>.
22508 The <em>list</em> can be nested. The system variable <tt>$0</tt> contains the expression found
22509 and can be used in <em>exp-replacement</em>. The function works like <a href="#ref-set">ref-set</a> but returns
22510 the whole list changed:</p>
22511
22512 <b>example:</b>
22513 <blockquote>
22514 <pre>
22515 (set 'data '((monday (apples 20 30) (oranges 2 4 9)) (tuesday (apples 5) (oranges 32 1))))
22516
22517 (set-ref-all (data 'apples) "Apples")
22518     <span class=arw>&rarr;</span> ((monday ("Apples" 20 30) ...  (tuesday ("Apples" 5) ...)))
22519 </pre>
22520 </blockquote>
22521
22522 <p>Using the default functor in the <tt>(<em>list</em> <em>key</em>)</tt> pattern allows the
22523 list to be passed by reference to a userdefined function containing a <tt>set-ref-all</tt>
22524 statemen. This would result in less memory usage and higher speeds in when doing replacements
22525 in large lists:</p>
22526
22527 <blockquote>
22528 <pre>
22529 (set 'data:data '((monday (apples 20 30) (oranges 2 4 9)) (tuesday (apples 5) (oranges 32 1))))
22530
22531 (define (foo ctx)
22532         ...
22533         (set-ref-all (ctx 'apples) "Apples")
22534         ...
22535 )
22536
22537 (foo data)
22538 </pre>
22539 </blockquote>
22540
22541 <p>When evaluating <tt>(foo data)</tt>, the list in <tt>data:data</tt> will be passed
22542 by reference and <tt>set-ref-all</tt> will make the changes on the original, not on
22543 a copy of <tt>data:data</tt>.</p>
22544
22545 <p>Like <a href="#find">find</a>, <a href="#replace">replace</a>,
22546 <a href="#ref">ref</a> and <a href="#ref-all">ref-all</a>,
22547 complex searches can be expressed using
22548 <a href="#match">match</a> or <a href="#unify">unify</a> in <em>func-compare</em>:</p>
22549
22550 <blockquote>
22551 <pre>
22552 (set 'data '((monday (apples 20 30) (oranges 2 4 9)) (tuesday (apples 5) (oranges 32 1))))
22553
22554 (set-ref-all (date '(oranges *)) (list (first $0) (apply + (rest $0))) match)
22555     <span class=arw>&rarr;</span> (... (oranges 15) ... (oranges 33) ...)
22556 </pre>
22557 </blockquote>
22558
22559 <p>The example sums all numbers found in records starting with the symbol <tt>oranges</tt>.
22560
22561 <p>See also <a href="#ref-set">ref-set</a> and <a href="#set-ref">set-ref</a> which replace
22562 only the first element found.</p>
22563
22564 <br /><br />
22565
22566 <a NAME="sgn"></a>
22567 <h2><span class="function">sgn</span></h2>
22568 <b>syntax: (sgn <em>num</em>)</b><br />
22569 <b>syntax: (sgn <em>num</em> <em>expr-1</em> [<em>expr-2</em>] [<em>expr-3</em>])</b>
22570
22571 <p>
22572         In the first syntax,
22573         the <tt>sgn</tt> function is a logical function
22574         that extracts the sign of a real number
22575         according to the following rules:
22576 </p>
22577
22578 <blockquote><b><em>
22579 x &gt; 0 : sgn(x) = 1<br />
22580 x &lt; 0 : sgn(x) = -1<br />
22581 x = 0 : sgn(x) = 0<br />
22582 </em></b></blockquote>
22583
22584 <b>example:</b>
22585 <blockquote>
22586 <pre>
22587 (sgn -3.5)  <span class=arw>&rarr;</span> -1
22588 (sgn 0)     <span class=arw>&rarr;</span> 0
22589 (sgn 123)   <span class=arw>&rarr;</span> 1
22590 </pre>
22591 </blockquote>
22592
22593 <p>
22594         In the second syntax, the result of evaluating
22595         one of the optional expressions
22596         <em>expr-1</em>, <em>expr-2</em>, or <em>expr-3</em> is returned,
22597         instead of <tt>-1</tt>, <tt>0</tt>, or <tt>1</tt>.
22598         In absence of expression <em>expr-2</em> or <em>expr-3</em>,
22599         <tt>nil</tt> is returned.
22600 </p>
22601
22602 <b>example:</b>
22603 <blockquote>
22604 <pre>
22605 (sgn x -1 0 1)         ; works like (sgn x)
22606 (sgn x -1 1 1)         ; return -1 for negative x all others 1
22607 (sgn x nil true true)  ; return nil for negative else true
22608 (sgn x (abs x) 0)      ; return (abs x) for negative x, 0 for x = 0, else nil
22609 </pre>
22610 </blockquote>
22611
22612 <p>
22613         Any expression or constant can be used for
22614         <em>expr-1</em>, <em>expr-2</em>, or <em>expr-3</em>.
22615 </p>
22616
22617 <br /><br />
22618
22619
22620 <a NAME="share"></a>
22621 <h2><span class="function">share</span></h2>
22622 <b>syntax: (share)</b><br />
22623 <b>syntax: (share <em>int-address-or-handle</em>)</b><br />
22624 <b>syntax: (share <em>int-address-or-handle</em> <em>exp-value</em>)</b><br /><br />
22625 <b>syntax: (share <em>nil</em> <em>int-address</em>)</b>
22626
22627 <p>
22628         Accesses shared memory
22629         for communicating between
22630         several newLISP processes or threads.
22631         When called without arguments,
22632          <tt>share</tt> requests a page of shared memory
22633         (the page is 4k on Win32 but may differ on Linux/UNIX)
22634         from the operating system.
22635         This returns a memory address on Linux/UNIX
22636         and a handle on Win32,
22637         which can then be
22638         assigned to a variable
22639         for later reference.
22640     This function is not available on OS/2.
22641 </p>
22642
22643 <p>
22644         To set the contents of shared memory,
22645         use the third syntax of <tt>share</tt>.
22646         Supply a shared memory address on Linux/UNIX
22647         or a handle on Win32 in <em>int-address-or-handle</em>,
22648         along with an integer, float, or string expression
22649         in <em>exp-value</em>.
22650         Using this syntax,
22651         the value supplied in <em>exp-value</em>
22652         is also the return value.
22653 </p>
22654
22655 <p>
22656         To access the contents of shared memory,
22657         use the second syntax of <tt>share</tt>,
22658         supplying only the shared memory address or handle.
22659         The return value will be an integer or floating point number,
22660         a string, or <tt>nil</tt> or <tt>true</tt>.
22661         If the memory has not been previously set to a value,
22662         <tt>nil</tt> will be returned.
22663 </p>
22664
22665 <p>
22666         Only available on UNIX-like operating systems,
22667         the last syntax unmaps a shared memory address.
22668         Note that using a shared address after unmapping it
22669         will crash the system.
22670 </p>
22671
22672 <p>
22673         Memory can be shared between
22674         parent and child processes or threads,
22675         but not between independent processes.
22676 </p>
22677
22678 <b>example:</b>
22679 <blockquote>
22680 <pre>
22681 (set 'num (share))
22682 (set 'str (share))
22683
22684 (share num 123)  <span class=arw>&rarr;</span> 123
22685
22686 (share str "hello world") <span class=arw>&rarr;</span> "hello world"
22687 (share str)               <span class=arw>&rarr;</span> "hello world"
22688
22689 (share mVar 123)  <span class=arw>&rarr;</span> 123
22690 (share mVar)      <span class=arw>&rarr;</span> 123
22691
22692 (share mVar true)  <span class=arw>&rarr;</span> true
22693 (share mVar)       <span class=arw>&rarr;</span> true
22694
22695 (share nil mVar)  <span class=arw>&rarr;</span> true  ; unmap only on UNIX
22696 </pre>
22697 </blockquote>
22698
22699 <p>
22700         For a more comprehensive example of using shared memory
22701         in a multithreaded Linux/UNIX application,
22702         see the file <tt>example/prodcons.lsp</tt> in the
22703         newLISP source distribution.
22704 </p>
22705
22706 <p>
22707         Note that shared memory access
22708         between different threads or processes
22709         should be synchronized using a <a href="#semaphore">semaphore</a>.
22710         Simultaneous access to shared memory
22711         can crash the running process/thread.
22712 </p>
22713
22714 <p>
22715         To find out the maximum length of a string buffer
22716         that could be stored in a shared memory address,
22717         execute the following:
22718 </p>
22719
22720 <blockquote>
22721 <pre>
22722 (length (share (share) (dup " " 1000000)))
22723 <span class=arw>&rarr;</span> 4087
22724 </pre>
22725 </blockquote>
22726
22727 <p>
22728         The statement above tries to initialize
22729         a shared memory address to 100,000 bytes,
22730         but only <tt>4087</tt> will be initialized
22731         as a string buffer.
22732         The page size of this platform is
22733         <tt>4096 bytes</tt>&mdash;<tt>4087</tt> plus <tt>8 bytes</tt>
22734         of header information for type and size,
22735         as well as 1 terminating byte for displayable strings.
22736 </p>
22737
22738 <p>
22739         On Linux/UNIX systems,
22740         more than one number or string
22741         can be stored in one memory page
22742         by using offsets added to the main segment address:
22743 </p>
22744
22745 <b>example:</b>
22746 <blockquote>
22747 <pre>
22748 ;; Linux/UNIX only
22749
22750 (set 'num-1 (share))
22751 (set 'num-2 (+ num-1 12))
22752 (set 'num-3 (+ num-2 12))
22753 (set 'str-1 (+ num-3 12))
22754
22755 (share num-1 123)
22756 (share num-2 123.456)
22757  &hellip;
22758
22759 (share num-1)  <span class=arw>&rarr;</span> 123
22760 (share num-3)  <span class=arw>&rarr;</span> 123.456
22761  &hellip;
22762
22763 ;; etc.
22764 </pre>
22765 </blockquote>
22766
22767 <p>
22768         For numbers, reserve 12 bytes;
22769         for strings, reserve 12 bytes,
22770         plus the length of the string,
22771         as well as 1 for the terminating zero-byte.
22772         For the boolean values <tt>nil</tt> and <tt>true</tt>,
22773         4 bytes should be reserved.
22774 </p>
22775
22776 <p>
22777         Note that a shorter string
22778         could accidentally be overwritten
22779         with a longer one.
22780         Therefore,
22781         shared strings should be stored
22782         after other shared number fields
22783         or should reside on their own shared memory page.
22784 </p>
22785
22786 <p>
22787         The functions <a href="#get-int">get-int</a>,
22788         <a href="#get-float">get-float</a>,
22789         <a href="#get-string">get-string</a>,
22790         and <a href="#get-char">get-char</a>&mdash;as
22791         well as <a href="#pack">pack</a>
22792         and <a href="#unpack">unpack</a>&mdash;could
22793         also be used to access contents
22794         from a shared memory page.
22795         This low-level address
22796         requires precise knowledge
22797         of the type of information stored,
22798         but it allows for very compact storage
22799         of information without type/header information
22800         in a string buffer.
22801 </p>
22802
22803 <b>example:</b>
22804 <blockquote>
22805 <pre>
22806 ;; Linux/UNIX and Win32
22807
22808 (set 'mem (share))
22809
22810 (mem share (pack "s5 ld lf" "hello" 123 123.456))
22811 (unpack "s10 ls lf" (mem share))
22812 <span class=arw>&rarr;</span> ("hello" 123 123.456)
22813 </pre>
22814 </blockquote>
22815
22816 <p>
22817         On Linux/UNIX,
22818         supplying a wrong or unmapped share address
22819         can cause newLISP to crash.
22820 </p>
22821
22822 <br /><br />
22823
22824
22825 <a NAME="signal"></a>
22826 <h2><span class="function">signal</span></h2>
22827 <b>syntax: (signal <em>int-signal</em> <em>sym-handler</em>)</b> <br />
22828 <b>syntax: (signal <em>int-signal</em> <em>func-handler</em>)</b> <br />
22829
22830 <b>syntax: (signal <em>int-signal</em>&nbsp;&nbsp;nil | true)</b> <br />
22831 <b>syntax: (signal <em>int-signal</em>)</b>
22832
22833 <p>
22834         Sets a user-defined handler in <em>sym-handler</em> for a signal specified in <em>int-signal</em>
22835         or sets to a function expression in <em>func-handler</em>.</p>
22836 <p>
22837         If <tt>nil</tt> is specified,
22838         the signal handler  will be set to <tt>SIG_IGN</tt>, and the signal will be ignored.
22839         Specifying <tt>true</tt> will set the signal handler to <tt>SIG_DFL</tt>, the default handler
22840     of the underlying platform OS. On startup newLISP either specifies an empty
22841     newLISP handler or a Ctrl-C handler for <tt>SIGINT</tt> and a <tt>waitpipd(-1, 0, WNOHANG)</tt>
22842     C-call for <tt>SIGCHLD</tt>.
22843 </p>
22844
22845 <p>
22846         Different signals are available
22847         on different OS platforms
22848         and Linux/UNIX flavors.
22849         The numbers to specify in <em>int-signal</em>
22850         also differ from platform to platform.
22851         Valid values can normally be extracted from a file found in <tt>/usr/include/sys/signal.h</tt> or <tt>/usr/include/signal.h</tt>.
22852 </p>
22853
22854 <p>
22855         Some signals make newLISP exit
22856         even after a user-defined handler
22857         has been specified and executed
22858         (e.g., signal SIGKILL).
22859         This behavior may also be different
22860         on different platforms.
22861 </p>
22862
22863 <b>example:</b>
22864 <blockquote>
22865 <pre>
22866 (constant 'SIGINT 2)
22867 (define (ctrlC-handler) (println "ctrl-C has been pressed"))
22868
22869 (signal SIGINT 'ctrlC-handler)
22870
22871 ; now press ctrl-C
22872 ; the following line will appear
22873 ; this will only work in an interactive terminal window
22874 ; and will not work in the newLISP-GS editor
22875
22876 ctrl-C has been pressed
22877 </pre>
22878 </blockquote>
22879
22880 <p>
22881         On Win32,
22882         the above example would
22883         execute the handler
22884         before exiting newLISP.
22885         On most Linux/UNIX systems,
22886         newLISP would stay loaded
22887         and the prompt would appear
22888         after hitting the [enter] key.
22889 </p>
22890
22891 <p>
22892         Instead of specifying a symbol containing the signal handler,
22893         a function can be specified directly.
22894         The signal number is passed as a parameter:
22895 </p>
22896
22897 <blockquote>
22898 <pre>
22899 (signal SIGINT exit)  <span class=arw>&rarr;</span> $signal-2
22900
22901 (sginal SIGINT (fn (s) (println "signal " s " occurred")))
22902 </pre>
22903 </blockquote>
22904
22905 <p>
22906         Note that the signal SIGKILL
22907         (9 on most platforms)
22908         will always terminate the application
22909         regardless of an existing signal handler.
22910 </p>
22911
22912 <p>
22913         The signal could have been sent
22914         from another shell on the same computer:
22915 </p>
22916
22917 <blockquote>
22918 <pre>
22919 kill -s SIGINT 2035
22920 </pre>
22921 </blockquote>
22922
22923 <p>
22924         In this example,
22925         <tt>2035</tt> is the process ID
22926         of the running newLISP.
22927 </p>
22928
22929 <p>
22930         The signal could also have been sent
22931         from another newLISP application:
22932 </p>
22933
22934 <blockquote>
22935 <pre>
22936 (constant 'SIGINT 2)
22937 (import "libc.so" "kill")
22938
22939 (kill 2035 SIGINT)
22940 </pre>
22941 </blockquote>
22942
22943 <p>
22944         When importing <tt>kill</tt>,
22945         make sure it always receives an integer
22946         for the signal number.
22947         If needed,
22948         use the <a href="#int">int</a> function
22949         to first convert the number.
22950 </p>
22951
22952 <p>
22953         If newLISP receives a signal
22954         while evaluating another function,
22955         it will still accept the signal
22956         and the handler function will be executed:
22957 </p>
22958
22959 <blockquote>
22960 <pre>
22961 (constant 'SIGINT 2)
22962 (define (ctrlC-handler) (println "ctrl-C has been pressed"))
22963
22964 (signal SIGINT 'ctrlC-handler)
22965 ;; or
22966 (signal SIGINT ctrlC-handler)
22967
22968
22969 (while true (sleep 300) (println "busy"))
22970
22971 ;; generates following output
22972 busy
22973 busy
22974 busy
22975 ctrl-C has been pressed
22976 busy
22977 busy
22978 &hellip;
22979 </pre>
22980 </blockquote>
22981
22982 <p>
22983         Specifying only a signal number
22984         will return either the name of
22985         the current defined handler function
22986         or <tt>nil</tt>.
22987 </p>
22988
22989 <p>
22990         The user-defined signal handler
22991         can pass the the signal number
22992         as a parameter.
22993 </p>
22994
22995 <blockquote>
22996 <pre>
22997 (define (signal-handler sig)
22998         (println "received signal: " sig))
22999
23000 ;; set all signals from 1 to 8 to the same handler
23001 (for (s 1 8)
23002         (signal s 'signal-handler))
23003 </pre>
23004 </blockquote>
23005
23006 <p>
23007         In this example,
23008         all signals from 1 to 8 are set
23009         to the same handler.
23010 </p>
23011
23012
23013 <br /><br />
23014
23015
23016 <a NAME="silent"></a>
23017 <h2><span class="function">silent</span></h2>
23018
23019 <b>syntax: (silent [<em>expr-1</em> [<em>expr-2</em> ... ]])</b>
23020
23021 <p>
23022         Evaluates one or more expressions in <em>expr-1</em>&mdash;.
23023         <tt>silent</tt> is similar to <a HREF="#begin">begin</a>,
23024         but it suppresses console output
23025         of the return value
23026         and the following prompt.
23027         It is often used
23028         when communicating from
23029         a remote application with newLISP
23030         (e.g., GUI front-ends
23031         or other applications controlling newLISP),
23032         and the return value is of no interest.
23033 </p>
23034
23035 <p>
23036         Silent mode is reset when returning to a prompt.
23037         This way,
23038         it can also be used without arguments
23039         in a batch of expressions.
23040         When in interactive mode,
23041         hit [enter] twice after a statement
23042         using <tt>silent</tt>
23043         to get the prompt back.
23044 </p>
23045
23046
23047 <b>example:</b>
23048 <blockquote>
23049 <pre>
23050 (silent (my-func))  ; same as next
23051
23052 (silent) (my-func)  ; same effect as previous
23053 </pre>
23054 </blockquote>
23055
23056 <br /><br />
23057
23058 <a NAME="sin"></a>
23059 <h2><span class="function">sin</span></h2>
23060 <b>syntax: (sin <em>num-radians</em>)</b>
23061
23062 <p>
23063         Calculates the sine function
23064         from <em>num-radians</em>
23065         and returns the result.
23066 </p>
23067
23068 <b>example:</b>
23069 <blockquote>
23070 <pre>
23071 (sin 1)                     <span class=arw>&rarr;</span> 0.8414709838
23072 (set 'pi (mul 2 (acos 0)))  <span class=arw>&rarr;</span> 3.141592654
23073 (sin (div pi 2))            <span class=arw>&rarr;</span> 1
23074 </pre>
23075 </blockquote>
23076
23077 <br /><br />
23078
23079 <br /><br />
23080
23081 <a NAME="sinh"></a>
23082 <h2><span class="function">sinh</span></h2>
23083 <b>syntax: (sinh <em>num-radians</em>)</b>
23084
23085 <p>Calculates the hyperbolic sine of <em>num-radians</em>.
23086 The hyperbolic sine is defined mathematically as: <em>(exp (x) - exp (-x)) / 2</em>.
23087 An overflow to <tt>inf</tt> may occur if <em>num-radians</em> is too large.</p>
23088
23089 <b>example:</b>
23090 <blockquote>
23091 <pre>
23092 (sinh 1)     <span class=arw>&rarr;</span> 1.175201194
23093 (sinh 10)    <span class=arw>&rarr;</span> 11013.23287
23094 (sinh 1000)  <span class=arw>&rarr;</span> inf
23095 (sub (tanh 1) (div (sinh 1) (cosh 1))) <span class=arw>&rarr;</span> 0
23096 </pre>
23097 </blockquote>
23098
23099 <br /><br />
23100
23101 <a NAME="sleep"></a>
23102 <h2><span class="function">sleep</span></h2>
23103
23104 <b>syntax: (sleep <em>int-milli-seconds</em>)</b>
23105
23106 <p>
23107         Gives up CPU time
23108         to other processes
23109         for the amount of milliseconds specified
23110         in <em>int-milli-seconds</em>.
23111 </p>
23112
23113 <b>example:</b>
23114 <blockquote>
23115 <pre>
23116 (sleep 1000)  ; sleeps 1 second
23117 </pre>
23118 </blockquote>
23119
23120 <p>
23121         On some platforms,
23122         <tt>sleep</tt> is only available
23123         with a resolution of one second.
23124         In this case,
23125         the parameter <em>int-milli-seconds</em>
23126         will be rounded to the nearest
23127         full second.
23128 </p>
23129
23130 <br /><br />
23131
23132 <a NAME="slice"></a>
23133 <h2><span class="function">slice</span></h2>
23134
23135 <b>syntax: (slice <em>list</em> <em>int-index</em> [<em>int-length</em>])</b><br />
23136 <b>syntax: (slice <em>array</em> <em>int-index</em> [<em>int-length</em>])</b><br />
23137 <b>syntax: (slice <em>str</em> <em>int-index</em> [<em>int-length</em>])</b>
23138
23139 <p>
23140         In the first form,
23141         <tt>slice</tt> copies a sublist
23142         from a <em>list</em>.
23143         The original list is left unchanged.
23144         The sublist extracted
23145         starts at index <em>int-index</em>
23146         and has a length of <em>int-length</em>.
23147         If <em>int-length</em> is negative
23148         <tt>slice</tt> will take the parameter
23149         as offset counting from the end and copy
23150     up to that offset.
23151         If the parameter is omitted,
23152         <tt>slice</tt> copies all of the elements
23153         to the end of the list.
23154 </p>
23155
23156 <p>
23157         See also <a HREF="#indexing">Indexing elements of strings and lists</a>.
23158 </p>
23159
23160 <b>example:</b>
23161 <blockquote>
23162 <pre>
23163 (slice '(a b c d e f) 3 2)   <span class=arw>&rarr;</span> (d e)
23164 (slice '(a b c d e f) 2 -2)  <span class=arw>&rarr;</span> (c d)
23165 (slice '(a b c d e f) 2)  <span class=arw>&rarr;</span> (c d e f)
23166 (slice '(a b c d e f) -4 3)  <span class=arw>&rarr;</span> (c d e)
23167
23168 (set 'A (array 3 2 (sequence 1 6))) <span class=arw>&rarr;</span> ((1 2) (3 4) (5 6))
23169 (slice A 1 2) <span class=arw>&rarr;</span> ((3 4) (5 6))
23170 </pre>
23171 </blockquote>
23172
23173 <p>
23174         In the second form,
23175         a part of the string in <em>str</em>
23176         is extracted.
23177         <em>int-index</em> contains the start index
23178         and <em>int-length</em> contains the length
23179         of the substring.
23180         If <em>int-length</em> is not specified,
23181         everything to the end of the string is extracted.
23182         <tt>slice</tt> also works on string buffers
23183         containing binary data like 0's (zeroes).
23184         It operates on byte boundaries
23185         rather than character boundaries.
23186         See also <a HREF="#indexing">Indexing elements of strings and lists</a>.
23187 </p>
23188
23189 <b>example:</b>
23190 <blockquote>
23191 <pre>
23192 (slice "Hello World" 6 2)  <span class=arw>&rarr;</span> "Wo"
23193 (slice "Hello World" 0 5)  <span class=arw>&rarr;</span> "Hello"
23194 (slice "Hello World" 6)    <span class=arw>&rarr;</span> "World"
23195 (slice "newLISP" -4 2)     <span class=arw>&rarr;</span> "LI"
23196 </pre>
23197 </blockquote>
23198
23199 <p>
23200         Note that an <em>implicit slice</em>
23201         is available for lists.
23202         See the chapter <a href="#implicit_rest_slice">Implicit rest and slice</a>.
23203 </p>
23204
23205 <p>
23206         Be aware that <a href="#slice">rest</a>
23207         always works on byte boundaries
23208         rather than character boundaries
23209         in the UTF-8&ndash;enabled version of newLISP.
23210         As a result,
23211         <a href="#slice">slice</a> can be used
23212         to manipulate binary content.
23213 </p>
23214
23215 <br /><br />
23216
23217 <a NAME="sort"></a>
23218 <h2><span class="function">sort</span></h2>
23219 <b>syntax: (sort <em>list</em> [<em>func-compare</em>])</b><br />
23220
23221 <p>
23222         All members in <em>list</em>
23223         are sorted in ascending order.
23224         Anything may be sorted,
23225         regardless of the types.
23226         When members are themselves lists,
23227         each list element
23228         is recursively compared.
23229         If two expressions
23230         of different types are compared,
23231         the lower type is sorted
23232         before the higher type
23233         in the following order:
23234 </p>
23235
23236 <pre>
23237   Atoms: nil, true, integer or float, string, symbol, primitive
23238
23239   Lists: quoted expression, list, lambda, lambda-macro
23240 </pre>
23241
23242 <p>
23243         The sort is destructive,
23244         changing the order of the elements in the original list.
23245         The return value of <tt>sort</tt> is a copy of the sorted list.
23246 </p>
23247
23248 <p>
23249         An optional comparison operator,
23250         user-defined function,
23251         or anonymous function
23252         can be supplied.
23253         The functor or operator
23254         can be given with or without
23255         a preceding quote.
23256 </p>
23257
23258 <b>example:</b>
23259 <blockquote>
23260 <pre>
23261 (sort '(v f r t h n m j))     <span class=arw>&rarr;</span> (f h j m n r t v)
23262 (sort '((3 4) (2 1) (1 10)))  <span class=arw>&rarr;</span> ((1 10) (2 1) (3 4))
23263 (sort '((3 4) "hi" 2.8 8 b))  <span class=arw>&rarr;</span> (2.8 8 "hi" b (3 4))
23264
23265 (set 's '(k a l s))
23266 (sort s)  <span class=arw>&rarr;</span> (a k l s)
23267
23268 (sort '(v f r t h n m j) '&gt;)
23269 <span class=arw>&rarr;</span> (v t r n m j h f)
23270 ;; the quote can be omitted beginning with version 8.4.5
23271 (sort '(v f r t h n m j) &gt;)
23272 <span class=arw>&rarr;</span> (v t r n m j h f)
23273 (sort s &lt;)  <span class=arw>&rarr;</span> (a k l s)
23274 (sort s &gt;)  <span class=arw>&rarr;</span> (s l k a)
23275 s           <span class=arw>&rarr;</span> (s l k a)
23276
23277 ;; define a comparison function
23278 (define (comp x y)
23279     (&gt; (last x) (last y)))
23280
23281 (set 'db '((a 3) (g 2) (c 5)))
23282
23283 (sort db comp)  <span class=arw>&rarr;</span>  ((c 5) (a 3) (g 2))
23284
23285 ;; use an anonymous function
23286 (sort db (fn (x y) (&gt; (last x) (last y))))
23287 </pre>
23288 </blockquote>
23289
23290 <br /><br />
23291
23292 <a NAME="source"></a>
23293 <h2><span class="function">source</span></h2>
23294 <b>syntax: (source)</b><br />
23295 <b>syntax: (source <em>sym-1</em> [<em>sym-2</em> ... ])</b>
23296
23297 <p>
23298         Works almost identically to <a href="#save">save</a>,
23299         except symbols and contexts get serialized to a string
23300         instead of being written to a file.
23301         Multiple variable symbols,
23302         definitions, and contexts
23303         can be specified.
23304         If no argument is given,
23305         <tt>source</tt> serializes the entire
23306         newLISP workspace.
23307         When context symbols are serialized,
23308         any symbols contained within that context
23309         will be serialized, as well.
23310         Symbols containing <tt>nil</tt>
23311         are not serialized.
23312         System symbols beginning with the <tt>$</tt> (dollar sign) character
23313         are only serialized when mentioned explicitly.
23314 </p>
23315
23316 <p>
23317         Symbols not belonging to the current context
23318         are written out with their context prefix.
23319 </p>
23320
23321 <b>example:</b>
23322 <blockquote>
23323 <pre>
23324 (define (double x) (+ x x))
23325
23326 (source 'double)  <span class=arw>&rarr;</span> "(define (double x)\n  (+ x x))\n\n"
23327 </pre>
23328 </blockquote>
23329
23330 <p>
23331         As with <a href="#save">save</a>,
23332         the formatting of line breaks
23333         and leading spaces or tabs
23334         can be controlled using the
23335         <a href="#pretty-print">pretty-print</a> function.
23336 </p>
23337
23338 <br /><br />
23339
23340 <a NAME="sqrt"></a>
23341 <h2><span class="function">sqrt</span></h2>
23342 <b>syntax: (sqrt <em>num</em>)</b>
23343
23344 <p>
23345         Calculates the square root from
23346         the expression in <em>num</em>
23347         and returns the result.
23348 </p>
23349
23350 <b>example:</b>
23351 <blockquote>
23352 <pre>
23353 (sqrt 10)  <span class=arw>&rarr;</span> 3.16227766
23354 (sqrt 25)  <span class=arw>&rarr;</span> 5
23355 </pre>
23356 </blockquote>
23357
23358 <br /><br />
23359
23360 <a NAME="starts-with"></a>
23361 <h2><span class="function">starts-with</span></h2>
23362 <b>syntax: (starts-with <em>str str-key</em> [<em>num-option</em>] )</b><br>
23363 <b>syntax: (starts-with <em>list</em> [<em>expr</em>] )</b>
23364
23365 <p>
23366         In the first version,
23367         <tt>starts-with</tt> checks if the string <em>str</em>
23368         starts with a key string in <em>str-key</em> and
23369         returns <tt>true</tt> or <tt>nil</tt>
23370         depending on the outcome.
23371 </p>
23372
23373 <p>
23374         If a regular expression number is specified in <em>num-option</em>,
23375         <em>str-key</em> contains a regular expression pattern.
23376         See <a href="#regex">regex</a> for valid <em>option</em> numbers.
23377 </p>
23378
23379 <b>example:</b>
23380 <blockquote>
23381 <pre>
23382 (starts-with "this is useful" "this")      <span class=arw>&rarr;</span> true
23383 (starts-with "this is useful" "THIS")      <span class=arw>&rarr;</span> nil
23384 (starts-with "this is useful" "THIS" nil)  <span class=arw>&rarr;</span> true
23385 ;; use regular expressions
23386 (starts-with "this is useful" "this|that" 1)  <span class=arw>&rarr;</span> true
23387
23388 </pre>
23389 </blockquote>
23390
23391 <p>
23392         In the second version,
23393         <tt>starts-with</tt> checks to see if a list
23394         starts with the list element in <em>expr</em>.
23395         <tt>true</tt> or <tt>nil</tt> is returned
23396         depending on outcome.
23397 </p>
23398
23399 <b>example:</b>
23400 <blockquote>
23401 <pre>
23402 (starts-with '(1 2 3 4 5) 1)             <span class=arw>&rarr;</span> true
23403 (starts-with '(a b c d e) 'b)            <span class=arw>&rarr;</span> nil
23404 (starts-with '((+ 3 4) b c d) '(+ 3 4))  <span class=arw>&rarr;</span> true
23405 </pre>
23406 </blockquote>
23407
23408
23409 <p>
23410         See also the <a HREF="#ends-with">ends-with</a> function.
23411 </p>
23412
23413 <br /><br />
23414
23415 <a NAME="string"></a>
23416 <h2><span class="function">string</span></h2>
23417 <b>syntax: (string <em>exp-1</em> [ <em>exp-2</em> ... ])</b>
23418
23419 <p>
23420         Translates into a string anything that results
23421         from evaluating <em>exp-1</em>&mdash;.
23422         If more than one expression is specified,
23423         the resulting strings are concatenated.
23424 </p>
23425
23426 <b>example:</b>
23427 <blockquote>
23428 <pre>
23429 (string 'hello)          <span class=arw>&rarr;</span> "hello"
23430 (string 1234)            <span class=arw>&rarr;</span> "1234"
23431 (string '(+ 3 4))        <span class=arw>&rarr;</span> "(+ 3 4)"
23432 (string (+ 3 4) 8)       <span class=arw>&rarr;</span> "78"
23433 (string 'hello " " 123)  <span class=arw>&rarr;</span> "hello 123"
23434 </pre>
23435 </blockquote>
23436
23437 <p>
23438         If a buffer passed to <tt>string</tt>
23439         contains <tt>\000</tt>,
23440         only the string up to the first terminating zero will be copied:
23441 </p>
23442
23443 <blockquote>
23444 <pre>
23445 (set 'buff "ABC\000\000\000")  <span class=arw>&rarr;</span> "ABC\000\000\000"
23446
23447 (length buff)  <span class=arw>&rarr;</span> 6
23448
23449 (string buff)  <span class=arw>&rarr;</span> "ABC"
23450
23451 (length (string buff))  <span class=arw>&rarr;</span> 3
23452 </pre>
23453 </blockquote>
23454
23455 <p>
23456         Use the <a HREF="#append">append</a>
23457         and <a HREF="#join">join</a>
23458         (allows the joining string
23459         to be specified) functions
23460         to concatenate strings.
23461         Use the <a href="#source">source</a> function
23462         to convert a lambda expression
23463         into its newLISP source string representation.
23464 </p>
23465
23466 <br /><br />
23467
23468 <a NAME="stringp"></a>
23469 <h2><span class="function">string?</span></h2>
23470 <b>syntax: (string? <em>exp</em>)</b>
23471
23472 <p>
23473         Evaluates <em>exp</em> and tests
23474         to see if it is a string.
23475         Returns <tt>true</tt> or <tt>nil</tt>
23476         depending on the result.
23477 </p>
23478
23479 <b>example:</b>
23480 <blockquote>
23481 <pre>
23482 (set 'var "hello")
23483 (string? var)  <span class=arw>&rarr;</span> true
23484 </pre>
23485 </blockquote>
23486
23487 <br /><br />
23488
23489 <a NAME="sub"></a>
23490 <h2><span class="function">sub</span></h2>
23491 <b>syntax: (sub <em>num-1</em> [<em>num-2</em> ... ])</b>
23492
23493 <p>
23494         Successively subtracts
23495         the expressions in <em>num-1</em>,
23496         <em>num-2</em>&mdash;.
23497         <tt>sub</tt> performs mixed-type arithmetic
23498         and handles integers or floating points,
23499         but it will always return
23500         a floating point number.
23501         If only one argument is supplied,
23502         its sign is reversed.
23503         Any floating point calculation
23504         with <tt>NaN</tt> also returns <tt>NaN</tt>.
23505 </p>
23506
23507 <b>example:</b>
23508 <blockquote>
23509 <pre>
23510 (sub 10 8 0.25)  <span class=arw>&rarr;</span> 1.75
23511 (sub 123)        <span class=arw>&rarr;</span> -123
23512 </pre>
23513 </blockquote>
23514
23515 <br /><br />
23516
23517 <a NAME="swap"></a>
23518 <h2><span class="function">swap</span></h2>
23519 <b>syntax: (swap <em>num-1</em> <em>num-2</em> <em>list</em>)</b><br>
23520 <b>syntax: (swap <em>num-1</em> <em>num-2</em> <em>str</em>)</b><br>
23521 <b>syntax: (swap <em>sym-1</em> <em>sym-2</em>)</b>
23522
23523 <p>
23524         In the first form,
23525         <tt>swap</tt> switches the elements in <em>list</em>
23526         at indices <em>num-1 and num-2</em>
23527         and returns the changed list.
23528 </p>
23529
23530 <p>
23531         In the second form,
23532         the characters in <em>str</em> at indices <em>num-1 and num-2</em>
23533         are swapped and the changed string is returned.
23534 </p>
23535
23536 <p>
23537         In the third form,
23538         the contents of the two unquoted symbols in
23539         <em>sym-1 and sym-2</em> are swapped.
23540 </p>
23541
23542 <p>
23543         <tt>swap</tt> is a destructive operation
23544         that changes the contents of the list, string,
23545         or symbols involved.
23546 </p>
23547
23548 <b>example:</b>
23549 <blockquote>
23550 <pre>
23551 (set 'lst '(a b c d e f))
23552
23553 (swap 0 5 lst)  <span class=arw>&rarr;</span> '(f b c d e a)
23554 lst             <span class=arw>&rarr;</span> '(f b c d e a)
23555
23556 (swap 0 -1 lst)  <span class=arw>&rarr;</span> '(a b c d e f)
23557 lst              <span class=arw>&rarr;</span> '(a b c d e f)
23558
23559 (swap 3 4 "abcdef")  <span class=arw>&rarr;</span> "abcedf"
23560
23561 (set 'x 1 'y 2)
23562
23563 (swap x y)  <span class=arw>&rarr;</span> 1
23564
23565 x  <span class=arw>&rarr;</span> 2
23566 y  <span class=arw>&rarr;</span> 1
23567 </pre>
23568 </blockquote>
23569
23570 <br /><br />
23571
23572 <a NAME="sym"></a>
23573 <h2><span class="function">sym</span></h2>
23574 <b>syntax: (sym <em>string</em> [<em>sym-context</em> <em>nil-flag</em>] )</b><br />
23575 <b>syntax: (sym <em>number</em> [<em>sym-context</em> <em>nil-flag</em>] )</b><br />
23576
23577 <b>syntax: (sym <em>symbol</em> [<em>sym-context</em> <em>nil-flag</em>] )</b>
23578
23579 <p>
23580         Translates the first argument in <em>string</em>,
23581         <em>number</em>, or <em>symbol</em>
23582         into a symbol and returns it.
23583         If the optional context is not specified
23584         in <em>sym-context</em>,
23585         the current context is used
23586         when doing symbol lookup or creation.
23587         Symbols will be created
23588         if they do not already exist.
23589         When the context does not exist
23590         and the context is specified by a quoted symbol,
23591         the symbol also gets created.
23592         If the context specification is unquoted,
23593         the context is the specified name
23594         or the context specification is a variable
23595         containing the context.
23596 </p>
23597
23598 <p>
23599         <tt>sym</tt> can create symbols within the symbol table
23600         that are not legal symbols in newLISP source code
23601         (e.g., numbers or names containing special characters
23602         such as parentheses, colons, etc.).
23603         This makes <tt>sym</tt> usable
23604         as a function for associative memory access,
23605         much like <em>hash table</em> access
23606         in other scripting languages.
23607 </p>
23608
23609 <p>
23610         As a third optional argument,
23611         <tt>nil</tt> can be specified
23612         to suppress symbol creation
23613         if the symbol is not found.
23614         In this case,
23615         <tt>sym</tt> returns <tt>nil</tt>
23616         if the symbol looked up does not exist.
23617         Using this last form,
23618         <tt>sym</tt> can be used
23619         to check for the existence
23620         of a symbol.
23621 </p>
23622
23623 <b>example:</b>
23624 <blockquote>
23625 <pre>
23626 (sym "some")           <span class=arw>&rarr;</span> some
23627 (set (sym "var") 345)  <span class=arw>&rarr;</span> 345
23628 var                    <span class=arw>&rarr;</span> 345
23629 (sym "aSym" 'MyCTX)    <span class=arw>&rarr;</span> MyCTX:aSym
23630 (sym "aSym" MyCTX)     <span class=arw>&rarr;</span> MyCTX:aSym  ; unquoted context
23631
23632 (sym "foo" MyCTX nil)  <span class=arw>&rarr;</span> nil  ; 'foo does not exist
23633 (sym "foo" MyCTX)      <span class=arw>&rarr;</span> foo  ; 'foo is created
23634 (sym "foo" MyCTX nil)  <span class=arw>&rarr;</span> foo  ; foo now exists
23635 </pre>
23636 </blockquote>
23637
23638 <p>
23639         Because the function <tt>sym</tt>
23640         returns the symbol looked up or created,
23641         expressions with <tt>sym</tt> can be embedded
23642         directly in other expressions
23643         that use symbols as arguments.
23644         The following example shows
23645         the use of <tt>sym</tt>
23646         as a hash-like function
23647         for associative memory access,
23648         as well as symbol configurations
23649         that are not legal newLISP symbols:
23650 </p>
23651
23652 <b>example:</b>
23653 <blockquote>
23654 <pre>
23655 ;; using sym for simulating hash tables
23656
23657 (set (sym "John Doe" 'MyDB') 1.234)
23658 (set (sym "(" 'MyDB) "parenthesis open")
23659 (set (sym 12 'MyDB) "twelve")
23660
23661 (eval (sym "John Doe" 'MyDB))  <span class=arw>&rarr;</span> 1.234
23662 (eval (sym "(" 'MyDB))         <span class=arw>&rarr;</span> "parenthesis open"
23663 (eval (sym 12 'MyDB))          <span class=arw>&rarr;</span> "twelve"
23664
23665 ;; delete a symbol from a symbol table or hash
23666 (delete (sym "John Doe" 'MyDB))  <span class=arw>&rarr;</span> true
23667 </pre>
23668 </blockquote>
23669
23670 <p>
23671         The last statement shows
23672         how a symbol can be eliminated
23673         using <a href="#delete">delete</a>.
23674 </p>
23675
23676 <p>
23677         The third syntax allows symbols to be used
23678         instead of strings for the symbol name
23679         in the target context.
23680         In this case,
23681         <tt>sym</tt> will extract the name from the symbol
23682         and use it as the name string
23683         for the symbol in the target context:
23684 </p>
23685
23686 <b>example:</b>
23687 <blockquote>
23688 <pre>
23689 (sym 'myVar 'FOO)  <span class=arw>&rarr;</span> FOO:myVar
23690
23691 (define-macro (def-context)
23692   (dolist (s (rest (args)))
23693     (sym s (first (args)))))
23694
23695 (def-context foo x y z)
23696
23697 (symbols foo)  <span class=arw>&rarr;</span> (foo:x foo:y foo:z)
23698 </pre>
23699 </blockquote>
23700
23701 <p>
23702         The <tt>def-context</tt> macro
23703         shows how this could be used
23704         to create a macro that creates
23705         contexts and their variables
23706         in a dynamic fashion.
23707 </p>
23708
23709 <p>
23710         Available since version 8.7.4,
23711         one syntax of the <a href="#context">context</a> function
23712         can be used to create, set, and evaluate symbols
23713         in a shorter, faster way.
23714 </p>
23715
23716 <br /><br />
23717
23718
23719 <a NAME="symbolp"></a>
23720 <h2><span class="function">symbol?</span></h2>
23721 <b>syntax: (symbol? <em>exp</em>)</b><br />
23722
23723 <p>
23724         Evaluates the <em>exp</em> expression
23725         and returns <tt>true</tt> if the value is a symbol;
23726         otherwise, it returns <tt>nil</tt>.
23727 </p>
23728
23729 <b>example:</b>
23730 <blockquote>
23731 <pre>
23732 (set 'x 'y)  <span class=arw>&rarr;</span> y
23733
23734 (symbol? x)  <span class=arw>&rarr;</span> true
23735
23736 (symbol? 123)  <span class=arw>&rarr;</span> nil
23737
23738 (symbol? (first '(var x y z)))  <span class=arw>&rarr;</span> true
23739
23740 </pre>
23741 </blockquote>
23742
23743 <p>
23744         The first statement sets the contents of <tt>x</tt>
23745         to the symbol <tt>y</tt>.
23746         The second statement then checks the contents of <tt>x</tt>.
23747         The last example checks the first element of a list.
23748 </p>
23749
23750 <br /><br />
23751
23752 <a NAME="symbols"></a>
23753 <h2><span class="function">symbols</span></h2>
23754 <b>syntax: (symbols [<em>context</em>])</b>
23755
23756 <p>
23757         Returns a sorted list of all symbols
23758         in the current context
23759         when called without an argument.
23760         If a context symbol is specified,
23761         symbols defined in that context are returned.
23762 </p>
23763
23764 <b>example:</b>
23765 <blockquote>
23766 <pre>
23767 (symbols)       ; list of all symbols in current context
23768 (symbols 'CTX)  ; list of symbols in context CTX
23769 (symbols CTX)   ; omitting the quote
23770 (set 'ct CTX)   ; assigning context to a variable
23771 (symbols ct)    ; list of symbols in context CTX
23772 </pre>
23773 </blockquote>
23774
23775 <p>
23776         The quote can be omitted
23777         because contexts evaluate to themselves.
23778 </p>
23779
23780 <br /><br />
23781
23782 <a NAME="sys-error"></a>
23783 <h2><span class="function">sys-error</span></h2>
23784 <b>syntax: (sys-error)</b>
23785
23786 <p>
23787         Reports error numbers generated
23788         by the underlying OS
23789         newLISP is running on.
23790         The error numbers reported
23791         may differ on the platforms
23792         newLISP has been compiled for.
23793         Consult the platform's C library information,
23794         (e.g., the GNU <tt>libc</tt> reference).
23795         Most errors reported
23796         refer to system resources such as files and semaphores.
23797 </p>
23798
23799 <p>
23800         Whenever a function in newLISP
23801         within the system resources area
23802         returns <tt>nil</tt>,
23803         <tt>sys-error</tt> can be checked
23804         for the underlying reason.
23805         For file operations,
23806         <tt>sys-error</tt> may be set
23807         for nonexistent files
23808         or wrong permissions
23809         when accessing the resource.
23810         Another cause of error
23811         could be the exhaustion of certain system resources
23812         like file handles or semaphores.
23813 </p>
23814
23815 <br /><br />
23816 <b>example:</b>
23817 <blockquote>
23818 <pre>
23819 ;; trying to open a nonexistent file
23820 (open "blahbla" "r")  <span class=arw>&rarr;</span> nil
23821
23822 (sys-error)  <span class=arw>&rarr;</span> 2
23823
23824 (sys-error 0)  <span class=arw>&rarr;</span> 0  ; clear errno
23825 </pre>
23826 </blockquote>
23827
23828 <p>
23829         The error number can be cleared
23830         by giving a <tt>0</tt> (zero)
23831         for the optional argument.
23832 </p>
23833
23834 <br /><br />
23835
23836 <a NAME="sys-info"></a>
23837 <h2><span class="function">sys-info</span></h2>
23838 <b>syntax: (sys-info [<em>int-idx</em>])</b>
23839
23840 <p>
23841         Calling <tt>sys-info</tt>
23842         without <em>int-idx</em>
23843         returns a list of internal resource statistics.
23844         Eight integers report the following status:
23845 </p>
23846
23847 <pre>
23848   0 - Number of LISP cells
23849   1 - Maximum number of LISP cells constant
23850   2 - Number of symbols
23851   3 - Evaluation/recursion level
23852   4 - Environment stack level
23853   5 - Maximum call stack constant
23854   6 - Version number as an integer constant
23855   7 - Operating system constant:
23856       linux=1, bsd=2, osx=3, solaris=4, cygwin=5, win32=6,
23857       os/2=7, tru64unix=9
23858       the highest bit 7 will be set for UTF-8 versions (add 128)
23859       bit 6 will be added for library versions (add 64)
23860 </pre>
23861
23862 <p>
23863         The numbers from <tt>0</tt> to <tt>7</tt>
23864         indicate the optional offset
23865         in the returned list.
23866 </p>
23867
23868 <p>
23869         When using <em>int-idx</em>,
23870         one element of the list will be returned.
23871 </p>
23872
23873 <b>example:</b>
23874 <blockquote>
23875 <pre>
23876 (sys-info)     <span class=arw>&rarr;</span> (348 268435456 269 1 0 1024 8404 6)
23877 (sys-info 3)   <span class=arw>&rarr;</span> 1
23878 (sys-info -2)  <span class=arw>&rarr;</span> 8404
23879 </pre>
23880 </blockquote>
23881
23882 <p>
23883         The number for the maximum of LISP cells
23884         can be changed via the <tt>-m</tt>
23885         command-line switch.
23886         For each megabyte of LISP cell memory,
23887         64k memory cells can be allocated.
23888         The maximum call stack depth
23889         can be changed using the <tt>-s</tt>
23890         command-line switch.
23891 </p>
23892
23893 <br /><br />
23894
23895 <a NAME="tan"></a>
23896 <h2><span class="function">tan</span></h2>
23897 <b>syntax: (tan <em>num-radians</em>)</b>
23898
23899 <p>
23900         Calculates the tangent function from <em>num-radians</em>
23901         and returns the result.
23902 </p>
23903
23904 <b>example:</b>
23905 <blockquote>
23906 <pre>
23907 (tan 1)                     <span class=arw>&rarr;</span> 1.557407725
23908 (set 'pi (mul 2 (asin 1)))  <span class=arw>&rarr;</span> 3.141592654
23909 (tan (div pi 4))            <span class=arw>&rarr;</span> 1
23910 </pre>
23911 </blockquote>
23912 <br /><br />
23913
23914 <a NAME="tanh"></a>
23915 <h2><span class="function">tanh</span></h2>
23916 <b>syntax: (tanh <em>num-radians</em>)</b>
23917
23918 <p>Calculates the hyperbolic cosine of <em>num-radians</em>.
23919 The hyperbolic sine is defined mathematically as: <em>sinh (x) / cosh (x)</em>.
23920 </p>
23921
23922 <b>example:</b>
23923 <blockquote>
23924 <pre>
23925 (tanh 1)     <span class=arw>&rarr;</span> 0.761594156
23926 (tanh 10)    <span class=arw>&rarr;</span> 0.9999999959
23927 (tanh 1000)  <span class=arw>&rarr;</span> 1
23928 (= (tanh 1) (div (sinh 1) (cosh 1)))  <span class=arw>&rarr;</span> true
23929 </pre>
23930 </blockquote>
23931
23932 <br /><br />
23933
23934 <a NAME="throw"></a>
23935 <h2><span class="function">throw</span></h2>
23936 <b>syntax: (throw <em>exp</em>)</b>
23937
23938 <p>
23939         Works together with
23940         the <a href="#catch">catch</a> function.
23941         <tt>throw</tt> forces the return of a previous <tt>catch</tt> statement
23942         and puts the <em>exp</em> into the result symbol of <tt>catch</tt>.
23943 </p>
23944
23945
23946 <b>example:</b>
23947 <blockquote>
23948 <pre>
23949 (define (throw-test)
23950     (dotimes (x 1000)
23951         (if (= x 500) (throw "interrupted"))))
23952
23953 (catch (throw-test) 'result)  <span class=arw>&rarr;</span> true
23954
23955 result  <span class=arw>&rarr;</span> "interrupted"
23956
23957 (catch (throw-text))  <span class=arw>&rarr;</span> "interrupted"
23958 </pre>
23959 </blockquote>
23960
23961 <p>
23962         The last example shows a shorter form of <a href="#catch">catch</a>,
23963         which returns the <tt>throw</tt> result directly.
23964 </p>
23965
23966 <p>
23967         <tt>throw</tt> is useful for breaking out of a loop
23968         or for early return from user-defined functions
23969         or expression blocks.
23970         In the following example,
23971         the <tt>begin</tt> block will return <tt>X</tt>
23972         if <tt>(foo X)</tt> is <tt>true</tt>;
23973         else <tt>Y</tt> will be returned:
23974 </p>
23975
23976 <blockquote>
23977 <pre>
23978 (catch (begin
23979     &hellip;
23980     (if (foo X) (throw X) Y)
23981     &hellip;
23982 ))
23983 </pre>
23984 </blockquote>
23985
23986 <p>
23987         <tt>throw</tt> will <em>not</em> cause an error exception.
23988         Use <a href="#throw-error">throw-error</a>
23989         to throw user error exceptions.
23990 </p>
23991
23992
23993 <br /><br />
23994
23995 <a NAME="throw-error"></a>
23996 <h2><span class="function">throw-error</span></h2>
23997 <b>syntax: (throw-error expr)</b>
23998
23999 <p>
24000         Causes a user-defined error exception
24001         with text provided by evaluating <em>expr</em>.
24002 </p>
24003
24004 <b>example:</b>
24005 <blockquote>
24006 <pre>
24007 (define (foo x y)
24008         (if (= x 0) (throw-error "first argument cannot be 0"))
24009         (+ x y))
24010
24011 (foo 1 2)  <span class=arw>&rarr;</span> 3
24012
24013 (foo 0 2)  ; causes a user error exception
24014 <span class=err>user error : first argument cannot be 0
24015 called from user-defined function foo</span>
24016 </pre>
24017 </blockquote>
24018
24019 <p>
24020         The user error can be handled
24021         like any other error exception
24022         using user-defined error handlers
24023         and the <a href="#error-event">error-event</a> function,
24024         or the form of <a href="#catch">catch</a>
24025         that can capture error exceptions.
24026 </p>
24027
24028 <br /><br />
24029
24030 <a NAME="time"></a>
24031 <h2><span class="function">time</span></h2>
24032 <b>syntax: (time <em>exp</em> [<em>int-count</em>)</b>
24033
24034 <p>
24035         Evaluates the expression in <em>exp</em>
24036         and returns the time spent on evaluation
24037         in milliseconds.
24038 </p>
24039
24040 <b>example:</b>
24041 <blockquote>
24042 <pre>
24043 (time (myprog x y z))  <span class=arw>&rarr;</span> 450
24044
24045 (time (myprog x y z) 10)  <span class=arw>&rarr;</span> 4420
24046 </pre>
24047 </blockquote>
24048
24049 <p>
24050         In first the example,
24051         450 milliseconds elapsed
24052         while evaluating <tt>(myprog x y z)</tt>.
24053         The second example returns the time
24054         for ten evaluations of  <tt>(myprog x y z)</tt>.
24055         See also <a HREF="#date">date</a>,
24056         <a HREF="#date-value">date-value</a>,
24057         <a HREF="#time-of-day">time-of-day</a>,
24058         and <a HREF="#now">now</a>.
24059 </p>
24060
24061 <br /><br />
24062
24063 <a NAME="time-of-day"></a>
24064 <h2><span class="function">time-of-day</span></h2>
24065
24066 <b>syntax: (time-of-day)</b>
24067
24068 <p>
24069         Returns the time in milliseconds
24070         since the start of the current day.
24071 </p>
24072
24073 <p>
24074         See also the <a HREF="#date">date</a>,
24075         <a HREF="#date-value">date-value</a>,
24076         <a HREF="#time">time</a>,
24077         and <a HREF="#now">now</a> functions.
24078 </p>
24079
24080 <br /><br />
24081
24082 <a NAME="timer"></a>
24083 <h2><span class="function">timer</span></h2>
24084 <b>syntax: (timer <em>sym-event-handler</em> <em>num-seconds</em> [<em>int-option</em>])</b><br />
24085 <b>syntax: (timer <em>func-event-handler</em> <em>num-seconds</em> [<em>int-option</em>])</b><br />
24086
24087 <b>syntax: (timer <em>sym-event-handler</em>)</b><br />
24088 <b>syntax: (timer <em>func-event-handler</em>)</b><br />
24089 <b>syntax: (timer)</b>
24090
24091 <p>
24092         Starts a one-shot timer
24093         firing off the Unix signal <tt>SIGALRM</tt>, <tt>SIGVTALRM</tt>,
24094         or <tt>SIGPROF</tt> after the time in seconds
24095         (specified in <em>num-seconds</em>) has elapsed.
24096         When the timer fires,
24097         it calls the user-defined function
24098         in <em>sym-event-handler</em>.
24099 </p>
24100
24101 <p>
24102         On Linux/UNIX,
24103         an optional <tt>0</tt>, <tt>1</tt>,
24104         or <tt>2</tt> can be specified
24105         to control how the timer counts.
24106         With default option <tt>0</tt>,
24107         real time is measured.
24108         Option <tt>1</tt> measures the time
24109         the CPU spends processing in the thread or process
24110         owning the timer.
24111         Option <tt>3</tt> is a combination of both
24112         called <em>profiling time</em>.
24113         See the UNIX man page <tt>setitimer()</tt>
24114         for details.
24115 </p>
24116
24117 <p>
24118         The event handler
24119         can start the timer again
24120         to achieve a continuous flow of events.
24121         Starting with version 8.5.9,
24122         seconds can be defined
24123         as floating point numbers
24124         with a fractional part
24125         (e.g., <tt>0.25</tt> for 250 milliseconds).
24126 </p>
24127
24128 <p>
24129         Defining <tt>0</tt> (zero) as time
24130         shuts the running timer down
24131         and prevents it from firing.
24132 </p>
24133
24134 <p>
24135         When called with <em>sym-event-handler</em>,
24136         <tt>timer</tt> returns the elapsed time
24137         of the timer in progress.
24138         This can be used to program
24139         timelines or schedules.
24140 </p>
24141
24142 <p>
24143         <tt>timer</tt> called without arguments
24144         returns the symbol of the current event handler.
24145 </p>
24146
24147
24148 <b>example:</b>
24149 <blockquote>
24150 <pre>
24151 (define (ticker)
24152     (println (date)) (timer 'ticker 1.0))
24153
24154 &gt; (ticker)
24155 <b>Tue Apr 12 20:44:48 2005</b> ; first execution of ticker
24156 <span class=arw>&rarr;</span> ticker                    ; return value from ticker
24157 &gt; <b>Tue Apr 12 20:44:49 2005</b>    ; first timer event
24158 <b>Tue Apr 12 20:44:50 2005</b> ; second timer event ...
24159 <b>Tue Apr 12 20:44:51 2005
24160 Tue Apr 12 20:44:52 2005
24161 Tue Apr 12 20:44:53 2005
24162 Tue Apr 12 20:44:54 2005
24163 Tue Apr 12 20:44:55 2005</b>
24164 </pre>
24165 </blockquote>
24166
24167 <p>
24168         The example shows an event handler, <tt>ticker</tt>,
24169         which starts the timer again after each event.
24170 </p>
24171
24172 <p>
24173         Note that a timer cannot interrupt an
24174         ongoing built-in function.
24175         The timer interrupt gets registered by newLISP,
24176         but a timer handler cannot run
24177         until one expression is evaluated
24178         and the next one starts.
24179         To interrupt an ongoing I/O operation with <tt>timer</tt>,
24180         use the following pattern,
24181         which calls <a href="#net-select">net-select</a>
24182         to test if a socket is ready for reading:
24183 </p>
24184
24185 <b>example:</b>
24186 <blockquote>
24187 <pre>
24188 define (interrupt)
24189     (set 'timeout true))
24190
24191 (set 'listen (net-listen 30001))
24192 (set 'socket (net-accept listen))
24193
24194 (timer 'interrupt 10)
24195 ;; or specifying the function directly
24196 (timer (fn () (set 'timeout true)) 10)
24197
24198 (until (or timeout done)
24199     (if (net-select socket "read" 100000)
24200         (begin
24201             (read-buffer socket 'buffer 1024)
24202             (set 'done true)))
24203 )
24204
24205 (if timeout
24206     (println "timeout")
24207     (println buffer))
24208
24209 (exit)
24210 </pre>
24211 </blockquote>
24212
24213 <p>
24214         In this example,
24215         the <tt>until</tt> loop will run
24216         until something can be read from <tt>socket</tt>,
24217         or until ten seconds have passed
24218         and the <tt>timeout</tt> variable is set.
24219 </p>
24220
24221 <br /><br />
24222
24223 <a NAME="title-case"></a>
24224 <h2><span class="function">title-case</span></h2>
24225 <b>syntax: (title-case <em>str</em>)</b><br />
24226 <b>syntax: (title-case <em>str</em> <em>bool</em>)</b>
24227
24228 <p>
24229         Returns a copy of the string in <em>str</em>
24230         with the first character converted to uppercase.
24231         When the optional <em>bool</em> parameter
24232         evaluates to any value other than <tt>nil</tt>,
24233         the rest of the string is converted to lowercase.
24234 </p>
24235
24236 <b>example:</b>
24237 <blockquote>
24238 <pre>
24239 (title-case "hello")       <span class=arw>&rarr;</span> "Hello"
24240 (title-case "hELLO" true)  <span class=arw>&rarr;</span> "Hello"
24241 </pre>
24242 </blockquote>
24243
24244 <p>
24245         See also the <a href="#lower-case">lower-case</a>
24246         and <a href="#upper-case">upper-case</a> functions.
24247 </p>
24248
24249 <br /><br />
24250
24251
24252 <a NAME="trace"></a>
24253 <h2><span class="function">trace</span></h2>
24254
24255 <b>syntax: (trace [<em>exp</em>])</b>
24256
24257 <p>
24258         Tracing is switched on when <em>exp</em> evaluates to anything
24259         besides <tt>nil</tt> or an empty list <tt>()</tt>.
24260         When no argument is supplied,
24261         <tt>trace</tt> evaluates to <tt>true</tt> or <tt>nil</tt>
24262         depending on the current trace mode.
24263         If trace mode is switched on,
24264         newLISP goes into debugging mode after entering
24265     the next user defined function,
24266         displaying the function and highlighting the current expression
24267         upon entry and exit.</p>
24268
24269 <p>
24270         Highlighting is done by bracketing the expression
24271         between two # (number sign) characters.
24272         This can be changed to a different character
24273         using <a HREF="#trace-highlight">trace-highlight</a>.
24274         Upon exit from the expression,
24275         the result of its evaluation
24276         is also reported.
24277 </p>
24278
24279 <p>
24280         If an expression occurs more than once in a function,
24281         the first occurrence of the executing function
24282         will always be highlighted (bracketed).
24283 </p>
24284
24285 <p>
24286         newLISP execution stops with a prompt line
24287         at each entry and exit of an expression.
24288 </p>
24289
24290 <blockquote>
24291 <pre>
24292 [-&gt; 2] s|tep n|ext c|ont q|uit &gt;
24293 </pre>
24294 </blockquote>
24295
24296 <p>
24297         At the prompt,
24298         an <tt>s</tt>, <tt>n</tt>, <tt>c</tt>,
24299         or <tt>q</tt> can be entered
24300         to step into or
24301         merely execute the next expression.
24302         Any expression can be entered
24303         at the prompt for evaluation.
24304         Entering the name of a variable,
24305         for example,
24306         would evaluate to its contents.
24307         In this way,
24308         a variable's contents
24309         can be checked during debugging
24310         or set to different values.
24311 </p>
24312
24313 <b>example:</b>
24314 <blockquote>
24315 <pre>
24316 ;; switches newLISP into debugging mode
24317 (trace true)  <span class=arw>&rarr;</span> true
24318
24319 ;; the debugger will show each step
24320 (my-func a b c)
24321
24322 ;; switched newLISP out of debugging mode
24323 (trace nil)  <span class=arw>&rarr;</span> nil
24324 </pre>
24325 </blockquote>
24326 <p>
24327         To set break points
24328         where newLISP should interrupt
24329         normal execution
24330         and go into debugging mode,
24331         put <tt>(trace true)</tt> statements
24332         into the LISP code where execution
24333         should switch on the debugger.
24334 </p>
24335
24336 <p>
24337         Use the <a HREF="#debug">debug</a> function
24338         as a shortcut for the above example.
24339 </p>
24340
24341 <br /><br />
24342
24343 <a NAME="trace-highlight"></a>
24344 <h2><span class="function">trace-highlight</span></h2>
24345 <b>syntax: (trace-highlight <em>str-pre</em> <em>str-post</em> [<em>str-header</em> <em>str-footer </em>] )</b>
24346
24347 <p>
24348         Sets the characters or string of characters
24349         used to enclose expressions
24350         during <a HREF="#trace">trace</a>.
24351         By default,
24352         the # (number sign) is used
24353         to enclose the expression highlighted
24354         in <a HREF="#trace">trace</a> mode.
24355         This can be changed to different characters
24356         or strings of up to seven characters.
24357         If the console window accepts terminal control characters,
24358         this can be used to display the expression in a different color,
24359         bold, reverse, and so forth.
24360 </p>
24361
24362 <p>
24363         Two more strings can optionally be specified
24364         for <em>str-header and str-footer</em>,
24365         which control the separator and prompt.
24366         A maximum of 15 characters is allowed
24367         for the header and 31 for the footer.
24368 </p>
24369
24370 <b>example:</b>
24371 <blockquote>
24372 <pre>
24373 ;; active expressions are enclosed in &gt;&gt; and &lt;&lt;
24374
24375 (trace-highlight "&gt;&gt;" "&lt;&lt;")
24376
24377 ;; 'bright' color on a VT100 or similar terminal window
24378
24379 (trace-highlight "\027[1m" "\027[0m")
24380
24381 </pre>
24382 </blockquote>
24383
24384 <p>
24385         The first example replaces the default <tt>#</tt> (number sign)
24386         with a <tt>&gt;&gt;</tt> and <tt>&lt;&lt;</tt>.
24387         The second example works on most Linux shells.
24388         It may not, however, work in console windows
24389         under Win32 or CYGWIN,
24390         depending on the configuration of the terminal.
24391 </p>
24392
24393 <br /><br />
24394
24395
24396
24397 <a NAME="transpose"></a>
24398 <h2><span class="function">transpose</span></h2>
24399 <b>syntax: (transpose <em>matrix</em>)</b>
24400
24401 <p>
24402         Transposes a <em>matrix</em>
24403         by reversing the rows and columns
24404         and converting all of the cells
24405         to floating point numbers.
24406         Any kind of list-matrix
24407         can be transposed.
24408         Matrices are made rectangular
24409         by filling in <tt>nil</tt> for missing elements,
24410         omitting elements where appropriate,
24411         or expanding atoms in rows into lists.
24412         Matrix dimensions are calculated
24413         using the number of rows in the original matrix
24414         for columns and the number of elements in the first row
24415         as number of rows for the transposed matrix.
24416 </p>
24417
24418 <p>
24419         The dimensions of a matrix
24420         are defined by the number of rows
24421         and the number of elements in the first row.
24422         A matrix can either be a nested list
24423         or an <a href="#array">array</a>.
24424 </p>
24425
24426 <b>example:</b>
24427 <blockquote>
24428 <pre>
24429 (set 'A '((1 2 3) (4 5 6)))
24430 (transpose A)                      <span class=arw>&rarr;</span> ((1 4) (2 5) (3 6))
24431 (transpose (list (sequence 1 5)))  <span class=arw>&rarr;</span> ((1) (2) (3) (4) (5))
24432
24433 (transpose '((a b) (c d) (e f)))  <span class=arw>&rarr;</span> ((a c e) (b d f))
24434 </pre>
24435 </blockquote>
24436
24437 <p>
24438         The number of columns in a matrix
24439         is defined by the number of elements
24440         in the first row of the matrix.
24441         If other rows have fewer elements,
24442         <tt>transpose</tt> will assume <tt>nil</tt>
24443         for those missing elements.
24444         Superfluous elements in a row will be ignored.
24445 </p>
24446
24447 <blockquote>
24448 <pre>
24449 (set 'A '((1 2 3) (4 5) (7 8 9)))
24450
24451 (transpose A)  <span class=arw>&rarr;</span> ((1 4 7) (2 5 8) (3 nil 9))
24452 </pre>
24453 </blockquote>
24454
24455 <p>
24456         If a row is any other data type
24457         besides a list,
24458         the transposition treats it
24459         like an entire row of elements
24460         of that data type:
24461 </p>
24462
24463 <blockquote>
24464 <pre>
24465 (set 'A '((1 2 3) X (7 8 9)))
24466
24467 (transpose A)  <span class=arw>&rarr;</span> ((1 X 7) (2 X 8) (3 X 9))
24468 </pre>
24469 </blockquote>
24470
24471 <p>
24472         All operations shown here on lists
24473         can also be performed on arrays.
24474 </p>
24475
24476 <p>
24477         See also the matrix operations
24478         <a href="#det">det</a>, <a HREF="#invert">invert</a>,
24479     <a href="#mat">mat</a> and <a HREF="#multiply">multiply</a>.
24480 </p>
24481
24482 <br /><br />
24483
24484
24485 <a NAME="trim"></a>
24486 <h2><span class="function">trim</span></h2>
24487 <b>syntax: (trim <em>str</em> [ <em>str-char</em> ])</b><br />
24488 <b>syntax: (trim <em>str</em> [ <em>str-left-char</em>] [<em>str-right-char</em> ])</b>
24489
24490 <p>
24491         The first syntax trims the string <em>str</em> from both sides,
24492         stripping the leading and trailing characters as given
24493         in <em>str-char</em>.
24494         If <em>str-char</em> contains no character,
24495         the space character is assumed.
24496         <tt>trim</tt> returns the new string.
24497 </p>
24498
24499 <p>
24500         The second syntax can either trim
24501         different characters from both sides
24502         or trim only one side
24503         if an empty string is specified
24504         for the other.
24505 </p>
24506
24507 <b>example:</b>
24508 <blockquote>
24509 <pre>
24510 (trim "   hello  ")              <span class=arw>&rarr;</span> "hello"
24511 (trim "----hello-----" "-")      <span class=arw>&rarr;</span> "hello"
24512 (trim "00012340" "0" "")         <span class=arw>&rarr;</span> "12340"
24513 (trim "1234000" "" "0")          <span class=arw>&rarr;</span> "1234"
24514 (trim "----hello=====" "-" "=")  <span class=arw>&rarr;</span> "hello"
24515 </pre>
24516 </blockquote>
24517
24518 <br /><br />
24519
24520 <a name="truep"></a>
24521 <h2><span class="function">true?</span></h2>
24522 <b>syntax: (true? <em>expr</em>)</b>
24523
24524 <p>
24525         If the expression in <em>expr</em>
24526         evaluates to anything other than <tt>nil</tt>,
24527     or the empty list <tt>()</tt>
24528         <tt>true?</tt> returns <tt>true</tt>;
24529         else it returns <tt>nil</tt>.
24530 </p>
24531
24532 <b>example:</b>
24533 <blockquote>
24534 <pre>
24535 (map true? '(x 1 "hi" (a b c) nil ()))
24536 <span class=arw>&rarr;</span> (true true true true nil nil)
24537 (true? nil)  <span class=arw>&rarr;</span> nil
24538 (true? '())  <span class=arw>&rarr;</span> nil
24539 </pre>
24540 </blockquote>
24541
24542 <p>Since version 9.1 <tt>true?</tt> behaves like <a href="#if">if</a>
24543 rejecting the empty list <tt>()</tt></p>
24544
24545 <br /><br />
24546
24547
24548 <a NAME="unicode"></a>
24549 <h2><span class="function">unicode</span></h2>
24550
24551 <b>syntax: (unicode <em>str</em>)</b>
24552
24553 <p>
24554         Converts ASCII/UTF-8 character strings in <em>str</em>
24555         to UCS-4&ndash;encoded Unicode of 4-byte integers per character.
24556         This function is only available
24557         on UTF-8&ndash;enabled versions of newLISP.
24558 </p>
24559
24560 <b>example:</b>
24561 <blockquote>
24562 <pre>
24563 (unicode "new")
24564 <span class=arw>&rarr;</span> "n\000\000\000e\000\000\000w\000\000\000\000\000\000\000"
24565
24566
24567 (utf8 (unicode "new"))  <span class=arw>&rarr;</span> "new"
24568 </pre>
24569 </blockquote>
24570
24571 <p>
24572         On <em>big endian</em> CPU architectures,
24573         the byte order will be reversed from high to low.
24574         The <tt>unicode</tt> and <a href="#utf8">utf8</a> functions
24575         are the inverse of each other.
24576         These functions are only necessary
24577         if UCS-4 Unicode is in use.
24578         Most systems use UTF-8 encoding only.
24579 </p>
24580
24581 <br /><br />
24582
24583 <a NAME="unify"></a>
24584 <h2><span class="function">unify</span></h2>
24585 <b>syntax: (unify <em>expr-1</em> <em>expr-2</em> [<em>list-env</em>])</b>
24586
24587 <p>
24588         Evaluates and matches
24589         <em>expr-1</em> and <em>expr-2</em>.
24590         Expressions match if they are equal
24591         or if one of the expressions is
24592         an unbound variable
24593         (which would then be bound to the other expression).
24594         If expressions are lists,
24595         they are matched by comparing subexpressions.
24596         Unbound variables start with an uppercase character
24597         to distinguish them from symbols.
24598         <tt>unify</tt> returns <tt>nil</tt>
24599         when the unification process fails,
24600         or it returns a list of variable associations on success.
24601         When no variables were bound,
24602         but the match is still successful,
24603         <tt>unify</tt> returns an empty list.
24604     newLISP uses a modified <em>J. Alan Robinson</em> unification algorithm
24605     with <em>occurs check</em>.
24606 </p>
24607
24608 <p>
24609     Like <a href="#match">match</a> <tt>unify</tt> is frequently
24610     employed as a parameter functor in <a href="#find">find</a>,
24611     <a href="#ref">ref</a>,  <a href="#ref-all">ref-all</a> and
24612     <a href="#replace">replace</a>.
24613 </p>
24614
24615
24616 <b>example:</b>
24617 <blockquote>
24618 <pre>
24619 (unify 'A 'A)  <span class=arw>&rarr;</span> ()  ; tautology
24620
24621 (unify 'A 123)  <span class=arw>&rarr;</span> ((A 123))  ; A bound to 123
24622
24623 (unify '(A B) '(x y))  <span class=arw>&rarr;</span> ((A x) (B y))  ; A bound to x, B bound to y
24624
24625 (unify '(A B) '(B abc))  <span class=arw>&rarr;</span> ((A abc) (B abc))  ; B is alias for A
24626
24627 (unify 'abc 'xyz)  <span class=arw>&rarr;</span> nil  ; fails because symbols are different
24628
24629 (unify '(A A) '(123 456))  <span class=arw>&rarr;</span> nil  ; fails because A cannot be bound to different values
24630
24631 (unify '(f A) '(f B))  <span class=arw>&rarr;</span> ((A B))  ; A and B are aliases
24632
24633 (unify '(f A) '(g B))  <span class=arw>&rarr;</span> nil  ; fails because heads of terms are different
24634
24635 (unify '(f A) '(f A B))  <span class=arw>&rarr;</span> nil  ; fails because terms are of different arity
24636
24637 (unify '(f (g A)) '(f B))  <span class=arw>&rarr;</span> ((B (g A)))  ; B bound to (g A)
24638
24639 (unify '(f (g A) A) '(f B xyz))  <span class=arw>&rarr;</span> ((B (g xyz)) (A xyz))  ; B bound to (g xyz) A to xyz
24640
24641 (unify '(f A) 'A)  <span class=arw>&rarr;</span> nil  ; fails because of infinite unification (f(f(f &hellip;)))
24642
24643 (unify '(A xyz A) '(abc X X))  <span class=arw>&rarr;</span>  nil ; indirect alias A to X doesn't match bound terms
24644
24645 (unify '(p X Y a) '(p Y X X))  <span class=arw>&rarr;</span> '((Y a) (X a)))  ; X alias Y and binding to 'a
24646
24647 (unify '(q (p X Y) (p Y X)) '(q Z Z))  <span class=arw>&rarr;</span> ((Y X) (Z (p X X)))  ; indirect alias
24648
24649 ;; some examples taken from <a href="http://en.wikipedia.org/wiki/Unification">http://en.wikipedia.org/wiki/Unification</a>
24650 </pre>
24651 </blockquote>
24652
24653 <p>
24654         <tt>unify</tt> can take an optional binding
24655         or association list in <em>list-env</em>.
24656         This is useful when chaining <tt>unify</tt> expressions
24657         and the results of previous <tt>unify</tt> bindings
24658         must be included:
24659 </p>
24660
24661 <b>example:</b>
24662 <blockquote>
24663 <pre>
24664 (unify '(f X) '(f 123))  <span class=arw>&rarr;</span> ((X 123))
24665
24666 (unify '(A B) '(X A) '((X 123)))
24667 <span class=arw>&rarr;</span> ((X 123) (A 123) (B 123))
24668 </pre>
24669 </blockquote>
24670
24671 <p>
24672         In the previous example,
24673         <tt>X</tt> was bound to <tt>123</tt> earlier
24674         and is included in the second statement
24675         to pre-bind <tt>X</tt>.
24676 </p>
24677
24678 <p>
24679         Note that variables are not actually bound
24680         as a newLISP assignment. Rather,
24681         an association list is returned
24682         showing the logical binding.
24683         A special syntax of <a href="#expand">expand</a>
24684         can be used to actually replace bound variables
24685         with their terms:
24686 </p>
24687
24688 <blockquote>
24689 <pre>
24690 (set 'bindings (unify '(f (g A) A) '(f B xyz)))
24691 <span class=arw>&rarr;</span> ((B (g xyz)) (A xyz))
24692
24693 (expand '(f (g A) A) bindings)  <span class=arw>&rarr;</span> (f (g xyz) xyz)
24694
24695 ; or in one statement
24696 (expand '(f (g A) A) (unify '(f (g A) A) '(f B xyz)))
24697 <span class=arw>&rarr;</span> (f (g xyz) xyz)
24698 </pre>
24699 </blockquote>
24700
24701 <p>The function <a href="#bind">bind</a> can be used to set unified
24702 variables:</p>
24703
24704 <blockquote>
24705 <pre>
24706 (bind (unify '(f (g A) A) '(f B xyz)))
24707
24708 A <span class=arw>&rarr;</span> xyz
24709 B <span class=arw>&rarr;</span> (g xyz)
24710 </pre>
24711 </blockquote>
24712
24713
24714
24715 <p>
24716         The following example shows how propositional logic
24717         can be modeled using <tt>unify</tt>
24718         and <a href="#expand">expand</a>:
24719 </p>
24720
24721 <blockquote>
24722 <pre>
24723 ; if somebody is human, he is mortal -&gt; (X human) :- (X mortal)
24724 ; socrates is human -&gt; (socrates human)
24725 ; is socrates mortal? -&gt; ?  (socrates mortal)
24726
24727 (expand '(X mortal)
24728          (unify '(X human) '(socrates human)))
24729 <span class=arw>&rarr;</span> (socrates mortal)
24730 </pre>
24731 </blockquote>
24732
24733 <p>
24734         The following is a more complex example
24735         showing a small, working PROLOG (Programming in Logic)
24736         implementation.
24737 </p>
24738
24739 <blockquote>
24740 <pre>
24741 ;; a small PROLOG implementation
24742
24743 (set 'facts '(
24744     (socrates philosopher)
24745     (socrates greek)
24746     (socrates human)
24747     (einstein german)
24748     (einstein (studied physics))
24749     (einstein human)
24750 ))
24751
24752 (set 'rules '(
24753     ((X mortal) &lt;- (X human))
24754     ((X (knows physics)) &lt;- (X physicist))
24755     ((X physicist) &lt;- (X (studied physics)))
24756 ))
24757
24758
24759 (define (query term)
24760     (or  (if (find term facts) true) (catch (prove-rule term))))
24761
24762 (define (prove-rule term)
24763     (dolist (r rules)
24764         (if (list? (set 'e (unify term (first r))))
24765             (if (query (expand (last r) e))
24766                 (throw true))))
24767     nil
24768 )
24769
24770 ; try it
24771
24772 &gt; (query '(socrates human))
24773 <b>true</b>
24774 &gt; (query '(socrates (knows physics)))
24775 <b>nil</b>
24776 &gt; (query '(einstein (knows physics)))
24777 <b>true</b>
24778 </pre>
24779 </blockquote>
24780
24781 <p>
24782         The program handles a database of <tt>facts</tt>
24783         and a database of simple
24784         <em>A is a fact if B is a fact</em> <tt>rules</tt>.
24785         A fact is proven true
24786         if it either can be found in the <tt>facts</tt> database
24787         or if it can be proven using a rule.
24788         Rules can be nested:
24789         for example, to prove that somebody <tt>(knows physics)</tt>,
24790         it must be proved true that somebody is a <tt>physicist</tt>.
24791         But somebody is only a physicist
24792         if that person <tt>studied physics</tt>.
24793         The <tt>&lt;-</tt> symbol
24794         separating the left and right terms of the rules
24795         is not required
24796         and is only added to make the rules database
24797         more readable.
24798 </p>
24799
24800 <p>
24801         This implementation does not handle multiple terms
24802         in the right premise part of the rules,
24803         but it does handle backtracking of the <tt>rules</tt> database
24804         to try out different matches.
24805         It does not handle backtracking
24806         in multiple premises of the rule.
24807         For example,
24808         if in the following rule <tt>A if B and C and D</tt>,
24809         the premises <tt>B</tt> and <tt>C</tt> succeed
24810         and <tt>D</tt> fails,
24811         a backtracking mechanism might need to go back
24812         and reunify the <tt>B</tt> or <tt>A</tt> terms
24813         with different facts or rules
24814         to make <tt>D</tt> succeed.
24815 </p>
24816
24817 <p>
24818         The above algorithm could be written differently
24819         by omitting <a href="#expand">expand</a>
24820         from the definition of <tt>prove-rule</tt>
24821         and by passing the environment, <tt>e</tt>,
24822         as an argument to the <tt>unify</tt> and <tt>query</tt> functions.
24823 </p>
24824
24825 <p>
24826         A <em>learning</em> of proven facts
24827         can be implemented by appending them
24828         to the <tt>facts</tt> database
24829         once they are proven.
24830         This would speed up subsequent queries.
24831 </p>
24832
24833 <p>
24834         Larger PROLOG implementations
24835         also allow the evaluation of terms in rules.
24836         This makes it possible to implement functions
24837         for doing other work
24838         while processing rule terms.
24839         <tt>prove-rule</tt> could accomplish this testing
24840         for the symbol <tt>eval</tt> in each rule term.
24841 </p>
24842
24843 <br /><br />
24844
24845 <a NAME="unique"></a>
24846 <h2><span class="function">unique</span></h2>
24847 <b>syntax: (unique <em>list</em>)</b>
24848
24849 <p>
24850         Returns a unique version of <em>list</em>
24851         with all duplicates removed.
24852 </p>
24853
24854 <b>example:</b>
24855 <blockquote>
24856 <pre>
24857 (unique '(2 3 4 4 6 7 8 7))  <span class=arw>&rarr;</span> (2 3 4 6 7 8)
24858 </pre>
24859 </blockquote>
24860
24861 <p>
24862         Note that the list does not need to be sorted,
24863         but a sorted list makes <tt>unique</tt> perform faster.
24864 </p>
24865
24866 <p>
24867         The functions <a HREF="#difference">difference</a>
24868         and <a HREF="#intersect">intersect</a> work with sets.
24869 </p>
24870
24871 <br /><br />
24872
24873 <a NAME="unless"></a>
24874 <h2><span class="function">unless</span></h2>
24875 <b>syntax: (unless <em>exp-condition</em> <em>exp-1</em> [<em>exp-2</em>])</b>
24876
24877 <p>
24878         <tt>unless</tt> is equivalent to
24879         (<a HREF="#if">if</a> (<a HREF="#not">not</a>
24880         <em>exp-condition</em> <em>exp-1</em> [<em>exp-2</em>])).
24881         If the value of <em>exp-condition</em> is <tt>nil</tt>
24882         or the empty list <tt>()</tt>,
24883         <em>exp-1</em> is evaluated;
24884         otherwise, <em>exp-2</em> is evaluated.
24885 </p>
24886
24887 <b>example:</b>
24888 <blockquote>
24889 <pre>
24890 (set 'x 50)                       <span class=arw>&rarr;</span> 50
24891 (unless (&lt; x 100) "big" "small")  <span class=arw>&rarr;</span> "small"
24892 (set 'x 1000)                     <span class=arw>&rarr;</span> 1000
24893 (unless (&lt; x 100) "big" "small")  <span class=arw>&rarr;</span> "big"
24894 </pre>
24895 </blockquote>
24896
24897 <br /><br />
24898
24899 <a NAME="unpack"></a>
24900
24901 <h2><span class="function">unpack</span></h2>
24902
24903 <b>syntax: (unpack <em>str-format</em> <em>str-addr-packed</em>)</b>
24904
24905 <p>
24906         Unpacks a binary structure
24907         in <em>str-addr-packed</em>
24908         into LISP variables
24909         using the format in <em>str-format</em>.
24910         <tt>unpack</tt> is the reverse operation of <tt>pack</tt>.
24911         Note that <em>str-addr-packed</em>
24912         may also be an integer representing a memory address.
24913         This facilitates the unpacking of structures
24914         returned from imported, shared library functions.
24915 </p>
24916
24917 <p>
24918         The following characters may define a format:
24919 </p>
24920 <br />
24921 <blockquote>
24922 <table border="0" cellpadding="1" width="95%" summary="format chracters in pack">
24923
24924 <tr align="left" valign="bottom"><th>format</th><th>description</th></tr>
24925
24926 <tr>
24927 <td WIDTH="10%"><tt>c </tt></td>
24928 <td WIDTH="90%">a signed 8-bit number</td>
24929 </tr>
24930
24931 <tr>
24932 <td><tt>b </tt></td>
24933 <td>an unsigned 8-bit number</td>
24934 </tr>
24935
24936 <tr>
24937 <td><tt>d </tt></td>
24938 <td>a signed 16-bit short number</td>
24939 </tr>
24940
24941 <tr>
24942 <td><tt>u </tt></td>
24943 <td>an unsigned 16-bit short number</td>
24944 </tr>
24945
24946 <tr>
24947 <td><tt>ld</tt></td>
24948 <td>a signed 32-bit long number</td>
24949 </tr>
24950
24951 <tr>
24952 <td><tt>lu</tt></td>
24953 <td>an unsigned 32-bit long number</td>
24954 </tr>
24955
24956 <tr>
24957 <td><tt>Ld</tt></td>
24958 <td>a signed 64-bit long number</td>
24959 </tr>
24960
24961 <tr>
24962 <td><tt>Lu</tt></td>
24963 <td>an unsigned 64-bit long number</td>
24964 </tr>
24965
24966 <tr>
24967 <td><tt>f </tt></td>
24968 <td>a float in 32-bit representation</td>
24969
24970 </tr>
24971
24972 <tr>
24973 <td><tt>lf</tt></td>
24974 <td>a double float in 64-bit representation</td>
24975 </tr>
24976
24977 <tr>
24978 <td><tt>sn</tt></td>
24979 <td>a string of <em>n</em> null padded ASCII characters</td>
24980 </tr>
24981
24982 <tr>
24983
24984 <td><tt>nn</tt></td>
24985 <td><em>n</em> null characters</td>
24986 </tr>
24987
24988 <tr>
24989 <td><tt>&gt;</tt></td>
24990 <td>switches to big endian byte order</td>
24991 </tr>
24992
24993 <tr>
24994 <td><tt>&lt;</tt></td>
24995 <td>switches to little endian byte order</td>
24996 </tr>
24997
24998
24999 </table>
25000
25001 </blockquote>
25002 <br />
25003 <b>example:</b>
25004 <blockquote>
25005 <pre>
25006 (pack "c c c" 65 66 67)  <span class=arw>&rarr;</span> "ABC"
25007 (unpack "c c c" "ABC")   <span class=arw>&rarr;</span> (65 66 67)
25008
25009 (set 's (pack "c d u" 10 12345 56789))
25010 (unpack "c d u" s)  <span class=arw>&rarr;</span> (10 12345 56789)
25011
25012 (set 's (pack "s10 f" "result" 1.23))
25013 (unpack "s10 f" s)  <span class=arw>&rarr;</span> ("result\000\000\000\000" 1.230000019)
25014
25015 (set 's (pack "s3 lf" "result" 1.23))
25016 (unpack "s3 f" s)  <span class=arw>&rarr;</span> ("res" 1.23)
25017
25018 (set 's (pack "c n7 c" 11 22))
25019 (unpack "c n7 c" s)  <span class=arw>&rarr;</span> (11 22))
25020 </pre>
25021 </blockquote>
25022
25023 <p>
25024         The <tt>&gt;</tt> and <tt>&lt;</tt> specifiers
25025         can be used to switch between
25026         <em>little endian</em> and <em>big endian</em> byte order
25027         when packing or unpacking:
25028 </p>
25029
25030 <blockquote>
25031
25032 <pre>
25033 ;; on a little endian system (e.g., Intel CPUs)
25034 (set 'buff (pack "d" 1))  <span class=arw>&rarr;</span> "\001\000"
25035
25036 (unpack "d" buff)   <span class=arw>&rarr;</span> (1)
25037 (unpack "&gt;d" buff)  <span class=arw>&rarr;</span> (256)
25038 </pre>
25039 </blockquote>
25040
25041
25042 <p>
25043         Switching the byte order
25044         will affect all number formats
25045         with 16-, 32-, or 64-bit sizes.
25046 </p>
25047
25048
25049 <p>
25050         The <tt>pack</tt> and <tt>unpack</tt> format
25051         need not be the same,
25052         as in the following example:
25053 </p>
25054
25055 <blockquote>
25056 <pre>
25057 (set 's (pack "s3" "ABC"))
25058 (unpack "c c c" s)  <span class=arw>&rarr;</span> (65 66 67)
25059 </pre>
25060 </blockquote>
25061
25062 <p>
25063         The examples show spaces between the format specifiers.
25064         Although not required, they can improve readability.
25065 </p>
25066
25067 <p>
25068 If the buffer's size at a memory address
25069 is smaller than the formatting string specifies,
25070 some formatting characters may be left unused.</p>
25071
25072 <p>
25073         See also the <a href="#address">address</a>,
25074         <a HREF="#get-int">get-int</a>,
25075         <a HREF="#get-long">get-long</a>,
25076         <a HREF="#get-char">get-char</a>,
25077         <a HREF="#get-string">get-string</a>,
25078         and <a HREF="#pack">pack</a> functions.
25079 </p>
25080
25081 <br /><br />
25082
25083
25084 <a NAME="until"></a>
25085 <h2><span class="function">until</span></h2>
25086 <b>syntax: (until <em>exp-condition</em> <em>body</em>)</b>
25087
25088 <p>
25089         Evaluates the condition
25090         in <em>exp-condition body</em>.
25091         If the result is <tt>nil</tt> or the empty list <tt>()</tt>,
25092         the expressions in <em>body</em> are evaluated.
25093         Evaluation is repeated until the exp-condition results in a value
25094         other than <tt>nil</tt> or the empty list.
25095         The result of the last expression evaluated
25096         is the return value of the <tt>until</tt> expression.
25097         <tt>until</tt> works like
25098         (<a HREF="#while">while</a> (<a HREF="#not">not</a> &hellip;)).
25099 </p>
25100
25101 <b>example:</b>
25102 <blockquote>
25103 <pre>
25104 (device (open "somefile.txt" "read"))
25105 (set 'line-count 0)
25106 (until (not (read-line)) (inc 'line-count))
25107 (close (device))
25108 (print "the file has " line-count " lines\n")
25109 </pre>
25110 </blockquote>
25111
25112 <p>
25113         Use the <a href="#do-until">do-until</a> function
25114         to test the condition <em>after</em> evaluation
25115         of the body expressions.
25116 </p>
25117
25118 <br /><br />
25119
25120 <a NAME="upper-case"></a>
25121 <h2><span class="function">upper-case</span></h2>
25122 <b>syntax: (upper-case <em>str</em>)</b>
25123
25124 <p>
25125         Returns a copy of the string in <em>str</em>
25126         converted to uppercase.
25127         International characters are converted correctly.
25128 </p>
25129
25130 <b>example:</b>
25131 <blockquote>
25132 <pre>
25133 (upper-case "hello world")  <span class=arw>&rarr;</span> "HELLO WORLD"
25134 </pre>
25135 </blockquote>
25136
25137 <p>
25138         See also the <a HREF="#lower-case">lower-case</a>
25139         and <a href="#title-case">title-case</a> functions.
25140 </p>
25141
25142 <br /><br />
25143
25144
25145 <a NAME="utf8"></a>
25146 <h2><span class="function">utf8</span></h2>
25147 <b>syntax: (utf8 <em>str</em>)</b>
25148
25149 <p>
25150         Converts a UCS-4,
25151         4-byte,
25152         Unicode-encoded string (<em>str</em>)
25153         into UTF-8.
25154         This function is only available
25155         on UTF-8&ndash;enabled versions of newLISP.
25156 </p>
25157
25158 <b>example:</b>
25159 <blockquote>
25160 <pre>
25161 (unicode "new")
25162 <span class=arw>&rarr;</span> "n\000\000\000e\000\000\000w\000\000\000\000\000\000\000"
25163
25164 (utf8 (unicode "new"))  <span class=arw>&rarr;</span> "new"
25165 </pre>
25166 </blockquote>
25167
25168 <p>
25169         The <tt>utf8</tt> function can also be used
25170         to test for the presence of UTF-8&ndash;enabled newLISP:
25171 </p>
25172
25173 <blockquote>
25174 <pre>
25175 (if utf8 (do-utf8-version-of-code) (do-ascii-version-of-code))
25176 </pre>
25177 </blockquote>
25178
25179 <p>
25180         On <em>big endian</em> CPU architectures,
25181         the byte order will be reversed
25182         from highest to lowest.
25183         The <tt>utf8</tt>
25184         and <a href="#unicode">unicode</a> functions
25185         are the inverse of each other.
25186         These functions are only necessary
25187         if UCS-4 Unicode is in use.
25188         Most systems use UTF-8 Unicode encoding only.
25189 </p>
25190
25191 <br /><br />
25192
25193 <a NAME="utf8len"></a>
25194 <h2><span class="function">utf8len</span></h2>
25195 <b>syntax: (utf8len <em>str</em>)</b>
25196
25197 <p>Returns the number of characters in a UTF-8&ndash;encoded string.
25198 UTF-8 characters can be encoded in more than one 8-bit byte.
25199 <tt>utf8len</tt> returns the number of UTF-8 characters in a string.
25200 This function is only available on UTF-8&ndash;enabled versions of newLISP.</p>
25201
25202 <b>example:</b>
25203 <blockquote>
25204 <pre>
25205 (utf8-len "我能吞下玻璃而不伤身体。")    <span class=arw>&rarr;</span> 12
25206 (length "我能吞下玻璃而不伤身体。")      <span class=arw>&rarr;</span> 36
25207 </pre>
25208 </blockquote>
25209
25210 <p>See also the <a href="#unicode">unicode</a> and <a href="#utf8">utf8</a> functions.</p>
25211 <p></p>
25212
25213 <br /><br />
25214 <!-- 8.9.4 -->
25215 <a NAME="uuid"></a>
25216 <h2><span class="function">uuid</span></h2>
25217 <b>syntax: (uuid [<em>str-node</em>])</b>
25218
25219 <p>
25220         Constructs and returns
25221         a UUID (Universally Unique IDentifier).
25222         Without a node spec in <em>str-node</em>,
25223         a type 4 UUID random generated byte number
25224         is returned.
25225         When the optional <em>str-node</em> parameter is used,
25226         a type 1 UUID is returned.
25227         The string in <em>str-node</em>
25228         specifies a valid MAC (Media Access Code)
25229         from a network adapter installed on the node
25230         or a random node ID.
25231         When a random node ID is specified,
25232         the least significant bit of the first node byte
25233         should be set to 1
25234         to avoid clashes with real MAC identifiers.
25235         UUIDs of type 1 with node ID
25236         are generated from a timestamp and other data.
25237         See <a href="http://www.ietf.org/rfc/rfc4122.txt">RFC 4122</a>
25238         for details on UUID generation.
25239 </p>
25240
25241 <b>example:</b>
25242 <blockquote>
25243 <pre>
25244 ;; type 4 UUID for any system
25245
25246 (uuid)  <span class=arw>&rarr;</span> "493AAD61-266F-48A9-B99A-33941BEE3607"
25247
25248 ;; type 1 UUID preferred for distributed systems
25249
25250 ;; configure node ID for ether 00:14:51:0a:e0:bc
25251 (set 'id (pack "cccccc" 0x00 0x14 0x51 0x0a 0xe0 0xbc))
25252
25253 (uuid  id)  <span class=arw>&rarr;</span> "0749161C-2EC2-11DB-BBB2-0014510AE0BC"
25254 </pre>
25255 </blockquote>
25256
25257 <p>
25258         Each invocation of the <tt>uuid</tt> function
25259         will yield a new unique UUID.
25260         The UUIDs are generated without systemwide
25261         shared stable store (see RFC 4122).
25262         If the system generating the UUIDs
25263         is distributed over several nodes,
25264         then type 1 generation should be used
25265         with a different node ID on each node.
25266         For several processes on the same node,
25267         valid UUIDs are guaranteed
25268         even if requested at the same time.
25269         This is because the process ID
25270         of the generating newLISP process
25271         is part of the seed
25272         for the random number generator.
25273         When type 4 IDs are used on a distributed system,
25274         two identical UUID's are still highly unlikely
25275         and impossible for type 1 IDs
25276         if real MAC addresses are used.
25277 </p>
25278
25279 <br><br>
25280
25281
25282 <a NAME="wait-pid"></a>
25283 <h2><span class="function">wait-pid</span></h2>
25284 <b>syntax: (wait-pid <em>int-pid</em> [<em>int-options</em>])</b>
25285
25286 <p>
25287         Waits for a child process specified in <em>int-pid</em> to end.
25288         The child process was previously started
25289         with <a href="#process">process</a> or <a href="#fork">fork</a>.
25290         When the child process specified in <em>int-pid</em> ends,
25291         a status value describing the reason for termination
25292         of the child process or thread is returned.
25293         The interpretation of the returned status value
25294         differs between Linux and other flavors of UNIX.
25295         Consult the Linux/UNIX man pages
25296         for the <tt>waitpid</tt> command
25297         (without the hyphen used in newLISP)
25298         for further information.
25299 </p>
25300
25301 <p>
25302         When <tt>-1</tt> is specified for <em>int-pid</em>,
25303         the status information of any child process started is returned.
25304         When <tt>0</tt> is specified,
25305         <tt>wait-pid</tt> only watches
25306         child processes in the same process group
25307         as the calling process.
25308         Any other negative value for <em>int-pid</em>
25309         reports child processes in the same process group
25310         as specified with a negative sign in <em>int-pid</em>.
25311 </p>
25312
25313 <p>
25314         This function is only available on Linux
25315         and other UNIX-like operating systems
25316         or on a CYGWIN compiled version of newLISP
25317         on Win32.
25318         An option can be specified in <em>int-option</em>.
25319         See Linux/UNIX documentation
25320         for details on options.
25321 </p>
25322
25323 <b>example:</b>
25324 <blockquote><pre>
25325 (set 'pid (fork (my-thread)))
25326
25327 (set 'status (wait-pid pid))  ; wait until my-thread ends
25328
25329 (println "thread: " pid " has finished with status: " status)
25330 </pre></blockquote>
25331
25332 <p>
25333         The process <tt>my-thread</tt> is started,
25334         then the main program blocks
25335         in the <tt>wait-pid</tt> call
25336         until <tt>my-thread</tt> has finished.
25337 </p>
25338
25339 <br /><br />
25340
25341 <a NAME="when"></a>
25342 <h2><span class="function">when</span></h2>
25343 <b>syntax: (when <em>exp-condition</em> <em>body</em>)</b>
25344
25345 <p>The statements in <em>body</em> are only evaluated if <em>exp-condition</em>
25346 evalutes to <tt>true</tt></p>
25347
25348 <p>Because <tt>when</tt> does not have an <em>else</em> condition as in
25349 <a href="#if">if</a>, the statements in <em>body</em> need not to be grouped with
25350 <a href="#begin">begin</a>:</p>
25351
25352 <blockquote><pre>
25353 (when (read-line)
25354         (set 'result (analyze (current-line)))
25355         (report result
25356         (finish)
25357 )
25358 </pre></blockquote>
25359 <br /><br />
25360
25361 <a NAME="while"></a>
25362 <h2><span class="function">while</span></h2>
25363 <b>syntax: (while <em>exp-condition</em> <em>body</em>)</b>
25364
25365 <p>
25366         Evaluates the condition
25367         in <em>exp-condition</em>.
25368         If the result is not <tt>nil</tt> or the empty list <tt>()</tt>,
25369         the expressions in <em>body</em> are evaluated.
25370         Evaluation is repeated until an <em>exp-condition</em> results
25371         in <tt>nil</tt> or the empty list <tt>()</tt>.
25372         The result of the body's last expression
25373         is the return value of
25374         the <tt>while</tt> expression.
25375 </p>
25376
25377 <b>example:</b>
25378 <blockquote>
25379 <pre>
25380 (device (open "somefile.txt" "read"))
25381 (set 'line-count 0)
25382 (while (read-line) (inc 'line-count))
25383 (close (device))
25384 (print "the file has " line-count " lines\n")
25385 </pre>
25386 </blockquote>
25387
25388 <p>
25389         Use the <a href="#do-while">do-while</a> function
25390         to evaluate the condition
25391         <em>after</em> evaluating the body of expressions.
25392 </p>
25393
25394 <br /><br />
25395
25396 <a NAME="write-buffer"></a>
25397
25398 <h2><span class="function">write-buffer</span></h2>
25399 <b>syntax: (write-buffer <em>int-file</em> <em>sym-buffer</em> [<em>int-size</em>])</b><br />
25400 <b>syntax: (write-buffer <em>int-file</em> <em>str-buffer</em> [<em>int-size</em>])</b><br /><br />
25401
25402 <b>syntax: (write-buffer <em>str-device</em> <em>sym-buffer</em> [<em>int-size</em>])</b><br />
25403 <b>syntax: (write-buffer <em>str-device</em> <em>str-buffer</em> [<em>int-size</em>])</b>
25404
25405
25406 <p>
25407         Using the first syntax,
25408         <tt>write-buffer</tt> writes <em>int-size</em> bytes
25409         from a buffer in <em>sym-buffer</em> or <em>str-buffer</em>
25410         to a file specified in <em>int-file</em>,
25411         previously obtained from a file <tt>open</tt> operation.
25412         If <em>int-size</em> is not specified,
25413         all data in <em>sym-buffer</em> or <em>str-buffer</em>
25414         is written.
25415         <tt>write-buffer</tt> returns the number of bytes written
25416         or <tt>nil</tt> on failure.
25417 </p>
25418
25419 <p>
25420         The string buffer symbol can be used
25421         with or without quoting a symbol.
25422 </p>
25423
25424 <b>example:</b>
25425 <blockquote>
25426 <pre>
25427 (set 'handle (open "myfile.ext" "write"))
25428 (write-buffer handle 'data 100)
25429
25430 ;; string buffer w/o quote
25431 (write-buffer handle data 100)
25432 (write-buffer handle "a quick message\n")
25433 </pre>
25434 </blockquote>
25435 <p>
25436         The code in the example writes 100 bytes
25437         to the file <tt>myfile.ext</tt>
25438         from the contents in <tt>data</tt>.
25439 </p>
25440
25441 <p>
25442         Using the second syntax,
25443         <tt>write-buffer</tt> appends contents from a string
25444         specified in <em>sym-buffer</em> or <em>str-buffer</em>
25445         to the string specified in <em>str-device</em>,
25446         which acts like a stream device.
25447 </p>
25448
25449
25450 <b>example:</b>
25451 <blockquote>
25452 <pre>
25453 ;; fast in-place string appending
25454 (set 'str "")
25455 (dotimes (x 5) (write-buffer str "hello"))
25456
25457 str  <span class=arw>&rarr;</span> "HelloHelloHelloHelloHello")
25458
25459 ;; much slower method of string concatenation
25460 (dotimes (x 5) (set 'str (append str "hello")))
25461 </pre>
25462 </blockquote>
25463
25464 <p>
25465         The above example appends a string to <tt>str</tt> five times.
25466         This method is much faster than
25467         using <a href="#append">append</a>
25468         when concatenating to a string in place.
25469 </p>
25470
25471 <p>
25472         See also the <a HREF="#read-buffer">read-buffer</a> function.
25473 </p>
25474
25475 <br /><br />
25476
25477 <a NAME="write-char"></a>
25478 <h2><span class="function">write-char</span></h2>
25479 <b>syntax: (write-char <em>int-file int-byte</em>)</b>
25480
25481 <p>
25482         Writes a byte specified in <em>int-byte</em>
25483         to a file specified by the file handle in <em>int-file</em>.
25484         The file handle is obtained
25485         from a previous <tt>open</tt> operation.
25486         Each <tt>write-char</tt> advances the file pointer
25487         by one byte.
25488 </p>
25489
25490 <b>example:</b>
25491 <blockquote>
25492 <pre>
25493 (define (slow-file-copy from-file to-file)
25494     (set 'in-file (open from-file "read"))
25495     (set 'out-file (open to-file "write"))
25496     (while (set 'chr (read-file in-file))
25497         (write-char out-file chr))
25498      (close in-file)
25499     (close out-file)
25500     "finished")
25501 </pre>
25502 </blockquote>
25503
25504 <p>
25505         Use the <a HREF="#print">print</a>
25506         and <a HREF="#device">device</a> functions
25507         to write larger portions of data at a time.
25508         Note that newLISP already supplies a faster
25509         built-in function called
25510         <a HREF="#copy-file">copy-file</a>.
25511 </p>
25512
25513 <p>
25514         See also the <a HREF="#read-char">read-char</a> function.
25515 </p>
25516
25517 <br /><br />
25518
25519 <a NAME="write-file"></a>
25520 <h2><span class="function">write-file</span></h2>
25521 <b>syntax: (write-file <em>str-file-name</em> <em>str-buffer</em>)</b>
25522
25523 <p>
25524         Writes a file in <em>str-file-name</em>
25525         with contents in <em>str-buffer</em>
25526         in one swoop and returns
25527         the number of bytes written.
25528 </p>
25529
25530 <b>example:</b>
25531 <blockquote>
25532 <pre>
25533 (write-file "myfile.enc"
25534     (encrypt (read-file "/home/lisp/myFile") "secret"))
25535 </pre>
25536 </blockquote>
25537
25538 <p>
25539         The file <tt>myfile</tt> is read,
25540         <a HREF="#encrypt">encrypted</a> using the password <tt>secret</tt>,
25541         and written back into the new file <tt>myfile.enc</tt>
25542         in the current directory.
25543 </p>
25544
25545 <p>
25546         <tt>write-file</tt> can take an
25547         <tt>http://</tt> or <tt>file://</tt> URL
25548         in <em>str-file-name</em>.
25549         In this case,
25550         <tt>write-file</tt> works exactly like <a href="#put-url">put-url</a>
25551         and can take the same additional parameters:
25552 </p>
25553
25554 <b>example:</b>
25555 <blockquote>
25556 <pre>
25557 (write-file "http://asite.com/message.txt" "This is a message" )
25558 </pre>
25559 </blockquote>
25560
25561 <p>
25562         The file <tt>message.txt</tt> is created
25563         and written at a remote location, <tt>http://asite.com</tt>,
25564         with the contents of <em>str-buffer</em>.
25565         In this mode,
25566         <tt>write-file</tt> can also be used to transfer files
25567         to remote newLISP server nodes.
25568 </p>
25569
25570 <p>
25571         See also the <a HREF="#append-file">append-file</a>
25572         and <a HREF="#read-file">read-file</a> functions.
25573 </p>
25574
25575 <br /><br />
25576
25577 <a NAME="write-line"></a>
25578 <h2><span class="function">write-line</span></h2>
25579 <b>syntax: (write-line [<em>str</em>] [<em>int-file</em>])</b><br />
25580
25581 <b>syntax: (write-line [<em>str</em>] [<em>str-device</em>])</b>
25582
25583 <p>
25584         The string in <em>str</em>
25585         and the line termination character(s)
25586         are written to the console or a file.
25587         If no file handle is specified in <em>int-file</em>,
25588         <tt>write-line</tt> writes to the current device,
25589         normally the console screen.
25590         When all arguments are omitted,
25591         <tt>write-line</tt> writes the contents
25592         of the last <a HREF="#read-line">read-line</a> to the screen.
25593 </p>
25594
25595 <b>example:</b>
25596 <blockquote>
25597 <pre>
25598 (write-line "hello there")
25599
25600 (set 'out-file (open "myfile" "write"))
25601 (write-line "hello there" out-file)
25602 (close out-file)
25603
25604 (set 'myFile (open "init.lsp" "read")
25605 (while (read-line myFile) (write-line))
25606
25607 ;; using a string device:
25608
25609 (set 'str "")
25610 (dotimes (x 4) (write-line "hello" str))
25611
25612 str  <span class=arw>&rarr;</span> "hello\r\nhello\r\nhello\r\nhello\r\n"  ; on Win32
25613
25614 str  <span class=arw>&rarr;</span> "hello\nhello\nhello\nhello\n"  ; on Linux/UNIX
25615 </pre>
25616 </blockquote>
25617
25618 <p>
25619         The first example puts a string out on the current <a HREF="#device">device</a>,
25620         which is probably the console window <tt>(device 0)</tt>.
25621         The second example opens/creates a file,
25622         writes a line to it,
25623         and closes the file.
25624         The third example shows the usage of <tt>write-line</tt>
25625         without arguments.
25626         The contents of <tt>init.lsp</tt>
25627         are written to the console screen.
25628 </p>
25629
25630 <p>
25631         In the second syntax,
25632         a string can be specified
25633         as a device in <em>str-device</em>
25634         (like the <a href="#write-buffer">write-buffer</a> function).
25635         When a string device is written to,
25636         the string in <em>str-device</em> gets appended with <em>str</em>
25637         and the line termination character(s).
25638 </p>
25639
25640 <br /><br />
25641
25642
25643 <a NAME="xml-error"></a>
25644 <h2><span class="function">xml-error</span></h2>
25645 <b>syntax: (xml-error)</b>
25646
25647 <p>
25648         Returns a list of error information
25649         from the last <a HREF="#xml-parse">xml-parse</a> operation;
25650         otherwise, returns <tt>nil</tt>
25651         if no error occurred.
25652         The first element contains text
25653         describing the error,
25654         and the second element is a number indicating
25655         the last scan position in the source XML text,
25656         starting at 0 (zero).
25657 </p>
25658
25659 <b>example:</b>
25660 <blockquote>
25661 <pre>
25662 (xml-parse "&lt;atag&gt;hello&lt;/atag&gt;&lt;fin")  <span class=arw>&rarr;</span> nil
25663
25664 (xml-error)  <span class=arw>&rarr;</span> ("expected closing tag: &gt;" 18)
25665 </pre>
25666 </blockquote>
25667
25668 <br /><br />
25669
25670
25671 <a NAME="xml-parse"></a>
25672 <h2><span class="function">xml-parse</span></h2>
25673 <b>syntax: (xml-parse <em>string-xml</em> [<em>int-options</em> [<em>sym-context</em> [<em>func-callback</em>]])</b>
25674
25675 <p>
25676         Parses a string containing XML 1.0 compliant,
25677         <em>well-formed</em> XML.
25678         <tt>xml-parse</tt> does not perform DTD validation.
25679         It skips DTDs (Document Type Declarations)
25680         and processing instructions.
25681         Nodes of type ELEMENT, TEXT, CDATA,
25682         and COMMENT are parsed, and
25683         a newLISP list structure is returned.
25684         When an element node does not have
25685         attributes or child nodes,
25686         it instead contains an empty list.
25687         Attributes are returned as association lists,
25688         which can be accessed using <a HREF="#assoc">assoc</a>.
25689         When <tt>xml-parse</tt> fails
25690         due to malformed XML,
25691         <tt>nil</tt> is returned
25692         and <a HREF="#xml-error">xml-error</a> can be used
25693         to access error information.
25694 </p>
25695
25696 <b>example:</b>
25697 <blockquote>
25698 <pre>
25699 (set 'xml
25700   "&lt;person name='John Doe' tel='555-1212'&gt;nice guy&lt;/person&gt;")
25701
25702 (xml-parse xml)
25703 <span class=arw>&rarr;</span> (("ELEMENT" "person"
25704     (("name" "John Doe")
25705      ("tel" "555-1212"))
25706     (("TEXT" "nice guy"))))
25707 </pre>
25708 </blockquote>
25709
25710 <br />
25711 <b>Modifying the translation process.</b>
25712 <p>
25713         Optionally, the <em>int-options</em> parameter
25714         can be specified
25715         to suppress whitespace,
25716         empty attribute lists,
25717         and comments.
25718         It can also be used
25719         to transform tags
25720         from strings into symbols.
25721         Another function, <a HREF="#xml-type-tags">xml-type-tags</a>,
25722         serves for translating the XML tags.
25723         The following option numbers can be used:
25724 </p>
25725
25726 <br />
25727
25728 <blockquote>
25729 <table border="0" cellpadding="1" summary="option numbers for xml-parse">
25730 <tr align="left" valign="bottom"><th>option</th><th>description</th></tr>
25731 <tr><td>1</td><td>suppress whitespace text tags</td></tr>
25732 <tr><td>2</td><td>suppress empty attribute lists</td></tr>
25733 <tr><td>4</td><td>suppress comment tags</td></tr>
25734 <tr><td>8</td><td>translate string tags into symbols</td></tr>
25735
25736 <tr><td>16</td><td>add SXML (S-expression XML) attribute tags</td></tr>
25737 </table>
25738 </blockquote>
25739 <br />
25740 <p>
25741         Options can be combined
25742         by adding the numbers
25743         (e.g., <tt>3</tt> would combine the options
25744         for suppressing whitespace text tags/info
25745         and empty attribute lists).
25746 </p>
25747
25748 <p>
25749         The following examples
25750         show how the different options can be used:
25751 </p>
25752 <br />
25753 <b>XML source:</b>
25754
25755 <blockquote>
25756 <pre>
25757 &lt;?xml version="1.0" ?&gt;
25758 &lt;DATABASE name="example.xml"&gt;
25759 &lt;!--This is a database of fruits--&gt;
25760     &lt;FRUIT&gt;
25761         &lt;NAME&gt;apple&lt;/NAME&gt;
25762         &lt;COLOR&gt;red&lt;/COLOR&gt;
25763         &lt;PRICE&gt;0.80&lt;/PRICE&gt;
25764     &lt;/FRUIT&gt;
25765
25766     &lt;FRUIT&gt;
25767         &lt;NAME&gt;orange&lt;/NAME&gt;
25768         &lt;COLOR&gt;orange&lt;/COLOR&gt;
25769         &lt;PRICE&gt;1.00&lt;/PRICE&gt;
25770     &lt;/FRUIT&gt;
25771
25772     &lt;FRUIT&gt;
25773        &lt;NAME&gt;banana&lt;/NAME&gt;
25774        &lt;COLOR&gt;yellow&lt;/COLOR&gt;
25775        &lt;PRICE&gt;0.60&lt;/PRICE&gt;
25776     &lt;/FRUIT&gt;
25777 &lt;/DATABASE&gt;
25778 </pre>
25779 </blockquote>
25780
25781 <br />
25782 <b>Parsing without any options:</b>
25783
25784 <blockquote>
25785 <pre>
25786 (xml-parse (read-file "example.xml"))
25787 <span class=arw>&rarr;</span> (("ELEMENT" "DATABASE" (("name" "example.xml")) (("TEXT" "\r\n\t")
25788     ("COMMENT" "This is a database of fruits")
25789     ("TEXT" "\r\n\t")
25790     ("ELEMENT" "FRUIT" () (("TEXT" "\r\n\t\t") ("ELEMENT" "NAME" ()
25791        (("TEXT" "apple")))
25792       ("TEXT" "\r\n\t\t")
25793       ("ELEMENT" "COLOR" () (("TEXT" "red")))
25794       ("TEXT" "\r\n\t\t")
25795       ("ELEMENT" "PRICE" () (("TEXT" "0.80")))
25796       ("TEXT" "\r\n\t")))
25797     ("TEXT" "\r\n\r\n\t")
25798     ("ELEMENT" "FRUIT" () (("TEXT" "\r\n\t\t") ("ELEMENT" "NAME" ()
25799        (("TEXT" "orange")))
25800       ("TEXT" "\r\n\t\t")
25801       ("ELEMENT" "COLOR" () (("TEXT" "orange")))
25802       ("TEXT" "\r\n\t\t")
25803       ("ELEMENT" "PRICE" () (("TEXT" "1.00")))
25804       ("TEXT" "\r\n\t")))
25805     ("TEXT" "\r\n\r\n\t")
25806     ("ELEMENT" "FRUIT" () (("TEXT" "\r\n\t\t") ("ELEMENT" "NAME" ()
25807        (("TEXT" "banana")))
25808       ("TEXT" "\r\n\t\t")
25809       ("ELEMENT" "COLOR" () (("TEXT" "yellow")))
25810       ("TEXT" "\r\n\t\t")
25811       ("ELEMENT" "PRICE" () (("TEXT" "0.60")))
25812       ("TEXT" "\r\n\t")))
25813     ("TEXT" "\r\n"))))
25814 </pre>
25815 </blockquote>
25816
25817 <p>
25818         The <tt>TEXT</tt> elements containing only whitespace
25819         make the output very confusing.
25820         As the database in <tt>example.xml</tt> only contains data,
25821         we can suppress whitespace and comments
25822         with option <tt>(+ 1 3)</tt>:
25823 </p>
25824
25825 <br />
25826
25827 <b>Filtering whitespace TEXT, COMMENT tags, and empty attribute lists:</b>
25828
25829 <blockquote>
25830 <pre>
25831 (xml-parse (read-file "example.xml") (+ 1 2 4))
25832 <span class=arw>&rarr;</span> (("ELEMENT" "DATABASE" (("name" "example.xml")) (
25833      ("ELEMENT" "FRUIT" (
25834        ("ELEMENT" "NAME" (("TEXT" "apple")))
25835        ("ELEMENT" "COLOR" (("TEXT" "red")))
25836        ("ELEMENT" "PRICE" (("TEXT" "0.80")))))
25837      ("ELEMENT" "FRUIT" (
25838        ("ELEMENT" "NAME" (("TEXT" "orange")))
25839        ("ELEMENT" "COLOR" (("TEXT" "orange")))
25840        ("ELEMENT" "PRICE" (("TEXT" "1.00")))))
25841      ("ELEMENT" "FRUIT" (
25842        ("ELEMENT" "NAME" (("TEXT" "banana")))
25843        ("ELEMENT" "COLOR" (("TEXT" "yellow")))
25844        ("ELEMENT" "PRICE" (("TEXT" "0.60"))))))))
25845 </pre>
25846 </blockquote>
25847
25848 <p>
25849         The resulting output looks much more readable,
25850         but it can still be improved
25851         by using symbols instead of strings
25852         for the tags "FRUIT", "NAME", "COLOR", and "PRICE",
25853         as well as by suppressing the XML type tags
25854         "ELEMENT" and "TEXT" completely
25855         using the <a HREF="#xml-type-tags">xml-type-tags</a> directive.
25856 </p>
25857
25858 <br />
25859
25860 <b>Suppressing XML type tags with <a HREF="#xml-type-tags">xml-type-tags</a> and translating string tags into symbol tags:</b>
25861
25862 <blockquote>
25863 <pre>
25864 ;; suppress all XML type tags for TEXT and ELEMENT
25865 ;; instead of "CDATA", use cdata and instead of "COMMENT", use !--
25866
25867 (xml-type-tags nil 'cdata '!-- nil)
25868
25869 ;; turn on all options for suppressing whitespace and empty
25870 ;; attributes, translate tags to symbols
25871
25872 (xml-parse (read-file "example.xml") (+ 1 2 8))
25873 <span class=arw>&rarr;</span> ((DATABASE (("name" "example.xml"))
25874      (!-- "This is a database of fruits")
25875      (FRUIT (NAME "apple") (COLOR "red") (PRICE "0.80"))
25876      (FRUIT (NAME "orange") (COLOR "orange") (PRICE "1.00"))
25877      (FRUIT (NAME "banana") (COLOR "yellow") (PRICE "0.60"))))
25878 </pre>
25879 </blockquote>
25880
25881 <p>
25882         When tags are translated into symbols by using option <tt>8</tt>,
25883         a context can be specified in <em>sym-context</em>.
25884         If no context is specified,
25885         all symbols will be created inside the current context.
25886 </p>
25887
25888 <blockquote>
25889 <pre>
25890 (xml-type-tags nil nil nil nil)
25891 (xml-parse "&lt;msg&gt;Hello World&lt;/msg&gt;" (+ 1 2 4 8 16) 'CTX)
25892 <span class=arw>&rarr;</span> ((CTX:msg "Hello World"))
25893 </pre>
25894 </blockquote>
25895
25896 <p>
25897         Specifying <tt>nil</tt> for the XML type tags TEXT and ELEMENT
25898         makes them disappear.
25899         At the same time,
25900         parentheses of the child node list
25901         are removed so that
25902         child nodes now appear as members of the list,
25903         starting with the tag symbol
25904         translated from the string tags
25905         "FRUIT", "NAME", etcetera.
25906 </p>
25907
25908 <br />
25909 <b>Parsing into SXML (S-expressions XML) format:</b>
25910 <p>
25911         Using <a href="#xml-type-tags">xml-type-tags</a> to suppress
25912         all XML-type tags&mdash;along with the option numbers
25913         <tt>1</tt>, <tt>4</tt>, <tt>8</tt>, and <tt>16</tt>&mdash;SXML
25914         formatted output can be generated:
25915 </p>
25916
25917 <blockquote>
25918 <pre>
25919 (xml-type-tags nil nil nil nil)
25920 (xml-parse (read-file "example.xml") (+ 1 2 4 8 16))
25921 <span class=arw>&rarr;</span> ((DATABASE (@ (name "example.xml"))
25922     (FRUIT (NAME "apple") (COLOR "red") (PRICE "0.80"))
25923     (FRUIT (NAME "orange") (COLOR "orange") (PRICE "1.00"))
25924     (FRUIT (NAME "banana") (COLOR "yellow") (PRICE "0.60"))))
25925 </pre>
25926 </blockquote>
25927
25928 <p>
25929         Note that using option number <tt>16</tt>
25930         causes an <tt>@</tt> (at symbol) to be added to attribute lists.
25931 </p>
25932
25933 <p>
25934         See also the <a HREF="#xml-type-tags">xml-type-tags</a> function
25935         for further information on XML parsing.
25936 </p>
25937 <br />
25938 <b>Parsing into a specified context</b>
25939 <p>When parsing XML expressions XML tags are translated into newLISP symbols.
25940 The <i>sym-context</i> option specifies the target context for the symbol
25941 creation:
25942 <blockquote>
25943 <pre>
25944 (xml-type-tags nil nil nil nil)
25945 (xml-parse (read-file "example.xml") (+ 1 2 4 8 16) 'CTX)
25946 <span class=arw>&rarr;</span>((CTX:DATABASE (@ (name "example.xml"))
25947     (CTX:FRUIT (CTX:NAME "apple") (CTX:COLOR "red") (CTX:PRICE "0.80"))
25948     (CTX:FRUIT (CTX:NAME "orange") (CTX:COLOR "orange") (CTX:PRICE "1.00"))
25949     (CTX:FRUIT (CTX:NAME "banana") (CTX:COLOR "yellow") (CTX:PRICE "0.60"))))
25950 </pre>
25951 </blockquote>
25952
25953 <p>If the context does not exist, it will be created. If it exists, the quote can
25954 be omitted or the context can be referred to by a variable.</p>
25955
25956 <blockquote>
25957 <pre>
25958 </pre>
25959 </blockquote>
25960
25961
25962 <br />
25963 <b>Using a call back function</b>
25964 <p>Normally <tt>xml-parse</tt> will not return until all parsing has finished.
25965 Using the <em>func-callback</em> option <tt>xml-parse</tt> will call back after
25966 each tag closing with the generated S-expression and a start position and
25967 length in the source XML:</p>
25968
25969 <blockquote>
25970 <pre>
25971 ;; demo callback feature
25972 (define (xml-callback s-expr start size)
25973     (if (or (= (s-expr 0) 'NAME) (= (s-expr 0) 'COLOR) (= (s-expr 0) 'PRICE))
25974         (begin
25975             (print "parsed expresson:" s-expr)
25976             (println ", source:" (start size example-xml))
25977         )
25978     )
25979 )
25980
25981 (xml-type-tags nil 'cdata '!-- nil)
25982 (xml-parse  (read-file "example.xml") (+ 1 2 8) MAIN xml-callback)
25983 </pre>
25984 </blockquote>
25985
25986 <p>THe following output will be generated by the callback function <tt>xml-callback</tt>:</p>
25987 <blockquote>
25988 <pre>
25989 parsed expresson:(NAME "apple"), source:&lt;NAME&gt;apple&lt;/NAME&gt;
25990 parsed expresson:(COLOR "red"), source:&lt;COLOR&gt;red&lt;/COLOR&gt;
25991 parsed expresson:(PRICE "0.80"), source:&lt;PRICE&gt;0.80&lt;/PRICE&gt;
25992 parsed expresson:(NAME "orange"), source:&lt;NAME&gt;orange&lt;/NAME&gt;
25993 parsed expresson:(COLOR "orange"), source:&lt;COLOR&gt;orange&lt;/COLOR&gt;
25994 parsed expresson:(PRICE "1.00"), source:&lt;PRICE&gt;1.00&lt;/PRICE&gt;
25995 parsed expresson:(NAME "banana"), source:&lt;NAME&gt;banana&lt;/NAME&gt;
25996 parsed expresson:(COLOR "yellow"), source:&lt;COLOR&gt;yellow&lt;/COLOR&gt;
25997 parsed expresson:(PRICE "0.60"), source:&lt;PRICE&gt;0.60&lt;/PRICE&gt;
25998 </pre>
25999 </blockquote>
26000
26001 <p>The example callback handler function filters the tags of interest and processes
26002 them as they occur.</p>
26003
26004 <br /><br />
26005
26006 <a NAME="xml-type-tags"></a>
26007 <h2><span class="function">xml-type-tags</span></h2>
26008
26009 <b>syntax: (xml-type-tags [<em>expr-text-tag</em> <em>expr-cdata-tag</em> <em>expr-comment-tag</em> <em>expr-element-tags</em>])</b>
26010
26011 <p>
26012         Can suppress completely
26013         or replace the XML type tags
26014         "TEXT", "CDATA", "COMMENT", and "ELEMENT"
26015         with something else specified
26016         in the parameters.
26017 </p>
26018
26019 <p>
26020         Note that <tt>xml-type-tags</tt>
26021         only suppresses or translates the tags themselves
26022         but does not suppress or modify the tagged information.
26023         The latter would be done
26024         using option numbers in <a HREF="#xml-parse">xml-parse</a>.
26025 </p>
26026
26027 <p>
26028         Using <tt>xml-type-tags</tt> without arguments
26029         returns the current type tags:
26030 </p>
26031
26032 <b>example:</b>
26033 <blockquote>
26034 <pre>
26035 (xml-type-tags)  <span class=arw>&rarr;</span> ("TEXT" "CDATA" "COMMENT" "ELEMENT")
26036
26037 (xml-type-tags nil 'cdata '!-- nil)
26038 </pre>
26039 </blockquote>
26040
26041 <p>
26042         The first example just shows the currently used type tags.
26043         The second example specifies suppression of the "TEXT" and "ELEMENT" tags
26044         and shows <tt>cdata</tt> and <tt>!--</tt> instead of
26045         "CDATA" and "COMMENT".
26046 </p>
26047
26048 <br /><br />
26049
26050 <a NAME="zerop"></a>
26051 <h2><span class="function">zero?</span></h2>
26052 <b>syntax: (zero? <em>expr</em>)</b>
26053
26054 <p>
26055         Checks the evaluation of <em>expr</em>
26056         to see if it equals <tt>0</tt> (zero).
26057 </p>
26058
26059 <b>example:</b>
26060 <blockquote>
26061 <pre>
26062 (set 'value 1.2)
26063 (set 'var 0)
26064 (zero? value)  <span class=arw>&rarr;</span> nil
26065 (zero? var)    <span class=arw>&rarr;</span> true
26066
26067 (map zero? '(0 0.0 3.4 4))  <span class=arw>&rarr;</span> (true true nil nil)
26068 </pre>
26069 </blockquote>
26070
26071 <p>
26072         <tt>zero?</tt> will return <tt>nil</tt>
26073         on data types other than numbers.
26074 </p>
26075
26076 <br /><br />
26077
26078
26079 <center style="font-size: 150%">
26080 <span class="divider">(&nbsp;<font color="#7ba9d4">&part;</font>&nbsp;)</span>
26081 </center>
26082
26083 <br /><br />
26084
26085 <a NAME="error_codes"></a>
26086 <center><h1>newLISP APPENDIX</h1></center>
26087
26088 <h2>Error codes</h2>
26089
26090 <blockquote>
26091 <pre>
26092     not enough memory                  1
26093     environment stack overflow         2
26094     call stack overflow                3
26095     problem accessing file             4
26096     not an expression                  5
26097     missing parenthesis                6
26098     string token too long              7
26099     missing argument                   8
26100     number or string expected          9
26101     value expected                    10
26102     string expected                   11
26103     symbol expected                   12
26104     context expected                  13
26105     symbol or context expected        14
26106     list expected                     15
26107     list or array expected            16
26108     list or symbol expected           17
26109     list or string expected           18
26110     list or number expected           19
26111     array expected                    20
26112     array, list or string expected    21
26113     lambda expected                   22
26114     lambda-macro expected             23
26115     invalid function                  24
26116     invalid lambda expression         25
26117     invalid macro expression          26
26118     invalid let parameter list        27
26119     problem saving file               28
26120     division by zero                  29
26121     matrix expected                   30
26122     wrong dimensions                  31
26123     matrix is singular                32
26124     syntax in regular expression      33
26125     throw without catch               34
26126     problem loading library           35
26127     import function not found         36
26128     symbol is protected               37
26129     error number too high             38
26130     regular expression                39
26131     missing end of text [/text]       40
26132     mismatch in number of arguments   41
26133     problem in format string          42
26134     data type and format don't match  43
26135     invalid parameter                 44
26136     invalid parameter: 0.0            45
26137     invalid parameter: NaN            46
26138     illegal parameter type            47
26139     symbol not in MAIN context        48
26140     symbol not in current context     49
26141     target cannot be MAIN             50
26142     list index out of bounds          51
26143     array index out of bounds         52
26144     string index out of bounds        53
26145     nesting level too deep            54
26146     user error                        55
26147     user reset -                      56
26148     received SIGINT -                 57
26149     function is not reentrant         58
26150 </pre>
26151 </blockquote>
26152
26153
26154 <br /><br /><br />
26155
26156 <a NAME="tcpip_error_codes"></a>
26157 <h2>TCP/IP and UDP Error Codes</h2>
26158
26159 <blockquote>
26160 <pre>
26161  0: No error
26162  1: Cannot open socket
26163  2: Host name not known
26164  3: Not a valid service
26165  4: Connection failed
26166  5: Accept failed
26167  6: Connection closed
26168  7: Connection broken
26169  8: Socket send() failed
26170  9: Socket recv() failed
26171 10: Cannot bind socket
26172 11: Too much sockets in net-select
26173 12: Listen failed
26174 13: Badly formed IP
26175 14: Select failed
26176 15: Peek failed
26177 16: Not a valid socket
26178 </pre>
26179 </blockquote>
26180
26181 <br /><br />
26182 <center style="font-size: 150%">
26183 <span class="divider">(&nbsp;<font color="#7ba9d4">&part;</font>&nbsp;)</span>
26184 </center>
26185 <br /><br />
26186
26187 <table BORDER=0 summary="GNUFDL">
26188 <tr>
26189 <td>
26190
26191 <blockquote>
26192 <a NAME="GNUFDL"></a>
26193 <center>
26194 <h2><span class="function">GNU Free Documentation License</span></h2>
26195 <p>Version 1.2, November 2002</p>
26196
26197 <p>
26198 Copyright (C) 2000,2001,2002  Free Software Foundation, Inc.
26199 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
26200 Everyone is permitted to copy and distribute verbatim copies
26201 of this license document, but changing it is not allowed.
26202 </p>
26203 </center>
26204
26205 <br><br>
26206
26207 <b>0. PREAMBLE</b>
26208
26209 <p>The purpose of this License is to make a manual, textbook, or other
26210 functional and useful document "free" in the sense of freedom: to
26211 assure everyone the effective freedom to copy and redistribute it,
26212 with or without modifying it, either commercially or noncommercially.
26213 Secondarily, this License preserves for the author and publisher a way
26214 to get credit for their work, while not being considered responsible
26215 for modifications made by others.
26216 </p>
26217 <p>This License is a kind of "copyleft", which means that derivative
26218 works of the document must themselves be free in the same sense. It
26219 complements the GNU General Public License, which is a copyleft
26220 license designed for free software.
26221 </p>
26222 <p>We have designed this License in order to use it for manuals for
26223 free
26224 software, because free software needs free documentation: a free
26225 program should come with manuals providing the same freedoms that the
26226 software does. But this License is not limited to software manuals;
26227 it can be used for any textual work, regardless of subject matter or
26228 whether it is published as a printed book. We recommend this License
26229 principally for works whose purpose is instruction or reference.
26230 </p>
26231 <p><b>1. APPLICABILITY AND DEFINITIONS</b>
26232 </p>
26233 <p>This License applies to any manual or other work, in any medium,
26234 that
26235 contains a notice placed by the copyright holder saying it can be
26236 distributed under the terms of this License. Such a notice grants a
26237 world-wide, royalty-free license, unlimited in duration, to use that
26238 work under the conditions stated herein. The "Document", below,
26239 refers to any such manual or work. Any member of the public is a
26240 licensee, and is addressed as "you". You accept the license if you
26241 copy, modify or distribute the work in a way requiring permission
26242 under copyright law.
26243 </p>
26244 <p>A "Modified Version" of the Document means any work containing the
26245 Document or a portion of it, either copied verbatim, or with
26246 modifications and/or translated into another language.
26247 </p>
26248 <p>A "Secondary Section" is a named appendix or a front-matter section
26249 of
26250 the Document that deals exclusively with the relationship of the
26251 publishers or authors of the Document to the Document's overall subject
26252 (or to related matters) and contains nothing that could fall directly
26253 within that overall subject. (Thus, if the Document is in part a
26254 textbook of mathematics, a Secondary Section may not explain any
26255 mathematics.) The relationship could be a matter of historical
26256 connection with the subject or with related matters, or of legal,
26257 commercial, philosophical, ethical or political position regarding
26258 them.
26259 </p>
26260 <p>The "Invariant Sections" are certain Secondary Sections whose titles
26261 are designated, as being those of Invariant Sections, in the notice
26262 that says that the Document is released under this License. If a
26263 section does not fit the above definition of Secondary then it is not
26264 allowed to be designated as Invariant. The Document may contain zero
26265 Invariant Sections. If the Document does not identify any Invariant
26266 Sections then there are none.
26267 </p>
26268 <p>The "Cover Texts" are certain short passages of text that are
26269 listed,
26270 as Front-Cover Texts or Back-Cover Texts, in the notice that says that
26271 the Document is released under this License. A Front-Cover Text may
26272 be at most 5 words, and a Back-Cover Text may be at most 25 words.
26273 </p>
26274 <p>A "Transparent" copy of the Document means a machine-readable copy,
26275 represented in a format whose specification is available to the
26276 general public, that is suitable for revising the document
26277 straightforwardly with generic text editors or (for images composed of
26278 pixels) generic paint programs or (for drawings) some widely available
26279 drawing editor, and that is suitable for input to text formatters or
26280 for automatic translation to a variety of formats suitable for input
26281 to text formatters. A copy made in an otherwise Transparent file
26282 format whose markup, or absence of markup, has been arranged to thwart
26283 or discourage subsequent modification by readers is not Transparent.
26284 An image format is not Transparent if used for any substantial amount
26285 of text. A copy that is not "Transparent" is called "Opaque".
26286 </p>
26287 <p>Examples of suitable formats for Transparent copies include plain
26288 ASCII without markup, Texinfo input format, LaTeX input format, SGML
26289 or XML using a publicly available DTD, and standard-conforming simple
26290 HTML, PostScript or PDF designed for human modification. Examples of
26291 transparent image formats include PNG, XCF and JPG. Opaque formats
26292 include proprietary formats that can be read and edited only by
26293 proprietary word processors, SGML or XML for which the DTD and/or
26294 processing tools are not generally available, and the
26295 machine-generated HTML, PostScript or PDF produced by some word
26296 processors for output purposes only.
26297 </p>
26298 <p>The "Title Page" means, for a printed book, the title page itself,
26299 plus such following pages as are needed to hold, legibly, the material
26300 this License requires to appear in the title page. For works in
26301 formats which do not have any title page as such, "Title Page" means
26302 the text near the most prominent appearance of the work's title,
26303 preceding the beginning of the body of the text.
26304 </p>
26305 <p>A section "Entitled XYZ" means a named subunit of the Document whose
26306 title either is precisely XYZ or contains XYZ in parentheses following
26307 text that translates XYZ in another language. (Here XYZ stands for a
26308 specific section name mentioned below, such as "Acknowledgements",
26309 "Dedications", "Endorsements", or "History".) To "Preserve the Title"
26310 of such a section when you modify the Document means that it remains a
26311 section "Entitled XYZ" according to this definition.
26312 </p>
26313 <p>The Document may include Warranty Disclaimers next to the notice
26314 which
26315 states that this License applies to the Document. These Warranty
26316 Disclaimers are considered to be included by reference in this
26317 License, but only as regards disclaiming warranties: any other
26318 implication that these Warranty Disclaimers may have is void and has
26319 no effect on the meaning of this License.
26320 </p>
26321 <p><b>2. VERBATIM COPYING</b>
26322 </p>
26323 <p>You may copy and distribute the Document in any medium, either
26324 commercially or noncommercially, provided that this License, the
26325 copyright notices, and the license notice saying this License applies
26326 to the Document are reproduced in all copies, and that you add no other
26327 conditions whatsoever to those of this License. You may not use
26328 technical measures to obstruct or control the reading or further
26329 copying of the copies you make or distribute. However, you may accept
26330 compensation in exchange for copies. If you distribute a large enough
26331 number of copies you must also follow the conditions in section 3.
26332 </p>
26333 <p>You may also lend copies, under the same conditions stated above,
26334 and
26335 you may publicly display copies.
26336 </p>
26337 <p><b>3. COPYING IN QUANTITY</b>
26338 </p>
26339 <p>If you publish printed copies (or copies in media that commonly have
26340 printed covers) of the Document, numbering more than 100, and the
26341 Document's license notice requires Cover Texts, you must enclose the
26342 copies in covers that carry, clearly and legibly, all these Cover
26343 Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on
26344 the back cover. Both covers must also clearly and legibly identify
26345 you as the publisher of these copies. The front cover must present
26346 the full title with all words of the title equally prominent and
26347 visible. You may add other material on the covers in addition.
26348 Copying with changes limited to the covers, as long as they preserve
26349 the title of the Document and satisfy these conditions, can be treated
26350 as verbatim copying in other respects.
26351 </p>
26352 <p>If the required texts for either cover are too voluminous to fit
26353 legibly, you should put the first ones listed (as many as fit
26354 reasonably) on the actual cover, and continue the rest onto adjacent
26355 pages.
26356 </p>
26357 <p>If you publish or distribute Opaque copies of the Document numbering
26358 more than 100, you must either include a machine-readable Transparent
26359 copy along with each Opaque copy, or state in or with each Opaque copy
26360 a computer-network location from which the general network-using
26361 public has access to download using public-standard network protocols
26362 a complete Transparent copy of the Document, free of added material.
26363 If you use the latter option, you must take reasonably prudent steps,
26364 when you begin distribution of Opaque copies in quantity, to ensure
26365 that this Transparent copy will remain thus accessible at the stated
26366 location until at least one year after the last time you distribute an
26367 Opaque copy (directly or through your agents or retailers) of that
26368 edition to the public.
26369 </p>
26370 <p>It is requested, but not required, that you contact the authors of
26371 the
26372 Document well before redistributing any large number of copies, to give
26373 them a chance to provide you with an updated version of the Document.
26374 </p>
26375 <p><b>4. MODIFICATIONS</b>
26376 </p>
26377 <p>You may copy and distribute a Modified Version of the Document under
26378 the conditions of sections 2 and 3 above, provided that you release
26379 the Modified Version under precisely this License, with the Modified
26380 Version filling the role of the Document, thus licensing distribution
26381 and modification of the Modified Version to whoever possesses a copy
26382 of it. In addition, you must do these things in the Modified Version:
26383 </p>
26384 <blockquote>
26385   <p><b>A.</b> Use in the Title Page (and on the covers, if
26386 any) a title distinct from that of the Document, and from those of
26387 previous versions (which should, if there were any, be listed in the
26388 History section of the Document). You may use the same title as a
26389 previous version if the original publisher of that version gives
26390 permission.</p>
26391   <p><b>B.</b> List on the Title Page, as authors, one or
26392 more persons or entities responsible for authorship of the
26393 modifications in the Modified Version, together with at least five of
26394 the principal authors of the Document (all of its principal authors, if
26395 it has fewer than five), unless they release you from this requirement.</p>
26396   <p><b>C.</b> State on the Title page the name of the
26397 publisher of the Modified Version, as the publisher.</p>
26398   <p><b>D.</b> Preserve all the copyright notices of the
26399 Document.</p>
26400   <p><b>E.</b> Add an appropriate copyright notice for your
26401 modifications adjacent to the other copyright notices.</p>
26402   <p><b>F.</b> Include, immediately after the copyright
26403 notices, a license notice giving the public permission to use the
26404 Modified Version under the terms of this License, in the form shown in
26405 the Addendum below.</p>
26406   <p><b>G.</b> Preserve in that license notice the full
26407 lists of Invariant Sections and required Cover Texts given in the
26408 Document's license notice.</p>
26409   <p><b>H.</b> Include an unaltered copy of this License.</p>
26410   <p><b>I.</b> Preserve the section Entitled "History",
26411 Preserve its Title, and add to it an item stating at least the title,
26412 year, new authors, and publisher of the Modified Version as given on
26413 the Title Page. If there is no section Entitled "History" in the
26414 Document, create one stating the title, year, authors, and publisher of
26415 the Document as given on its Title Page, then add an item describing
26416 the Modified Version as stated in the previous sentence.</p>
26417   <p><b>J.</b> Preserve the network location, if any, given
26418 in the Document for public access to a Transparent copy of the
26419 Document, and likewise the network locations given in the Document for
26420 previous versions it was based on. These may be placed in the "History"
26421 section. You may omit a network location for a work that was published
26422 at least four years before the Document itself, or if the original
26423 publisher of the version it refers to gives permission.</p>
26424   <p><b>K.</b> For any section Entitled "Acknowledgements"
26425 or "Dedications", Preserve the Title of the section, and preserve in
26426 the section all the substance and tone of each of the contributor
26427 acknowledgements and/or dedications given therein.</p>
26428   <p><b>L.</b> Preserve all the Invariant Sections of the
26429 Document, unaltered in their text and in their titles. Section numbers
26430 or the equivalent are not considered part of the section titles.</p>
26431   <p><b>M.</b> Delete any section Entitled "Endorsements".
26432 Such a section may not be included in the Modified Version.</p>
26433   <p><b>N.</b> Do not retitle any existing section to be
26434 Entitled "Endorsements" or to conflict in title with any Invariant
26435 Section.</p>
26436   <p><b>O.</b> Preserve any Warranty Disclaimers.</p>
26437 </blockquote>
26438 <p>
26439 If the Modified Version includes new front-matter sections or
26440 appendices that qualify as Secondary Sections and contain no material
26441 copied from the Document, you may at your option designate some or all
26442 of these sections as invariant. To do this, add their titles to the
26443 list of Invariant Sections in the Modified Version's license notice.
26444 These titles must be distinct from any other section titles.
26445 </p>
26446 <p>You may add a section Entitled "Endorsements", provided it contains
26447 nothing but endorsements of your Modified Version by various
26448 parties--for example, statements of peer review or that the text has
26449 been approved by an organization as the authoritative definition of a
26450 standard.
26451 </p>
26452 <p>You may add a passage of up to five words as a Front-Cover Text, and
26453 a
26454 passage of up to 25 words as a Back-Cover Text, to the end of the list
26455 of Cover Texts in the Modified Version. Only one passage of
26456 Front-Cover Text and one of Back-Cover Text may be added by (or
26457 through arrangements made by) any one entity. If the Document already
26458 includes a cover text for the same cover, previously added by you or
26459 by arrangement made by the same entity you are acting on behalf of,
26460 you may not add another; but you may replace the old one, on explicit
26461 permission from the previous publisher that added the old one.
26462 </p>
26463 <p>The author(s) and publisher(s) of the Document do not by this
26464 License
26465 give permission to use their names for publicity for or to assert or
26466 imply endorsement of any Modified Version.
26467 </p>
26468 <p><b>5. COMBINING DOCUMENTS</b>
26469 </p>
26470 <p>You may combine the Document with other documents released under
26471 this
26472 License, under the terms defined in section 4 above for modified
26473 versions, provided that you include in the combination all of the
26474 Invariant Sections of all of the original documents, unmodified, and
26475 list them all as Invariant Sections of your combined work in its
26476 license notice, and that you preserve all their Warranty Disclaimers.
26477 </p>
26478 <p>The combined work need only contain one copy of this License, and
26479 multiple identical Invariant Sections may be replaced with a single
26480 copy. If there are multiple Invariant Sections with the same name but
26481 different contents, make the title of each such section unique by
26482 adding at the end of it, in parentheses, the name of the original
26483 author or publisher of that section if known, or else a unique number.
26484 Make the same adjustment to the section titles in the list of
26485 Invariant Sections in the license notice of the combined work.
26486 </p>
26487 <p>In the combination, you must combine any sections Entitled "History"
26488 in the various original documents, forming one section Entitled
26489 "History"; likewise combine any sections Entitled "Acknowledgements",
26490 and any sections Entitled "Dedications". You must delete all sections
26491 Entitled "Endorsements."
26492 </p>
26493 <p><b>6. COLLECTIONS OF DOCUMENTS</b>
26494 </p>
26495 <p>You may make a collection consisting of the Document and other
26496 documents
26497 released under this License, and replace the individual copies of this
26498 License in the various documents with a single copy that is included in
26499 the collection, provided that you follow the rules of this License for
26500 verbatim copying of each of the documents in all other respects.
26501 </p>
26502 <p>You may extract a single document from such a collection, and
26503 distribute
26504 it individually under this License, provided you insert a copy of this
26505 License into the extracted document, and follow this License in all
26506 other respects regarding verbatim copying of that document.
26507 </p>
26508 <p><b>7. AGGREGATION WITH INDEPENDENT WORKS</b>
26509 </p>
26510 <p>A compilation of the Document or its derivatives with other separate
26511 and independent documents or works, in or on a volume of a storage or
26512 distribution medium, is called an "aggregate" if the copyright
26513 resulting from the compilation is not used to limit the legal rights
26514 of the compilation's users beyond what the individual works permit.
26515 When the Document is included in an aggregate, this License does not
26516 apply to the other works in the aggregate which are not themselves
26517 derivative works of the Document.
26518 </p>
26519 <p>If the Cover Text requirement of section 3 is applicable to these
26520 copies of the Document, then if the Document is less than one half of
26521 the entire aggregate, the Document's Cover Texts may be placed on
26522 covers that bracket the Document within the aggregate, or the
26523 electronic equivalent of covers if the Document is in electronic form.
26524 Otherwise they must appear on printed covers that bracket the whole
26525 aggregate.
26526 </p>
26527 <p><b>8. TRANSLATION</b>
26528 </p>
26529 <p>Translation is considered a kind of modification, so you may
26530 distribute translations of the Document under the terms of section 4.
26531 Replacing Invariant Sections with translations requires special
26532 permission from their copyright holders, but you may include
26533 translations of some or all Invariant Sections in addition to the
26534 original versions of these Invariant Sections. You may include a
26535 translation of this License, and all the license notices in the
26536 Document, and any Warranty Disclaimers, provided that you also include
26537 the original English version of this License and the original versions
26538 of those notices and disclaimers. In case of a disagreement between
26539 the translation and the original version of this License or a notice
26540 or disclaimer, the original version will prevail.
26541 </p>
26542 <p>If a section in the Document is Entitled "Acknowledgements",
26543 "Dedications", or "History", the requirement (section 4) to Preserve
26544 its Title (section 1) will typically require changing the actual
26545 title.
26546 </p>
26547 <p><b>9. TERMINATION</b>
26548 </p>
26549 <p>You may not copy, modify, sublicense, or distribute the Document
26550 except
26551 as expressly provided for under this License. Any other attempt to
26552 copy, modify, sublicense or distribute the Document is void, and will
26553 automatically terminate your rights under this License. However,
26554 parties who have received copies, or rights, from you under this
26555 License will not have their licenses terminated so long as such
26556 parties remain in full compliance.
26557 </p>
26558 <p><b>10. FUTURE REVISIONS OF THIS LICENSE</b>
26559 </p>
26560 <p>The Free Software Foundation may publish new, revised versions
26561 of the GNU Free Documentation License from time to time. Such new
26562 versions will be similar in spirit to the present version, but may
26563 differ in detail to address new problems or concerns. See
26564 http://www.gnu.org/copyleft/.
26565 </p>
26566 <p>Each version of the License is given a distinguishing version
26567 number.
26568 If the Document specifies that a particular numbered version of this
26569 License "or any later version" applies to it, you have the option of
26570 following the terms and conditions either of that specified version or
26571 of any later version that has been published (not as a draft) by the
26572 Free Software Foundation. If the Document does not specify a version
26573 number of this License, you may choose any version ever published (not
26574 as a draft) by the Free Software Foundation.
26575 </p>
26576 <br><br>
26577
26578 <hr>
26579
26580 <br><br>
26581 </blockquote>
26582 </td>
26583 </tr>
26584 </table>
26585
26586 <br><br>
26587
26588 <table BORDER=0 summary="GNUGPL" >
26589 <tr>
26590 <td>
26591 <a NAME="GNUGPL"></a>
26592 <blockquote>
26593 <center>
26594 <h2><span class="function">GNU GENERAL PUBLIC LICENSE</span></H2>
26595                       <p>Version 3, 29 June 2007</p>
26596 </center>
26597
26598 <p>
26599  Copyright (C) 2007 Free Software Foundation, Inc. http://fsf.org/
26600  Everyone is permitted to copy and distribute verbatim copies
26601  of this license document, but changing it is not allowed.i
26602 </p>
26603
26604 <center><b>Preamble</b></center>
26605
26606 <p>
26607   The GNU General Public License is a free, copyleft license for
26608 software and other kinds of works.
26609 </p>
26610 <p>
26611   The licenses for most software and other practical works are designed
26612 to take away your freedom to share and change the works.  By contrast,
26613 the GNU General Public License is intended to guarantee your freedom to
26614 share and change all versions of a program--to make sure it remains free
26615 software for all its users.  We, the Free Software Foundation, use the
26616 GNU General Public License for most of our software; it applies also to
26617 any other work released this way by its authors.  You can apply it to
26618 your programs, too.
26619 </p>
26620 <p>
26621   When we speak of free software, we are referring to freedom, not
26622 price.  Our General Public Licenses are designed to make sure that you
26623 have the freedom to distribute copies of free software (and charge for
26624 them if you wish), that you receive source code or can get it if you
26625 want it, that you can change the software or use pieces of it in new
26626 free programs, and that you know you can do these things.
26627 </p>
26628 <p>
26629   To protect your rights, we need to prevent others from denying you
26630 these rights or asking you to surrender the rights.  Therefore, you have
26631 certain responsibilities if you distribute copies of the software, or if
26632 you modify it: responsibilities to respect the freedom of others.
26633 </p>
26634 <p>
26635   For example, if you distribute copies of such a program, whether
26636 gratis or for a fee, you must pass on to the recipients the same
26637 freedoms that you received.  You must make sure that they, too, receive
26638 or can get the source code.  And you must show them these terms so they
26639 know their rights.
26640 </p>
26641 <p>
26642   Developers that use the GNU GPL protect your rights with two steps:
26643 </p>
26644 <p>
26645 (1) assert copyright on the software, and (2) offer you this License
26646 giving you legal permission to copy, distribute and/or modify it.
26647 </p>
26648 <p>
26649   For the developers' and authors' protection, the GPL clearly explains
26650 that there is no warranty for this free software.  For both users' and
26651 authors' sake, the GPL requires that modified versions be marked as
26652 changed, so that their problems will not be attributed erroneously to
26653 authors of previous versions.
26654 </p>
26655 <p>
26656   Some devices are designed to deny users access to install or run
26657 modified versions of the software inside them, although the manufacturer
26658 can do so.  This is fundamentally incompatible with the aim of
26659 protecting users' freedom to change the software.  The systematic
26660 pattern of such abuse occurs in the area of products for individuals to
26661 use, which is precisely where it is most unacceptable.  Therefore, we
26662 have designed this version of the GPL to prohibit the practice for those
26663 products.  If such problems arise substantially in other domains, we
26664 stand ready to extend this provision to those domains in future versions
26665 of the GPL, as needed to protect the freedom of users.
26666 </p>
26667 <p>
26668   Finally, every program is threatened constantly by software patents.
26669 States should not allow patents to restrict development and use of
26670 software on general-purpose computers, but in those that do, we wish to
26671 avoid the special danger that patents applied to a free program could
26672 make it effectively proprietary.  To prevent this, the GPL assures that
26673 patents cannot be used to render the program non-free.
26674 </p>
26675 <p>
26676   The precise terms and conditions for copying, distribution and
26677 modification follow.
26678 </p>
26679 <p>
26680 <center><b>TERMS AND CONDITIONS</b></center>
26681
26682 <p><b>0. Definitions.</b></p>
26683
26684 </p>
26685 <p>
26686   "This License" refers to version 3 of the GNU General Public License.
26687 </p>
26688 <p>
26689   "Copyright" also means copyright-like laws that apply to other kinds of
26690 works, such as semiconductor masks.
26691 </p>
26692 <p>
26693   "The Program" refers to any copyrightable work licensed under this
26694 License.  Each licensee is addressed as "you".  "Licensees" and
26695 "recipients" may be individuals or organizations.
26696 </p>
26697 <p>
26698   To "modify" a work means to copy from or adapt all or part of the work
26699 in a fashion requiring copyright permission, other than the making of an
26700 exact copy.  The resulting work is called a "modified version" of the
26701 earlier work or a work "based on" the earlier work.
26702 </p>
26703 <p>
26704   A "covered work" means either the unmodified Program or a work based
26705 on the Program.
26706 </p>
26707 <p>
26708   To "propagate" a work means to do anything with it that, without
26709 permission, would make you directly or secondarily liable for
26710 infringement under applicable copyright law, except executing it on a
26711 computer or modifying a private copy.  Propagation includes copying,
26712 distribution (with or without modification), making available to the
26713 public, and in some countries other activities as well.
26714 </p>
26715 <p>
26716   To "convey" a work means any kind of propagation that enables other
26717 parties to make or receive copies.  Mere interaction with a user through
26718 a computer network, with no transfer of a copy, is not conveying.
26719 </p>
26720 <p>
26721   An interactive user interface displays "Appropriate Legal Notices"
26722 to the extent that it includes a convenient and prominently visible
26723 feature that (1) displays an appropriate copyright notice, and (2)
26724 tells the user that there is no warranty for the work (except to the
26725 extent that warranties are provided), that licensees may convey the
26726 work under this License, and how to view a copy of this License.  If
26727 the interface presents a list of user commands or options, such as a
26728 menu, a prominent item in the list meets this criterion.
26729
26730 <p><b>1. Source Code.</b></p>
26731
26732 </p>
26733 <p>
26734   The "source code" for a work means the preferred form of the work
26735 for making modifications to it.  "Object code" means any non-source
26736 form of a work.
26737 </p>
26738 <p>
26739   A "Standard Interface" means an interface that either is an official
26740 standard defined by a recognized standards body, or, in the case of
26741 interfaces specified for a particular programming language, one that
26742 is widely used among developers working in that language.
26743 </p>
26744 <p>
26745   The "System Libraries" of an executable work include anything, other
26746 than the work as a whole, that (a) is included in the normal form of
26747 packaging a Major Component, but which is not part of that Major
26748 Component, and (b) serves only to enable use of the work with that
26749 Major Component, or to implement a Standard Interface for which an
26750 implementation is available to the public in source code form.  A
26751 "Major Component", in this context, means a major essential component
26752 (kernel, window system, and so on) of the specific operating system
26753 (if any) on which the executable work runs, or a compiler used to
26754 produce the work, or an object code interpreter used to run it.
26755 </p>
26756 <p>
26757   The "Corresponding Source" for a work in object code form means all
26758 the source code needed to generate, install, and (for an executable
26759 work) run the object code and to modify the work, including scripts to
26760 control those activities.  However, it does not include the work's
26761 System Libraries, or general-purpose tools or generally available free
26762 programs which are used unmodified in performing those activities but
26763 which are not part of the work.  For example, Corresponding Source
26764 includes interface definition files associated with source files for
26765 the work, and the source code for shared libraries and dynamically
26766 linked subprograms that the work is specifically designed to require,
26767 such as by intimate data communication or control flow between those
26768 subprograms and other parts of the work.
26769 </p>
26770 <p>
26771   The Corresponding Source need not include anything that users
26772 can regenerate automatically from other parts of the Corresponding
26773 Source.
26774 </p>
26775 <p>
26776   The Corresponding Source for a work in source code form is that
26777 same work.
26778 </p>
26779 <p>
26780 <b>2. Basic Permissions.</b>
26781
26782 </p>
26783 <p>
26784   All rights granted under this License are granted for the term of
26785 copyright on the Program, and are irrevocable provided the stated
26786 conditions are met.  This License explicitly affirms your unlimited
26787 permission to run the unmodified Program.  The output from running a
26788 covered work is covered by this License only if the output, given its
26789 content, constitutes a covered work.  This License acknowledges your
26790 rights of fair use or other equivalent, as provided by copyright law.
26791 </p>
26792 <p>
26793   You may make, run and propagate covered works that you do not
26794 convey, without conditions so long as your license otherwise remains
26795 in force.  You may convey covered works to others for the sole purpose
26796 of having them make modifications exclusively for you, or provide you
26797 with facilities for running those works, provided that you comply with
26798 the terms of this License in conveying all material for which you do
26799 not control copyright.  Those thus making or running the covered works
26800 for you must do so exclusively on your behalf, under your direction
26801 and control, on terms that prohibit them from making any copies of
26802 your copyrighted material outside their relationship with you.
26803 </p>
26804 <p>
26805   Conveying under any other circumstances is permitted solely under
26806 the conditions stated below.  Sublicensing is not allowed; section 10
26807 makes it unnecessary.
26808 </p>
26809 <p>
26810 <b>3. Protecting Users' Legal Rights From Anti-Circumvention Law.</b>
26811
26812 </p>
26813 <p>
26814   No covered work shall be deemed part of an effective technological
26815 measure under any applicable law fulfilling obligations under article
26816 11 of the WIPO copyright treaty adopted on 20 December 1996, or
26817 similar laws prohibiting or restricting circumvention of such
26818 measures.
26819 </p>
26820 <p>
26821   When you convey a covered work, you waive any legal power to forbid
26822 circumvention of technological measures to the extent such circumvention
26823 is effected by exercising rights under this License with respect to
26824 the covered work, and you disclaim any intention to limit operation or
26825 modification of the work as a means of enforcing, against the work's
26826 users, your or third parties' legal rights to forbid circumvention of
26827 technological measures.
26828 </p>
26829 <p>
26830 <b>4. Conveying Verbatim Copies.</b>
26831 </p>
26832 <p>
26833  You may convey verbatim copies of the Program's source code as you
26834 receive it, in any medium, provided that you conspicuously and
26835 appropriately publish on each copy an appropriate copyright notice;
26836 keep intact all notices stating that this License and any
26837 non-permissive terms added in accord with section 7 apply to the code;
26838 keep intact all notices of the absence of any warranty; and give all
26839 recipients a copy of this License along with the Program.
26840 </p>
26841 <p>
26842   You may charge any price or no price for each copy that you convey,
26843 and you may offer support or warranty protection for a fee.
26844 </p>
26845 <p>
26846 <b>5. Conveying Modified Source Versions.</b>
26847 </p>
26848 <p>
26849   You may convey a work based on the Program, or the modifications to
26850 produce it from the Program, in the form of source code under the
26851 terms of section 4, provided that you also meet all of these conditions:
26852 </p>
26853 <p>
26854 <blockquote>
26855     a) The work must carry prominent notices stating that you modified
26856     it, and giving a relevant date.
26857 </blockquote>
26858 </p>
26859 <p>
26860 <blockquote>
26861     b) The work must carry prominent notices stating that it is
26862     released under this License and any conditions added under section
26863     7.  This requirement modifies the requirement in section 4 to
26864     "keep intact all notices".
26865 </blockquote>
26866 </p>
26867 <p>
26868 <blockquote>
26869     c) You must license the entire work, as a whole, under this
26870     License to anyone who comes into possession of a copy.  This
26871     License will therefore apply, along with any applicable section 7
26872     additional terms, to the whole of the work, and all its parts,
26873     regardless of how they are packaged.  This License gives no
26874     permission to license the work in any other way, but it does not
26875     invalidate such permission if you have separately received it.
26876 </blockquote>
26877 </p>
26878 <p>
26879 <blockquote>
26880     d) If the work has interactive user interfaces, each must display
26881     Appropriate Legal Notices; however, if the Program has interactive
26882     interfaces that do not display Appropriate Legal Notices, your
26883     work need not make them do so.
26884 </blockquote>
26885 </p>
26886 <p>
26887   A compilation of a covered work with other separate and independent
26888 works, which are not by their nature extensions of the covered work,
26889 and which are not combined with it such as to form a larger program,
26890 in or on a volume of a storage or distribution medium, is called an
26891 "aggregate" if the compilation and its resulting copyright are not
26892 used to limit the access or legal rights of the compilation's users
26893 beyond what the individual works permit.  Inclusion of a covered work
26894 in an aggregate does not cause this License to apply to the other
26895 parts of the aggregate.
26896 </p>
26897 <p>
26898 <b>6. Conveying Non-Source Forms.</b>
26899
26900 </p>
26901 <p>
26902   You may convey a covered work in object code form under the terms
26903 of sections 4 and 5, provided that you also convey the
26904 machine-readable Corresponding Source under the terms of this License,
26905 in one of these ways:
26906 </p>
26907 <p>
26908 <blockquote>
26909     a) Convey the object code in, or embodied in, a physical product
26910     (including a physical distribution medium), accompanied by the
26911     Corresponding Source fixed on a durable physical medium
26912     customarily used for software interchange.
26913 </blockquote>
26914 </p>
26915 <p>
26916 <blockquote>
26917     b) Convey the object code in, or embodied in, a physical product
26918     (including a physical distribution medium), accompanied by a
26919     written offer, valid for at least three years and valid for as
26920     long as you offer spare parts or customer support for that product
26921     model, to give anyone who possesses the object code either (1) a
26922     copy of the Corresponding Source for all the software in the
26923     product that is covered by this License, on a durable physical
26924     medium customarily used for software interchange, for a price no
26925     more than your reasonable cost of physically performing this
26926     conveying of source, or (2) access to copy the
26927     Corresponding Source from a network server at no charge.
26928 </blockquote>
26929 </p>
26930 <p>
26931 <blockquote>
26932     c) Convey individual copies of the object code with a copy of the
26933     written offer to provide the Corresponding Source.  This
26934     alternative is allowed only occasionally and noncommercially, and
26935     only if you received the object code with such an offer, in accord
26936     with subsection 6b.
26937 </blockquote>
26938 </p>
26939 <p>
26940 <blockquote>
26941     d) Convey the object code by offering access from a designated
26942     place (gratis or for a charge), and offer equivalent access to the
26943     Corresponding Source in the same way through the same place at no
26944     further charge.  You need not require recipients to copy the
26945     Corresponding Source along with the object code.  If the place to
26946     copy the object code is a network server, the Corresponding Source
26947     may be on a different server (operated by you or a third party)
26948     that supports equivalent copying facilities, provided you maintain
26949     clear directions next to the object code saying where to find the
26950     Corresponding Source.  Regardless of what server hosts the
26951     Corresponding Source, you remain obligated to ensure that it is
26952     available for as long as needed to satisfy these requirements.
26953 </blockquote>
26954 </p>
26955 <p>
26956 <blockquote>
26957     e) Convey the object code using peer-to-peer transmission, provided
26958     you inform other peers where the object code and Corresponding
26959     Source of the work are being offered to the general public at no
26960     charge under subsection 6d.
26961 </blockquote>
26962 </p>
26963 <p>
26964   A separable portion of the object code, whose source code is excluded
26965 from the Corresponding Source as a System Library, need not be
26966 included in conveying the object code work.
26967 </p>
26968 <p>
26969   A "User Product" is either (1) a "consumer product", which means any
26970 tangible personal property which is normally used for personal, family,
26971 or household purposes, or (2) anything designed or sold for incorporation
26972 into a dwelling.  In determining whether a product is a consumer product,
26973 doubtful cases shall be resolved in favor of coverage.  For a particular
26974 product received by a particular user, "normally used" refers to a
26975 typical or common use of that class of product, regardless of the status
26976 of the particular user or of the way in which the particular user
26977 actually uses, or expects or is expected to use, the product.  A product
26978 is a consumer product regardless of whether the product has substantial
26979 commercial, industrial or non-consumer uses, unless such uses represent
26980 the only significant mode of use of the product.
26981 </p>
26982 <p>
26983   "Installation Information" for a User Product means any methods,
26984 procedures, authorization keys, or other information required to install
26985 and execute modified versions of a covered work in that User Product from
26986 a modified version of its Corresponding Source.  The information must
26987 suffice to ensure that the continued functioning of the modified object
26988 code is in no case prevented or interfered with solely because
26989 modification has been made.
26990 </p>
26991 <p>
26992   If you convey an object code work under this section in, or with, or
26993 specifically for use in, a User Product, and the conveying occurs as
26994 part of a transaction in which the right of possession and use of the
26995 User Product is transferred to the recipient in perpetuity or for a
26996 fixed term (regardless of how the transaction is characterized), the
26997 Corresponding Source conveyed under this section must be accompanied
26998 by the Installation Information.  But this requirement does not apply
26999 if neither you nor any third party retains the ability to install
27000 modified object code on the User Product (for example, the work has
27001 been installed in ROM).
27002 </p>
27003 <p>
27004   The requirement to provide Installation Information does not include a
27005 requirement to continue to provide support service, warranty, or updates
27006 for a work that has been modified or installed by the recipient, or for
27007 the User Product in which it has been modified or installed.  Access to a
27008 network may be denied when the modification itself materially and
27009 adversely affects the operation of the network or violates the rules and
27010 protocols for communication across the network.
27011 </p>
27012 <p>
27013   Corresponding Source conveyed, and Installation Information provided,
27014 in accord with this section must be in a format that is publicly
27015 documented (and with an implementation available to the public in
27016 source code form), and must require no special password or key for
27017 unpacking, reading or copying.
27018 </p>
27019 <p>
27020 <b>7. Additional Terms.</b>
27021 </p>
27022 <p>
27023   "Additional permissions" are terms that supplement the terms of this
27024 License by making exceptions from one or more of its conditions.
27025 Additional permissions that are applicable to the entire Program shall
27026 be treated as though they were included in this License, to the extent
27027 that they are valid under applicable law.  If additional permissions
27028 apply only to part of the Program, that part may be used separately
27029 under those permissions, but the entire Program remains governed by
27030 this License without regard to the additional permissions.
27031 </p>
27032 <p>
27033   When you convey a copy of a covered work, you may at your option
27034 remove any additional permissions from that copy, or from any part of
27035 it.  (Additional permissions may be written to require their own
27036 removal in certain cases when you modify the work.)  You may place
27037 additional permissions on material, added by you to a covered work,
27038 for which you have or can give appropriate copyright permission.
27039 </p>
27040 <p>
27041   Notwithstanding any other provision of this License, for material you
27042 add to a covered work, you may (if authorized by the copyright holders of
27043 that material) supplement the terms of this License with terms:
27044 </p>
27045 <p>
27046 <blockquote>
27047     a) Disclaiming warranty or limiting liability differently from the
27048     terms of sections 15 and 16 of this License; or
27049 </blockquote>
27050 </p>
27051 <p>
27052 <blockquote>
27053     b) Requiring preservation of specified reasonable legal notices or
27054     author attributions in that material or in the Appropriate Legal
27055     Notices displayed by works containing it; or
27056 </blockquote>
27057 </p>
27058 <p>
27059 <blockquote>
27060     c) Prohibiting misrepresentation of the origin of that material, or
27061     requiring that modified versions of such material be marked in
27062     reasonable ways as different from the original version; or
27063 </blockquote>
27064 </p>
27065 <p>
27066 <blockquote>
27067     d) Limiting the use for publicity purposes of names of licensors or
27068     authors of the material; or
27069 </blockquote>
27070 </p>
27071 <p>
27072 <blockquote>
27073     e) Declining to grant rights under trademark law for use of some
27074     trade names, trademarks, or service marks; or
27075 </blockquote>
27076 </p>
27077 <p>
27078 <blockquote>
27079     f) Requiring indemnification of licensors and authors of that
27080     material by anyone who conveys the material (or modified versions of
27081     it) with contractual assumptions of liability to the recipient, for
27082     any liability that these contractual assumptions directly impose on
27083     those licensors and authors.
27084 </blockquote>
27085 </p>
27086 <p>
27087   All other non-permissive additional terms are considered "further
27088 restrictions" within the meaning of section 10.  If the Program as you
27089 received it, or any part of it, contains a notice stating that it is
27090 governed by this License along with a term that is a further
27091 restriction, you may remove that term.  If a license document contains
27092 a further restriction but permits relicensing or conveying under this
27093 License, you may add to a covered work material governed by the terms
27094 of that license document, provided that the further restriction does
27095 not survive such relicensing or conveying.
27096 </p>
27097 <p>
27098   If you add terms to a covered work in accord with this section, you
27099 must place, in the relevant source files, a statement of the
27100 additional terms that apply to those files, or a notice indicating
27101 where to find the applicable terms.
27102 </p>
27103 <p>
27104   Additional terms, permissive or non-permissive, may be stated in the
27105 form of a separately written license, or stated as exceptions;
27106 the above requirements apply either way.
27107 </p>
27108 <p>
27109 <b>8. Termination.</b>
27110 </p>
27111 <p>
27112   You may not propagate or modify a covered work except as expressly
27113 provided under this License.  Any attempt otherwise to propagate or
27114 modify it is void, and will automatically terminate your rights under
27115 this License (including any patent licenses granted under the third
27116 paragraph of section 11).
27117 </p>
27118 <p>
27119   However, if you cease all violation of this License, then your
27120 license from a particular copyright holder is reinstated (a)
27121 provisionally, unless and until the copyright holder explicitly and
27122 finally terminates your license, and (b) permanently, if the copyright
27123 holder fails to notify you of the violation by some reasonable means
27124 prior to 60 days after the cessation.
27125 </p>
27126 <p>
27127   Moreover, your license from a particular copyright holder is
27128 reinstated permanently if the copyright holder notifies you of the
27129 violation by some reasonable means, this is the first time you have
27130 received notice of violation of this License (for any work) from that
27131 copyright holder, and you cure the violation prior to 30 days after
27132 your receipt of the notice.
27133 </p>
27134 <p>
27135   Termination of your rights under this section does not terminate the
27136 licenses of parties who have received copies or rights from you under
27137 this License.  If your rights have been terminated and not permanently
27138 reinstated, you do not qualify to receive new licenses for the same
27139 material under section 10.
27140 </p>
27141 <p>
27142 <b>9. Acceptance Not Required for Having Copies.</b>
27143 </p>
27144 <p>
27145   You are not required to accept this License in order to receive or
27146 run a copy of the Program.  Ancillary propagation of a covered work
27147 occurring solely as a consequence of using peer-to-peer transmission
27148 to receive a copy likewise does not require acceptance.  However,
27149 nothing other than this License grants you permission to propagate or
27150 modify any covered work.  These actions infringe copyright if you do
27151 not accept this License.  Therefore, by modifying or propagating a
27152 covered work, you indicate your acceptance of this License to do so.
27153 </p>
27154 <p>
27155 <b>10. Automatic Licensing of Downstream Recipients.</b>
27156 </p>
27157 <p>
27158   Each time you convey a covered work, the recipient automatically
27159 receives a license from the original licensors, to run, modify and
27160 propagate that work, subject to this License.  You are not responsible
27161 for enforcing compliance by third parties with this License.
27162 </p>
27163 <p>
27164   An "entity transaction" is a transaction transferring control of an
27165 organization, or substantially all assets of one, or subdividing an
27166 organization, or merging organizations.  If propagation of a covered
27167 work results from an entity transaction, each party to that
27168 transaction who receives a copy of the work also receives whatever
27169 licenses to the work the party's predecessor in interest had or could
27170 give under the previous paragraph, plus a right to possession of the
27171 Corresponding Source of the work from the predecessor in interest, if
27172 the predecessor has it or can get it with reasonable efforts.
27173 </p>
27174 <p>
27175   You may not impose any further restrictions on the exercise of the
27176 rights granted or affirmed under this License.  For example, you may
27177 not impose a license fee, royalty, or other charge for exercise of
27178 rights granted under this License, and you may not initiate litigation
27179 (including a cross-claim or counterclaim in a lawsuit) alleging that
27180 any patent claim is infringed by making, using, selling, offering for
27181 sale, or importing the Program or any portion of it.
27182 </p>
27183 <p>
27184 <b>11. Patents.</b>
27185 </p>
27186 <p>
27187   A "contributor" is a copyright holder who authorizes use under this
27188 License of the Program or a work on which the Program is based.  The
27189 work thus licensed is called the contributor's "contributor version".
27190 </p>
27191 <p>
27192   A contributor's "essential patent claims" are all patent claims
27193 owned or controlled by the contributor, whether already acquired or
27194 hereafter acquired, that would be infringed by some manner, permitted
27195 by this License, of making, using, or selling its contributor version,
27196 but do not include claims that would be infringed only as a
27197 consequence of further modification of the contributor version.  For
27198 purposes of this definition, "control" includes the right to grant
27199 patent sublicenses in a manner consistent with the requirements of
27200 this License.
27201 </p>
27202 <p>
27203   Each contributor grants you a non-exclusive, worldwide, royalty-free
27204 patent license under the contributor's essential patent claims, to
27205 make, use, sell, offer for sale, import and otherwise run, modify and
27206 propagate the contents of its contributor version.
27207 </p>
27208 <p>
27209   In the following three paragraphs, a "patent license" is any express
27210 agreement or commitment, however denominated, not to enforce a patent
27211 (such as an express permission to practice a patent or covenant not to
27212 sue for patent infringement).  To "grant" such a patent license to a
27213 party means to make such an agreement or commitment not to enforce a
27214 patent against the party.
27215 </p>
27216 <p>
27217   If you convey a covered work, knowingly relying on a patent license,
27218 and the Corresponding Source of the work is not available for anyone
27219 to copy, free of charge and under the terms of this License, through a
27220 publicly available network server or other readily accessible means,
27221 then you must either (1) cause the Corresponding Source to be so
27222 available, or (2) arrange to deprive yourself of the benefit of the
27223 patent license for this particular work, or (3) arrange, in a manner
27224 consistent with the requirements of this License, to extend the patent
27225 license to downstream recipients.  "Knowingly relying" means you have
27226 actual knowledge that, but for the patent license, your conveying the
27227 covered work in a country, or your recipient's use of the covered work
27228 in a country, would infringe one or more identifiable patents in that
27229 country that you have reason to believe are valid.
27230 </p>
27231 <p>
27232   If, pursuant to or in connection with a single transaction or
27233 arrangement, you convey, or propagate by procuring conveyance of, a
27234 covered work, and grant a patent license to some of the parties
27235 receiving the covered work authorizing them to use, propagate, modify
27236 or convey a specific copy of the covered work, then the patent license
27237 you grant is automatically extended to all recipients of the covered
27238 work and works based on it.
27239 </p>
27240 <p>
27241   A patent license is "discriminatory" if it does not include within
27242 the scope of its coverage, prohibits the exercise of, or is
27243 conditioned on the non-exercise of one or more of the rights that are
27244 specifically granted under this License.  You may not convey a covered
27245 work if you are a party to an arrangement with a third party that is
27246 in the business of distributing software, under which you make payment
27247 to the third party based on the extent of your activity of conveying
27248 the work, and under which the third party grants, to any of the
27249 parties who would receive the covered work from you, a discriminatory
27250 patent license (a) in connection with copies of the covered work
27251 conveyed by you (or copies made from those copies), or (b) primarily
27252 for and in connection with specific products or compilations that
27253 contain the covered work, unless you entered into that arrangement,
27254 or that patent license was granted, prior to 28 March 2007.
27255 </p>
27256 <p>
27257   Nothing in this License shall be construed as excluding or limiting
27258 any implied license or other defenses to infringement that may
27259 otherwise be available to you under applicable patent law.
27260 </p>
27261 <p>
27262 <b>12. No Surrender of Others' Freedom.</b>
27263 </p>
27264 <p>
27265   If conditions are imposed on you (whether by court order, agreement or
27266 otherwise) that contradict the conditions of this License, they do not
27267 excuse you from the conditions of this License.  If you cannot convey a
27268 covered work so as to satisfy simultaneously your obligations under this
27269 License and any other pertinent obligations, then as a consequence you may
27270 not convey it at all.  For example, if you agree to terms that obligate you
27271 to collect a royalty for further conveying from those to whom you convey
27272 the Program, the only way you could satisfy both those terms and this
27273 License would be to refrain entirely from conveying the Program.
27274 </p>
27275 <p>
27276 <b>13. Use with the GNU Affero General Public License.</b>
27277 </p>
27278 <p>
27279   Notwithstanding any other provision of this License, you have
27280 permission to link or combine any covered work with a work licensed
27281 under version 3 of the GNU Affero General Public License into a single
27282 combined work, and to convey the resulting work.  The terms of this
27283 License will continue to apply to the part which is the covered work,
27284 but the special requirements of the GNU Affero General Public License,
27285 section 13, concerning interaction through a network will apply to the
27286 combination as such.
27287 </p>
27288 <p>
27289 <b>14. Revised Versions of this License.</b>
27290 </p>
27291 <p>
27292   The Free Software Foundation may publish revised and/or new versions of
27293 the GNU General Public License from time to time.  Such new versions will
27294 be similar in spirit to the present version, but may differ in detail to
27295 address new problems or concerns.
27296 </p>
27297 <p>
27298   Each version is given a distinguishing version number.  If the
27299 Program specifies that a certain numbered version of the GNU General
27300 Public License "or any later version" applies to it, you have the
27301 option of following the terms and conditions either of that numbered
27302 version or of any later version published by the Free Software
27303 Foundation.  If the Program does not specify a version number of the
27304 GNU General Public License, you may choose any version ever published
27305 by the Free Software Foundation.
27306 </p>
27307 <p>
27308   If the Program specifies that a proxy can decide which future
27309 versions of the GNU General Public License can be used, that proxy's
27310 public statement of acceptance of a version permanently authorizes you
27311 to choose that version for the Program.
27312 </p>
27313 <p>
27314   Later license versions may give you additional or different
27315 permissions.  However, no additional obligations are imposed on any
27316 author or copyright holder as a result of your choosing to follow a
27317 later version.
27318 </p>
27319 <p>
27320 <b>15. Disclaimer of Warranty.</b>
27321 </p>
27322 <p>
27323   THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY
27324 APPLICABLE LAW.  EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
27325 HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY
27326 OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO,
27327 THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
27328 PURPOSE.  THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM
27329 IS WITH YOU.  SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF
27330 ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
27331 </p>
27332 <p>
27333 <b>16. Limitation of Liability.</b>
27334 </p>
27335 <p>
27336   IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
27337 WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS
27338 THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY
27339 GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE
27340 USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF
27341 DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD
27342 PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS),
27343 EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF
27344 SUCH DAMAGES.
27345 </p>
27346 <p>
27347 <b>17. Interpretation of Sections 15 and 16.</b>
27348 </p>
27349 <p>
27350   If the disclaimer of warranty and limitation of liability provided
27351 above cannot be given local legal effect according to their terms,
27352 reviewing courts shall apply local law that most closely approximates
27353 an absolute waiver of all civil liability in connection with the
27354 Program, unless a warranty or assumption of liability accompanies a
27355 copy of the Program in return for a fee.
27356 </p>
27357 <p>
27358 <center><b>END OF TERMS AND CONDITIONS</b></center>
27359 </p>
27360 </blockquote>
27361 </td>
27362 </tr>
27363 </table>
27364
27365 <br /><br />
27366 <center style="font-size: 150%">
27367 <span class="divider">(&nbsp;<font color="#7ba9d4">&part;</font>&nbsp;)</span>
27368 </center>
27369 <br /><br />
27370
27371 </body>
27372 </html>
27373