File: newlisp_manual.html

package info (click to toggle)
newlisp 10.7.5-2
links: PTS, VCS
area: main
in suites: bookworm, bullseye, forky, sid, trixie
size: 6,248 kB
sloc: ansic: 33,280; lisp: 4,181; sh: 609; makefile: 215
file content (30419 lines) | stat: -rw-r--r-- 955,491 bytes
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html>
<head>
   <meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
   <meta name="author" content="Lutz Mueller"/>
   <meta name="keywords" content="newLISP Lisp SCHEME programming language 
   manual reference Artificial Intelligence AI NUEVATEC"/>
   <meta name="description" content="newLISP User Manual and Reference"/>
   <title>newLISP v.10.7.5 Manual and Reference</title>

<style type="text/css" media="screen">

.divider {
	margin-top: 2em; 
	margin-bottom: 1em;
	font-family: Times New Roman, Times, serif;
	color: #ffAA28;
	}

.title {
	font-family:Optima, Georgia, Times New Roman, Times, serif; 
	font-size: 500%;
	color: #404040;
	}

span.arw {
	color:#303030;
	font-size: 100%;
	font-weight: bold;
	}
	
span.err {
	color:#cc0000;
	}

span.function {
	font-family: Verdana, Lucida Sans, Helvetica,  sans-serif;
	color:#dd0000;
	}

span.gnu {
	font-family: Verdana, Lucida Sans, Helvetica,  sans-serif;
	color:#dd0000;
	}

h4	{
	font-family: Verdana, Lucida Sans, Helvetica,  sans-serif;
    color: #404040;
	}

b	{
	font-family: Verdana, Lucida Sans, Helvetica,  sans-serif;
    color: #606060;
	font-weight: 600;
	}


body, h1, h2, h3 {
	font-family: Helvetica, sans-serif;
	color: #404040;
	line-height: 120%;
 	}

h1, h2, h3 {
	font-family: Helvetica,  sans-serif;
	color: #101010;
	line-height: 120%;
    font-weight: 100;
 	}

p {
	font-family: Helvetica Neue, Verdana, Lucida Sans, sans-serif;
	color: #404040;
	line-height: 120%;
 	}

table {
	margin: 0px;
	margin-left: 10px;
	border-style: solid;
	border-color: #888888;
	border-width: 0px;
	padding: 0px;
	background: #f8ffff;
	font-size: 95%;
    }
    
th {
	border-style: solid;
	border-width: 1px;
	border-color: #888888;
	padding: 3px;
	background: #eeeeee;
    font-size: 100%;
    }
    
td {
	border-style: solid;
	border-width: 1px;
	border-color: #888888;
	padding: 3px;
	background: #f8ffff;
    font-size: 100%;
    }
    

pre {
	margin: 0px;
	margin-left: 10px;
	margin-right: 10px;
	border-style: dashed;
	border-width: 1px;
	border-color: #888888;
	padding: 4px;
    font-family: Andale Mono, "Bitstream Vera Sans Mono", Monaco, "Courier New";
    font-size: 90%;
	background: #f8ffff;
    }


tt {
	font-family: Andale Mono, "Bitstream Vera Sans Mono", Monaco, "Courier New";
	font-size: 100%;
	}

.license {
	margin: 30px;
	}
	
</style>

</head>
<body text="#000000" bgcolor="#FFFFFF" link="#376590" vlink="#551A8B" alink="#ffAA28">

<br/><br/><br/><br/><br/><br/><br/><br/><br/>


<center>
<span class="title">newLISP<font size='3'>&#174;</font></span>
</center>

<br/>

<center>
<b>For macOS, GNU Linux, Unix and Windows</b>
</center>

<center>
<h2>User Manual and Reference v.10.7.5</h2>
</center>

<br/><br/><br/><br/>
<center>
<span style="line-height:80%;">
<font size='1'>
<br/>Copyright &copy; 2019 Lutz Mueller&nbsp;<a href="http://www.nuevatec.com">www.nuevatec.com</a>. 
All rights reserved.<br/><br/>
Permission is granted to copy, distribute and/or modify this document
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 
<a href="#GNUFDL">GNU Free Documentation License</a>.<br/>
The accompanying software is protected by the 
<a href="#GNUGPL">GNU General Public License</a> V.3, June 2007.<br/>
newLISP is a registered trademark of Lutz Mueller.

</font>
</span>
</center>
<br/><br/><br/>

<center><h1>Contents</h1></center>

<h3><a href="#users_manual">User Manual</a></h3>

<ol>
<li><a href="#introduction">Introduction</a></li>
<li><a href="#deprecated">Deprecated functions and future changes</a></li>
<li><a href="#REPL">Interactive Lisp mode</a></li>
<li><a href="#options">Command line options</a>
  <ul>
  <li><a href="#cmd_help">Command line help summary</a></li>
  <li><a href="#url_files">Specifying files as URLs</a></li>
  <li><a href="#no_init">No loading of init.lsp</a></li>
  <li><a href="#stack_size">Stack size</a></li>
  <li><a href="#max_mem">Maximum memory usage</a></li>
  <li><a href="#direct_exec">Direct execution mode</a></li>
  <li><a href="#logging">Logging I/O</a></li>
  <li><a href="#working_dir">Specifying the working directory</a></li>
  <li><a href="#tcpip_server">newLISP as a TCP/IP server</a></li>
  <li><a href="#daemon">TCP/IP daemon mode</a></li>
  <li><a href="#prompt">Suppressing the prompt and HTTP processing</a></li>
  <li><a href="#forcing_prompt">Forcing prompts in pipe I/O mode</a></li>
  <li><a href="#http_mode">HTTP only server mode</a></li>
  <li><a href="#local_domain_server">Local domain Unix socket server</a></li>
  <li><a href="#conn_timeout">Connection timeout</a></li>
  <li><a href="#inetd_daemon"><tt>inetd</tt> daemon mode</a></li>
  <li><a href="#link">Linking a source file with newLISP for a new executable</a></li>
  </ul>
</li>

<li><a href="#startup">Startup, directories, environment</a>
  <ul>
  <li><a href="#environment">Environment variable NEWLISPDIR</a></li>
  <li><a href="#initialization">The initialization file <tt>init.lsp</tt></a></li>
  <li><a href="#directories_unix">Directories on Linux, BSD, macOS</a></li>
  <li><a href="#directories_win">Directories on MS Windows</a></li>
  </ul>
</li>

<li><a href="#shared-lib">Extending newLISP with shared libraries</a></li>
<li><a href="#newlisp-lib">newLISP as a shared library</a></li>
  <ul>
  <li><a href="#newlisp-lib">newLISP as a C library</a></li>
  <li><a href="#newlisp-js-lib">newLISP as a JavaScript library</a></li>
  </ul>
<li><a href="#expressions">Evaluating newLISP expressions</a>
  <ul>
  <li><a href="#multiline">Interactive multiline expressions</a></li>
  <li><a href="#int_float">Integer, floating point data and operators</a></li>
  <li><a href="#big_int">Big integer, unlimited precision arithmetic</a></li>
  <li><a href="#eval_rules">Evaluation rules and data types</a></li>
  </ul>
</li>

<li><a href="#lambda_expressions">Lambda expressions in newLISP</a></li>
<li><a href="#nil_and_true"><tt>nil</tt>, <tt>true</tt>, <tt>cons</tt> and <tt>()</tt> in newLISP</a></li>
<li><a href="#arrays">Arrays</a></li>
<li><a href="#indexing">Indexing elements of strings, lists and arrays</a>
  <ul>
  <li><a href="#implicit_indexing">Implicit indexing for <tt>nth</tt></a></li>
  <li><a href="#implicit_default">Implicit indexing and the default functor</a></li>
  <li><a href="#implicit_rest_slice">Implicit indexing for <tt>rest</tt> and <tt>slice</tt></a></li>
  <li><a href="#implicit_modify">Modify references in lists, arrays and strings</a></li>
  </ul>
</li>  

<li><a href="#destructive">Destructive versus non-destructive functions</a>
<ul>
	<li><a href="#make_nondestructive">Make a destructive function non-destructive</a></li>
</ul>
</li>

<li><a href="#return">Early return from functions, loops, blocks</a>
  <ul>
  <li><a href="#flow_catch_throw">Using <tt>catch</tt> and <tt>throw</tt></a></li>
  <li><a href="#flow_and_or">Using <tt>and</tt> and <tt>or</tt></a></li>
  </ul>
</li>

<li><a href="#scoping">Dynamic and lexical scoping</a></li>

<li><a href="#contexts">Contexts</a>
  <ul>
  <li><a href="#context_rules">Symbol creation in contexts</a></li>
  <li><a href="#creating_contexts">Creating contexts</a></li>
  <li><a href="#scope_global">Global scope</a></li>
  <li><a href="#protection">Symbol protection</a></li>
  <li><a href="#overwrite">Overwriting global symbols and built-ins</a></li>
  <li><a href="#context_vars">Variables holding contexts</a></li>
  <li><a href="#sequence_creating">Sequence of creating contexts</a></li>
  <li><a href="#context_modules">Contexts as programming modules</a></li>
  <li><a href="#context_data">Contexts as data containers</a></li>
  <li><a href="#loading_contexts">Loading and declaring contexts</a></li>
  <li><a href="#serializing">Serializing context objects</a></li>
  </ul>
</li>

<li><a href="#default_function">The context default functor</a>
  <ul>
  <li><a href="#func_memory">Functions with memory</a></li>
  <li><a href="#hash">Hash functions and dictionaries</a></li>
  <li><a href="#pass_big">Passing data by reference</a></li>
  </ul>
</li>

<li><a href="#foop">Functional object-oriented programming</a>
  <ul>
  <li><a href="#newlisp_classes">FOOP classes and constructors</a></li>
  <li><a href="#newlisp_objects">Objects</a></li>
  <li><a href="#colon_operator">The colon <tt>:</tt> operator and polymorphism</a></li>
  <li><a href="#structure_foop">Structuring a larger FOOP program</a></li>
  </ul>
</li>

<li><a href="#multi_processing">Concurrent processing and distributed computing</a>
	<ul>
	<li><a href="#cilk">The Cilk API</a></li>
	<li><a href="#distributed">Distributed network computing</a></li>
	</ul>
</li>

<li><a href="#JSON_XML">JSON, XML, SXML and XML-RPC</a></li>
<li><a href="#internationalization">Customization, localization and UTF-8</a>
  <ul>
  <li><a href="#naming">Customizing function names</a></li>
  <li><a href="#switching">Switching the locale</a></li>
  <li><a href="#decimal_point">Decimal point and decimal comma</a></li>
  <li><a href="#unicode_utf8">Unicode and UTF-8 encoding</a></li>
  <li><a href="#utf8_capable">Functions working on UTF-8 characters</a></li>
  <li><a href="#utf8_version">Functions only available on UTF-8 enabled versions</a></li>
  </ul>
</li>

<li><a href="#commas">Commas in parameter lists</a></li>
</ol>

<h3><a href="#function_ref">Function Reference</a></h3>
<ol>
<li><a href="#symbol_names">Syntax of symbol variables and numbers</a></li>
<li><a href="#type_ids">Data types and names in the reference</a></li>
<li><a href="#functions">Functions in groups</a>
  <ul>
  <li><a href="#list_processing">List processing, flow control, and integer arithmetic</a></li>
  <li><a href="#string_operators">String and conversion functions</a></li>
  <li><a href="#floating_point">Floating point math and special functions</a></li>
  <li><a href="#matrices">Matrix functions</a></li>
  <li><a href="#array-funcs">Array functions</a></li>
  <li><a href="#bit_operators">Bit operators</a></li>
  <li><a href="#predicates">Predicates</a></li>
  <li><a href="#timedate">Date and time functions</a></li>
  <li><a href="#montecarlo">Statistics, simulation and modeling functions</a></li>
  <li><a href="#pattern">Pattern matching</a></li>
  <li><a href="#financial">Financial math functions</a></li>
  <li><a href="#input_output">File and I/O operations</a></li>
  <li><a href="#processes">Processes and the Cilk API</a></li>
  <li><a href="#directory_management">File and directory management</a></li>
  <li><a href="#http_api">HTTP networking API</a></li>
  <li><a href="#socket_tcpip">Socket TCP/IP, UDP and ICMP network API</a></li>
  <li><a href="#JS">API for newLISP in a web browser</a></li>
  <li><a href="#reflection">Reflection and customization</a></li>
  <li><a href="#system_functions">System functions</a></li>
  <li><a href="#importing_libraries">Importing libraries</a></li>
  <li><a href="#internals">newLISP internals API</a></li>
  </ul>
</li>

<li><a href="#functions_alphabetical">Functions in alphabetical order</a>
<p>
<b>
<a href="newlisp_manual.html#shell">!</a>&nbsp;
<a href="newlisp_manual.html#arithmetic">+-*/%</a>&nbsp;
<a href="newlisp_manual.html#abort">Ab</a>&nbsp;
<a href="newlisp_manual.html#append">Ap</a>&nbsp;
<a href="newlisp_manual.html#asin">As</a>&nbsp;
<a href="newlisp_manual.html#base64-dec">Ba</a>&nbsp;
<a href="newlisp_manual.html#callback">Ca</a>&nbsp;
<a href="newlisp_manual.html#clean">Cl</a>&nbsp;
<a href="newlisp_manual.html#command-event">Co</a>&nbsp;
<a href="newlisp_manual.html#current-line">Cu</a>&nbsp;
<a href="newlisp_manual.html#dec">De</a>&nbsp;
<a href="newlisp_manual.html#difference">Di</a>&nbsp;
<a href="newlisp_manual.html#do-until">Do</a>&nbsp;
<a href="newlisp_manual.html#encrypt">En</a>&nbsp;
<br/>
<a href="newlisp_manual.html#exec">Ex</a>&nbsp;
<a href="newlisp_manual.html#file-info">Fi</a>&nbsp;
<a href="newlisp_manual.html#flat">Fl</a>&nbsp;
<a href="newlisp_manual.html#gammaln">Ga</a>&nbsp;
<a href="newlisp_manual.html#global">Gl</a>&nbsp;
<a href="newlisp_manual.html#inc">In</a>&nbsp;
<a href="newlisp_manual.html#lambdap">La</a>&nbsp;
<a href="newlisp_manual.html#listp">Li</a>&nbsp;
<a href="newlisp_manual.html#macrop">Ma</a>&nbsp;
<a href="newlisp_manual.html#mul">Mu</a>&nbsp;
<a href="newlisp_manual.html#net-accept">Net</a>&nbsp;
<a href="newlisp_manual.html#new">New</a>&nbsp;
<a href="newlisp_manual.html#nth">Nt</a>&nbsp;
<a href="newlisp_manual.html#pack">Pa</a>&nbsp;
<br/>
<a href="newlisp_manual.html#pretty-print">Pr</a>&nbsp;
<a href="newlisp_manual.html#randomize">Ra</a>&nbsp;
<a href="newlisp_manual.html#read">Rea</a>&nbsp;
<a href="newlisp_manual.html#regex">Reg</a>&nbsp;
<a href="newlisp_manual.html#search">Sea</a>&nbsp;
<a href="newlisp_manual.html#sequence">Seq</a>&nbsp;
<a href="newlisp_manual.html#sleep">Sl</a>&nbsp;
<a href="newlisp_manual.html#starts-with">St</a>&nbsp;
<a href="newlisp_manual.html#sync">Sy</a>&nbsp;
<a href="newlisp_manual.html#time-of-day">Ti</a>&nbsp;
<a href="newlisp_manual.html#truep">Tr</a>&nbsp;
<a href="newlisp_manual.html#utf8">Ut</a>&nbsp;
<a href="newlisp_manual.html#write-file">Wr</a>&nbsp;
</b>
</p>
</li>  
</ol>

<h3><a href="#appendix">Appendix</a></h3>

<ul>
<li><a href="#error_codes">Error Codes</a></li>
<li><a href="#system_symbols">System Symbols</a></li>
<li><a href="#GNUFDL">GNU Free Documentation License</a></li>
<li><a href="#GNUGPL">GNU General Public License</a></li>
</ul>

<br/>
<a name="introduction"></a>

<center style="font-size: 150%">
<span class="divider">(&nbsp;<font color="#7ba9d4">&part;</font>&nbsp;)</span>
</center>

<br/><br/>

<a name="users_manual"></a>
<center><h1>newLISP User Manual</h1></center>


<h2>1. Introduction</h2>

<p>
newLISP focuses on the core components of Lisp: <em>lists</em>, <em>symbols</em>, 
and <em>lambda expressions</em>. To these, newLISP adds <em>arrays</em>,
<em>implicit indexing</em> on lists and arrays, and <em>dynamic</em> and 
<em>lexical scoping</em>. Lexical scoping is implemented using separate namespaces 
called <em>contexts</em>.</p>

<p>The result is an easier-to-learn Lisp that is even smaller than most Scheme 
implementations, but which still has about 350 built-in functions.
Not much over 200k in size on BSD systems, newLISP is built for high portability
using only the most common Unix system C-libraries. It loads quickly and has 
a small memory footprint. newLISP is as fast or faster than other popular 
scripting languages and uses very few resources.</p>

<p>Both built-in and user-defined functions, along with variables, share the 
same global symbol tree and are manipulated by the same functions. Lambda expressions 
and user-defined functions can be handled like any other list expression.</p>

<p>newLISP is dynamically scoped inside lexically separated contexts (namespaces). 
Contexts in newLISP are used for multiple purposes. They allow (1) partitioning of 
programs into modules, (2) the definition of <em>Classes</em> in FOOP 
(Functional Object Oriented Programming), (3) the definition of functions with 
state and (4) the creation of Hash trees for associative key &rarr; value storage.</p>

<p>newLISP's efficient <em>red-black</em> tree implementation can handle millions 
of symbols in namespaces or hashes without degrading performance.</p>

<p>newLISP allocates and reclaims memory automatically, without using traditional 
asynchronous garbage collection.
All objects &mdash; except for contexts, built-in primitives, and symbols &mdash;
are passed by value and are referenced only once. Upon creation objects are scheduled
for delayed deletion and Lisp cells are recycled for newly created objects.
This results in predictable processing times without the pauses found in traditional 
garbage collection. newLISP's unique automatic memory management makes it the fastest 
interactive Lisp available. More than any other Lisp, it implements the 
<em>data equals program</em> paradigm and full self reflection.</p>

<p>Many of newLISP's built-in functions are polymorphic and accept a variety 
of data types and optional parameters. This greatly reduces the number of 
functions and syntactic forms necessary to learn and implement.
High-level functions are available for string and list processing, financial math, 
statistics, and Artificial Intelligence applications.</p>

<p>newLISP has functions to modify, insert, or delete elements inside 
complex <em>nested</em> lists or <em>multi-dimensional</em> array structures.</p>

<p>Because strings can contain null characters in newLISP, they can be used to 
process binary data with most string manipulating functions.</p>

<p>newLISP can also be extended with a shared library interface
to import functions that access data in foreign binary data structures.
The distribution contains modules for importing popular C-library APIs.</p>

<p>newLISP's HTTP, TCP/IP, and UDP socket interfaces make it easy to write 
distributed networked applications. Its built-in XML interface, along with 
its text-processing features &mdash; Perl Compatible Regular Expressions (PCRE) 
and text-parsing functions &mdash; make newLISP a useful tool for CGI processing.
The source distribution includes examples of HTML forms processing.
newLISP can be run a as a CGI capable web server using its built-in http mode option.</p>

<p>newLISP has built-in support for distributed processing on networks and parallel,
concurrent processing on the same CPU with one or more processing cores.</p>

<p>The source distribution can be compiled for Linux, macOS/Darwin, BSDs, many 
other Unix flavors and MS Windows. newLISP can be compiled as a 64-bit LP64 application 
for full 64-bit memory addressing.</p>

<p>Since version 10.5.7, newLISP also can be compiled to JavaScript and run in
a <a href="http://www.newlisp.org/newlisp-js/">web browser</a>.</p>

<br/>

<h3>Licensing</h3>

<p>newLISP are licensed under version 3
of the <a href="#GNUGPL">GPL (General Public License)</a>.
The newLISP documentation as well as other documentation packaged with newLISP 
are licensed under the <a href="#GNUFDL">GNU Free Documentation License</a>. </p>

<br/>

<center>
<span class="divider">(&nbsp;<font color="#7ba9d4">&sect;</font>&nbsp;)</span>
</center>

<br/>

<a name="deprecated"></a>
<h2>2. Deprecated functions since version 10.3.0</h2>

<p>Since version 10.3.0 newLISP can switch between IPv4 and IPv6 modes during
run-time using the new <a href="#net-ipv">net-ipv</a> function. The 
<tt>-6</tt> commandline option can be used to start newLISP in IPv6 mode. 
After transition to IPv6 the <tt>-6</tt>
commandline switch will be changed to <tt>-4</tt> for starting up in IPv4
mode.</p>

<p>The old writing <tt>parse-date</tt> of <a href="#date-parse">date-parse</a>
is still recognized but deprecated since version 10.3.0. The old writing will 
be removed in a future version.</p>

<p>Since version 10.4.2 <tt>if-not</tt> is deprecated and will be removed in a
future version.</p>

<p>Since version 10.4.6 newLISP has a built-in function <a href="#json-parse">
json-parse</a> for translating JSON data into S-expressions. The module
file <tt>json.lsp</tt> is removed from the distribution.</p>

<p>Since version 10.4.8 newLISP has built-in support for unlimited precision
integers. This makes the GNU GMP module <tt>gmp.lsp</tt> obsolete.</p>

<br/>

<center>
<span class="divider">(&nbsp;<font color="#7ba9d4">&sect;</font>&nbsp;)</span>
</center>

<br/>

<a name="REPL"></a>
<h2>3. Interactive Lisp mode</h2>
<p>The best way to experience Lisp and experiment with it, is using interactive 
mode in a terminal window or operating system command shell. Since version 10.3, 
newLISP's read-eval-print-loop (REPL) accepts multi-line statements.</p>

<p>To enter a multi-line statement hit the [enter] key on an empty line after
the system prompt. To exit multi-line mode, hit the [enter] key again on an empty
line. In the following example computer output is shown in bold letters:</p>

<pre>
<b>></b> 
(define (foo x y)
    (+ x y))

<b>(lambda (x y) (+ x y))
></b> (foo 3 4)
<b>7
></b> 
</pre>

<p>Note, that multi-line mode is only possible in an OS command terminal window
or command shell.</p>

<p>Interactive Lisp mode can accept operating system shell commands. To hit
an OS command enter the '<tt>!</tt>' character right after the prompt, immediately
followed by the shell command:</p>

<pre>
<b>> </b>!ls *.html
<b>CodePatterns.html		MemoryManagement.html	newLISPdoc.html
ExpressionEvaluation.html	manual_frame.html		newlisp_index.html
License.html			newLISP-10.3-Release.html	newlisp_manual.html
> </b>
</pre>

<p>In the example a <tt>ls</tt> shell command is entered to show HTML files
in the current directory. On MS Windows a <tt>dir</tt> command could be used
in the same fashion.</p>

<p>The mode can also be used to call an editor or any other program:</p>

<pre>
<b>> </b>!vi foo.lsp
</pre>

<p>The Vi editor will open to edit the program "foo.lsp". After leaving
the editor the program could be run using a load statement:</p>

<pre>
<b>> </b>(load "foo.lsp")
</pre>

<p>The program <tt>foo.lsp</tt> is now run.</p>

<p>When using a Unix terminal or command shell, tab-expansion for built-in newLISP
functions can be used:</p>

<pre>
<b>> </b>(pri
<b>print       println     primitive?  
> (pri</b>
</pre>

<p>After entering the characters <tt> (pri </tt>  hit the [tab] key once to
show all the built-in functions starting with the same characters. When hitting
[tab] twice before a function name has started, all built-in function names will
be displayed.</p>

<p>On most Unix, parenthesis matching can be enabled on the commandline by
including the following line in the file <tt>.inputrc</tt> in the home
directory:</p>

<pre>
set blink-matching-paren on
</pre>

<p>Not all systems have a version of <tt>libreadline</tt> advanced enough for 
this to work.</p>


<br/>
<center>
<span class="divider">(&nbsp;<font color="#7ba9d4">&sect;</font>&nbsp;)</span>
</center>
<br/>

<a name="options"></a>
<h2>4. Command-line options, startup and directories</h2>

<a name="cmd_help"></a>
<h3>Command line help summary</h3>

<p>When starting newLISP from the command-line several switches and options and 
source files can be specified. Executing:</p>

<pre>
newlisp -h
</pre>

<p>in a command shell will produce the following summary of options and switches:</p>

<pre>
 -h this help (no init.lsp)
 -n no init.lsp (must be first)
 -x &lt;source&gt; &lt;target&gt; link (no init.lsp)
 -v version
 -s &lt;stacksize&gt;
 -m &lt;max-mem-MB&gt; cell memory
 -e &lt;quoted lisp expression&gt;
 -l &lt;path-file&gt; log connections
 -L &lt;path-file&gt; log all
 -w &lt;working dir&gt;
 -c no prompts, HTTP
 -C force prompts
 -t &lt;usec-server-timeout&gt;
 -p &lt;port-no&gt;
 -d &lt;port-no&gt; demon mode
 -http only
 -http-safe safe mode
 -6 IPv6 mode
</pre>

<p>Before or after the command-line switches, files to load and execute can 
be specified. If a newLISP executable program is followed by parameters,
the program must finish with and <tt>(exit)</tt> statement, else newLISP 
will take command-line parameters as additional newLISP scripts to be 
loaded and executed.</p>

<p>On Linux and other Unix systems, a <tt>newlisp</tt> <em>man page</em> 
can be found:</p>

<pre>
man newlisp
</pre>		

<p>This will display a man page in the Linux/Unix shell.</p>

<br/>

<a name="url_files"></a>
<h3>Specifying files as URLs</h3>

<p>newLISP will load and execute files specified on the command-line. Files are 
specified with either their pathname or a <tt>file://</tt> URL on the local file 
system or with a <tt>http://</tt> URL on remote file systems running an HTTP
server. That HTTP server can be newLISP running in HTTP server mode.</p>

<pre>
newlisp aprog.lsp bprog.lsp prog.lsp
newlisp http://newlisp.org/example.lsp
newlisp file:///usr/home/newlisp/demo.lsp
</pre>

<br/>

<a name="no_init"></a>
<h3>No loading of init.lsp</h3>

<p>This option suppresses loading of any present initialization file <tt>init.lsp</tt> 
or <tt>.init.lsp</tt>. In order to work, this must be the first option specified:</p>

<pre>
newlisp -n
</pre>

<p>More about <a href="#initialization">initialization files.</a></p>

<br/>

<a name="stack_size"></a>
<h3>Stack size</h3>

<pre>
newlisp -s 4000
newlisp -s 100000 aprog bprog
newlisp -s 6000 myprog
newlisp -s 6000 http://asite.com/example.lsp
</pre>		

<p>The above examples show starting newLISP with different stack sizes using 
the <tt>-s</tt> option, as well as loading one or more newLISP source files
and loading files specified by an URL. When no stack size is specified, 
the stack defaults to 2048. Per stack position about 80 bytes of memory are
preallocated.</p>

<br/>

<a name="max_mem"></a>
<h3>Maximum memory usage</h3>

<pre>
newlisp -m 128
</pre>		

<p>This example limits newLISP 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 newLISP 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 dynamic memory usage.</p>

<br/>

<a name="direct_exec"></a>
<h3>Direct execution mode</h3>

<p>Small pieces of newLISP code can be executed directly from the command-line:</p>

<pre>
newlisp -e "(+ 3 4)"  <span class="arw">&rarr;</span> 7 ; On MS Windows and Unix

newlisp -e '(append "abc" "def")'  <span class="arw">&rarr;</span> "abcdef" ; On Unix
</pre>		

<p>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 string delimiters. Note that there is a space between 
<tt>-e</tt> and the quoted command string.</p>

<br/>

<a name="logging"></a>
<h3>Logging I/O</h3>

<p>In any mode, newLISP can write a log when started with the <tt>-l</tt> or <tt>-L</tt> 
option. Depending on the mode newLISP is running, different output is written to the log 
file. Both options always must specify the  path of a log-file. The path may be a relative 
path and can be either attached or detached to the <tt>-l</tt> or <tt>-L</tt> option. 
If the file does not exist, it is created when the first logging output is written.</p>

<pre>
newlisp -l./logfile.txt -c

newlisp -L /usr/home/www/log.txt -http -w /usr/home/www/htpdocs
</pre>

<p>The following table shows the items logged in different situations:</p>

<table  width="98%" summary="logging formats">
<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>
<tr><td><tt>newlisp -l</tt></td>
    <td>log only input and network connections</td>
    <td>log only network connections</td></tr>
<tr><td><tt>newlisp -L</tt></td>
    <td>log also newLISP output (w/o prompts)</td>
    <td>log also HTTP requests</td></tr>
</table><br/>

<p>All logging output is written to the file specified after the <tt>-l</tt> 
or <tt>-L</tt> option.</p>

<br/>

<a name="working_dir"></a>
<h3>Specifying the working directory</h3>

<p>The <tt>-w</tt> option specifies the initial working directory for newLISP 
after startup:</p>

<pre>
newlisp -w /usr/home/newlisp
</pre>

<p>All file requests without a directory path will now be directed to the path 
specified with the <tt>-w</tt> option.</p>

<br/>

<a name="prompt"></a>
<h3>Suppressing the prompt and HTTP processing</h3>

<p>The command-line prompt and initial copyright banner can be suppressed:</p>

<pre>
newlisp -c
</pre>

<p>Listen and connection messages are suppressed if logging is not enabled. 
The <tt>-c</tt> option is useful when controlling newLISP 
from other programs; it is mandatory when setting it up 
as a <a href="#net-eval">net-eval</a> server.</p>

<p>The <tt>-c</tt> option also enables newLISP server nodes to answer
<tt>HTTP GET</tt>, <tt>PUT</tt>, <tt>POST</tt> and <tt>DELETE</tt> requests, 
as well as perform CGI processing. Using the <tt>-c</tt> option,
together with the <tt>-w</tt> and <tt>-d</tt> options,
newLISP can serve as a standalone <tt>httpd</tt> webserver:</p>

<pre>
newlisp -c -d 8080 -w /usr/home/www
</pre>

<p>When running newLISP as a <tt>inetd</tt> or <tt>xinetd</tt> enabled
server on Unix machines, use:</p>

<pre>
newlisp -c -w /usr/home/www
</pre>

<p>
In <tt>-c</tt> mode, newLISP processes command-line requests as well as
HTTP and <a href="#net-eval">net-eval</a> requests. Running
newLISP in this mode is only recommended on a machine behind
a firewall. This mode should not be run on machines open and accessible
through the Internet. To suppress the processing of 
<a href="#net-eval">net-eval</a> and command-line&ndash;like requests, use 
the safer <tt>-http</tt> option.</p>

<br/>

<a name="forcing_prompt"></a>
<h3>Forcing prompts in pipe I/O mode</h3>

<p>A capital <tt>C</tt> forces prompts when running newLISP in pipe I/O mode
inside the Emacs editor:</p>

<pre>
newlisp -C
</pre>

<p>
To suppress console output from return values from evaluations, 
use <a href="#silent">silent</a>.</p>

<br/>

<a name="tcpip_server"></a>
<h3>newLISP as a TCP/IP server</h3>

<pre>
newlisp some.lsp -p 9090
</pre>		

<p>
This example shows how newLISP can listen for commands on a TCP/IP socket 
connection. In this case, standard I/O is redirected to the port specified with
the <tt>-p</tt> option. <tt>some.lsp</tt> is an optional file loaded during 
startup, before listening for a connection begins.</p>

<p>
The <tt>-p</tt> option is mainly used to control newLISP from another 
application, such as a newLISP GUI front-end or a program written in another 
language. As soon as the controlling client closes the connection, newLISP 
will exit.</p>

<p>
A telnet application can be used to test running newLISP as a server. First 
enter:</p>

<pre>
newlisp -p 4711 &amp;
</pre>		

<p>
The <tt>&amp;</tt> indicates to a Unix shell to run the process in the 
background. On Windows, start the server process without the <tt>&amp;</tt> 
in the foreground and open a second command window for the telnet application.
Now connect with a telnet:</p>

<pre>
telnet localhost 4711
</pre>	

<p>
If connected, the newLISP sign-on banner and prompt appear. Instead of 
<tt>4711</tt>, any other port number could be used.</p>

<p>
When the client application closes the connection, newLISP will exit, too.
</p>

<br/>

<a name="daemon"></a>
<h3>TCP/IP daemon mode</h3>

<p>When the connection to the client is closed in <tt>-p</tt> mode, newLISP 
exits. To avoid this, use the <tt>-d</tt> option instead of the <tt>-p</tt> 
option:</p>

<pre>
newlisp -d 4711 &amp;
</pre>		

<p>
This works like the <tt>-p</tt> option, but newLISP does not exit after a 
connection closes. Instead, it stays in memory, listening for a new connection 
and preserving its state. An <a href="#exit">exit</a> issued from a client 
application closes the network connection, and the newLISP daemon remains 
resident, waiting for a new connection. Any port number could be used in place 
of <tt>4711</tt>. </p>

<p>After each transaction, when a connection closes, newLISP will go through a 
reset process, reinitialize stack and signals and go to the <tt>MAIN</tt> 
context. Only the contents of program and variable symbols will be preserved 
when running a stateful server.</p>

<p>
When running in <tt>-p</tt> or <tt>-d</tt> mode, the opening and closing tags 
<tt>[cmd]</tt> and <tt>[/cmd]</tt> must be used to enclose multiline 
statements.  They must each appear on separate lines. This makes it possible 
to transfer larger portions of code from controlling applications. </p>

<p>The following variant of the <tt>-d</tt> mode is frequently used in a 
distributed computing environment, together with 
<a href="#net-eval">net-eval</a> on the client side:</p>

<pre>
newlisp -c -d 4711 &amp;
</pre>		

<p>The <tt>-c</tt> spec suppresses prompts, making this mode suitable 
for receiving requests from the <a href="#net-eval">net-eval</a> function.</p>

<p>newLISP server nodes running will also answer <tt>HTTP GET</tt>, 
<tt>PUT</tt> and <tt>DELETE</tt> requests. This can be used to retrieve and 
store files with <a href="#get-url">get-url</a>, <a href="#put-url">put-url</a>,
<a href="#delete-url">delete-url</a>, <a href="#read-file">read-file</a>, 
<a href="#write-file">write-file</a> and <a href="#append-file">append-file</a>,
or to load and save programs using <a href="#load">load</a> and 
<a href="#save">save</a> from and to remote server nodes. See the chapters for 
the <tt>-c</tt> and <tt>-http</tt> options for more details.</p>

<br/>

<a name="http_mode"></a>
<h3>HTTP-only server mode</h3>
<p> newLISP can be limited to HTTP processing using the <tt>-http</tt> option.
With this mode, a secure <tt>httpd</tt> web server daemon can be configured:</p>

<pre>
newlisp -http -d 8080 -w /usr/home/www
</pre>

<p> When running newLISP as an <tt>inetd</tt> or <tt>xinetd</tt>-enabled
server on Unix machines, use:</p>

<pre>
newlisp -http -w /usr/home/www
</pre>

<p>To further enhance security and HTTP processing, load a program during 
startup when using this mode:</p>

<pre>
newlisp httpd-conf.lsp -http -w /usr/home/www
</pre>

<p>The file <tt>httpd-conf.lsp</tt> contains a <a href="#command-event">command-event</a>
function configuring a user-defined function to analyze, filter and translate requests.
See the reference for this function for a working example.</p>

<p>In the HTTP modes enabled by either <tt>-c</tt> or <tt>-http</tt>, the 
following file types are recognized, and a correctly formatted 
<tt>Content-Type:</tt> header is sent back:</p>

<table  summary="media types">
<tr align="left"><th>file extension</th><th>media type</th></tr>
<tr><td>.avi</td><td>video/x-msvideo</td></tr>
<tr><td>.css</td><td>text/css</td></tr>
<tr><td>.gif</td><td>image/gif</td></tr>
<tr><td>.htm</td><td>text/htm</td></tr>
<tr><td>.html</td><td>text/html</td></tr>
<tr><td>.jpg</td><td>image/jpg</td></tr>
<tr><td>.js</td><td>application/javascript</td></tr>
<tr><td>.mov</td><td>video/quicktime</td></tr>
<tr><td>.mp3</td><td>audio/mpeg</td></tr>
<tr><td>.mpg</td><td>video/mpeg</td></tr>
<tr><td>.pdf</td><td>application/pdf</td></tr>
<tr><td>.png</td><td>image/png</td></tr>
<tr><td>.wav</td><td>audio/x-wav</td></tr>
<tr><td>.zip</td><td>application/zip</td></tr>
<tr><td><em>any other</em></td><td>text/plain</td></tr>
</table><br/>

<p>To serve CGI, HTTP server mode needs a <tt>/tmp</tt> directory on Unix-like
platforms or a <tt>C:\tmp</tt> directory on MS Windows. newLISP can process GET, PUT,
POST and DELETE requests and create custom response headers. CGI files must have
the extension <tt>.cgi</tt> and have executable permission on Unix. More 
information about CGI processing for newLISP server modes can be found in the 
document <a href="http://www.newlisp.org/CodePatterns.html">
Code Patterns in newLISP</a>. </p>

<p>In both server modes <tt>-c</tt> and <tt>-http</tt> the environment 
variables DOCUMENT_ROOT, HTTP_HOST, REMOTE_ADDR, REQUEST_METHOD, REQUEST_URI, 
SERVER_SOFTWARE and QUERY_STRING are set. The variables CONTENT_TYPE, 
CONTENT_LENGTH, HTTP_HOST, HTTP_USER_AGENT and HTTP_COOKIE are also set, if 
present in the HTTP header sent by the client. Environment variables can be
read using the <a href="#env">env</a> function.</p>

<br/>
		
<a name="local_domain_server"></a>
<h3>Local domain Unix socket server</h3>

<p>Instead of a port, a local domain Unix socket path can be specified in
the <tt>-d</tt> or <tt>-p</tt> server modes.</p>

<pre>
newlisp -c -d /tmp/mysocket &amp;
</pre>	

<p>Test the server using another newLISP process:</p>

<pre>
newlisp -e '(net-eval "/tmp/mysocket" 0 "(symbols)")'
</pre>	

<p>A list of all built-in symbols will be printed to the terminal</p>

<p>This mode will work together with local domain socket modes of
<a href="#net-connect">net-connect</a>, <a href="#net-listen">net-listen</a>,
and <a href="#net-eval">net-eval</a>. Local domain sockets opened with 
<tt>net-connect</tt> and <tt>net-listen</tt> can be served using
<a href="#net-accept">net-accept</a>, <a href="#net-receive">net-receive</a>,
and <a href="#net-send">net-send</a>. Local domain socket connections
can be monitored using <a href="#net-peek">net-peek</a> and 
<a href="#net-select">net-select</a>.</p>

<p>Local domain socket connections are much faster than normal TCP/IP network
connections and preferred for communications between processes on
the same local file system in distributed applications. This mode is not
available on MS Windows.</p>

<br/>

<a name="conn_timeout"></a>
<h3>Connection timeout</h3>

<p>Specifies  a  connection timeout when running in <tt>-p</tt> or <tt>-d</tt> 
demon mode. A newLISP Server will disconnect when no further input is read 
after accepting a client connection. The timeout is specified in micro 
seconds:</p>

<pre>
newlisp -c -t 3000000 -d 4711 &amp;
</pre>

<p>The example specifies a timeout of three seconds.</p>

<br/>

<a name="inetd_daemon"></a>
<h3><tt>inetd</tt>	 daemon mode</h3>

<p>
The <tt>inetd</tt> server running on virtually all Linux/Unix OSes can function 
as a proxy for newLISP. The server accepts TCP/IP or UDP connections and passes 
on requests via standard I/O to newLISP. <tt>inetd</tt> starts a newLISP 
process for each client connection. When a client disconnects, the connection 
is closed and the newLISP process exits.</p>

<p>
<tt>inetd</tt> and newLISP together can handle multiple connections efficiently 
because of newLISP's small memory footprint, fast executable, and short program 
load times. When working with <a href="#net-eval">net-eval</a>, this mode is 
preferred for efficiently handling multiple requests in a distributed computing 
environment.</p>

<p>
Two files must be configured: <tt>services</tt> and <tt>inetd.conf</tt>. 
Both are ASCII-editable and can usually be found at <tt>/etc/services</tt> and 
<tt>/etc/inetd.conf</tt>.
</p>

<p>
Put one of the following lines into <tt>inetd.conf:</tt>
</p>

<pre>
net-eval  stream  tcp  nowait  root  /usr/local/bin/newlisp -c
											 
# as an alternative, a program can also be preloaded
											 
net-eval  stream  tcp  nowait  root  /usr/local/bin/newlisp -c myprog.lsp
</pre>

<p>
Instead of <tt>root</tt>, another user and optional group can be specified. 
For details, see the Unix man page for <tt>inetd</tt>.
</p>

<p>
The following line is put into the <tt>services</tt> file:
</p>

<pre>
net-eval        4711/tcp     # newLISP net-eval requests
</pre>		

<p>
On macOS and some Unix systems, <tt>xinetd</tt> can be used instead of 
<tt>inetd</tt>. Save the following to a file named <tt>net-eval</tt> in the 
<tt>/etc/xinetd.d/</tt> directory:
</p>

<pre>
service net-eval
{
    socket_type = stream
    wait = no
    user = root
    server = /usr/local/bin/newlisp
    port = 4711
    server_args = -c
    only_from = localhost
}
</pre>		
<p>
For security reasons, <tt>root</tt> should be changed to a different user
and file permissions of the www document directory adjusted accordingly.
The <tt>only_from</tt> spec can be left out to permit remote access.
</p>

<p>
See the man pages for <tt>xinetd</tt> and <tt>xinetd.conf</tt> 
for other configuration options.
</p>

<p>
After configuring the daemon, <tt>inetd</tt> or 
<tt>xinetd</tt> must be restarted to 
allow the new or changed configuration files to be read:
</p>

<pre>
kill -HUP &lt;pid&gt;
</pre>	
<p>
Replace <tt>&lt;pid&gt;</tt> with the process ID of the 
running <tt>xinetd</tt> process.
</p>

<p>A number or network protocol other than 4711 or TCP can be specified.</p>

<p>
newLISP handles everything as if the input were being entered 
on a newLISP command-line without a prompt. To test the 
<tt>inetd</tt> setup, the <tt>telnet</tt> program can be used:
</p>

<pre>
telnet localhost 4711
</pre>		

<p>
newLISP expressions can now be entered, and <tt>inetd</tt> will 
automatically handle the startup and communications of a newLISP 
process. Multiline expressions can be entered by bracketing them 
with <tt>[cmd]</tt> and <tt>[/cmd]</tt> tags, each on separate lines.
</p>

<p>newLISP server nodes answer <tt>HTTP GET</tt> and <tt>PUT</tt> requests. 
This can be used to retrieve and store files 
with <a href="#get-url">get-url</a>, <a href="#put-url">put-url</a>,
<a href="#read-file">read-file</a>, <a href="#write-file">write-file</a>
and <a href="#append-file">append-file</a>,
or to load and save programs using <a href="#load">load</a> 
and <a href="#save">save</a> from and to remote server nodes.</p>
		
<br/>

<a name="link"></a>
<h3>Linking a source file with newLISP for a new executable</h3>

<p>Source code and the newLISP executable can be linked together to build a 
self-contained application by using the <tt>-x</tt> command line flag.</p>

<pre>
;; uppercase.lsp - Link example
(println (upper-case (main-args 1)))
(exit)
</pre>		

<p>The program <tt>uppercase.lsp</tt> takes the first word on the command-line 
and converts it to uppercase.</p>

<p>To build this program as a self-contained executable,
follow these steps:</p>

<pre>
# on OSX, Linux and other UNIX

newlisp -x uppercase.lsp uppercase

chmod 755 uppercase # give executable permission

# on Windows the target needs .exe extension

newlisp -x uppercase.lsp uppercase.exe
</pre>		

<p>newLISP will find a newLISP executable in the execution path of the
environment and link a copy of the source code.</p>

<pre>
uppercase "convert me to uppercase"
</pre>	

<p>On Linux and other UNIX, if the current directory is not in the 
executable path:</p>

<pre>
./uppercase "convert me to uppercase"
</pre>	


<p>The console should print:</p>

<pre>
CONVERT ME TO UPPERCASE
</pre>		

<p>Note that neither one of the initialization files <tt>init.lsp</tt> nor 
<tt>.init.lsp</tt> is loaded during startup of linked programs.</p>

<br/>


<center>
<span class="divider">(&nbsp;<font color="#7ba9d4">&sect;</font>&nbsp;)</span>
</center>
<br/>


<a name="startup"></a>
<h2>5. Startup, directories, environment</h2>

<a name="environment"></a>
<h3>Environment variable <tt>NEWLISPDIR</tt></h3>
<p>During startup, newLISP sets the environment variable <tt>NEWLISPDIR</tt>, 
if it is not set already. On Linux, BSDs, macOS and other Unixes the 
variable is set to <tt>/usr/local/share/newlisp</tt>. On MS Windows the variable is set 
to <tt>%PROGRAMFILES%/newlisp</tt>. On most MS Windows systems <tt>%PROGRAMFILES%</tt> evaluates to the <tt>C:\Program Files (x86)\</tt> directory.</p>

<p>The environment variable <tt>NEWLISPDIR</tt> is useful when loading files 
installed with newLISP:</p>

<pre>
(load (append (env "NEWLISPDIR") "/modules/mysql.lsp"))
</pre>

<p>A predefined function <tt>module</tt> can be used to shorten
the second statement loading from the <tt>modules/</tt>
directory:</p> 

<pre>
(module "mysql.lsp")
</pre>

<br/>

<a name="initialization"></a>
<h3> The initialization file <tt>init.lsp</tt></h3>
<p>Before loading any files specified on the command-line, and before the 
banner and prompt are shown. newLISP tries to load a file <tt>.init.lsp</tt> 
from the home directory of the user starting newLISP. On macOS, Linux and 
other Unix the home directory is found in the <tt>HOME</tt> environment 
variable.  On MS Windows the directory name is contained in the <tt>USERPROFILE</tt>
or <tt>DOCUMENT_ROOT</tt> environment variable.</p>

<p>If a <tt>.init.lsp</tt> cannot be found in the home directory newLISP tries
to load the file <tt>init.lsp</tt> from the directory found in the 
environment variable <tt>NEWLISPDIR</tt>.</p>

<p>When newLISP is run as a shared library, an initialization file is looked 
for in the environment variable <tt>NEWLISPLIB_INIT</tt>. The full path-name 
of the initialization file must be specified. If <tt>NEWLISPLIB_INIT</tt> is 
not defined, no initialization file will be loaded by the library module.</p>

<p> Although newLISP does not require <tt>init.lsp</tt> to run, it is 
convenient for defining functions and system-wide variables.</p>

<p>Note that neither one of the initialization files <tt>init.lsp</tt> nor 
<tt>.init.lsp</tt> is loaded during startup of linked programs or
when one of the options <tt>-n</tt>, <tt>-h</tt>, <tt>-x</tt> is
specified.</p>

<br/>

<a name="directories_unix"></a>
<h3> Directories on Linux, BSD, macOS and other Unix </h3>
<p>
The directory <tt>/usr/local/share/newlisp/modules</tt> contains modules with useful 
functions POP3 mail, etc. The directory <tt>/usr/local/share/doc/newlisp/</tt> 
contains documentation in HTML format.</p>

<br/>

<a name="directories_win"></a>
<h3>Directories on MS Windows</h3>

<p>
On MS Windows systems, all files are installed in the default directory 
<tt>%PROGRAMFILES%\newlisp</tt>.  <tt>PROGRAMFILES</tt> is a MS Windows environment 
variable that resolves to <tt>C:\Program files\newlisp\</tt> in English 
language installations. The subdirectory <tt>%PROGRAMFILES%\newlisp\modules</tt> 
contains modules for interfacing to external libraries and sample programs.</p>

<br/>
<center>
<span class="divider">(&nbsp;<font color="#7ba9d4">&sect;</font>&nbsp;)</span>
</center>
<br/>

<a name="shared-lib"></a>
<h2>6. Extending newLISP with shared libraries</h2>
<p>Many shared libraries on Unix and MS Windows systems can be used to
extend newLISP's functionality. Examples are libraries for writing graphical
user interfaces, libraries for encryption or decryption and libraries for 
accessing databases.</p>

<p>The function <a href="#import">import</a> is used to import functions from 
external libraries. The function <a href="#callback">callback</a> is used to 
register callback functions in external libraries. 
Other functions like <a href="#pack">pack</a>,
<a href="#unpack">unpack</a>, <a href="#get-char">get-char</a>, <a href="#get-string">get-string</a>,
<a href="#get-int">get-int</a> and <a href="#get-long">get-long</a> exist
to facilitate formatting input and output to and from imported library 
functions. The fucntion <a href="#cpymem">cpymem</a> allows direct memory-to-memory
copy specifying addresses.</p>

<p>Most of the functions used when writing APIs for share libraries can cause
newLISP to segfault when not used correctly. The reference documentation marks
these functions with a <a href="#shared-lib"><font size="+1">&#x26A0;</font></a> character linking
to this chapter.</p>

<p>See also the chapter 
<a href="http://www.newlisp.org/downloads/CodePatterns.html#toc-23">
23. Extending newLISP</a> in the
<a href="http://www.newlisp.org/downloads/CodePatterns.html">
Code Patterns in newLISP</a> document.</p>

<br/>
<center>
<span class="divider">(&nbsp;<font color="#7ba9d4">&sect;</font>&nbsp;)</span>
</center>
<br/>

<a name="newlisp-lib"></a>
<h2>7. newLISP as a shared library</h2>

<h3>newLISP as C library</h3>

<p>newLISP can be compiled as a shared C library. On Linux, BSDs and other Unix 
flavors the library is called <tt>newlisp.so</tt>. On Windows it is called 
<tt>newlisp.dll</tt> and <tt>newlisp.dylib</tt> on macOS. A newLISP shared 
library is used like any other shared library. A newLISP shared library is
only required for importing newLISP functionality into other programming
languages.</p>

<p>The main function to import is <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 retrieved 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 not the prompt string.</p>

<p>When calling <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.</p>

<p>To enable <em>stdio</em> on the console, import the function <tt>newlispLibConsole</tt>
and call it with a parameter of <tt>1</tt> for enabling I/O on the console
with <em>stdin</em> and <em>stdout</em>.</p>

<p>Since v.10.3.3 callbacks can also be registered using 
<tt>newlispCallback</tt>.  For more information read the chapter 
<a href="http://www.newlisp.org/downloads/CodePatterns.html#toc-24">
24. newLISP compiled as a shared library</a> in the 
<a href="http://www.newlisp.org/downloads/CodePatterns.html">
Code Patterns in newLISP</a> document.</p>


<a name="newlisp-js-lib"></a>
<h3>newLISP as a JavaScript library</h3>

<p>Since version 10.5.7, newLISP can be compiled to JavaScript using the
<a href="https://github.com/kripken/emscripten/wiki">Emscripten</a>
toolset. The library can be used to run newLISP clientr-side in a web 
browser, just like JavaScript or HTML. An HTML page can host both,
newLISP code and JavaScript code together. Both languages can call
each other. For more information see the <tt>newlisp-js-x.x.x.zip</tt>
distribution package which contains the library <tt>newlisp-js-lib.js</tt>,
documentaion and example applications. A small newLISP development
environment hosted in a browser can also be accessed here:
<a href="http://www.newlisp.org/newlisp-js/">newlisp-js</a>
The application contains links to another example application,
documentation and a download link for the whole package.</p>

<p>newLISP compiled as a JavaScript library adds new functions linked 
from <a href="newlisp_manual.html#JS">API for newLISP in a web browser</a>.
</p>
 

<br/>
<center>
<span class="divider">(&nbsp;<font color="#7ba9d4">&sect;</font>&nbsp;)</span>
</center>
<br/>

<a name="expressions"></a>
<h2>8. Evaluating newLISP expressions</h2>

<p>The following is a short introduction to newLISP statement evaluation 
and the role of integer and floating point arithmetic in newLISP.</p>

<p>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.</p>

<br/>

<a name="multiline"></a>
<h3>Interactive multiline expressions</h3>

<p>Multiline expressions can be entered by entering an empty line first. 
Once in multiline mode, another empty line returns from entry mode 
and evaluates the statement(s) entered (ouput in boldface):</p>

<pre>
&gt;
(define (foo x y)
    (+ x y))

<b>(lambda (x y) (+ x y))</b>
&gt; (foo 3 4)
<b>7</b>
&gt; _
</pre>		

<p>Entering multiline mode by hitting the enter key on an empty line 
suppresses the prompt. Entering another empty line will leave the multiline 
mode and evaluate expressions.</p>

<p>As an alternativo to entering empty lines, the <tt>[cmd]</tt> and 
<tt>[/cmd]</tt> tags are used, each entered on separate lines. This mode is 
used by some interactive IDEs controlling newLISP and internally by the 
<a href="#net-eval">net-eval</a> function.</p>

<br/>

<a name="int_float"></a>
<h3>Integer, floating point data and operators</h3>

<p>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.</p>

<p>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.</p>

<p>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>:</p>

<pre>
(constant '+ add)
(constant '- sub)
(constant '* mul)
(constant '/ div)
 
;; or all 4 operators at once
(constant '+ add '- sub '* mul '/ div)
</pre>		

<p>
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. </p>

<p>Care must be taken when <a href="#import">importing</a> 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:</p>

<pre>
(import "mylib.dll" "foo")  ; importing int foo(int x) from C
(foo (int x))               ; passed argument as integer
(import "mylib.dll" "bar")  ; importing C int bar(double y)
(bar (float y))             ; force double float
</pre>		

<p>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.</p>

<p>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. Since version 8.9.7, 
integer operations in newLISP are 64 bit operations, whereas 64 bit double 
floating point numbers offer only 52 bits of resolution in the integer part 
of the number.</p>
		
<br/>
<a name="big_int"></a>
<h3>Big integer, multiple precision arithmetic</h3>

<p>The following operators, functions and predicates work on big integers:</p>

<table  summary="functions working on big integers">
<tr align="left"><th>function</th><th>description</th></tr>

<tr>
<td width="16%"><a href="#arithmetic">+ - * / ++ -- %</a></td>
<td width="80%">arithmetic operators</td>
</tr>

<tr>
<td><a href="#logical">&lt; &gt; = &lt;= &gt;= !=</a></td>
<td>logical operators</td>
</tr>

<tr>
<td><a href="#abs">abs</a></td>
<td>returns the absolute value of a number</td>
</tr>

<tr>
<td><a href="#gcd">gcd</a></td>
<td>calculates the greatest common divisor of a group of integers</td>
</tr>

<tr>
<td><a href="#evenp">even?</a></td>
<td>checks the parity of an integer number</td>
</tr>

<tr>
<td><a href="#oddp">odd?</a></td>
<td>checks the parity of an integer number</td>
</tr>

<tr>
<td><a href="#numberp">number?</a></td>
<td>checks if an expression is a float or an integer</td>
</tr>

<tr>
<td><a href="#zerop">zero?</a></td>
<td>checks if an expression is 0 or 0.0</td>
</tr>
</table>

<p>If the first argument in any of these operators and functions is a big 
integer, the calculation performed will be in big integer mode. In the
<a href="#function_ref">Function Reference</a> section of this manual
these are marked with a <a href="#big_int"><font size="-1">bigint</font></a>
suffix.</p> 

<p>Literal integer values greater than 9223372036854775807
or smaller than -9223372036854775808, or integers with an appended letter L,
will be converted and processed in big integer mode. The function 
<a href="#bigint">bigint</a>  can be used to convert from integer, float or string 
format to big integer. The predicate <a href="#bigintp">bigint?</a> checks for 
big integer type.</p>

<pre>
; first argument triggers big integer mode because it's big enough

(+ 123456789012345678901234567890 12345) <span class='arw'>&rarr;</span> 123456789012345678901234580235L

; first small literal put in big integer format by 
; appending L to guarantee big integer mode

(+ 12345L 123456789012345678901234567890) <span class='arw'>&rarr;</span> 123456789012345678901234580235L

(setq x 1234567890123456789012345)
(* x x) <span class='arw'>&rarr;</span> 1524157875323883675049533479957338669120562399025L

; conversion from bigint to float introduces rounding errors

(bigint (float (* x x))) <span class='arw'>&rarr;</span> 1524157875323883725344000000000000000000000000000L

; sequence itself does not take big integers, before using
; apply, the sequence is converted with bigint

(apply * (map bigint (sequence 1 100))) ; calculate 100!
<span class='arw'>&rarr;</span> 93326215443944152681699238856266700490715968264381
  62146859296389521759999322991560894146397615651828
  62536979208272237582511852109168640000000000000000
  00000000L

; only the first operand needs to be bigint for apply
; to work. The following gives the same result

(apply * (cons 1L (sequence 2 100)))

; length on big integers returns the number of decimal digits
(length (apply * (map bigint (sequence 1 100)))) 
<span class='arw'>&rarr;</span> 158 ; decimal digits

; all fibonacci numbers up to 200, only the first number 
; needs to be formatted as big integer, the rest follows
; automatically - when executed from the command line in 
; a 120 char wide terminal, this shows a beautiful pattern

(let (x 1L) (series x (fn (y) (+ x (swap y x))) 200))

</pre>

<p> When doing mixed integer / big integer arithmetic, the first
argument should be a big integer to avoid erratic behaviour.</p>

<pre>
; because the first argument is 64-bit, no big integer arithmetic 
; will be done, although the second argument is big integer 

(+ 123 12345L)
<span class='arw'>&rarr;</span> 12468

; the second argument is recognized as a big integer
; and overflows the capacity of a 64-bit integer

(+ 123 123453456735645634565463563546)
<span class='arw'>&rarr;</span> <span class="err">ERR: number overflows in function +</span>

; now the first argument converts to big integer and the
; whole expression evaluates in big integer mode

(+ 123L 123453456735645634565463563546)
<span class='arw'>&rarr;</span> 123453456735645634565463563669L
</pre>

<p>Under most circumstances mixing float, integers and big integers is 
transparent. Functions automatically do conversions when needed on the 
second argument. The overflow behavior when using normal integers and 
floats only, has not changed from newLISP versions previous to 10.5.0.</p>

<br/>
<a name="eval_rules"></a>
<h3>Evaluation rules and data types</h3>

<p>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.
</p>
<p>
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.</p>

<p>When evaluation occurs from the command-line, the result is printed to the 
console window.</p>

<p>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.</p>

<p><b>nil</b> and <b>true</b> are Boolean data types that 
evaluate to themselves:</p>

<pre>
nil    <span class='arw'>&rarr;</span> nil
true   <span class='arw'>&rarr;</span> true
</pre>		

<p><b>Integers</b>, <b>big integers</b> and <b>floating point</b> numbers evaluate to themselves:</p>

<pre>
123      <span class='arw'>&rarr;</span> 123    ; decimal integer
0xE8     <span class='arw'>&rarr;</span> 232    ; hexadecimal prefixed by 0x
055      <span class='arw'>&rarr;</span> 45     ; octal prefixed by 0 (zero)
0b101010 <span class='arw'>&rarr;</span> 42     ; binary prefixed by 0b
1.23     <span class='arw'>&rarr;</span> 1.23   ; float
123e-3   <span class='arw'>&rarr;</span> 0.123  ; float in scientific notation

123456789012345678901234567890
<span class='arw'>&rarr;</span> 123456789012345678901234567890L ; parses to big integer
</pre>		
<p>
Integers are 64-bit including the sign bit.  Valid integers 
are numbers between -9,223,372,036,854,775,808 and
+9,223,372,036,854,775,807. Larger numbers converted from floating point 
numbers are truncated to one of the two limits. Integers internal to newLISP, 
which are limited to 32-bit numbers, overflow to either +2,147,483,647 or
-2,147,483,648.</p>

<p>Floating point numbers are IEEE 754 64-bit doubles.
Unsigned numbers up to 18,446,744,073,709,551,615 can be displayed
using special formatting characters for <a href="#format">format</a>.</p>

<p>Big integers are of unlimited precision and only limited in size by memory. 
The memory requirement of a big integer is:</p>

<blockquote>
<b><i>bytes = 4 * ceil(digits / 9) + 4.</i></b>
</blockquote>

<p>Where <i>digits</i> are decimal digits, <i>bytes</i> are 8 bits and <i>ceil</i>
is the ceiling function rounding up to the next integer.</p>

<p>
<b>Strings</b> may contain null characters and can have different 
delimiters. They evaluate to themselves.</p>

<pre>
"hello"             <span class='arw'>&rarr;</span>"hello"  
"\032\032\065\032"  <span class='arw'>&rarr;</span>"  A " 
"\x20\x20\x41\x20"  <span class='arw'>&rarr;</span>"  A "
"\t\r\n"            <span class='arw'>&rarr;</span>"\t\r\n" 
"\x09\x0d\x0a"      <span class='arw'>&rarr;</span>"\t\r\n"

;; null characters are legal in strings:
"\000\001\002"       <span class='arw'>&rarr;</span> "\000\001\002"
{this "is" a string} <span class='arw'>&rarr;</span> "this \"is\" a string"
 
;; use [text] tags for text longer than 2047 bytes:
[text]this is a string, too[/text]
<span class='arw'>&rarr;</span> "this is a string, too"
</pre>	
<p>Strings delimited by <tt>"</tt> (double quotes) will also process 
the following characters escaped with a <tt>\</tt> (backslash):</p>

<table  width="98%" summary="special characters in strings">
<tr align="left"><th>character</th><th>description</th></tr>

<tr><td><tt>\"</tt></td>
<td>for a double quote inside a quoted string</td></tr>

<tr><td><tt>\n</tt></td>
<td>for a line-feed character (ASCII 10)</td></tr>

<tr><td><tt>\r</tt></td>
<td>for a return character (ASCII 13)</td></tr>

<tr><td><tt>\b</tt></td>
<td>for a backspace BS character (ASCII 8)</td></tr>

<tr><td><tt>\t</tt></td>
<td>for a TAB character (ASCII 9)</td></tr>

<tr><td><tt>\f</tt></td>
<td>for a formfeed FF character (ASCII 12)</td></tr>

<tr><td><tt>\nnn</tt></td>
<td>for a three-digit ASCII number (nnn format 
between 000 and 255)</td></tr>

<tr><td><tt>\xnn</tt></td>
<td>for a two-digit-hex ASCII number (xnn format between x00 and xff)</td></tr> 

<tr><td><tt>\unnnn</tt></td>
<td>for a unicode character encoded in the four <tt>nnnn</tt> hexadecimal
digits. newLISP will translate this to a UTF8 character in the UTF8 enabled 
versions of newLISP.</td>
</tr>

<tr><td><tt>\\</tt></td><td>for the backslash character (ASCII 92) 
itself</td></tr>
</table><br/>

<p>Quoted strings cannot exceed 2,047 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,047 characters.</p>

<p>The <tt>{</tt> (left curly bracket), <tt>}</tt> (right curly bracket), 
and <tt>[text], [/text]</tt> delimiters do not perform escape character 
processing.</p>

<p><b>Lambda and lambda-macro expressions</b> evaluate to themselves:</p>

<pre>
(lambda (x) (* x x))                   <span class='arw'>&rarr;</span> (lambda (x) (* x x))
(lambda-macro (a b) (set (eval a) b))  <span class='arw'>&rarr;</span> (lambda-macro (a b) (set (eval a) b))
(fn (x) (* x x))                       <span class='arw'>&rarr;</span> (lambda (x) (* x x))  ; an alternative syntax
</pre>		

<p><b>Symbols</b> evaluate to their contents:</p>

<pre>
(set 'something 123)  <span class='arw'>&rarr;</span> 123
something             <span class='arw'>&rarr;</span> 123
</pre>		

<p><b>Contexts</b> evaluate to themselves:</p>

<pre>
(context 'CTX)  <span class='arw'>&rarr;</span> CTX
CTX             <span class='arw'>&rarr;</span> CTX
</pre>		

<p><b>Built-in functions</b> also evaluate to themselves:</p>

<pre>
add                <span class='arw'>&rarr;</span> add &lt;B845770D&gt;
(eval (eval add))  <span class='arw'>&rarr;</span> add &lt;B845770D&gt;
(constant '+ add)  <span class='arw'>&rarr;</span> add &lt;B845770D&gt;
+                  <span class='arw'>&rarr;</span> add &lt;B845770D&gt;
</pre>		

<p>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.</p>

<p><b>Quoted expressions</b> lose one ' (single quote) when evaluated:
</p>

<pre>
'something  <span class='arw'>&rarr;</span> something
''''any     <span class='arw'>&rarr;</span> '''any
'(a b c d)  <span class='arw'>&rarr;</span> (a b c d)
</pre>		

<p>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).</p>
		
<p><b>Lists</b> are evaluated by first evaluating the first list element
before the rest of the expression (as in Scheme). The result of the 
evaluation is applied to the remaining elements in the list and must 
be one of the following: a <tt>lambda</tt> expression, <tt>lambda-macro</tt> 
expression, or <tt>primitive</tt> (built-in) function.</p>

<pre>
(+ 1 2 3 4)                  <span class='arw'>&rarr;</span> 10
(define (double x) (+ x x))  <span class='arw'>&rarr;</span> (lambda (x) (+ x x))
</pre>		

<p>or</p>

<pre>
(set 'double (lambda (x) (+ x x)))
(double 20)               <span class='arw'>&rarr;</span> 40
((lambda (x) (* x x)) 5)  <span class='arw'>&rarr;</span> 25
</pre>		

<p>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. </p>

<p>Like Scheme, newLISP evaluates the <em>functor</em> (function object) 
part of an expression before applying the result to its arguments. For 
example:</p>

<pre>
((if (&gt; X 10) * +) X Y)
</pre>		

<p>Depending on the value of X, this expression applies the <tt>*</tt> 
(product) or <tt>+</tt> (sum) function to X and Y.
</p>

<p>Because their arguments are not evaluated, <tt>lambda-macro</tt> 
expressions are useful for extending the syntax of the language. Most 
built-in functions evaluate their arguments from left to right (as needed) 
when executed. Some exceptions to this rule are indicated in the reference 
section of this manual. Lisp functions that do not evaluate all or some of 
their arguments are called <em>special forms</em>.</p>

<p><b>Arrays</b> evaluate to themselves:</p>

<pre>
(set 'A (array 2 2 '(1 2 3 4))) <span class='arw'>&rarr;</span> ((1 2) (3 4))
(eval A)                        <span class='arw'>&rarr;</span> ((1 2) (3 4))
</pre>


<p><b>Shell commands</b>: If an <tt>!</tt> (exclamation mark) 
is entered as the first character on the command-line followed by a shell 
command, the command will be executed. For example, <tt>!ls</tt> on Unix or 
<tt>!dir</tt> on MS Windows will display a listing of the present working directory. 
No spaces are permitted between the <tt>!</tt> and the shell command. Symbols 
beginning with an <tt>!</tt> are still allowed inside expressions or  on the 
command-line when preceded by a space. Note: This mode only works when running 
in the shell and does not work when controlling newLISP from another 
application.
</p>

<p>To exit the newLISP shell on Linux/Unix, press <tt>Ctrl-D</tt>; on MS Windows, 
type <tt>(exit)</tt> or <tt>Ctrl-C</tt>, then the x key.
</p>

<p>Use the <a href="#exec">exec</a> function to access shell commands from 
other applications or to pass results back to newLISP.
</p>

<br/>
<center>
<span class="divider">(&nbsp;<font color="#7ba9d4">&sect;</font>&nbsp;)</span>
</center>

<br/>
<a name="lambda_expressions"></a>
<h2>9. Lambda expressions in newLISP</h2>

<p>Lambda expressions in newLISP evaluate to themselves and can be treated
just like regular lists:</p>

<pre>
(set 'double (lambda (x) (+ x x)))
(set 'double (fn (x) (+ x x)))      ; alternative syntax

(last double)  <span class='arw'>&rarr;</span> (+ x x)            ; treat lambda as a list
</pre>		

<p>Note: No <tt>'</tt> is necessary before the lambda expression because 
lambda expressions evaluate to themselves in newLISP.</p>
<p>
The second line uses the keyword <tt>fn</tt>, an alternative syntax first suggested 
by Paul Graham for his Arc language project.
</p>
<p>
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:
</p>
<pre>
(append (lambda (x)) '((+ x x)))  <span class='arw'>&rarr;</span> (lambda (x) (+ x x))
</pre>		<p>
<a href="#cons">cons</a>, on the other hand, associates the arguments from right to left:
</p>
<pre>
(cons '(x) (lambda (+ x x)))  <span class='arw'>&rarr;</span> (lambda (x) (+ x x))
</pre>		<p>
Note that the <tt>lambda</tt> keyword is not a symbol in a list, but a
designator of a special <em>type</em> of list: the <em>lambda list</em>.
</p>
<pre>
(length (lambda (x) (+ x x)))  <span class='arw'>&rarr;</span> 2
(first (lambda (x) (+ x x)))   <span class='arw'>&rarr;</span> (x)
</pre>		<p>
Lambda expressions can be mapped or applied onto arguments to work as user-defined, anonymous functions:
</p>
<pre>
((lambda (x) (+ x x)) 123)           <span class='arw'>&rarr;</span> 246
(apply (lambda (x) (+ x x)) '(123))  <span class='arw'>&rarr;</span> 246
(map (lambda (x) (+ x x)) '(1 2 3))  <span class='arw'>&rarr;</span> (2 4 6)
</pre>		

<p>A lambda expression can be assigned to a symbol, which in turn can be 
used as a function:</p>

<pre>
(set 'double (lambda (x) (+ x x)))  <span class='arw'>&rarr;</span> (lambda (x) (+ x x))
(double 123)                        <span class='arw'>&rarr;</span> 246
</pre>		

<p>The <a href="#define">define</a> function is just a shorter way of
assigning a lambda expression to a symbol:</p>

<pre>
(define (double x) (+ x x)))  <span class='arw'>&rarr;</span> (lambda (x) (+ x x))
(double 123)                  <span class='arw'>&rarr;</span> 246
</pre>		

<p>In the above example, the expressions inside the lambda list are still 
accessible within <tt>double</tt>:</p>

<pre>
(set 'double (lambda (x) (+ x x)))  <span class='arw'>&rarr;</span> (lambda (x) (+ x x))
(last double)                       <span class='arw'>&rarr;</span> (+ x x)
</pre>		

<p>A lambda list can be manipulated as a first-class object using any function 
that operates on lists:</p>

<pre>
(setf (nth 1 double) '(mul 2 x))     <span class='arw'>&rarr;</span> (lambda (x) (mul 2 x))
double                           <span class='arw'>&rarr;</span> (lambda (x) (mul 2 x))
(double 123)                     <span class='arw'>&rarr;</span> 246
</pre>		

<p>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.</p>

<br/>
<center>
<span class="divider">(&nbsp;<font color="#7ba9d4">&sect;</font>&nbsp;)</span>
</center>
<br/>

<a name="nil_and_true"></a>
<h2>10. <tt>nil</tt>, <tt>true</tt>, <tt>cons</tt>, and <tt>()</tt></h2>

<p>In newLISP, <tt>nil</tt> and <tt>true</tt> represent both the symbols and the 
Boolean values <em>false</em> and <em>true</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.
</p>

<p>Evaluation of <tt>nil</tt> yields a Boolean false and is treated as such inside 
flow control  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.</p>

<pre>
(set 'lst '(nil nil nil))  <span class='arw'>&rarr;</span> (nil nil nil)
(map symbol? lst)          <span class='arw'>&rarr;</span> (true true true)
</pre>		

<p>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:</p>

<pre>
(if nil "no" "yes")  <span class='arw'>&rarr;</span> "yes"
(if true "yes" "no") <span class='arw'>&rarr;</span> "yes"
(map not lst)        <span class='arw'>&rarr;</span> (true true true)
</pre>		

<p>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>.</p>

<p>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, not 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>.</p>

<p>A list in newLISP is a newLISP 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 <em>car</em> and <em>cdr</em> for the names 
<em>head</em> and <em>tail</em>.</p>

<br/>
<center>
<span class="divider">(&nbsp;<font color="#7ba9d4">&sect;</font>&nbsp;)</span>
</center>
<br/>

<a name="arrays"></a>
<h2>11. Arrays</h2>

<p>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. Most 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.</p>

<p>In particular, the following functions can be used for creating, accessing, 
and modifying arrays:</p>

<table  summary="functions using arrays">
<tr align="left"><th>function</th><th>description</th></tr>

<tr>
<td width="16%"><a href="#append">append</a></td>
<td width="80%">appends arrays</td>
</tr>

<tr>
<td><a href="#apply">apply</a></td>
<td>apply a function or operator to a list of arguments.</td>
</tr>

<tr>
<td><a href="#array">array</a></td>
<td>creates and initializes an array with up to 16 dimensions</td>
</tr>

<tr>
<td><a href="#array-list">array-list</a></td>
<td>converts an array into a list</td>
</tr>

<tr>
<td><a href="#arrayp">array?</a></td>
<td>checks if expression is an array</td>
</tr>

<tr>
<td><a href="#corr">corr</a></td>
<td>calculates the <em>product-moment correlation</em> coefficient</td>
</tr>

<tr>
<td><a href="#det">det</a></td>
<td>returns the determinant of a matrix</td>
</tr>

<tr>
<td><a href="#dolist">dolist</a></td>
<td>evaluates once for each element in an array vector</td>
</tr>

<tr>
<td><a href="#first">first</a></td>
<td>returns the first row of an array</td>
</tr>

<tr>
<td><a href="#invert">invert</a></td>
<td>returns the inversion of a matrix</td>
</tr>

<tr>
<td><a href="#last">last</a></td>
<td>returns the last row of an array</td>
</tr>

<tr>
<td><a href="#length">length</a></td>
<td>returns the number of rows in an array or elements in a vector</td>
</tr>

<tr>
<td><a href="#map">map</a></td>
<td>applies a function to vector(s) of arguments
and returns results in a list.</td>
</tr>

<tr>
<td><a href="#mat">mat</a></td>
<td>perform scalar operations on matrices</td>
</tr>

<tr>
<td><a href="#multiply">multiply</a></td>
<td>multiplies two matrices</td>
</tr>

<tr>
<td><a href="#nth">nth</a></td>
<td>returns an element of and array</td>
</tr>

<tr>
<td><a href="#rest">rest</a></td>
<td>returns all but the first row of an array</td>
</tr>

<tr>
<td><a href="#reverse">reverse</a></td>
<td>reverses the elements or rows in an array</td>
</tr>

<tr>
<td><a href="#setf">setf</a></td>
<td>sets contents of an array reference</td>
</tr>

<tr>
<td><a href="#slice">slice</a></td>
<td>returns a slice of an array</td>
</tr>

<tr>
<td><a href="#sort">sort</a></td>
<td>sort the elements in an array</td>
</tr>

<tr>
<td><a href="#stats">stats</a></td>
<td>calculates some basic statistics for a data vector</td>
</tr>

<tr>
<td><a href="#t-test">t-test</a></td>
<td>compares means of data samples using the <em>Student's t</em> statistic</td>
</tr>

<tr>
<td><a href="#transpose">transpose</a></td>
<td>transposes a matrix</td>
</tr>
</table><br/>

<p>
newLISP represents multidimensional arrays with an array of arrays 
(i.e., the elements of the array are themselves arrays).
</p>

<p>When used interactively, newLISP prints and displays arrays as lists, 
with no way of distinguishing between them.</p>

<p>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.</p>

<p>Like lists, negative indices can be used to enumerate the elements 
of an array, starting from the last element.</p>

<p>An out-of-bounds index will cause an error message on an array or list.</p>

<p>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.</p>

<p>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 lists or arrays built with <a href="#array">array</a>.</p>

<p>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.</p>

<br/>
<center>
<span class="divider">(&nbsp;<font color="#7ba9d4">&sect;</font>&nbsp;)</span>
</center>
<br/>

<a name="indexing"></a>
<h2>12. Indexing elements of strings, lists, and arrays</h2>

<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 <em>int-index</em> 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> or less then -N causes an 
out-of-bounds error in lists and arrays.</p>

<br/>

<a name="implicit_indexing"></a>
<h3>Implicit indexing for <tt>nth</tt></h3>

<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>

<pre>
(set 'lst '(a b c (d e) (f g)))

(lst 0)    <span class='arw'>&rarr;</span> a      ; same as (nth 0 lst)
(lst 3)    <span class='arw'>&rarr;</span> (d e)
(lst 3 1)  <span class='arw'>&rarr;</span> e      ; same as (nth '(3 1) lst)
(lst -1)   <span class='arw'>&rarr;</span> (f g)

(set 'myarray (array 3 2 (sequence 1 6)))

(myarray 1)     <span class='arw'>&rarr;</span> (3 4)
(myarray 1 0)   <span class='arw'>&rarr;</span> 3
(myarray 0 -1)  <span class='arw'>&rarr;</span> 2

; indexing ASCII strings
("newLISP" 3)   <span class='arw'>&rarr;</span> "L"

; indexing strings in UTF8 enabled versions
 ("我能吞下玻璃而不伤身体。" 3) <span class='arw'>&rarr;</span> "下"
</pre>		

<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> and <a href="#ref-all">ref-all</a>.</p>

<pre>
(lst '(3 1))                <span class='arw'>&rarr;</span> e
(set 'vec (ref 'e lst))     <span class='arw'>&rarr;</span> (3 1)
(lst vec)                   <span class='arw'>&rarr;</span> e

; an empty index vector yields the original list or array

(lst '())  <span class='arw'>&rarr;</span> (set 'lst '(a b c (d e) (f g)))
</pre>		

<p>Note that implicit indexing is not breaking newLISP
syntax rules but is merely an expansion of existing rules to
other data types in the functor position of an s-expression. 
In original Lisp, the first element in an s-expression list
is applied as a function to the rest elements as arguments. In newLISP, a list 
in the functor position of an s-expression assumes self-indexing functionality 
using the index arguments following it.</p>

<p>Implicit indexing is faster than the explicit forms, but the explicit forms
may be more readable depending on context.</p>

<p>Note that in the UTF-8&ndash;enabled version of newLISP, implicit indexing 
of strings or using the <a href="#nth">nth</a> function work on character rather 
than single-byte boundaries.</p>

<br/>

<a name="implicit_default"></a>
<h3>Implicit indexing and the default functor</h3>

<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>

<pre>
(set 'MyList:MyList '(a b c d e f g))

(MyList 0)   <span class='arw'>&rarr;</span> a
(MyList 3)   <span class='arw'>&rarr;</span> d
(MyList -1)  <span class='arw'>&rarr;</span> g

(3 2 MyList) <span class='arw'>&rarr;</span> (d e)
(-3 MyList)  <span class='arw'>&rarr;</span> (e f g)

(set 'aList MyList)

(aList 3)  <span class='arw'>&rarr;</span> d
</pre>		

<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_vars">Variables holding contexts</a>.</p>

<p>The indexed default functor can also be used with <a href="#setf">setf</a> as shown 
in the following example:</p>

<pre>
(set 'MyList:MyList '(a b c d e f g))

(setf (MyList 3) 999)   <span class='arw'>&rarr;</span> 999
(MyList 3)              <span class='arw'>&rarr;</span> 999

MyList:MyList           <span class='arw'>&rarr;</span> (a b c 999 e f g)
</pre>

<br/>

<a name="implicit_rest_slice"></a>
<h3>Implicit indexing for <tt>rest</tt> and <tt>slice</tt> </h3>

<p> Implicit forms of <a href="#rest">rest</a> and <a href="#slice">slice</a> 
can be created by prepending a list with one or two numbers for offset and length.
If the length is negative it counts from the end of the list or string:</p>

<pre>
(set 'lst '(a b c d e f g))
; or as array
(set 'lst (array 7 '(a b c d e f g)))

(1 lst)      <span class='arw'>&rarr;</span> (b c d e f g)
(2 lst)      <span class='arw'>&rarr;</span> (c d e f g)
(2 3 lst)    <span class='arw'>&rarr;</span> (c d e)
(-3 2 lst)   <span class='arw'>&rarr;</span> (e f)
(2 -2 lst)   <span class='arw'>&rarr;</span> (c d e)

; resting and slicing is always on 8-bit char borders
; even on UTF8 enabled versions

(set 'str "abcdefg")

(1 str)      <span class='arw'>&rarr;</span> "bcdefg"
(2 str)      <span class='arw'>&rarr;</span> "cdefg"
(2 3 str)    <span class='arw'>&rarr;</span> "cde"
(-3 2 str)   <span class='arw'>&rarr;</span> "ef"
(2 -2 str)   <span class='arw'>&rarr;</span> "cde"

</pre>	

<p>The functions <a href="#rest">rest</a>, <a href="#first">first</a>
and <a href="#last">last</a> work on multi-byte character boundaries
in UTF-8 enabled versions of newLISP. But the implicit indexing forms for
slicing and resting will always work on single-byte boundaries and can be used for 
binary content. Offset and length results from the regular expression functions 
<a href="#find">find</a> and <a href="#regex">regex</a> are also in single-byte
counts and can be further processed with <a href="#slice">slice</a> or it's
implicit form.</p>

<br/>

<a name="implicit_modify"></a>
<h3>Modify references in lists, arrays and strings</h3>

<p>Parts in lists, arrays and strings referenced by indices can be modified using
<a href="#setf">setf</a>:</p>

<pre>
; lists

(set 'lst '(a b c d (e f g)))

(lst 1) <span class='arw'>&rarr;</span> b

(setf (lst 1) 'z) <span class='arw'>&rarr;</span> z

lst <span class='arw'>&rarr;</span> (a z c d (e f g))

(setf (lst -1) '(E F G)) <span class='arw'>&rarr;</span> (E F G)

lst <span class='arw'>&rarr;</span> (a z c d (E F G))

; arrays

(set 'myarray (array 2 3 (sequence 1 6))) <span class='arw'>&rarr;</span> ((1 2 3) (4 5 6))

(setf (myarray 1 2) 66) <span class='arw'>&rarr;</span> 66

myarray <span class='arw'>&rarr;</span> ((1 2 3) (4 5 66))

; strings

(set 's "NewLISP")

(setf (s 0) "n") <span class='arw'>&rarr;</span> "n"

s <span class='arw'>&rarr;</span> "newLISP"
</pre>


<p>Note that only full elements or nested lists or arrays can be changed this way.
Slices or rest parts of lists or arrays as used in implicit resting or slicing cannot
be substituted at once using <a href="#setf">setf</a>, but would have to be substituted
element by element. In strings only one character can be replaced at a time, but
that character can be replaced by a multi-character string.</p> 

<br/>

<center>
<span class="divider">(&nbsp;<font color="#7ba9d4">&sect;</font>&nbsp;)</span>
</center>
<br/>


<a name="destructive"></a>
<h2>13. Destructive versus nondestructive functions</h2>

<p>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 
variable, list, array, or string:</p>

<table  width="98%" summary="destructive functions">
<tr align="left"><th>function</th><th>description</th></tr>

<tr>
<td><a href="#inci">++</a></td>
<td>increments numbers in integer mode</td>
</tr>

<tr>
<td><a href="#deci">--</a></td>
<td>decrements numbers in integer mode</td>
</tr>

<tr>
<td><a href="#bind">bind</a></td>
<td>binds variable associations in a list</td>
</tr>

<tr>
<td><a href="#constant">constant</a></td>
<td>sets the contents of a variable and protects it</td>
</tr>

<tr>
<td><a href="#extend">extend</a></td>
<td>extends a list or string</td>
</tr>

<tr>
<td><a href="#dec">dec</a></td>
<td>decrements a number referenced by a variable, list or array</td>
</tr>

<tr>
<td><a href="#define">define</a></td>
<td>sets the contents of a variable</td>
</tr>

<tr>
<td><a href="#define-macro">define-macro</a></td>
<td>sets the contents of a variable</td>
</tr>

<tr>
<td><a href="#inc">inc</a></td>
<td>increments a number referenced by a variable, list or array</td>
</tr>

<tr>
<td><a href="#let">let</a></td>
<td>declares and initializes local variables</td>
</tr>

<tr>
<td><a href="#letn">letn</a></td>
<td>initializes local variables incrementally, like nested lets</td>
</tr>

<tr>
<td><a href="#letex">letex</a></td>
<td>expands local variables into an expression, then evaluates</td>
</tr>

<tr>
<td><a href="#net-receive">net-receive</a></td>
<td>reads into a buffer variable</td>
</tr>

<tr>
<td><a href="#pop">pop</a></td>
<td>pops an element from a list or string</td>
</tr>

<tr>
<td><a href="#pop-assoc">pop-assoc</a></td>
<td>removes an association from an association list</td>
</tr>

<tr>
<td><a href="#push">push</a></td>
<td>pushes a new element onto a list or string</td>
</tr>

<tr>
<td><a href="#read">read</a></td>
<td>reads into a buffer variable</td>
</tr>

<tr>
<td><a href="#receive">receive</a></td>
<td>receives a message from a parent or child process</td>
</tr>

<tr>
<td><a href="#replace">replace</a></td>
<td>replaces elements in a list or string</td>
</tr>

<tr>
<td><a href="#reverse">reverse</a></td>
<td>reverses a list or string</td>
</tr>

<tr>
<td><a href="#rotate">rotate</a></td>
<td>rotates the elements of a list or characters of a string</td>
</tr>

<tr>
<td><a href="#set">set</a></td>
<td>sets the contents of a variable</td>
</tr>

<tr>
<td><a href="#setf">setf setq</a></td>
<td>sets the contents of a variable, list, array or string</td>
</tr>

<tr>
<td><a href="#set-ref">set-ref</a></td>
<td>searches for an element in a nested list and replaces it</td>
</tr>

<tr>
<td><a href="#set-ref-all">set-ref-all</a></td>
<td>searches for an element in a nested list and replaces all instances</td>
</tr>

<tr>
<td><a href="#sort">sort</a></td>
<td>sorts the elements of a list or array</td>
</tr>

<tr>
<td><a href="#swap">swap</a></td>
<td>swaps two elements inside a list or string</td>
</tr>

<tr>
<td><a href="#write">write</a></td>
<td>write a string to a file or string buffer</td>
</tr>

</table><br/>

<br/>

<a name="make_nondestructive"></a>
<h3>Make a destructive function non-destructive</h3>

<p>Some destructive functions can be made non-destructive by wrapping the target 
object into the <a href="#copy">copy</a> function.</p>

<pre>
(set 'aList '(a b c d e f))

(replace 'c (copy aList)) <span class='arw'>&rarr;</span> (a b d e f)

aList <span class='arw'>&rarr;</span> (a b c d e f)
</pre>

<p>The list in <tt>aList</tt> is left unchanged.</p>

<br/>

<center>
<span class="divider">(&nbsp;<font color="#7ba9d4">&sect;</font>&nbsp;)</span>
</center>
<br/>

<a name="return"></a>
<h2>14. Early return from functions, loops, and blocks</h2>

<p>What follows are methods of interrupting the control flow inside both 
loops and the <a href="#begin">begin</a> expression.</p>

<p>The looping functions <a href="#dolist">dolist</a> and <a href="#dotimes">
dotimes</a> can take optional conditional expressions to leave the loop
early. <a href="#catch">catch</a> and <a href="#throw">throw</a> are a more
general form to break out of a loop body and are also applicable to other
forms or statement blocks.</p>

<br/>

<a name="flow_catch_throw"></a>
<h3>Using <tt>catch</tt> and <tt>throw</tt></h3>

<p>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>:</p>

<pre>
(define (foo x)
    ...
    (if condition (throw 123))
    ...
    456
)
									 
;; if condition is true

(catch (foo p))  <span class='arw'>&rarr;</span> 123
									 
;; if condition is not true
									 
(catch (foo p))  <span class='arw'>&rarr;</span> 456
</pre>		

<p>Breaking out of loops works in a similar way:</p>

<pre>
(catch
    (dotimes (i N)
        (if (= (foo i) 100) (throw i))))

<span class='arw'>&rarr;</span> value of i when foo(i) equals 100
</pre>		

<p>The example shows how an iteration can be exited before executing <tt>N</tt> times.</p>

<p>Multiple points of return can be coded using <a href="#throw">throw</a>:</p>

<pre>
(catch (begin
    (foo1)
    (foo2)
    (if condition-A (throw 'x))
    (foo3)
    (if condition-B (throw 'y))
    (foo4)
    (foo5)))
</pre>		

<p>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.</p>

<p>As an alternative to <a href="#catch">catch</a>, the <a href="#error-event">error-event</a> 
function can be used to catch errors caused by faulty code or user-initiated exceptions.</p>

<p>The <a href="#throw-error">throw-error</a> function may be used
to throw user-defined errors.</p>

<br/>

<a name="flow_and_or"></a>
<h3>Using <tt>and</tt> and <tt>or</tt></h3>

<p>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:</p>

<pre>
(and
    (func-a)
    (func-b)
    (func-c)
    (func-d))
</pre>		

<p>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.</p>

<p><a href="#or">or</a> can be used in a similar fashion:</p>

<pre>
(or
    (func-a)
    (func-b)
    (func-c)
    (func-d))
</pre>		
<p>
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>.
</p>

<br/>
<center>
<span class="divider">(&nbsp;<font color="#7ba9d4">&sect;</font>&nbsp;)</span>
</center>
<br/>

<a name="scoping"></a>
<h2>15. Dynamic and lexical scoping</h2>

<p>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>.</p>

<p>
When the parameter symbols of a lambda expression are bound to its arguments, 
the old bindings are pushed onto a stack. newLISP automatically restores the 
original variable bindings when leaving the lambda function. </p>
<p>
The following example illustrates the <em>dynamic scoping</em> mechanism. 
The text in bold is the output from newLISP:</p>

<pre>
&gt; (set 'x 1)
<b>1</b>
&gt; (define (f) x)
<b>(lambda () x)</b>
&gt; (f)
<b>1</b>
&gt; (define (g x) (f))
<b>(lambda (x) (f))</b>
&gt; (g 0)
<b>0</b>
&gt; (f)
<b>1</b> 
&gt; _
</pre>	

<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 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>

<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>.
</p>

<p>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:</p>

<pre>
(define (inc-symbol x y) (inc (eval x) y))
(set 'y 200)
(inc-symbol 'y 123)  <span class='arw'>&rarr;</span> 246
y                    <span class='arw'>&rarr;</span> 200  ; y is still 200
</pre>		
<p>
Because the global <tt>y</tt> shares the same symbol as the function's second parameter, 
<tt>inc-symbol</tt> returns 246 (123 + 123), leaving the global <tt>y</tt> unaffected. 
Dynamic scoping's <em>variable capture</em> can be a disadvantage when passing symbol 
references to user-defined functions. newLISP offers several methods to avoid variable
capture.</p>

<ul>
<li>The function <a href="#args">args</a> can be used when passing symbols.</li>
<li>One or more user-defined functions can be placed in their own namespace called 
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.</li>
</ul>

<p>
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.
</p>
<p>
newLISP uses contexts for different forms of lexical scoping. See the 
chapters <a href="#contexts">Contexts</a> and 
<a href="#default_function">default functors</a> for more information.</p>

<br/>
<center>
<span class="divider">(&nbsp;<font color="#7ba9d4">&sect;</font>&nbsp;)</span>
</center>
<br/>

<a name="contexts"></a>
<h2>16. Contexts</h2>

<p>In newLISP, symbols can be separated into namespaces called <em>contexts</em>. 
Each context has a private symbol table 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>

<p>Contexts are used to build modules of isolated variable and function definitions. 
They also can be used to build dictionaries fo key values pairs. Contexts can be 
copied and dynamically assigned to variables or passed as arguments by reference.
Because contexts in newLISP have lexically separated namespaces, they allow programming 
with <em>lexical scoping</em> and software object styles of programming.</p>

<p>Contexts are identified by symbols that are part of the root or <tt>MAIN</tt> 
context. Although context symbols are uppercased in this chapter, lowercase symbols 
may also be used.</p>

<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 MAIN, enter the following expression after starting newLISP:</p>

<pre>
(symbols)
</pre>

<p>To see all symbols in <tt>MAIN</tt> pointing to contexts:</p>

<pre>
(filter context? (map eval (symbols)))
</pre>

<p>To seel all context symbols in <tt>MAIN</tt> when <tt>MAIN</tt> is not the
current context:</p>

<pre>
(filter context? (map eval (symbols MAIN)))
</pre>

<br/>

<a name="context_rules"></a>
<h3>Symbol creation in contexts</h3>

<p>The following rules should simplify the process of understanding contexts by 
identifying to which context the created symbols are being assigned.</p>

<ol>
<li>
<p>newLISP first parses and translates each expression starting at the top
level. All symbols are created during this phase. After the expression is 
translated, it gets evaluated.</p>
</li>

<li>
<p>A symbol is created when newLISP first <em>sees</em> it, while calling 
the <a href="#load">load</a>, <a href="#sym">sym</a>, 
or <a href="#eval-string">eval-string</a> functions. When newLISP reads 
a source file, symbols are created <em>before</em> evaluation occurs. The
<a href="#reader-event">reader-event</a> function can be used to inspect
the expression after reading and translating but before evaluation. The
<a href="#read-expr">read-expr</a> function can be used to read and translate
newLISP source without evaluation.</p>
</li>

<li>
<p>When an unknown symbol is encountered during code translation, 
a search for its definition begins inside the current context. 
Failing that, the search continues inside <tt>MAIN</tt> for a 
built-in function, context, or global symbol. If no definition 
is found, the symbol is created locally inside the current context.</p>
</li>

<li>
<p>Once a symbol is created and assigned to a specific context, 
it will belong to that context permanently or until it is deleted
using the <a href="#delete">delete</a> function.</p>
</li>

<li>
<p>When a user-defined function is evaluated, the context is switched 
to the name-space which owns that symbol.</p>
</li>

<li><p>A context switch only influences symbol creation during 
<a href="#load">load</a>, <a href="#sym">sym</a>,
or <a href="#eval-string">eval-string</a>. 
<a href="#load">load</a> by default loads into MAIN except
 when context switches occur on the top level of the file loaded. 
For better style, the context should always be specified when the functions 
<a href="#sym">sym</a> and <a href="#eval-string">eval-string</a> 
are used. A context switch should normally only be made on the top level of 
a program, never inside a function.</p>
</li>
</ol>

<br/>

<a name="creating_contexts"></a>
<h3>Creating contexts</h3>

<p>Contexts can be created either by using the <a href="#context">context</a>
function or via implicit creation. The first method is used when writing larger 
portions of code belonging to the same context:</p>

<pre>
(context 'FOO)

(set 'var 123)

(define (func x y z)
    ... )

(context MAIN)
</pre>		

<p>If the context does not exist yet, the context symbol must be quoted.
If the symbol is not quoted, newLISP assumes the symbol is a variable
holding the symbol of the context to create. Because a context evaluates
to itself, already existing contexts like MAIN do not require quoting.</p>

<p>When newLISP reads the above code, it will read, then evaluate the first
statement: <tt>(context 'FOO)</tt>. This causes newLISP to switch the namespace
to FOO and the following symbols <tt>var</tt>, <tt>x</tt>, <tt>y</tt> and <tt>z</tt>
will all be created in the FOO context when reading and evaluating the remaining
expressions.</p>

<p>A context symbol is protected against change. Once a symbol refers to a 
context, it cannot be used for any other purpose, except when using 
<a href="#delete">delete</a>.</p>

<p>To refer to <tt>var</tt> or <tt>func</tt> from anywhere else outside the 
FOO namespace, they need to be prefixed with the context name:</p>

<pre>
FOO:var <span class='arw'>&rarr;</span> 123

(FOO:func p q r)
</pre>	

<p>Note, that in the above example only <tt>func</tt> belongs to the <tt>FOO</tt>
name space the symbols <tt>p q r</tt> all are part of the current context
from which the <tt>FOO:func</tt> call is made.</p>	

<p>The <a href="#symbols">symbols</a> function is used to show all symbols
belonging to a context:</p>

<pre>
(symbols FOO) <span class='arw'>&rarr;</span> (FOO:func FOO:var FOO:x FOO:y FOO:z)

; or from inside the context symbols are shown without context prefix
(context FOO) <span class='arw'>&rarr;</span> (func x y z)
(sumbols)
</pre>		

<br/>

<b>Implicitly creating contexts</b>

<p>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:</p>

<pre>
&gt; (set 'ACTX:var "hello")
<b>"hello"</b>
&gt; ACTX:var
<b>"hello"</b>
&gt; _
</pre>		

<p>Note that only the symbols prefixed with their context name will be part
of the context:</p>

<pre>
(define (ACTX:foo x y) 
    (+ x y))
</pre>		

<p>When above code is loaded in MAIN only <tt>foo</tt> will be part of 
<tt>ACTX</tt>. The symbols <tt>x</tt> and <tt>y</tt> will still be part
of <tt>MAIN</tt>. To make all locals of <tt>ACTX:foo</tt> members of
the <tt>ACTX</tt> context, they would either have to be prefixed with
<tt>ACTX</tt>, or the whole funtion must be preceded by a context
switch satement at the top level:</p>

<pre>
(context 'ACTX)
(define (foo x y)
    (+ x y)
(context MAIN

;; above same as

(define (ACTX:foo ACTX:x ACTX:y)
    (+ ACTX:x ACTX:y))
</pre>

<br/>

<b>Loading module files</b>
<br/>

<p>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 the newLISP source
code reader in which namespace to put all of the symbols and definitions:</p>

<pre>
;;; file MY_PROG.LSP
;;
;; everything from here on goes into GRAPH
(context 'GRAPH)
				 
(define (draw-triangle x y z)
    (&hellip;))

(define (draw-circle)
    (&hellip;))
									 
;; show the runtime context, which is GRAPH
(define (foo)
    (context))
									 
;; switch back to MAIN
(context 'MAIN)
				 
;; end of file					
</pre>		

<p>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 <tt>GRAPH:</tt></p>

<pre>
(GRAPH:draw-triangle 1 2 3)
(GRAPH:foo)  <span class='arw'>&rarr;</span> GRAPH										
</pre>		

<p>The last statement shows how the runtime context has changed to 
<tt>GRAPH</tt> (function <tt>foo</tt>'s context).</p>

<p>A symbol's name and context are used when comparing symbols from different 
contexts. The <a href="#term">term</a> function can be used to extract the term 
part from a fully qualified symbol.</p>

<pre>
;; same symbol name, but in different context
(= 'A:val 'B:val)                    <span class='arw'>&rarr;</span> nil
(= (term 'A:val) (term 'B:val))      <span class='arw'>&rarr;</span> true
(= (prefix 'A:val) (prefix 'B:val))  <span class='arw'>&rarr;</span> nil
</pre>		

<p>Note: The symbols in above example are quoted with a <tt>'</tt> (single quote) 
because we are interested in the symbol itself, not in the contents of the symbol.</p>

<br/>

<a name="scope_global"></a>
<h3>Global scope</h3>

<p>By default, only built-in functions and symbols like <tt>nil</tt> and
<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:</p>

<pre>
(set 'aVar 123) <span class='arw'>&rarr;</span> 123
(global 'aVar)  <span class='arw'>&rarr;</span> aVar

(context 'FOO)  <span class='arw'>&rarr;</span> FOO

aVar            <span class='arw'>&rarr;</span> 123
</pre>		

<p>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.</p>

<p>Once it is made visible to contexts through the <a href="#global">global</a> function, 
a symbol cannot be hidden from them again.</p>

<br/>

<a name="protection"></a>
<h3>Symbol protection</h3>

<p>By using the <a href="#constant">constant</a> function, symbols can be both set 
and protected from change at the same time:</p>

<pre>
&gt; (constant 'aVar 123)  <span class='arw'>&rarr;</span> 123
&gt; (set 'aVar 999)
<span class='err'>ERR: symbol is protected in function set : aVar</span>
&gt;_
</pre>		<p>
	A symbol needing to be both a constant and a global can be defined simultaneously:
</p>
<pre>
(constant (global 'aVar) 123)
</pre>		

<p>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.</p>

<br/>

<a name="overwrite"></a>
<h3>Overwriting global symbols and built-ins</h3>

<p>Global and built-in function symbols can be overwritten inside a
context by prefixing them with their <em>own</em> context symbol:</p>

<pre>
(context 'Account)

(define (Account:new &hellip;)
    (&hellip;))

(context 'MAIN)
</pre>		

<p>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.
</p>

<br/>

<a name="context_vars"></a>
<h3>Variables containing contexts</h3>

<p>Variables can be used to refer to contexts:</p>

<pre>
(set 'FOO:x 123)

(set 'ctx FOO)    <span class='arw'>&rarr;</span> FOO

ctx:x             <span class='arw'>&rarr;</span> 123

(set 'ctx:x 999)  <span class='arw'>&rarr;</span> 999

FOO:x             <span class='arw'>&rarr;</span> 999
</pre>		

<p>
Context variables are useful when writing functions, which need to refer to
different contexts during runtime or use contexts which do not exist during
definition:</p>

<pre>
(define (update ctx val)
    (set 'ctx:sum val)
    (ctx:func 999)
)

(context 'FOO)
(define (func x)
    (println "=&gt;" x))
(context MAIN)
</pre>		

<p>The following shows a terminal session using above definitions. The program
output is shown in bold-face:</p>

<pre>
<b>&gt;</b> (update FOO 123)
<b>=&gt; 999</b>

<b>&gt;</b> FOO:sum
<b>123</b>
<b>&gt;</b>
</pre>		

<p>The same one function <tt>update</tt> can display different behavior depending
on the context passed as first parameter. </p>

<br/>

<a name="sequence_creating"></a>
<h3>Sequence of creating or loading contexts</h3>

<p>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>:</p>

<pre>
;; demo - file for loading contexts
(context 'FOO)
(set 'ABC 123)
(context MAIN)

(context 'ABC)
(set 'FOO 456)
(context 'MAIN)
</pre>		

<p>Now load the file into the newlisp shell:</p>

<pre>
&gt; (load "demo")
<span class='err'>ERR: symbol is protected in function set : FOO</span>
&gt; _
</pre>		

<p>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.</p>

<p><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>.</p>

<br/>

<a name="context_modules"></a>
<h3>Contexts as programming modules</h3>

<p>Contexts in newLISP are mainly used for partitioning source into 
modules. Because each module lives in a different namespace, modules
are lexically separated and the names of symbols cannot clash with
identical names in other modules.</p>

<p>The <a href="http://newlisp.org/code/modules/">modules</a>, which are
part of the newLISP distribution, are a good example of how to put related
 functions into a module file, and how to document modules using
 the <a href="http://newlisp.org/newLISPdoc.html">newLISPdoc</a> utility.</p> 

<p>For best programming practice, a file should only contain one module and 
the filename should be similar if not identical to the context name used:</p>

<pre>
;; file db.lsp, commonly used database functions

(context 'db)

;; Variables used throughout this namespace

(define db:handle)
(define db:host "http://localhost")

;; Constants

(constant 'Max_N 1000000)
(constant 'Path "/usr/data/")

;; Functions

(define (db:open ... )
    ... )

(define (db:close ... )
    ... )

(define (db:update ... )
    ... )
</pre>


<p>The example shows a good practice of predefining variables, which are global
inside the namespace, and defining as constants the variables that will not change.</p>

<p>If a file must contain more than one context, then the end of the context
should be marked with a switch back to <tt>MAIN</tt>:</p>

<pre>
;; Multi context file multi.lsp

(context 'A-ctx)
...
(context MAIN)

(context 'B-ctx)
...
(context MAIN)

(context 'C-ctx)
...
(context MAIN)
</pre>

<p>In any case <a href="#load">load</a> will always switch back to the context
from where it was called.</p>

<br/>

<a name="context_data"></a>
<h3>Contexts as data containers</h3>

<p>Contexts are frequently uses as data containers, e.g. for configuration data:</p>

<pre>
;; Config.lsp - configuration setup

(context 'Config)

(set 'user-name "admin")
(set 'password "secret")
(set 'db-name "/usr/data/db.lsp")
...

;; eof
</pre>

<p>Loading the <tt>Config</tt> namespace will now load a whole variable set into
memory at once:</p>

<pre>
(load "Config.lsp")

(set 'file (open Config:db-name "read"))
...
...
</pre>

<p>In a similar fashion a whole data set can be saved:</p>

<pre>
(save "Config.lsp" 'Config)
</pre>

<p>Read more about this in the section <a href="#serializing">Serializing contexts</a>.</p>

<br/>

<a name="loading_contexts"></a>
<h3>Loading and declaring contexts</h3>

<p>Module files are loaded using the <a href="#load">load</a> function.
If a programming project contains numerous modules that refer
to each other, they can be pre-declared to avoid problems due to context forward 
references that can occur before the loading of that context.</p>

<pre>
;; pre-declaring contexts, finish with Main to return
(map context '(Utilities Config Acquisition Analysis SysLog MAIN))

;; loading context module files
(load "Utilities.lsp" "Acquisition.lsp")
(load "http://192.168.1.34/Config.lsp") ; load module from remote location
(load "Analysis.lsp" "SysLog.lsp")

(define (run)
    ... )

(run)

;; end of file </pre>

<p>When pre-declaring and loading modules as shown in the example, the sequence
of declaration or loading can be neglected. All forward references to variables
and definitions in modules not loaded yet will be translated correctly. Wrong
usage of a context symbol will result in an error message before that context
is loaded.</p>

<p>Modules not starting with a context switch are always loaded into <tt>MAIN</tt>
except when the <a href="#load">load</a> statement specifies a target context
as the last parameter. The <a href="#load">load</a> function can take <tt>URL</tt>s
to load modules from remote locations, via <tt>HTTP</tt>.</p>

<p>The current context after the <a href="#load">load</a> statement will always be 
the same as before the <a href="#load">load</a>.</p>

<br/>

<a name="serializing"></a>
<h3>Serializing contexts</h3>

<p>Serialization makes a software object <em>persistent</em>
by converting it into a character stream,
which is then saved to a file or string in memory.
In newLISP, anything referenced by a symbol can be serialized to a file
by using the <a href="#save">save</a> function.
Like other symbols, contexts are saved just by using their names:
</p>

<pre>
(save "mycontext.lsp" 'MyCtx)              ; save MyCtx to mycontext.lsp

(load "mycontext.lsp")                     ; loads MyCtx into memory

(save "mycontexts.lsp" 'Ctx1 'Ctx2 'Ctx3)  ; save multiple contexts at once
</pre>		

<p>
For details, see the functions <a href="#save">save</a> (mentioned above)
and <a href="#source">source</a> (for serializing to a newLISP string).
</p>

<br/>		
<center>
<span class="divider">(&nbsp;<font color="#7ba9d4">&sect;</font>&nbsp;)</span>
</center>

<br/>

<a name="default_function"></a>
<h2>17. The context default functor</h2>

<p>A <em>default functor</em> or <em>default function</em>
is a symbol or user-defined function or macro
with the same name as its namespace. When the context is used
as the name of a function or in the functor position of an s-expression,
newLISP executes the default function.</p>

<pre>
;; the default function

(define (Foo:Foo a b c) (+ a b c))

(Foo 1 2 3)  <span class='arw'>&rarr;</span> 6
</pre>

<p>If a default function is called from a context other than <tt>MAIN</tt>,
the context must already exist or be declared with a <em>forward declaration</em>,
which creates the context and the function symbol:</p>

<pre>
;; forward declaration of a default function
(define Fubar:Fubar)    

(context 'Foo)
(define (Foo:Foo a b c)
    &hellip;
    (Fubar a b)         ; forward reference
    (&hellip;))         ; to default function

(context MAIN)

;; definition of previously declared default function

(context 'Fubar)
(define (Fubar:Fubar x y)
    (&hellip;))

(context MAIN)
</pre>		

<p>Default functions work like global functions,
but they are lexically separate from the context in which they are called.</p>

<p>Like a lambda or lambda-macro function, default functions can be used 
with <a href="#map">map</a> or <a href="#apply">apply</a>.
</p>

<br/>

<a name="func_memory"></a>
<h3>Functions with memory</h3>

<p>A default function  can update the lexically isolated static variables
contained inside its namespace:</p>

<pre>
;; a function with memory

(define (Gen:Gen x)
    (if Gen:acc
        (inc Gen:acc x)
        (setq Gen:acc x)))

(Gen 1)  <span class='arw'>&rarr;</span> 1
(Gen 1)  <span class='arw'>&rarr;</span> 2
(Gen 2)  <span class='arw'>&rarr;</span> 4
(Gen 3)  <span class='arw'>&rarr;</span> 7

gen:acc  <span class='arw'>&rarr;</span> 7
</pre>		

<p>The first time the <tt>Gen</tt> function is called,
its accumulator is set to the value of the argument.
Each successive call increments <tt>Gen</tt>'s accumulator
by the argument's value.</p>

<p>The definition of <tt>Gen:Gen</tt> shows, how a function is put in its own namespace 
without using the surrounding <tt>(context 'Gen)</tt> and <tt>(context MAIN)</tt> 
statements. In that case only symbols qualified by the namespace prefix will 
end up in the <tt>Gen</tt> context. In the above example the variable 
<tt>x</tt> is still part of <tt>MAIN</tt>.</p>

<br/>

<a name="hash"></a>
<h3>Hash functions and dictionaries</h3>

<p>There are several functions that can be used to place symbols into namespace contexts. 
When using dictionaries as simple hash-like collections of variable &rarr; value pairs, use the 
uninitialized <a href="#default_function">default functor</a>:</p>

<pre>
(define Myhash:Myhash) ; create namespace and default functor

; or as a safer alternative

(new Tree 'Myhash) ; create from built-in template
</pre>		

<p>Either method can be used to make the  <tt>MyHash</tt> dictionary space and default
functor. The second method is safer, as it will protect the default functor 
<tt>MyHash:MyHash</tt> from change. The <em>default functor</em> in a namespace must 
contain <tt>nil</tt> to be used as a dictionary. The string used for the symbol name
is limited to 1022 characters and internally an underscore is prepended to the symbol
name used in the context. Creating key-value pairs and retrieving 
a value is easy:</p>

<pre>
(Myhash "var" 123) ; create and set variable/value pair

(Myhash "var")  <span class='arw'>&rarr;</span> 123 ; retrieve value

; keys can be integers and will be converted to strings internally

(Myhash 456 "hello")

(Myhash 456)    <span class='arw'>&rarr;</span> "hello"

; internally an underscore is prepended to the symbol name

(symbols Myhash)  <span class='arw'>&rarr;</span> (Myhash:Myhash Myhash:_456 Myhash:_var)
</pre>		

<p>Symbol variables created this way can contain spaces or other characters
normally not allowed in newLISP symbol names:</p>

<pre>
(define Foo:Foo)
; or to protect the default functor from change
; (new Tree 'Foo)

(Foo "John Doe" 123)         <span class='arw'>&rarr;</span> 123
(Foo "#1234" "hello world")  <span class='arw'>&rarr;</span> "hello world"
(Foo "var" '(a b c d))       <span class='arw'>&rarr;</span> (a b c d)

(Foo "John Doe")  <span class='arw'>&rarr;</span> 123
(Foo "#1234")     <span class='arw'>&rarr;</span> "hello world"
(Foo "var")     <span class='arw'>&rarr;</span> (a b c d)
</pre>		

<p>An entry which doesn't exist will return <tt>nil</tt>:</p>

<pre>
(Foo "bar")    <span class='arw'>&rarr;</span> nil
</pre>		

<p>Setting an entry to <tt>nil</tt> will effectively delete it from
the namespace.</p>

<p>An association list can be generated from the contents of the namespace:</p>

<pre>
(Foo) <span class='arw'>&rarr;</span> (("#1234" "hello world") ("John Doe" 123) ("var" (a b c d)))
</pre>		

<p>Entries in the dictionary can also be created from a list:</p>

<pre>
(Foo '(("#1234" "hello world") ("John Doe" 123) ("var" (a b c d))) <span class='arw'>&rarr;</span> Foo
</pre>		

<p>The list can also be used to iterate through the sorted key -&gt; value pairs:</p>

<pre>
(dolist (item (Foo)) (println (item 0) " -&gt; " (item 1)))

<b>#1234 -&gt; hello world
John Doe -&gt; 123
var -&gt; (a b c d)</b>
</pre>

<p>Like many built-in functions hash expressions return a reference to their content which 
can be modified directly:</p>

<pre>
(pop (Foo "var")) <span class='arw'>&rarr;</span> a

(Foo "var") <span class='arw'>&rarr;</span> (b c d)

(push 'z (Foo "var")) <span class='arw'>&rarr;</span> (z b c d)

(Foo "var") <span class='arw'>&rarr;</span> (z b c d)
</pre>

<p>When setting hash values the anaphoric system variable <tt>$it</tt>
can be used to refer to the old value when setting the new:</p>

<pre>
(Foo "bar" "hello world")

(Foo "bar" (upper-case $it))

(Foo "bar") <span class='arw'>&rarr;</span> "HELLO WORLD"
</pre>

<p>Hash values also can be modified using <a href="#setf">setf</a>:</p>

<pre>
(Foo "bar" 123)        <span class='arw'>&rarr;</span> 123

(setf (Foo "bar") 456) <span class='arw'>&rarr;</span> 456

(Foo "bar")            <span class='arw'>&rarr;</span> 456
</pre>

<p>But supplying the value as a second parameter to the hash functions 
is shorter to write and faster.</p>

<p>Dictionaries can easily be saved to a file and reloaded later:</p>

<pre>
; save dictionary
(save "Foo.lsp" 'Foo)

; load dictionary
(load "Foo.lsp")
</pre>	

<p>Internally the key strings are created and stored as symbols in the
hash context. All key strings are prepended with an <tt>_</tt> 
underscore character.  This protects against overwriting the default symbol and
symbols like <tt>set</tt> and <tt>sym</tt>, which are needed when loading
a hash namespace from disk or over <tt>HTTP</tt>. Note the following
difference:</p>

<pre>
(Foo) <span class='arw'>&rarr;</span> (("#1234" "hello world") ("John Doe" 123) ("var" (a b c d)))

(symbols Foo) <span class='arw'>&rarr;</span> (Foo:Foo Foo:_#1234 Foo:_John Doe Foo:_var)
</pre>	

<p>In the first line hash symbols are shown as strings without the preceding
underscore characters. The second line shows the internal form of the symbols with
prepended underscore characters.</p>


<p>For a more detailed introduction to <em>namespaces</em>, see the chapter on
<a href="#contexts">Contexts</a>.
</p>

<br/>

<a name="pass_big"></a>
<h3>Passing data by reference</h3>

<p>A <a href="#default_function">default functor</a> can also be used to hold data. 
If this data contains a list or string, the context name can be used as a reference to 
the data:</p>

<pre>
;; the default functor for holding data

(define Mylist:Mylist '(a b c d e f g))

(Mylist 3) <span class='arw'>&rarr;</span> d 

(setf (Mylist 3) 'D) <span class='arw'>&rarr;</span> D

Mylist:Mylist <span class='arw'>&rarr;</span> (a b c D e f g)

;; access list or string data from a default functor

(first Mylist) <span class='arw'>&rarr;</span> a

(reverse Mylist) <span class='arw'>&rarr;</span> (g f e D c b a)

(set 'Str:Str "acdefghijklmnop") 

(upper-case Str) <span class='arw'>&rarr;</span> "ACDEFGHIJKLMNOP"
</pre>

<p>Most of the time, newLISP passes parameters by <em>value copy</em>.
This poses a potential problem when passing large lists or strings
to user-defined functions or macros. Strings and lists, which are packed 
in a namespace using default functors, are passed automatically by reference:
</p>

<pre>
;; use a default functor to hold a list

(set 'Mydb:Mydb (sequence 1 100000))

(define (change-db obj idx value)
    (setf (obj idx) value))

; pass by context reference
(change-db Mydb 1234 "abcdefg")

(Mydb 1234)  <span class='arw'>&rarr;</span> "abcdefg"
</pre>		

<p> Any argument of a built-in function calling for either a list or a string 
&mdash; but no other data type &mdash; can receive data passed by reference. 
Any user-defined function can take either normal variables, or can take a context 
name for passing a reference to the default functor containing a list or string.</p>

<p>Note that on lists with less than about 100 elements or strings of less than 
about 50000 characters, the speed difference between reference and value passing is 
negligible. But on bigger data objects, differences in both speed and memory usage 
between reference and value passing can be significant.</p>

<p>Built-in and user-defined functions are suitable for <u>both</u> types of arguments, 
but when passing context names, data will be passed by reference.</p>

<p>Quoted symbols can also be used to pass data by reference, but this method
has disadvantages:</p>

<pre>
(define (change-list aList) (push 999 (eval aList)))

(set 'data '(1 2 3 4 5))

; note the quote ' in front of data
(change-list 'data)  <span class='arw'>&rarr;</span> (999 1 2 3 4 5)

data  <span class='arw'>&rarr;</span>  (999 1 2 3 4 5)
</pre>

<p>Although this method is simple to understand and use, it poses the potential 
problem of <em>variable capture</em> when passing the same symbol as used  
as a function parameter:</p>

<pre>
;; pass data by symbol reference

&gt; (set 'aList '(a b c d))
(a b c d)
&gt; (change-list 'aList)

<span class='err'>ERR: list or string expected : (eval aList)
called from user defined function change-list</span>
&gt; 
</pre>

<p>At the beginning of the chapter it was shown how to package data 
in a name-space using a default functor. Not only the default 
functor but any symbol in  context can be used to hold data. The 
disadvantage is that the calling function must have knowledge about
the symbol being used:</p>

<pre>
;; pass data by context reference

(set 'Mydb:data (sequence 1 100000))

(define (change-db obj idx value)
    (setf (obj:data idx) value))

(change-db Mydb 1234 "abcdefg")

(nth 1234 Mydb:data)   <span class='arw'>&rarr;</span> "abcdefg"
; or
(Mydb:data 1234)   <span class='arw'>&rarr;</span> "abcdefg"
</pre>

<p>
The function receives the namespace in the variable <tt>obj</tt>,
but it must have the knowledge that the list to access is contained
in the <tt>data</tt> symbol of that namespace (context).</p>

<br/>

<center>
<span class="divider">(&nbsp;<font color="#7ba9d4">&sect;</font>&nbsp;)</span>
</center>

<br/>

<a name="foop"></a>
<h2>18. Functional object-oriented programming</h2>

<p>Functional-object oriented programming (FOOP) is based on the following 
five principles:</p>

<ul>
<li><p>Class attributes and methods are stored in the namespace of the object class.</p></li>
<li><p>The namespace default functor holds the object constructor method.</p></li>
<li><p>An object is constructed using a list, the first element of which is the 
context symbol describing the class of the object.</p></li>
<li><p>Polymorphism is implemented using the <a href="#colon"><tt>:</tt> (colon)</a>
operator, which selects the appropriate class from the object.</p></li>
<li><p>A target object inside a class-method function is accessed via the <a href="#self">self</a>
function.</p></li>
</ul>

<p>The following paragraphs are a short introduction to FOOP as designed by 
<em>Michael Michaels</em> from <a href="http://neglook.com">neglook.com</a>.</p>


<br/>

<a name="newlisp_classes"></a>
<h3>FOOP classes and constructors</h3>

<p>Class attributes and methods are stored in the namespace of the object class. 
No object instance data is stored in this namespace/context. Data variables in
the class namespace only describe the class of objects as a whole but don't contain
any object specific information. A generic FOOP object constructor can be used
as a template for specific object constructors when creating new object classes
with <tt>new</tt>:</p>

<pre>
; built-in generic FOOP object constructor
(define (Class:Class) 
    (cons (context) (args)))

; create some new classes

(new Class 'Rectangle)   <span class='arw'>&rarr;</span> Rectangle
(new Class 'Circle)      <span class='arw'>&rarr;</span> Circle

; create some objects using the default constructor

(set 'rect (Rectangle 10 20))   <span class='arw'>&rarr;</span> (Rectangle 10 20)
(set 'circ (Circle 10 10 20))   <span class='arw'>&rarr;</span> (Circle 10 10 20)

; create a list of objects
; building the list using the list function instead of assigning
; a quoted list ensures that the object constructors are executed

(set 'shapes (list (Circle 5 8 12) (Rectangle 4 8) (Circle 7 7 15)))
<span class='arw'>&rarr;</span> ((Circle 5 8 12) (Rectangle 4 8) (Circle 7 7 15))
</pre>

<p>The generic FOOP constructor is already pre-defined, and FOOP
code can start with <tt>(new Class ...)</tt> statements right away.</p>

<p>As a matter of style, new classes should only be created in the MAIN context. 
If creating a new class while in a different namespace, the new class name 
must be prefixed with MAIN and the statement should be on the top-level:</p>

<pre>
(context 'Geometry)

(new Class 'MAIN:Rectangle)
(new Class 'MAIN:Circle)

...
</pre>

<p>Creating the namespace classes using <a href="#new">new</a> reserves the class 
name as a context in newLISP and facilitates forward references. At the same time, 
a simple constructor is defined for the new class for instantiating new objects. 
As a convention, it is recommended to start class names in upper-case to signal that 
the name stands for a namespace.</p>

<p>In some cases, it may be useful to overwrite the simple constructor, that was 
created during class creation, with <tt>new</tt>:</p>

<pre>
; overwrite simple constructor 
(define (Circle:Circle x y radius)
    (list Circle x y radius))
</pre>

<p>A constructor can also specify defaults:</p>

<pre>
; constructor with defaults
(define (Circle:Circle (x 10) (y 10) (radius 3))
    (list Circle x y radius))

(Circle) <span class='arw'>&rarr;</span> (Circle 10 10 3)
</pre>

<p>In many cases the constructor as created when using <tt>new</tt> is sufficient and overwriting
it is not necessary.</p>

<br/>

<a name="newlisp_objects"></a>
<h3>Objects and associations</h3>

<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 constructors defined previously:</p>

<pre>
(set 'myrect (Rectangle 5 5 10 20)) <span class='arw'>&rarr;</span> (Rectangle 5 5 10 20)
(set 'mycircle (Circle 1 2 10)) <span class='arw'>&rarr;</span> (Circle 1 2 10)
</pre>

<p>An object created is identical to the function necessary to create it (hence FOOP). 
Nested objects can be created in a similar manner:</p>

<pre>
; create classes
(new Class 'Person)
(new Class 'Address)
(new Class 'City)
(new Class 'Street)

; create an object containing other objects
(set 'JohnDoe (Person (Address (City "Boston") (Street 123 "Main Street"))))
<span class='arw'>&rarr;</span> (Person (Address (City "Boston") (Street 123 "Main Street")))
</pre>

<p>Objects in FOOP not only resemble functions they also resemble associations. The
<a href="#assoc">assoc</a> function can be used to access object data by name:</p>

<pre>
(assoc Address JohnDoe) <span class='arw'>&rarr;</span> (Address (City "Boston") (Street 123 "Main Street"))

(assoc (list Address Street) JohnDoe) <span class='arw'>&rarr;</span> (Street 123 "Main Street")
</pre>

<p>In a similar manner <a href="#setf">setf</a> together with <a href="#assoc">assoc</a> 
can be used to modify object data:</p>

<pre>
(setf (assoc (list Address Street) JohnDoe) '(Street 456 "Main Street"))
<span class='arw'>&rarr;</span> (Street 456 "Main Street")
</pre>

<p>The street number has been changed from <tt>123</tt> to <tt>456</tt>.</p>

<p>Note that in none of the <tt>assoc</tt> statements <tt>Address</tt> and <tt>Street</tt>
need to carry quotes. The same is true in the set statement: 
<tt>(set 'JohnDoe (Person ...))</tt> for the data part assigned. In both cases we do not 
deal with symbols or lists of symbols but rather with contexts and FOOP objects which 
evaluate to themselves. Quoting would not make a difference.</p>

<br/>

<a name="colon_operator"></a>
<h3>The colon <tt>:</tt> operator and polymorphism</h3>

<p>In newLISP, the colon character <tt>:</tt> is primarily used to
connect the context symbol with the symbol it is qualifying. 
Secondly, the colon function is used in FOOP to resolve a function's 
application <em>polymorphously</em>.</p>

<p>The following code defines two functions called <tt>area</tt>, 
each belonging to a different namespace / class. Both functions could
have been defined in different modules for better separation, but in 
this case they are defined in the same file and without bracketing 
<a href="#context">context</a> statements. Here, only
the symbols <tt>rectangle:area</tt> and <tt>circle:area</tt> belong
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>,
but this is of no concern.</p>

<pre>
;; class methods for rectangles

(define (Rectangle:area)
    (mul (self 3) (self 4)))

(define (Rectangle:move dx dy)
    (inc (self 1) dx) 
    (inc (self 2) dy))

;; class methods for circles

(define (Circle:area)
    (mul (pow (self 3) 2) (acos 0) 2))

(define (Circle:move dx dy)
    (inc (self 1) dx) 
    (inc (self 2) dy))
</pre>

<p>By prefixing the <tt>area</tt> or <tt>move</tt> symbol with the
<a href="#colon"><tt>:</tt> (colon)</a>, 
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> 

<pre>
(:area myrect) <span class='arw'>&rarr;</span> 200 ; same as (: area myrect)
(:area mycircle) <span class='arw'>&rarr;</span> 314.1592654 ; same as (: area mycircle)

;; map class methods uses curry to enclose the colon operator and class function

(map (curry :area) (list myrect mycircle)) <span class='arw'>&rarr;</span> (200 314.1592654)

(map (curry :area) '((Rectangle 5 5 10 20) (Circle 1 2 10))) <span class='arw'>&rarr;</span> (200 314.1592654) 


;; objects are mutable (since v10.1.8)

(:move myrect 2 3)
(:move mycircle 4 5) 

myrect    <span class='arw'>&rarr;</span> (Rectangle 7 8 10 20)
mycircle  <span class='arw'>&rarr;</span> (Circle 5 7 10)
</pre>

<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>

<p>Note, that although the caller specifies the called target object of the call,
the method definition does not include the object as a parameter. When writing 
functions to modify FOOP objects, instead the function <a href="#self">self</a>
is used to access and index the object.</p>

<br/>
<a name="structure_foop"></a>
<h3>Structuring a larger FOOP program</h3>

<p>In all the previous examples, class function methods where directly
written into the MAIN context namespace. This works and is adequate 
for smaller programs written by just one programmer. When writing larger 
systems, all the methods for one class should be surrounded by 
<a href="#context">context</a> statements to provide better isolation 
of parameter variables used and to create an isolated location for potential
class variables.</p>

<p>Class variables could be used in this example as a container for
lists of objects, counters or other information specific to a class
but not to a specific object. The following code segment rewrites the 
example from above in this fashion.</p>

<p>Each context / namespace could go into an extra file with the same
name as the class contained. Class creation, startup code and the main
control code is in a file <tt>MAIN.lsp</tt>:</p>

<pre>
; file MAIN.lsp - declare all classes used in MAIN

(new Class 'Rectangle)
(new Class 'Circle)

; start up code

(load "Rectangle.lsp")
(load "Circle.lsp")

; main control code

; end of file
</pre>

<p>Each class is in a separate file:</p>

<pre>
; file Rectangle.lsp - class methods for rectangles

(context Rectangle)

(define (Rectangle:area)
(mul (self 3) (self 4)))

(define (Rectangle:move dx dy)
(inc (self 1) dx) 
(inc (self 2) dy))

; end of file
</pre>

<p>And the <tt>Circle</tt> class file follows:</p>

<pre>
; file Circle.lsp - class methods for circles

(context Circle)

(define (Circle:area)
    (mul (pow (self 3) 2) (acos 0) 2))

(define (Circle:move dx dy)
    (inc (self 1) dx) 
    (inc (self 2) dy))

; end of file
</pre>

<p>All sets of class functions are now lexically separated
from each other.</p>

<br/>
<center>
<span class="divider">(&nbsp;<font color="#7ba9d4">&sect;</font>&nbsp;)</span>
</center>
<br/>


<a name="multi_processing"></a>
<h2>19. Concurrent processing and distributed computing</h2>

<p>newLISP has high-level APIs to control multiple processes on the same
CPU or distributed onto different computer nodes on a TCP/IP network.</p>

<br/>

<a name="cilk"></a>
<h3>Cilk API</h3>

<p>newLISP implements a <a href="http://supertech.csail.mit.edu/cilk/">Cilk</a>-
like API to launch and control concurrent processes. The API can take advantage of 
multi-core computer architectures. Only three functions, <a href="#spawn">spawn</a>, 
<a href="#sync">sync</a> and <a href="#abort">abort</a>, are necessary to start
multiple processes and collect the results in a synchronized fashion. The underlying
operating system distributes processes onto different cores inside the CPU or
executes them on the same core in parallel if there are not enough cores present.
Note that newLISP only implements the API; optimized scheduling
of spawned procedures is not performed as in Cilk. Functions are started in the order
they appear in <tt>spawn</tt> statements and are distributed and scheduled onto 
different cores in the CPU by the operating system.</p>

<p>When multiple cores are present, this can increase overall processing speed
by evaluating functions in parallel. But even when running on single core CPUs,
the Cilk API makes concurrent processing much easier for the programmer and
may speed up processing if subtasks include waiting for I/O or sleeping.</p>

<p>Since version 10.1 <a href="#send">send</a> and <a href="#receive">receive</a>
message functions are available for communications between parent and child 
processes. The functions can be used in blocking and non blocking communications 
and can transfer any kind of newLISP data or expressions. Transmitted expressions 
can be evaluated in the recipients environment.</p>

<p>Internally, newLISP uses the lower level <a href="#fork">fork</a>,
<a href="#wait-pid">wait-pid</a>, <a href="#destroy">destroy</a>, and 
<a href="#share">share</a> functionalities to control processes and synchronize
the passing of computed results via a shared memory interface.</p>

<p>Only on macOS and other Unixes will the Cilk API parallelize tasks.
On MS Windows, the API is not available.</p>

<br/>

<a name="distributed"></a>
<h3>Distributed network computing</h3>

<p>With only one function, <a href="#net-eval">net-eval</a>, newLISP implements
distributed computing. Using <tt>net-eval</tt>, different tasks can be mapped
and evaluated on different nodes running on a TCP/IP network or local domain Unix sockets
network when running on the same computer. <tt>net-eval</tt> does all the housekeeping 
required to connect to remote nodes, transfer functions to execute, and
collect the results. <tt>net-eval</tt> can also use a call-back function to
further structure consolidation of incoming results from remote nodes.</p>

<p>The functions <a href="#read-file">read-file</a>, <a href="#write-file">write-file</a>,  
<a href="#append-file">append-file</a> and <a href="#delete-file">delete-file</a> all can 
take URLs instead of path-file names. Server side newLISP running in demon mode or an other 
HTTP server like Apache, receive standard HTTP requests and translate them into the 
corresponding actions on files.</p>

<br/>
<center>
<span class="divider">(&nbsp;<font color="#7ba9d4">&sect;</font>&nbsp;)</span>
</center>

<br/>
<a name="JSON_XML"></a>
<h2>20. JSON, XML, S-XML, and XML-RPC</h2> 
<b>JSON support</b>
<p>JSON-encoded data can be parsed into S-expressions using the 
<a href="#json-parse">json-parse</a> function. Error information for
failed JSON translations can be retrieved using <a href="#json-error">json-error</a>.</p>

<p>For a description of the JSON format (<u>J</u>ava<u>S</u>cript <u>O</u>bject <u>N</u>otation)
consult <a href="http://json.org">json.org</a>.
Examples for correct formatted JSON text can be seen at 
<a href="http://json.org/examples.html">json.org/examples.html</a>.</p>

<p>To retrieve data in nested lists resulting from JSON translation, use the
<a href="#assoc">assoc</a>, <a href="#lookup">lookup</a> and <a href="#ref">ref</a>
functions.</p>

<p>See the description of <a href="#json-parse">json-parse</a> for a complete example
of parsing and processing JSON data.</p>

<b>XML support</b>
<p>newLISP's built-in support for XML-encoded data or documents
comprises three functions:
<a href="#xml-parse">xml-parse</a>,
<a href="#xml-type-tags">xml-type-tags</a>, and <a href="#xml-error">xml-error</a>.
</p>

<p>
Use the <a href="#xml-parse">xml-parse</a> function
to parse XML-encoded strings.
When <tt>xml-parse</tt> encounters an error,
<tt>nil</tt> is returned.
To diagnose syntax errors caused by incorrectly formatted XML,
use the function <a href="#xml-error">xml-error</a>.
The <a href="#xml-type-tags">xml-type-tags</a> function can be used
to control or suppress the appearance of XML type tags.
These tags classify XML into one of four categories:
text, raw string data, comments, and element data.</p>


<b>XML source:</b>
<pre>
&lt;?xml version="1.0"?&gt;
&lt;DATABASE name="example.xml"&gt;
&lt;!--This is a database of fruits--&gt;
&lt;FRUIT&gt;
&lt;NAME&gt;apple&lt;/NAME&gt;
&lt;COLOR&gt;red&lt;/COLOR&gt;
&lt;PRICE&gt;0.80&lt;/PRICE&gt;
&lt;/FRUIT&gt;
&lt;/DATABASE&gt;
</pre>		<br/>
<b>Parsing without options:</b>
<pre>
(xml-parse (read-file "example.xml"))
<span class='arw'>&rarr;</span>  (("ELEMENT" "DATABASE" (("name" "example.xml")) (("TEXT" "\r\n")
("COMMENT" "This is a database of fruits")
("TEXT" "\r\n        ")
("ELEMENT" "FRUIT" () (
	("TEXT" "\r\n\t        ")
	("ELEMENT" "NAME" () (("TEXT" "apple")))
	("TEXT" "\r\n\t\t")
	("ELEMENT" "COLOR" () (("TEXT" "red")))
	("TEXT" "\r\n\t\t")
	("ELEMENT" "PRICE" () (("TEXT" "0.80")))
	("TEXT" "\r\n\t")))
("TEXT" "\r\n"))))
</pre>		<p>
	S-XML can be generated directly from XML
	using <a href="#xml-type-tags">xml-type-tags</a>
	and the special option parameters
	of the <a href="#xml-parse">xml-parse</a> function:
</p>
<br/>
<b>S-XML generation using all options:</b>
<pre>
(xml-type-tags nil nil nil nil)
(xml-parse (read-file "example.xml") (+ 1 2 4 8 16))
<span class='arw'>&rarr;</span>  ((DATABASE (@ (name "example.xml"))
  (FRUIT (NAME "apple")
	  (COLOR "red")
	  (PRICE "0.80"))))
	
</pre>
<p>S-XML is XML reformatted as newLISP <em>S-expressions</em>.
The <tt>@</tt> (at symbol) denotes an XML attribute specification.</p>

<p>To retrieve data in nested lists resulting from S-XML translation, use the
<a href="#assoc">assoc</a>, <a href="#lookup">lookup</a> and <a href="#ref">ref</a>
functions.</p>

<p>See <a href="#xml-parse">xml-parse</a> in the reference section of the manual
for details on parsing and option numbers, as well as for a longer example.</p>

<br/>
<b>XML-RPC</b>
<br/>
<p>
	The remote procedure calling protocol XML-RPC uses
	HTTP post requests as a transport and
	XML for the encoding of method names, parameters, and parameter types.
	XML-RPC client libraries and servers have been implemented
	for most popular compiled and scripting languages.
</p>
<p>
	For more information about XML,
	visit <a href="http://www.xmlrpc.com/">www.xmlrpc.com</a>.
</p>
<p>
	XML-RPC clients and servers are easy to write
	using newLISP's built-in network and XML support.
	A stateless XML-RPC server implemented as a CGI service
	can be found in the file <tt>examples/xmlrpc.cgi</tt>. This
	script can be used together with a web server, like Apache.
	This XML-RPC service script implements
	the following methods:
</p>

<table  width="98%" summary="XMPRPC methods for newLISP server">
<tr align="left"><th>method</th><th>description</th></tr>
<tr>
<td><tt>system.listMethods</tt></td>
<td>Returns a list of all method names</td>
</tr>
<tr>
<td><tt>system.methodHelp</tt></td>
<td>Returns help for a specific method</td>
</tr>
<tr>
<td><tt>system.methodSignature</tt></td>
<td>Returns a list of return/calling signatures for a specific method </td>
</tr>
<tr>
<td><tt>newLISP.evalString</tt></td>
<td>Evaluates a Base64 newLISP expression string</td></tr>
</table><br/>

<p>
The first three methods are <em>discovery</em> methods implemented by most XML-RPC servers.
The last one is specific to the newLISP XML-RPC server script and
implements remote evaluation of a Base64-encoded string of newLISP source code.
newLISP's <a href="#base64-enc">base64-enc</a> and <a href="#base64-dec">base64-dec</a> functions
can be used to encode and decode Base64-encoded information.
</p>

<p>
In the <tt>modules</tt> directory of the source distribution,
the file <tt>xmlrpc-client.lsp</tt> implements a specific client interface for
all of the above methods.</p>

<pre>
(load "xmlrpc-client.lsp")  ; load XML-RPC client routines						 

(XMLRPC:newLISP.evalString
"http://localhost:8080/xmlrpc.cgi"
"(+ 3 4)")  <span class='arw'>&rarr;</span> "7"
</pre>		<p>
	In a similar fashion,
	standard <tt>system.xxx</tt> calls can be issued.
</p>
<p>
All functions return either a result if successful, or <tt>nil</tt> if a request fails.
In case of failure, the expression <tt>(XMLRPC:error)</tt> can be evaluated
to return an error message.</p>

<p>
For more information, please consult the header of the file <tt>modules/xmlrpc-client.lsp</tt>.
</p>

<br/>
<center>
<span class="divider">(&nbsp;<font color="#7ba9d4">&sect;</font>&nbsp;)</span>
</center>
<br/>

<a name="internationalization"></a>
<h2>21. Customization, localization, and UTF-8</h2>

<a name="naming"></a>
<h3>Customizing function names</h3>

<p>All built-in primitives in newLISP can be easily renamed:</p>

<pre>
(constant 'plus +)
</pre>		<p>
	Now, <tt>plus</tt> is functionally equivalent to <tt>+</tt>
	and runs at the same speed.
</p>
<p>
	The <a href="#constant">constant</a> function,
	rather than the <tt>set</tt> function,
	must be used to rename built-in primitive symbols.
	By default, all built-in function symbols
	are protected against accidental overwriting.
</p>

<p>
It is possible to redefine all integer arithmetic operators to their floating
point equivalents:
</p>

<pre>
(constant '+ add)
(constant '- sub)
(constant '* mul)
(constant '/ div)
</pre>		

<p>All operations using <tt>+</tt>, <tt>-</tt>, <tt>*</tt>, and <tt>/</tt>
are now performed as floating point operations.</p>

<p>Using the same mechanism, the names of built-in functions
can be translated into languages other than English:</p>

<pre>
(constant 'wurzel sqrt)    ; German for 'square-root'

; make the new symbol global at the same time
(constant (global 'imprime) print)  ; Spanish for 'print'
&hellip;
</pre>		

<p>The new symbol can be made global at the same time using <a href="#global">global</a>.</p>

<br/>

<a name="switching"></a>
<h3>Switching the locale</h3>

<p>newLISP can switch locales based on the platform and operating system.
On startup, non-UTF-8 enabled newLISP attempts to set the ISO C standard 
default POSIX locale, available for most platforms and locales.  On UTF-8
enabled newLISP the default locale for the platform is set. The 
<a href="#set-locale">set-locale</a> function can also be used to switch 
to the default locale:</p>
<pre>
(set-locale "")
</pre>		
<p>
This switches to the default locale used on your platform/operating system
and ensures character handling (e.g., <a href="#upper-case">upper-case</a>)
works correctly.</p>

<p>Many Unix systems have
a variety of locales available. To find out which ones are available on
a particular Linux/Unix/BSD system, execute the following command
in a system shell:</p>

<pre>
locale -a
</pre>		

<p>
This command prints a list of all the locales available on your system.
Any of these may be used as arguments to <a href="#set-locale">set-locale</a>:</p>

<pre>
(set-locale "es_US")
</pre>		<p>
	This would switch to a U.S. Spanish locale.
	Accents or other characters
	used in a U.S. Spanish environment
	would be correctly converted.
</p>
<p>
	See the manual description for more details
	on the usage of <a href="#set-locale">set-locale</a>.
</p>

<br/>

<a name="decimal_point"></a>
<h3>Decimal point and decimal comma</h3>

<p>Many countries use a comma instead of a period
as a decimal separator in numbers.
newLISP correctly parses numbers
depending on the locale set:</p>

<pre>
; switch to German locale on a Linux  or OSX system
(set-locale "de_DE") <span class='arw'>&rarr;</span> ("de_DE" ",")

; newLISP source and output use a decimal comma
(div 1,2 3)  <span class='arw'>&rarr;</span> 0,4
</pre>		

<p>The default POSIX C locale, which is set when newLISP starts up,
uses a period as a decimal separator.</p>

<p>The following countries use a <b>period as a decimal separator</b>:</p>

<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, Switzerland, 
Thailand, United Kingdom, and United States.</blockquote>

<p>The following countries use a <b>comma as a decimal separator</b>:</p>

<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, Ukraine, Uruguay, Venezuela, and Zimbabwe.</blockquote>


<br/>
<a name="unicode_utf8"></a>
<h3>Unicode and UTF-8 encoding</h3>

<p>Note that for many European languages,
the <a href="#set-locale">set-locale</a> mechanism
is sufficient to display non-ASCII character sets,
as long as each character is presented as <em>one</em> byte internally.
UTF-8 encoding is only necessary for multi-byte character sets as described 
in this chapter.</p>

<p>
	newLISP can be compiled
	as a UTF-8&ndash;enabled application.
	UTF-8 is a multi-byte encoding
	of the international Unicode character set.
	A UTF-8&ndash;enabled newLISP
	running on an operating system with UTF-8 enabled
	can handle any character of the installed locale.
</p>
<p>
	The following steps
	make UTF-8 work with newLISP
	on a specific operating system and platform:
</p>
<p>
	<tt>(1)</tt> Use one of the makefiles
	ending in <tt>utf8</tt>
	to compile newLISP as
	a UTF-8 application.
	If no UTF-8 makefile
	is available for your platform,
	the normal makefile
	for your operating system
	contains instructions
	on how to change it
	for UTF-8.
</p>
<p>
	The macOS binary installer contains
	a UTF-8&ndash;enabled version by default.
</p>
<p>
	<tt>(2)</tt> Enable the UTF-8 locale
	on your operating system.
	Check and set a UTF-8 locale
	on Unix and Unix-like OSes
	by using the <tt>locale</tt> command
	or the <tt>set-locale</tt> function within newLISP.
	On Linux, the locale can be changed by setting
	the appropriate environment variable.
	The following example uses <tt>bash</tt>
	to set the U.S. locale:
</p>
<pre>
export LC_CTYPE=en_US.UTF-8
</pre>		
<p><tt>(3)</tt> The UTF-8&ndash;enabled newLISP automatically switches to the locale found
on the operating system.  Make sure the command shell
is UTF-8&ndash;enabled.  The U.S. version of WinXP's <tt>notepad.exe</tt>
can display Unicode UTF-8&ndash;encoded characters, but the command shell cannot.
On Linux and other Unixes, the Xterm shell can be used
when started as follows:</p>

<pre>
LC_CTYPE=en_US.UTF-8 xterm
</pre>		<p>
	The following procedure can now be used
	to check for UTF-8 support.
	After starting newLISP, type:
</p>
<pre>
(println (char 937))               ; displays Greek uppercase omega
(println (lower-case (char 937)))  ; displays lowercase omega
</pre>		<p>
	While the uppercase omega (&Omega;) looks
	like a big O on two tiny legs,
	the lowercase omega (&omega;) has
	a shape similar to a small <tt>w</tt>
	in the Latin alphabet.
</p>
<p>
	Note: Only the output of <tt>println</tt>
	will be displayed as a character;
	<tt>println</tt>'s return value
	will appear on the console
	as a multi-byte ASCII character.
</p>
<p>
	When UTF-8&ndash;enabled newLISP
	is used on a non-UTF-8&ndash;enabled display,
	both the output and the return value
	will be two characters.
	These are the two bytes necessary
	to encode the omega character.
</p>

<br/>

<a name="utf8_capable"></a>
<h3>Functions working on UTF-8 characters</h3>

<p>When UTF-8&ndash;enabled newLISP is used, the following string functions work
on one- or multi-byte characters rather than one 8-bit byte boundaries:</p>

<table  width="98%" summary="functions working on character boundaries in UTF-8">
<tr align="left"><th>function</th><th>description</th></tr>

<tr>
<td><a href="#char">char</a></td>
<td>translates between characters and ASCII/Unicode</td>
</tr>

<tr>
<td><a href="#chop">chop</a></td>
<td>chops characters from the end of a string</td>
</tr>

<tr>
<td><a href="#date">date</a></td>
<td>converts date number to string (when used with the third argument)</td>
</tr>

<tr>
<td><a href="#dostring">dostring</a></td>
<td>evaluates once for each character in a string</td>
</tr>

<tr>
<td><a href="#explode">explode</a></td>
<td>transforms a string into a list of characters</td>
</tr>

<tr>
<td><a href="#first">first</a></td>
<td>gets first element in a list (car, head) or string</td>
</tr>

<tr>

<td><a href="#last">last</a></td>
<td>returns the last element of a list or string</td>
</tr>


<tr>
<td><a href="#lower-case">lower-case</a></td>
<td>converts a string to lowercase characters</td>
</tr>

<tr>
<td><a href="#nth">nth</a></td>
<td>gets the <em>nth</em> element of a list or string</td>
</tr>

<tr>
<td><a href="#pop">pop</a></td>
<td>deletes an element from a list or string</td>
</tr>

<tr>
<td><a href="#push">push</a></td>
<td>inserts a new element in a list or string</td>
</tr>

<tr>
<td><a href="#rest">rest</a></td>
<td>gets all but the first element of a list (cdr, tail) or string</td>
</tr>

<tr>
<td><a href="#select">select</a></td>
<td>selects and permutes elements from a list or string</td>
</tr>

<tr>
<td><a href="#title-case">title-case</a></td>
<td>converts the first character of a string to uppercase</td>
</tr>

<tr>
<td><a href="#trim">trim</a></td>
<td>trims a string from both sides</td>
</tr>

<tr>
<td><a href="#upper-case">upper-case</a></td>
<td>converts a string to uppercase characters</td>
</tr>

</table><br/>

<p>All other string functions work on 8-bit bytes.  When positions are returned,
as in <a href="#find">find</a> or <a href="#regex">regex</a>,
they are single 8-bit byte positions rather than character positions which
may be multi-byte.
The <a href="#get-char">get-char</a> and <a href="#slice">slice</a> functions
do not take multi-byte character offsets, but single-byte offsets, even
in UTF-8 enabled versions of newLISP.
The <a href="#reverse">reverse</a> function reverses
a byte vector, not a character vector. The last three functions can still 
be used to manipulate binary non-textual data in the UTF-8&ndash;enabled 
version of newLISP. To make <a href="#slice">slice</a> and <a href="#reverse">reverse</a>
work with UTF-8 strings, combine them with <a href="#explode">explode</a> and
<a href="#join">join</a>.</p>

<p>To enable UTF-8 in Perl Compatible Regular Expressions (PCRE)
&mdash; used by <a href="#directory">directory</a>, <a href="#find">find</a>, 
<a href="#member">member</a>, <a href="#parse">parse</a>, <a href="#regex">regex</a>, 
<a href="#regex-comp">regex-comp</a> and <a href="#replace">replace</a> &mdash;
set the option number accordingly (2048). Note that offset and lengths in 
<a href="#regex">regex</a> results are always in single byte counts.
See the <a href="#regex">regex</a> documentation for details.</p>

<p>Use <a href="#explode">explode</a> to obtain an array
of UTF-8 characters and to manipulate characters rather than bytes
when a UTF-8&ndash;enabled function is unavailable:</p>

<pre>
(join (reverse (explode str)))  ; reverse UTF-8 characters
</pre>		

<p>The above string functions (often used to manipulate non-textual binary data)
now work on character, rather than byte, boundaries,
so care must be exercised when using the UTF-8&ndash;enabled version.
The size of the first 127 ASCII characters &mdash;
along with the characters in popular code pages such as ISO 8859 &mdash;
is one byte long.  When working exclusively within these code pages,
UTF-8&ndash;enabled newLISP is not required. 
The <a href="#set-locale">set-locale</a> function alone
is sufficient for localized behavior.</p>

<br/>

<a name="utf8_version"></a>
<h3>Functions only available on UTF-8 enabled versions</h3>

<table  width="98%" summary="functions only available on UTF-8 version">
<tr align="left"><th>function</th><th>description</th></tr>

<tr>
<td><a href="#unicode">unicode</a></td>
<td>converts UTF-8 or ASCII strings into USC-4 Unicode</td>
</tr>

<tr>
<td><a href="#utf8">utf8</a></td>
<td>converts UCS-4 Unicode strings to UTF-8</td>
</tr>

<tr>
<td><a href="#utf8len">utf8len</a></td>
<td>returns the number of UTF-8 characters in a string</td>
</tr>

</table><br/>

<p>The first two functions are rarely used in practice,
as most Unicode text files are already UTF-8&ndash;encoded
(rather than UCS-4, which uses four-byte integer characters).
Unicode can be displayed directly when using the 
<tt>"%ls"</tt> <a href="#format">format</a> specifier.</p>

<p>For further details on UTF-8 and Unicode,
consult <a href="http://www.cl.cam.ac.uk/~mgk25/unicode.html"><em>UTF-8 and Unicode FAQ 
for Unix/Linux</em></a> by <em>Markus Kuhn</em>.</p>

<br/>
<center>
<span class="divider">(&nbsp;<font color="#7ba9d4">&sect;</font>&nbsp;)</span>
</center>

<br/>

<a name="commas"></a>
<h2>22. Commas in parameter lists</h2>

<p>
	Some of the example programs contain functions
	that use a comma to separate the parameters into two groups.
	This is not a special syntax of newLISP,
	but rather a visual trick.
	The comma is a symbol just like any other symbol.
	The parameters after the comma are not required
	when calling the function;
	they simply declare local variables in a convenient way.
	This is possible in newLISP because parameter variables in lambda expressions
	are local and arguments are optional:
</p>
<pre>
(define (my-func a b c , x y z)
    (set 'x &hellip;)
(&hellip;))
</pre>		
<p>
When calling this function, only <tt>a, b</tt>, and <tt>c</tt> are used as parameters.
The others (the comma symbol, <tt>x</tt>, <tt> y</tt>, and <tt>z</tt>) are initialized 
to <tt>nil</tt> and are local to the function.  After execution, the function's contents 
are forgotten and the environment's symbols are restored to their previous values.
</p>
<p>
	For other ways of declaring and initializing local variables,
	see <a href="#let">let</a>, <a href="#letex">letex</a> and
	<a href="#letn">letn</a>.
</p>

<br/>
<center>
<span class="divider">(&nbsp;<font color="#7ba9d4">&sect;</font>&nbsp;)</span>
</center>
<br/>


<br/><br/><br/>


<center style="font-size: 150%">
<span class="divider">(&nbsp;<font color="#7ba9d4">&part;</font>&nbsp;)</span>
</center>

<a name="function_ref"></a>
<center><h1>newLISP Function Reference</h1></center>

<br/><br/>

<a name="symbol_names"></a>
<h2>1. Syntax of symbol variables and numbers</h2>

<p>Source code in newLISP is parsed according to the rules outlined here. 
When in doubt, verify the behavior of newLISP's internal parser
by calling <a href="#parse">parse</a> without optional arguments.</p>

<br/>

<h3>Symbols for variable names</h3>
<p>
The following rules apply to the naming of symbols 
used as variables or functions:
</p>


<ol>
<li>Variable symbols should not start with any of the following characters:<br/>
<tt># ; " ' ( )  { } . , 0 1 2 3 4 5 6 7 8 9</tt><br/><br/></li>

<li>Variable symbols starting with a <tt>+</tt> or <tt>-</tt> cannot have a 
number as the second character.<br/><br/></li>

<li>Any character is allowed inside a variable name, except for:<br/>
<tt>" ' ( ) : ,</tt> and the space character. These mark the end of a variable symbol.<br/><br/></li>

<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.<br/><br/></li>

<li>A symbol name starting with <tt>$</tt> (dollar sign) is global. There are several of these
symbols already <a href="#system_symbols">built into newLISP</a> and set and changed 
internally. This type of global symbol can also be created by the user.
</li>

</ol>


<p>
All of the following symbols are legal variable names in newLISP:
</p>

<!-- example -->

<pre>
myvar
A-name
X34-zz
[* 7 5 ()};]
*111*
</pre>

<p>
Sometimes it is useful to create hash-like <a href="#hash">lookup dictionaries</a>
with keys containing characters that are illegal in newLISP variables. 
The functions <a href="#sym">sym</a> and <a href="#context">context</a> 
can be used to create symbols containing these characters:
</p>

<pre>
(set (sym "(#:L*") 456)  <span class='arw'>&rarr;</span> 456 ; the symbol '(#:L*'

(eval (sym "(#:L*"))  <span class='arw'>&rarr;</span> 456

(set (sym 1) 123)  <span class='arw'>&rarr;</span> 123

(eval (sym 1))  <span class='arw'>&rarr;</span> 123

1        <span class='arw'>&rarr;</span> 1
(+ 1 2)  <span class='arw'>&rarr;</span> 3
</pre>


<p>
The last example creates the symbol <tt>1</tt> 
containing the value <tt>123</tt>. 
Also note that creating such a symbol does not alter newLISP's normal operations, 
since <tt>1</tt> is still parsed as the number one.
</p>

<br/>

<h3>Numbers</h3>

<p>When parsing binary, hex, decimal, float and integer numbers, up to
1000 digits are parsed when present. The rest will be read as new token(s).
Note that IEEE 754 64-bit doubles distinguish only up to 16 significant
digits. If more than 308 digits are present before the decimal point, the
number will convert to <tt>inf</tt> (infinity). For big integers the 1000 
limitation exists only when parsing source. There is no limit when a result 
of big integers math exceeds 1000 digits.</p>

<p>
newLISP recognizes the following number formats:
</p>

<p>
<b>Integers</b> are one or more digits long, 
optionally preceded by a <tt>+</tt> or <tt>-</tt> sign. 
Any other character marks the end of the integer 
or may be part of the sequence 
if parsed as a float (see float syntax below).
</p>

<!-- example -->

<pre>
123
+4567
-999
</pre>

<p>
<b>Big integers</b> can be of unlimited precision and are processed
differently from normal 64-bi integers internally.</p>

<!-- example -->
<pre>
123456789012345678901234567890 ; will automatically be converted to big int
-123L                          ; appended L forces conversion
0L
</pre>

<p>when parsing the command line or programming source, newLISP will
recognise, integers bigger than 64-bit and convert the to big integers.
Smaller numbers can be forced to big integer format by appending the
letter L.</p>


<p>
<b>Hexadecimals</b> start with a <tt>0x</tt> (or <tt>0X</tt>),  
followed by any combination of the hexadecimal digits: 
<tt>0123456789abcdefABCDEF</tt>. 
Any other character ends the hexadecimal number. Only up to 16 hexadecimal digits
are valid and any more digits are ignored.
</p>

<!-- example -->

<pre>
0xFF    <span class='arw'>&rarr;</span>  255
0x10ab  <span class='arw'>&rarr;</span> 4267
0X10CC  <span class='arw'>&rarr;</span> 4300
</pre>

<p>
<b>Binaries</b> start with a <tt>0b</tt> (or <tt>0B</tt>),
followed by up to 64 bits coded with 1's or 0s. Any other character ends the binary number.
Only up to 64 bits are valid and any more bits are ignored.
</p>

<!-- example -->

<pre>
0b101010   <span class='arw'>&rarr;</span>  42
</pre>



<p>
<b>Octals</b> start with an optional <tt>+</tt> (plus) or <tt>-</tt> (minus) sign and a <tt>0</tt> (zero), 
followed by any combination of the octal digits: <tt>01234567</tt>. 
Any other character ends the octal number. Only up to 21 octal digits are valid
and any more digits are ignored.
</p>

<!-- example -->

<pre>
012   <span class='arw'>&rarr;</span>  10
010   <span class='arw'>&rarr;</span>   8
077   <span class='arw'>&rarr;</span>  63
-077  <span class='arw'>&rarr;</span> -63
</pre>



<p>
<b>Floating point</b> numbers can start 
with an optional <tt>+</tt> (plus) or <tt>-</tt> (minus) sign, 
but they cannot be followed by a <tt>0</tt> (zero); 
this would make them octal numbers instead of floating points. 
A single <tt>.</tt> (decimal point) can appear anywhere within
a floating point number, including at the beginning.
</p>

<p>Only 16 digits are siginificant and any more digits are ignored.</p>

<!-- example -->

<pre>
1.23     <span class='arw'>&rarr;</span>  1.23
-1.23    <span class='arw'>&rarr;</span> -1.23
+2.3456  <span class='arw'>&rarr;</span>  2.3456
.506     <span class='arw'>&rarr;</span>  0.506
</pre>


<p>
As described below, <b>scientific notation</b> 
starts with a floating point number
called the <em>significand</em> (or <em>mantissa</em>),
followed by the letter <tt>e</tt> or <tt>E</tt> 
and an integer <em>exponent</em>.
</p>

<!-- example -->

<pre>
1.23e3    <span class='arw'>&rarr;</span>  1230
-1.23E3   <span class='arw'>&rarr;</span> -1230
+2.34e-2  <span class='arw'>&rarr;</span>  0.0234
.506E3    <span class='arw'>&rarr;</span>  506
</pre>



<br/>
<center>
<span class="divider">(&nbsp;<font color="#7ba9d4">&sect;</font>&nbsp;)</span>
</center>
<br/>

<a name="type_ids"></a>
<h2>2. Data types and names in the reference</h2>

<p>To describe the types and names of a function's parameters, 
the following naming convention is used throughout the reference section:</p>


<b>syntax&#058; (format <em>str-format</em> <em>exp-data-1</em> [<em>exp-data-i</em> ... ])</b>



<p>Arguments are represented by symbols formed by the argument's type and name, 
separated by a <tt>-</tt> (hyphen). Here, <em>str-format</em> (a string) and 
<em>exp-data-1</em> (an expression) are named "format" and "data-1", respectively.</p>

<p>Arguments enclosed in brackets <tt>[</tt> and <tt>]</tt> are optional. When
arguments are separated by a vertical <tt>|</tt> then one of them must be chosen.</p>

<h3>array</h3>

<p>An array (constructed with the <a href="#array">array</a> function).</p>

<h3>body</h3>

<p>One or more expressions for evaluation. The expressions are evaluated sequentially 
if there is more than one.</p>


<pre>
1 7.8
nil
(+ 3 4)
"Hi" (+ a b)(print result)
(do-this)(do-that) 123
</pre>


<h3>bool</h3>

<p><tt>true</tt>, <tt>nil</tt>, or an expression evaluating to one of these two.
</p>


<pre>
true, nil, (&lt;= X 10)
</pre>


<h3>context</h3>

<p>An expression evaluating to a context (namespace) or a variable symbol 
holding a context.</p>


<pre>
MyContext, aCtx, TheCTX
</pre>


<h3>exp</h3>

<p>Any data type described in this chapter.</p>

<h3>func</h3>

<p>
	A symbol or an expression evaluating to 
	an operator symbol or lambda expression.
</p>


<pre>
+, add, (first '(add sub)), (lambda (x) (+ x x))
</pre>


<h3>int</h3>

<p>
An integer or an expression evaluating to an integer. 
Generally, if a floating point number is used 
when an int is expected, 
the value is truncated to an integer.
</p>


<pre>
123, 5, (* X 5)
</pre>


<h3>list</h3>
<p>
	A list of elements (any type) 
	or an expression evaluating to a list.
</p>

<pre>
(a b c "hello" (+ 3 4))
</pre>


<h3>num</h3>
<p>
An integer, a floating point number, 
or an expression evaluating to one of these two. 
If an integer is passed, 
it is converted to a floating point number.
</p>

<pre>
1.234, (div 10 3), (sin 1)
</pre>


<h3>matrix</h3>
<p>A list in which each row element is itself a list 
or an array in which each row element is itself an array.
All element lists or arrays (rows) are of the same length.
Any data type can be element of a matrix, but when
using specific matrix operations like <a href="#det">det</a>, 
<A href="#multiply">multiply</A>, or <A href="#invert">invert</A>, 
all numbers must be floats or integers.
</p>

<p>
The dimensions of a matrix are defined 
by indicating the number of rows
and the number of column elements per row. 
Functions working on matrices 
ignore superfluous columns in a row. 
For missing row elements, 
<tt>0.0</tt> is assumed by the functions 
<a href="#det">det</a>, <a href="#multiply">multiply</a>, 
and <a href="#invert">invert</a>, 
while <a href="#transpose">transpose</a> assumes <tt>nil</tt>.
Special rules apply for <a href="#transpose">transpose</a> 
when a whole row is not a list or an array, 
but some other data type.
</p>


<pre>
((1  2  3  4)
(5  6  7  8)
(9 10 11 12))        ; 3 rows 4 columns
		   
((1 2) (3 4) (5 6))  ; 3 rows 2 columns
</pre>


<h3>place</h3>

<p>A place referenced by a symbol or a place defined in a list, array 
or string by indexing with <a href="#nth">nth</a> or <a href="#indexing">implicit indexing</a>
or a place referenced by functions like <a href="#first">first</a>, <a href="#last">last</a>,
<a href="#assoc">assoc</a> or <a href="#lookup">lookup</a>.</p>


<h3>str</h3>

<p>A string or an expression that evaluates to a string.</p>

<p>Depending on the length and processing of special characters, strings are delimited
by either quotes <tt>""</tt>, braces <tt>{}</tt> or <tt>[text][/text]</tt> tags.</p>

<p>Strings limited by either quotes <tt>""</tt> or braces <tt>{}</tt> must not exceed
2047 characters. Longer strings should be limited by <tt>[text][/text]</tt> tags for
unlimited text length.</p>

<pre>
"Hello", (append first-name  " Miller")
</pre>


<p>
Special characters can be included in quoted strings 
by placing a <tt>\</tt> (backslash) before the character or 
digits to escape them:</p>

<table width="98%"  summary="escaping special characters in strings">
<tr align="left" valign="bottom"><th>character</th><th>description</th></tr>
<tr><td><tt>\"</tt></td><td>for a double quote inside a quoted string</td></tr>
<tr><td><tt>\n</tt></td> <td>the line-feed character (ASCII 10)</td></tr>
<tr> <td><tt>\r</tt></td> <td>the carriage return character (ASCII 13)</td> </tr>
<tr><td><tt>\b</tt></td><td>for a backspace BS character (ASCII 8)</td></tr>
<tr><td><tt>\t</tt></td><td>for a TAB character (ASCII 9)</td></tr>
<tr><td><tt>\f</tt></td><td>for a formfeed FF character (ASCII 12)</td></tr>
<tr><td><tt>\nnn</tt></td> <td>a decimal ASCII code where nnn is between 000 and 255</td></tr>
<tr><td><tt>\xnn</tt></td> <td>a hexadecimal code where nn is between 00 and FF</td></tr>
<tr><td><tt>\unnnn</tt></td><td>a unicode character encoded in the four <tt>nnnn</tt> hexadecimal
digits. When reading a quoted string, newLISP will translate 
this to a UTF8 character in the UTF8 enabled versions of newLISP.</td></tr>
<tr><td><tt>\\</tt></td> <td>the backslash character itself</td></tr>
</table><br/>

<p>Decimals start with a digit. Hexadecimals start with <tt>x</tt>:</p>

<pre>
"\065\066\067" <span class='arw'>&rarr;</span> "ABC"
"\x41\x42\x43" <span class='arw'>&rarr;</span> "ABC"
</pre>


<p>Instead of a <tt>"</tt> (double quote), a <tt>{</tt> (left curly bracket) 
and <tt>}</tt> (right curly bracket) can be used to delimit strings.
This is useful when quotation marks need to occur inside strings. 
Quoting with the curly brackets suppresses the backslash escape effect 
for special characters. Balanced nested curly brackets may be used within 
a string.  This aids in writing regular expressions or short sections of 
HTML.</p>


<pre>
(print "&lt;A href=\"http://mysite.com\"&gt;" ) ; the cryptic way

(print {&lt;A href="http://mysite.com"&gt;} )   ; the readable way


; path names on MS Windows

(set 'path "C:\\MyDir\\example.lsp")

; no escaping when using braces

(set 'path {C:\MyDir\example.lsp})

; on MS Windows the forward slash can be used in path names

(set 'path "C:/MyDir/example.lsp")

; inner braces are balanced
(regex {abc{1,2}} line) 

(print [text]
  this could be
  a very long (&gt; 2048 characters) text,
  i.e. HTML.
[/text])
</pre>


<p>
	The tags <tt>[text]</tt> and <tt>[/text]</tt> 
	can be used to delimit long strings 
	and suppress escape character translation. 
	This is useful for delimiting long HTML passages 
	in CGI files written in newLISP 
	or for situations where character translation 
	should be completely suppressed. 
	Always use the <tt>[text]</tt> tags 
	for strings longer than 2048 characters.
</p>

<h3>sym</h3>

<p>
	A symbol or expression evaluating to a symbol.
</p>


<pre>
'xyz, (first '(+ - /)), '*, '- , someSymbol,
</pre>



<p>Most of the context symbols in this manual start with an uppercase letter 
to distinguish them from other symbols.</p>

<h3>sym-context</h3>
<p>
A symbol, an existing context, or an expression evaluating to a symbol 
from which a context will be created.  If a context does not already exist, 
many functions implicitly create them 
(e.g., <a href="#bayes-train">bayes-train</a>, <a Href="#context">context</a>, 
<a href="#eval-string">eval-string</a>, 
<a href="#load">load</a>, <a href="#sym">sym</a>, and <a href="#xml-parse">xml-parse</a>).
The context must be specified when these functions are used 
on an existing context.  Even if a context already exists, 
some functions may continue to take quoted symbols (e.g., <a href="#context">context</a>).
For other functions, such as <a href="#contextp">context?</a>, the distinction is critical.
</p>


<br/>



<br/>
<center>
<span class="divider">(&nbsp;<font color="#7ba9d4">&sect;</font>&nbsp;)</span>
</center>
<br/>

<a name="functions"></a>
<h2>3. Functions in groups</h2>

<p>Some functions appear in more than one group.</p>

<a name="list_processing"></a>
<h3>List processing, flow control, and integer arithmetic</h3>

<table border="0" cellpadding="1" width="95%" align="center" summary="List processing, flow control and integer
arithmetic">

<tr>
<td WIDTH="16%"><a href="#arithmetic">+, -, *, /, %</a></td>
<td WIDTH="80%">integer arithmetic</td>
</tr>

<tr>
<td><a href="#inci">++</a></td>
<td>increment integer numbers</td>
</tr>

<tr>
<td><a href="#deci">--</a></td>
<td>decrement integer numbers</td>
</tr>

<tr>
<td><a href="#logical">&lt;, &gt;, =</a></td>
<td>compares any data type: less, greater, equal</td>
</tr>

<tr>
<td><a href="#logical">&lt;=, &gt;=, !=</a></td>
<td>compares any data type: less-equal, greater-equal, not-equal</td>
</tr>

<tr>
<td><a href="#colon">:</a></td>
<td>constructs a context symbol and applies it to an object</td>
</tr>

<tr>
<td><a href="#and">and</a></td>
<td>logical <tt>and</tt></td>
</tr>

<tr>
<td><a href="#append">append</a></td>
<td>appends lists ,arrays or strings to form a new list, array or string</td>
</tr>

<tr>
<td><a href="#apply">apply</a></td>
<td>applies a function or primitive to a list of arguments</td>
</tr>

<tr>
<td><a href="#args">args</a></td>
<td>retrieves the argument list of a function or macro expression</td>
</tr>

<tr>
<td><a href="#assoc">assoc</a></td>
<td>searches for keyword associations in a list</td>
</tr>

<tr>
<td><a href="#begin">begin</a></td>
<td>begins a block of functions</td>
</tr>

<tr>
<td><a href="#bigint">bigint</a></td>
<td>convert a number to big integer format</td>
</tr>

<tr>
<td><a href="#bind">bind</a></td>
<td>binds variable associations in a list</td>
</tr>

<tr>
<td><a href="#case">case</a></td>
<td>branches depending on contents of control variable</td>
</tr>

<tr>
<td><a href="#catch">catch</a></td>
<td>evaluates an expression, possibly catching errors</td>
</tr>

<tr>
<td><a href="#chop">chop</a></td>
<td>chops elements from the end of a list</td>
</tr>

<tr>
<td><a href="#clean">clean</a></td>
<td>cleans elements from a list</td>
</tr>

<tr>
<td><a href="#collect">collect</a></td>
<td>repeat evaluating an expression and collect results in a list</td>
</tr>

<tr>
<td><a href="#cond">cond</a></td>
<td>branches conditionally to expressions</td>
</tr>

<tr>
<td><a href="#cons">cons</a></td>
<td>prepends an element to a list, making a new list</td>
</tr>

<tr>
<td><a href="#constant">constant</a></td>
<td>defines a constant symbol</td>
</tr>

<tr>
<td><a href="#count">count</a></td>
<td>counts elements of one list that occur in another list</td>
</tr>

<tr>
<td><a href="#curry">curry</a></td>
<td>transforms a function f(x, y) into a function fx(y)</td>
</tr>

<tr>
<td><a href="#define">define</a></td>
<td>defines a new function or lambda expression</td>
</tr>

<tr>
<td><a href="#define-macro">define-macro</a></td>
<td>defines a macro or lambda-macro expression</td>
</tr>

<tr>
<td><a href="#def-new">def-new</a></td>
<td>copies a symbol to a different context (namespace)</td>
</tr>

<tr>
<td><a href="#difference">difference</a></td>
<td>returns the difference between two lists</td>
</tr>

<tr>
<td><a href="#doargs">doargs</a></td>
<td>iterates through the arguments of a function</td>
</tr>

<tr>
<td><a href="#dolist">dolist</a></td>
<td>evaluates once for each element in a list</td>
</tr>

<tr>
<td><a href="#dostring">dostring</a></td>
<td>evaluates once for each character in a string</td>
</tr>

<tr>
<td><a href="#dotimes">dotimes</a></td>
<td>evaluates once for each number in a range</td>
</tr>

<tr>
<td><a href="#dotree">dotree</a></td>
<td>iterates through the symbols of a context</td>
</tr>

<tr>
<td><a href="#do-until">do-until</a></td>
<td>repeats evaluation of an expression until the condition is met</td>
</tr>

<tr>
<td><a href="#do-while">do-while</a></td>
<td>repeats evaluation of an expression while the condition is true</td>
</tr>

<tr>
<td><a href="#dup">dup</a></td>
<td>duplicates a list or string a specified number of times</td>
</tr>

<tr>
<td><a href="#ends-with">ends-with</a></td>
<td>checks the end of a string or list against a key of the same type</td>
</tr>

<tr>
<td><a href="#eval">eval</a></td>
<td>evaluates an expression</td>

</tr>
<tr>
<td><a href="#exists">exists</a></td>
<td>checks for the existence of a condition in a list</td>
</tr>

<tr>
<td><a href="#expand">expand</a></td>
<td>replaces a symbol in a nested list</td>
</tr>

<tr>
<td><a href="#explode">explode</a></td>
<td>explodes a list or string</td>
</tr>

<tr>
<td><a href="#extend">extend</a></td>
<td>extends a list or string</td>
</tr>

<tr>
<td><a href="#first">first</a></td>
<td>gets the first element of a list or string</td>
</tr>

<tr>
<td><a href="#filter">filter</a></td>
<td>filters a list</td>
</tr>

<tr>
<td><a href="#find">find</a></td>
<td>searches for an element in a list or string</td>
</tr>

<tr>
<td><a href="#flat">flat</a></td>
<td>returns the flattened list</td>
</tr>

<tr>
<td><a href="#define">fn</a></td>
<td>defines a new function or lambda expression</td>
</tr>

<tr>
<td><a href="#for">for</a></td>
<td>evaluates once for each number in a range</td>
</tr>

<tr>
<td><a href="#for-all">for-all</a></td>
<td>checks if all elements in a list meet a condition</td>
</tr>

<tr>
<td><a href="#if">if</a></td>
<td>evaluates an expression conditionally</td>
</tr>

<tr>
<td><a href="#index">index</a></td>
<td>filters elements from a list and returns their indices</td>
</tr>


<tr>
<td><a href="#intersect">intersect</a></td>
<td>returns the intersection of two lists</td>
</tr>

<tr>
<td><a href="#define">lambda</a></td>
<td>defines a new function or lambda expression</td>
</tr>

<tr>
<td><a href="#last">last</a></td>
<td>returns the last element of a list or string</td>
</tr>

<tr>
<td><a href="#length">length</a></td>
<td>calculates the length of a list or string</td>
</tr>

<tr>
<td><a href="#let">let</a></td>
<td>declares and initializes local variables</td>
</tr>

<tr>
<td><a href="#letex">letex</a></td>
<td>expands local variables into an expression, then evaluates</td>
</tr>

<tr>
<td><a href="#letn">letn</a></td>
<td>initializes local variables incrementally, like nested lets</td>
</tr>

<tr>
<td><a href="#list">list</a></td>
<td>makes a list</td>
</tr>

<tr>
<td><a href="#local">local</a></td>
<td>declares local variables</td>
</tr>

<tr>
<td><a href="#lookup">lookup</a></td>
<td>looks up members in an association list</td>
</tr>

<tr>
<td><a href="#map">map</a></td>
<td>maps a function over members of a list, collecting the results</td>
</tr>

<tr>
<td><a href="#match">match</a></td>
<td>matches patterns against lists; for matching against strings, see 
<a href="#find">find</a> and <a href="#regex">regex</a></td>
</tr>

<tr>
<td><a href="#member">member</a></td>
<td>finds a member of a list or string</td>
</tr>

<tr>
<td><a href="#not">not</a></td>
<td>logical <tt>not</tt></td>
</tr>

<tr>
<td><a href="#nth">nth</a></td>
<td>gets the <em>nth</em> element of a list or string</td>
</tr>

<tr>
<td><a href="#or">or</a></td>
<td>logical <tt>or</tt></td>
</tr>

<tr>
<td><a href="#pop">pop</a></td>
<td>deletes and returns an element from a list or string</td>
</tr>

<tr>
<td><a href="#pop-assoc">pop-assoc</a></td>
<td>removes an association from an association list</td>
</tr>

<tr>
<td><a href="#push">push</a></td>
<td>inserts a new element into a list or string</td>
</tr>

<tr>
<td><a href="#quote">quote</a></td>
<td>quotes an expression</td>
</tr>

<tr>
<td><a href="#ref">ref</a></td>
<td>returns the position of an element inside a nested list</td>
</tr>

<tr>
<td><a href="#ref-all">ref-all</a></td>
<td>returns a list of index vectors of elements inside a nested list</td>
</tr>

<tr>
<td><a href="#rest">rest</a></td>
<td>returns all but the first element of a list or string</td>
</tr>

<tr>
<td><a href="#replace">replace</a></td>
<td>replaces elements inside a list or string</td>
</tr>

<tr>
<td><a href="#reverse">reverse</a></td>
<td>reverses a list or string</td>
</tr>

<tr>
<td><a href="#rotate">rotate</a></td>
<td>rotates a list or string</td>
</tr>

<tr>
<td><a href="#select">select</a></td>
<td>selects and permutes elements from a list or string</td>
</tr>

<tr>
<td><a href="#self">self</a></td>
<td>Accesses the target object inside a FOOP method</td>
</tr>

<tr>
<td><a href="#set">set</a></td>
<td>sets the binding or contents of a symbol</td>
</tr>

<tr>
<td><a href="#setf">setf setq</a></td>
<td>sets contents of a symbol or list, array or string reference</td>
</tr>

<tr>
<td><a href="#set-ref">set-ref</a></td>
<td>searches for an element in a nested list and replaces it</td>
</tr>

<tr>
<td><a href="#set-ref-all">set-ref-all</a></td>
<td>searches for an element in a nested list and replaces all instances</td>
</tr>

<tr>
<td><a href="#silent">silent</a></td>
<td>works like <a href="#begin">begin</a> but suppresses console output of the return value</td>
</tr>

<tr>
<td><a href="#slice">slice</a></td>
<td>extracts a sublist or substring</td>
</tr>

<tr>
<td><a href="#sort">sort</a></td>
<td>sorts the members of a list</td>
</tr>

<tr>
<td><a href="#starts-with">starts-with</a></td>
<td>checks the beginning of a string or list against a key of the same type</td>
</tr>

<tr>
<td><a href="#swap">swap</a></td>
<td>swaps two elements inside a list or string</td>
</tr>

<tr>
<td><a href="#unify">unify</a></td>
<td>unifies two expressions</td>
</tr>

<tr>
<td><a href="#unique">unique</a></td>
<td>returns a list without duplicates</td>
</tr>

<tr>
<td><a href="#union">union</a></td>
<td>returns a unique list of elements found in two or more lists.</td>
</tr>

<tr>
<td><a href="#unless">unless</a></td>
<td>evaluates an expression conditionally</td>
</tr>

<tr>
<td><a href="#until">until</a></td>
<td>repeats evaluation of an expression until the condition is met</td>
</tr>

<tr>
<td><a href="#when">when</a></td>
<td>evaluates a block of statements conditionally</td>
</tr>

<tr>
<td><a href="#while">while</a></td>
<td>repeats evaluation of an expression while the condition is true</td>
</tr>
</table><br/>

<a name="string_operators"></a>
<h3>String and conversion functions</h3>

<table border="0" cellpadding="1" width="95%" align="center" summary="String and conversion functions">


<tr>
<td WIDTH="16%"><a href="#address">address</a></td>
<td WIDTH="84%">gets the memory address of a number or string</td>
</tr>

<tr>
<td><a href="#bigint">bigint</a></td>
<td>convert a number to big integer format</td>
</tr>

<tr>
<td><a href="#bits">bits</a></td>
<td>translates a number into binary representation</td>
</tr>

<tr>
<td><a href="#char">char</a></td>
<td>translates between characters and ASCII codes</td>
</tr>

<tr>
<td><a href="#chop">chop</a></td>
<td>chops off characters from the end of a string</td>
</tr>

<tr>
<td><a href="#dostring">dostring</a></td>
<td>evaluates once for each character in a string</td>
</tr>

<tr>
<td><a href="#dup">dup</a></td>
<td>duplicates a list or string a specified number of times</td>
</tr>

<tr>
<td><a href="#ends-with">ends-with</a></td>
<td>checks the end of a string or list against a key of the same type</td>
</tr>

<tr>
<td><a href="#encrypt">encrypt</a></td>
<td>does a one-time&ndash;pad encryption and decryption of a string</td>
</tr>

<tr>
<td><a href="#eval-string">eval-string</a></td>
<td>compiles, then evaluates a string</td>
</tr>

<tr>
<td><a href="#explode">explode</a></td>
<td>transforms a string into a list of characters</td>
</tr>

<tr>
<td><a href="#extend">extend</a></td>
<td>extends a list or string</td>
</tr>

<tr>
<td><a href="#find">find</a></td>
<td>searches for an element in a list or string</td>
</tr>

<tr>
<td><a href="#find-all">find-all</a></td>
<td>returns a list of all pattern matches found in string</td>
</tr>

<tr>
<td><a href="#first">first</a></td>
<td>gets the first element in a list or string</td>
</tr>

<tr>
<td><a href="#float">float</a></td>
<td>translates a string or integer into a floating point number</td>
</tr>

<tr>
<td><a href="#format">format</a></td>
<td>formats numbers and strings as in the C language</td>
</tr>

<tr>
<td><a href="#get-char">get-char</a></td>

<td>gets a character from a memory address</td>
</tr>

<tr>
<td><a href="#get-float">get-float</a></td>
<td>gets a double float from a memory address</td>
</tr>

<tr>
<td><a href="#get-int">get-int</a>&nbsp;&nbsp;</td>
<td>gets a 32-bit integer from a memory address</td>
</tr>

<tr>
<td><a href="#get-long">get-long</a>&nbsp;&nbsp;</td>
<td>gets a long 64-bit integer from a memory address</td>
</tr>

<tr>
<td><a href="#get-string">get-string</a></td>
<td>gets a string from a memory address</td>
</tr>

<tr>
<td><a href="#int">int</a></td>
<td>translates a string or float into an integer</td>
</tr>

<tr>
<td><a href="#join">join</a></td>
<td>joins a list of strings</td>
</tr>

<tr>
<td><a href="#last">last</a></td>
<td>returns the last element of a list or string</td>
</tr>

<tr>
<td><a href="#lower-case">lower-case</a></td>
<td>converts a string to lowercase characters</td>
</tr>

<tr>
<td><a href="#member">member</a></td>
<td>finds a list or string member</td>
</tr>

<tr>
<td><a href="#name">name</a></td>
<td>returns the name of a symbol or its context as a string</td>
</tr>

<tr>
<td><a href="#nth">nth</a></td>
<td>gets the <em>nth</em> element in a list or string</td>
</tr>

<tr>
<td><a href="#pack">pack</a></td>
<td>packs newLISP expressions into a binary structure</td>
</tr>

<tr>
<td><a href="#parse">parse</a></td>
<td>breaks a string into tokens</td>
</tr>

<tr>
<td><a href="#pop">pop</a></td>
<td>pops from a string</td>
</tr>

<tr>
<td><a href="#push">push</a></td>
<td>pushes onto a string</td>
</tr>

<tr>
<td><a href="#regex">regex</a></td>
<td>performs a Perl-compatible regular expression search</td>
</tr>

<tr>
<td><a href="#regex-comp">regex-comp</a></td>
<td>pre-compiles a regular expression pattern</td>
</tr>

<tr>
<td><a href="#replace">replace</a></td>
<td>replaces elements in a list or string</td>

</tr>

<tr>
<td><a href="#rest">rest</a></td>
<td>gets all but the first element of a list or string</td>
</tr>

<tr>
<td><a href="#reverse">reverse</a></td>
<td>reverses a list or string</td>
</tr>

<tr>
<td><a href="#rotate">rotate</a></td>
<td>rotates a list or string</td>
</tr>

<tr>
<td><a href="#select">select</a></td>
<td>selects and permutes elements from a list or string</td>
</tr>

<tr>
<td><a href="#setf">setf setq</a></td>
<td>sets contents of a string reference</td>
</tr>

<tr>
<td><a href="#slice">slice</a></td>
<td>extracts a substring or sublist</td>
</tr>

<tr>
<td><a href="#source">source</a></td>
<td>returns the source required to bind a symbol as a string</td>
</tr>

<tr>
<td><a href="#starts-with">starts-with</a></td>
<td>checks the start of the string or list against a key string or list</td>
</tr>

<tr>
<td><a href="#string">string</a></td>
<td>transforms anything into a string</td>
</tr>

<tr>
<td><a href="#sym">sym</a></td>
<td>translates a string into a symbol</td>
</tr>

<tr>
<td><a href="#title-case">title-case</a></td>

<td>converts the first character of a string to uppercase</td>
</tr>

<tr>
<td><a href="#trim">trim</a></td>
<td>trims a string on one or both sides</td>
</tr>

<tr>
<td><a href="#unicode">unicode</a></td>
<td>converts ASCII or UTF-8 to UCS-4 Unicode</td>
</tr>

<tr>
<td><a href="#utf8">utf8</a></td>
<td>converts UCS-4 Unicode to UTF-8</td>
</tr>

<tr>
<td><a href="#utf8len">utf8len</a></td>
<td>returns length of an UTF-8 string in UTF-8 characters</td>
</tr>


<tr>
<td><a href="#unpack">unpack</a></td>
<td>unpacks a binary structure into newLISP expressions</td>
</tr>

<tr>

<td><a href="#upper-case">upper-case</a></td>
<td>converts a string to uppercase characters</td>
</tr>

</table><br/>

<a name="floating_point"></a>
<h3>Floating point math and special functions</h3>


<table border="0" cellpadding="1" width="95%" align="center" summary="Floating point math and special functions">


<tr>
<td WIDTH="16%"><a href="#abs">abs</a></td>
<td WIDTH="84%">returns the absolute value of a number</td>
</tr>

<tr>
<td><a href="#acos">acos</a></td>
<td>calculates the arc-cosine of a number</td>
</tr>

<tr>
<td><a href="#acosh">acosh</a></td>
<td>calculates the inverse hyperbolic cosine of a number</td>
</tr>

<tr>
<td><a href="#add">add</a></td>
<td>adds floating point or integer numbers and returns a floating point number</td>
</tr>

<tr>
<td><a href="#array">array</a></td>
<td>creates an array</td>
</tr>

<tr>
<td><a href="#array-list">array-list</a></td>
<td>returns a list conversion from an array</td>
</tr>

<tr>
<td><a href="#asin">asin</a></td>
<td>calculates the arcsine of a number</td>
</tr>

<tr>
<td><a href="#asinh">asinh</a></td>
<td>calculates the inverse hyperbolic sine of a number</td>
</tr>


<tr>
<td><a href="#atan">atan</a></td>
<td>calculates the arctangent of a number</td>
</tr>

<tr>
<td><a href="#atanh">atanh</a></td>
<td>calculates the inverse hyperbolic tangent of a number</td>
</tr>

<tr>
<td><a href="#atan2">atan2</a></td>
<td>computes the principal value of the arctangent of Y / X in radians</td>
</tr>

<tr>
<td><a href="#beta">beta</a></td>
<td>calculates the beta function</td>
</tr>

<tr>
<td><a href="#betai">betai</a></td>
<td>calculates the incomplete beta function</td>
</tr>

<tr>
<td><a href="#binomial">binomial</a></td>
<td>calculates the binomial function</td>
</tr>

<tr>
<td><a href="#ceil">ceil</a></td>

<td>rounds up to the next integer</td>
</tr>

<tr>
<td><a href="#cos">cos</a></td>
<td>calculates the cosine of a number</td>

</tr>
<tr>
<td><a href="#cosh">cosh</a></td>
<td>calculates the hyperbolic cosine of a number</td>
</tr>

<tr>
<td><a href="#crc32">crc32</a></td>
<td>calculates a 32-bit CRC for a data buffer</td>
</tr>

<tr>
<td><a href="#dec">dec</a></td>
<td>decrements a number in a variable, list or array</td>
</tr>

<tr>
<td><a href="#div">div</a></td>
<td>divides floating point or integer numbers</td>
</tr>

<tr>
<td><a href="#erf">erf</a></td>
<td>calculates the error function of a number</td>
</tr>

<tr>
<td><a href="#exp">exp</a></td>
<td>calculates the exponential <em>e</em> of a number</td>
</tr>

<tr>
<td><a href="#factor">factor</a></td>
<td>factors a number into primes</td>
</tr>

<tr>
<td><a href="#fft">fft</a></td>
<td>performs a fast Fourier transform (FFT)</td>
</tr>

<tr>
<td><a href="#floor">floor</a></td>
<td>rounds down to the next integer</td>
</tr>

<tr>
<td><a href="#flt">flt</a></td>
<td>converts a number to a 32-bit integer representing a float</td>
</tr>

<tr>
<td><a href="#gammai">gammai</a></td>
<td>calculates the incomplete Gamma function</td>
</tr>

<tr>
<td><a href="#gammaln">gammaln</a></td>
<td>calculates the log Gamma function</td>
</tr>

<tr>
<td><a href="#gcd">gcd</a></td>
<td>calculates the greatest common divisor of a group of integers</td>
</tr>

<tr>
<td><a href="#ifft">ifft</a></td>
<td>performs an inverse fast Fourier transform (IFFT)</td>
</tr>

<tr>
<td><a href="#inc">inc</a></td>
<td>increments a number in a variable, list or array</td>
</tr>

<tr>
<td><a href="#infp">inf?</a></td>
<td>checks if a floating point value is infinite</td>
</tr>

<tr>
<td><a href="#log">log</a></td>
<td>calculates the natural or other logarithm of a number</td>
</tr>

<tr>
<td><a href="#min">min</a></td>
<td>finds the smallest value in a series of values</td>
</tr>

<tr>
<td><a href="#max">max</a></td>
<td>finds the largest value in a series of values</td>

</tr>

<tr>
<td><a href="#mod">mod</a></td>
<td>calculates the modulo of two numbers</td>
</tr>

<tr>
<td><a href="#mul">mul</a></td>
<td>multiplies floating point or integer numbers</td>
</tr>

<tr>
<td><a href="#NaNp">NaN?</a></td>
<td>checks if a float is NaN (not a number)</td>
</tr>

<tr>
<td><a href="#round">round</a></td>
<td>rounds a number</td>
</tr>

<tr>
<td><a href="#pow">pow</a></td>
<td>calculates <em>x</em> to the power of <em>y</em></td>
</tr>

<tr>
<td><a href="#sequence">sequence</a></td>
<td>generates a list sequence of numbers</td>
</tr>

<tr>
<td><a href="#series">series</a></td>

<td>creates a geometric sequence of numbers</td>
</tr>

<tr>
<td><a href="#sgn">sgn</a></td>
<td>calculates the signum function of a number</td>
</tr>

<tr>
<td><a href="#sin">sin</a></td>
<td>calculates the sine of a number</td>
</tr>

<tr>
<td><a href="#sinh">sinh</a></td>
<td>calculates the hyperbolic sine of a number</td>
</tr>

<tr>
<td><a href="#sqrt">sqrt</a></td>
<td>calculates the square root of a number</td>
</tr>

<tr>
<td><a href="#ssq">ssq</a></td>
<td>calculates the sum of squares of a vector</td>
</tr>

<tr>
<td><a href="#sub">sub</a></td>
<td>subtracts floating point or integer numbers</td>
</tr>

<tr>
<td><a href="#tan">tan</a></td>
<td>calculates the tangent of a number</td>
</tr>

<tr>
<td><a href="#tanh">tanh</a></td>
<td>calculates the hyperbolic tangent of a number</td>
</tr>

<tr>
<td><a href="#uuid">uuid</a>&nbsp;</td>
<td>returns a UUID (Universal Unique IDentifier)</td>
</tr>

</table><br/>

<a name="matrices"></a>
<h3>Matrix functions</h3>


<table border="0" cellpadding="1" width="95%" align="center" summary="Matrix functions">

<tr>
<td  WIDTH="16%"><a href="#det">det</a></td>
<td  WIDTH="84%">returns the determinant of a matrix</td>
</tr>

<tr>
<td><a href="#invert">invert</a></td>
<td>returns the inversion of a matrix</td>
</tr>

<tr>
<td><a href="#mat">mat</a></td>
<td>performs scalar operations on matrices</td>
</tr>

<tr>
<td><a href="#multiply">multiply</a></td>
<td>multiplies two matrices</td>
</tr>

<tr>
<td><a href="#transpose">transpose</a>&nbsp;</td>
<td>returns the transposition of a matrix</td>
</tr>

</table><br/>

<a name="array-funcs"></a>
<h3>Array functions</h3>

<table border="0" cellpadding="1" width="95%" align="center" summary="Array functions">

<tr>
<td width="16%" ><a href="#append">append</a></td>
<td width="84%">appends arrays</td>
</tr>

<tr>
<td><a href="#array">array</a></td>
<td>creates and initializes an array with up to 16 dimensions</td>
</tr>

<tr>
<td><a href="#array-list">array-list</a></td>
<td>converts an array into a list</td>
</tr>

<tr>
<td><a href="#arrayp">array?</a></td>
<td>checks if expression is an array</td>
</tr>

<tr>
<td ><a href="#det">det</a></td>
<td>returns the determinant of a matrix</td>
</tr>

<tr>
<td ><a href="#first">first</a></td>
<td>returns the first row of an array</td>
</tr>

<tr>
<td ><a href="#invert">invert</a></td>
<td>returns the inversion of a matrix</td>
</tr>

<tr>
<td ><a href="#last">last</a></td>
<td>returns the last row of an array</td>
</tr>

<tr>
<td><a href="#mat">mat</a></td>
<td>performs scalar operations on matrices</td>
</tr>


<tr>
<td ><a href="#multiply">multiply</a></td>
<td>multiplies two matrices</td>
</tr>

<tr>
<td ><a href="#nth">nth</a></td>
<td>returns an element of an array</td>
</tr>

<tr>
<td ><a href="#rest">rest</a></td>
<td>returns all but the first row of an array</td>
</tr>

<tr>
<td><a href="#setf">setf</a></td>
<td>sets contents of an array reference</td>
</tr>

<tr>
<td ><a href="#slice">slice</a></td>
<td>returns a slice of an array</td>
</tr>

<tr>
<td ><a href="#transpose">transpose</a></td>
<td>transposes a matrix</td>
</tr>
</table><br/>

<a name="bit_operators"></a>
<h3>Bit operators</h3>

<table border="0" cellpadding="1" width="95%" align="center" summary="bit operators">


<tr>
<td WIDTH="16%"><a href="#bit_shift">&lt;&lt;, &gt;&gt;</a>&nbsp;&nbsp;&nbsp;</td>
<td WIDTH="84%">bit shift left, bit shift right</td>
</tr>

<tr>
<td><a href="#bit_and">&amp;</a></td>
<td>bitwise and</td>
</tr>

<tr>
<td><a href="#bit_inclusive">|</a></td>
<td>bitwise inclusive or</td>

</tr>

<tr>
<td><a href="#bit_exclusive">^</a></td>
<td>bitwise exclusive or</td>
</tr>

<tr>
<td><a href="#bit_not">~</a></td>
<td>bitwise not</td>
</tr>
</table><br/>

<a name="predicates"></a>
<h3>Predicates</h3>

<table border="0" cellpadding="1" width="95%" align="center" summary="Predicates">

<tr>
<td width="16%"><a href="#atomp">atom?</a></td>
<td width="84%">checks if an expression is an atom</td>
</tr>

<tr>
<td><a href="#arrayp">array?</a></td>
<td>checks if an expression is an array</td>
</tr>

<tr>
<td><a href="#bigintp">bigint?</a></td>
<td>checks if a number is a big integer</td>
</tr>

<tr>
<td><a href="#contextp">context?</a></td>
<td>checks if an expression is a context</td>
</tr>

<tr>
<td><a href="#directoryp">directory?</a></td>
<td>checks if a disk node is a directory</td>
</tr>

<tr>
<td><a href="#emptyp">empty?</a></td>
<td>checks if a list or string is empty</td>
</tr>

<tr>
<td><a href="#evenp">even?</a></td>
<td>checks the parity of an integer number</td>
</tr>

<tr>
<td><a href="#filep">file?</a></td>
<td>checks if a file exists</td>
</tr>

<tr>
<td><a href="#floatp">float?</a></td>
<td>checks if an expression is a float</td>
</tr>

<tr>
<td><a href="#globalp">global?</a></td>
<td>checks if a symbol is global</td>
</tr>

<tr>
<td><a href="#infp">inf?</a></td>
<td>checks if a floating point value is infinite</td>
</tr>

<tr>
<td><a href="#integerp">integer?</a></td>
<td>checks if an expression is an integer</td>
</tr>

<tr>
<td><a href="#lambdap">lambda?</a></td>
<td>checks if an expression is a lambda expression</td>
</tr>

<tr>
<td><a href="#legalp">legal?</a></td>
<td>checks if a string contains a legal symbol</td>
</tr>

<tr>
<td><a href="#listp">list?</a></td>
<td>checks if an expression is a list</td>
</tr>

<tr>
<td><a href="#macrop">macro?</a></td>
<td>checks if an expression is a lambda-macro expression</td>
</tr>

<tr>
<td><a href="#NaNp">NaN?</a></td>
<td>checks if a float is NaN (not a number)</td>
</tr>

<tr>
<td><a href="#nilp">nil?</a></td>
<td>checks if an expression is <tt>nil</tt></td>
</tr>

<tr>
<td><a href="#nullp">null?</a></td>
<td>checks if an expression is <tt>nil</tt>, <tt>""</tt>, <tt>()</tt>, <tt>0</tt> or <tt>0.0</tt></td>
</tr>

<tr>
<td><a href="#numberp">number?</a></td>
<td>checks if an expression is a float or an integer</td>
</tr>

<tr>
<td><a href="#oddp">odd?</a></td>
<td>checks the parity of an integer number</td>
</tr>

<tr>
<td><a href="#protectedp">protected?</a></td>
<td>checks if a symbol is protected</td>
</tr>

<tr>
<td><a href="#primitivep">primitive?</a></td>
<td>checks if an expression is a primitive</td>
</tr>

<tr>
<td><a href="#quotep">quote?</a></td>
<td>checks if an expression is quoted</td>
</tr>

<tr>
<td><a href="#stringp">string?</a></td>
<td>checks if an expression is a string</td>
</tr>

<tr>
<td><a href="#symbolp">symbol?</a></td>
<td>checks if an expression is a symbol</td>
</tr>

<tr>
<td><a href="#truep">true?</a></td>
<td>checks if an expression is not <tt>nil</tt></td>
</tr>

<tr>
<td><a href="#zerop">zero?</a></td>
<td>checks if an expression is <tt>0</tt> or <tt>0.0</tt></td>
</tr>

</table><br/>

<a name="timedate"></a>
<h3>Date and time functions</h3>

<table border="0" cellpadding="1" width="95%" align="center" summary="Time and date functions">

<tr>
<td WIDTH="16%"><a href="#date">date</a></td>
<td WIDTH="84%">converts a date-time value to a string</td>
</tr>

<tr>
<td><a href="#date-list">date-list</a></td>
<td>returns a list of year, month, day, hours, minutes, seconds from a time value in seconds</td>
</tr>

<tr>
<td><a href="#date-parse">date-parse</a></td>
<td>parses a date string and returns the number of seconds passed since January 1, 1970, (formerly <tt>parse-date</tt>)</td>
</tr>

<tr>
<td><a href="#date-value">date-value</a></td>
<td>calculates the time in seconds since January 1, 1970 for a date and time</td>
</tr>

<tr>
<td><a href="#now">now</a></td>
<td>returns a list of current date-time information</td>
</tr>

<tr>
<td><a href="#time">time</a></td>
<td>calculates the time it takes to evaluate an expression in milliseconds</td>
</tr>

<tr>
<td><a href="#time-of-day">time-of-day</a></td>
<td>calculates the number of milliseconds elapsed since the day started</td>
</tr>

</table><br/>

<a name="montecarlo"></a>
<h3>Statistics, simulation and modeling functions</h3>


<table border="0" cellpadding="1" width="95%" align="center" summary="Statistics, simulation and modelling math functions">


<tr>
<td width="16%"><a href="#amb">amb</a></td>
<td width="84%">randomly selects an argument and evaluates it</td>
</tr>

<tr>
<td width="16%"><a href="#bayes-query">bayes-query</a></td>
<td width="84%">calculates Bayesian probabilities for a data set</td>
</tr>

<tr>
<td width="16%"><a href="#bayes-train">bayes-train</a></td>
<td width="84%">counts items in lists for Bayesian or frequency analysis</td>
</tr>

<tr>
<td><a href="#corr">corr</a></td>
<td>calculates the <em>product-moment correlation</em> coefficient</td>
</tr>

<tr>
<td><a href="#crit-chi2">crit-chi2</a></td>
<td>calculates the <em>Chi&sup2;</em> statistic for a given probability</td>
</tr>

<tr>
<td><a href="#crit-f">crit-f</a></td>
<td>calculates the <em>F</em> statistic for a given probability</td>
</tr>

<tr>
<td><a href="#crit-t">crit-t</a></td>
<td>calculates the <em>Student's t</em> statistic for a given probability</td>
</tr>

<tr>
<td><a href="#crit-z">crit-z</a></td>
<td>calculates the normal distributed <em>Z</em> for a given probability</td>
</tr>

<tr>
<td><a href="#kmeans-query">kmeans-query</a></td>
<td>calculates distances to cluster centroids or other data points</td>
</tr>

<tr>
<td><a href="#kmeans-train">kmeans-train</a></td>
<td>partitions a data set into clusters</td>
</tr>

<tr>
<td><a href="#normal">normal</a></td>
<td>makes a list of normal distributed floating point numbers</td>
</tr>

<tr>
<td><a href="#prob-chi2">prob-chi2</a></td>
<td>calculates the tail probability of a <em>Chi&sup2;</em> distribution value</td>
</tr>

<tr>
<td><a href="#prob-f">prob-f</a></td>
<td>calculates the tail probability of a <em>F</em> distribution value</td>
</tr>

<tr>
<td><a href="#prob-t">prob-t</a></td>
<td>calculates the tail probability of a <em>Student's t</em> distribution value</td>
</tr>

<tr>
<td><a href="#prob-z">prob-z</a></td>
<td>calculates the cumulated probability of a <em>Z</em> distribution value</td>
</tr>

<tr>
<td><a href="#rand">rand</a></td>
<td>generates random numbers in a range</td>
</tr>

<tr>
<td><a href="#random">random</a></td>
<td>generates a list of evenly distributed floats</td>
</tr>

<tr>
<td><a href="#randomize">randomize</a></td>
<td>shuffles all of the elements in a list</td>
</tr>

<tr>
<td><a href="#seed">seed</a></td>
<td>seeds the internal random number generator</td>
</tr>

<tr>
<td><a href="#stats">stats</a></td>
<td>calculates some basic statistics for a data vector</td>
</tr>

<tr>
<td><a href="#t-test">t-test</a></td>
<td>compares means of data samples using the <em>Student's t</em> statistic</td>
</tr>

</table><br/>

<a name="pattern"></a>
<h3>Pattern matching</h3>


<table border="0" cellpadding="1" width="95%" align="center" summary="Time and date functions">

<tr>
<td><a href="#ends-with">ends-with</a></td>
<td>tests if a list or string ends with a pattern</td>
</tr>

<tr>
<td WIDTH="16%"><a href="#find">find</a></td>
<td WIDTH="84%">searches for a pattern in a list or string</td>
</tr>

<tr>
<td><a href="#find-all">find-all</a></td>
<td>finds all occurrences of a pattern in a string</td>
</tr>

<tr>
<td><a href="#match">match</a></td>
<td>matches list patterns</td>
</tr>

<tr>
<td><a href="#parse">parse</a></td>
<td>breaks a string along around patterns</td>
</tr>

<tr>
<td><a href="#ref">ref</a></td>
<td>returns the position of an element inside a nested list</td>
</tr>

<tr>
<td><a href="#ref-all">ref-all</a></td>
<td>returns a list of index vectors of elements inside a nested list</td>
</tr>

<tr>
<td><a href="#regex">regex</a></td>
<td>finds patterns in a string</td>
</tr>

<tr>
<td><a href="#replace">replace</a></td>
<td>replaces patterns in a string</td>
</tr>

<tr>
<td><a href="#search">search</a></td>
<td>searches for a pattern in a file</td>
</tr>

<tr>
<td><a href="#starts-with">starts-with</a></td>
<td>tests if a list or string starts with a pattern</td>
</tr>

<tr>
<td><a href="#unify">unify</a></td>
<td>performs a logical unification of patterns</td>
</tr>

</table><br/>

<a name="financial"></a>
<h3>Financial math functions</h3>


<table border="0" cellpadding="1" width="95%" align="center" summary="Financial math functions">

<tr>
<td WIDTH="16%"><a href="#fv">fv</a></td>
<td WIDTH="84%">returns the future value of an investment</td>
</tr>

<tr>
<td><a href="#irr">irr</a></td>
<td>calculates the internal rate of return</td>
</tr>

<tr>
<td><a href="#nper">nper</a></td>
<td>calculates the number of periods for an investment</td>
</tr>

<tr>
<td><a href="#npv">npv</a></td>
<td>calculates the net present value of an investment</td>
</tr>

<tr>
<td><a href="#pv">pv</a></td>

<td>calculates the present value of an investment</td>
</tr>

<tr>
<td><a href="#pmt">pmt</a></td>
<td>calculates the payment for a loan</td>
</tr>

</table><br/>

<a name="input_output"></a>
<h3>Input/output and file operations</h3>


<table border="0" cellpadding="1" width="95%" align="center" summary="Input/output and file operations">


<tr>
<td WIDTH="16%"><a href="#append-file">append-file</a></td>
<td WIDTH="84%">appends data to a file</td>
</tr>

<tr>
<td><a href="#close">close</a></td>
<td>closes a file</td>
</tr>

<tr>
<td><a href="#current-line">current-line</a></td>
<td>retrieves contents of last read-line buffer</td>
</tr>

<tr>
<td><a href="#device">device</a></td>
<td>sets or inquires about current print device</td>
</tr>

<tr>

<td><a href="#exec">exec</a></td>
<td>launches another program, then reads from or writes to it</td>
</tr>

<tr>
<td><a href="#load">load</a></td>
<td>loads and evaluates a file of newLISP code</td>
</tr>

<tr>
<td><a href="#open">open</a></td>
<td>opens a file for reading or writing</td>

</tr>

<tr>
<td><a href="#peek">peek</a></td>
<td>checks file descriptor for number of bytes ready for reading</td>
</tr>

<tr>
<td><a href="#print">print</a></td>
<td>prints to the console or a device</td>
</tr>

<tr>

<td><a href="#println">println</a></td>
<td>prints to the console or a device with a line-feed</td>
</tr>

<tr>
<td><a href="#read">read</a></td>
<td>reads binary data from a file</td>
</tr>

<tr>
<td><a href="#read-char">read-char</a></td>
<td>reads an 8-bit character from a file</td>
</tr>

<tr>
<td><a href="#read-file">read-file</a></td>
<td>reads a whole file in one operation</td>
</tr>

<tr>
<td><a href="#read-key">read-key</a></td>
<td>reads a keyboard key</td>
</tr>

<tr>
<td><a href="#read-line">read-line</a></td>
<td>reads a line from the console or file</td>
</tr>

<tr>
<td><a href="#read-utf8">read-utf8</a></td>
<td>reads UTF-8 character from a file</td>
</tr>

<tr>
<td><a href="#save">save</a></td>
<td>saves a workspace, context, or symbol to a file</td>
</tr>

<tr>
<td><a href="#search">search</a></td>
<td>searches a file for a string</td>

</tr>

<tr>
<td><a href="#seek">seek</a></td>
<td>sets or reads a file position</td>
</tr>

<tr>
<td><a href="#write">write</a></td>
<td>writes binary data to a file or string</td>
</tr>

<tr>

<td><a href="#write-char">write-char</a></td>
<td>writes a character to a file</td>
</tr>

<tr>
<td><a href="#write-file">write-file</a></td>
<td>writes a file in one operation</td>
</tr>

<tr>
<td><a href="#write-line">write-line</a></td>
<td>writes a line to the console or a file</td>
</tr>

</table><br/>

<a name="processes"></a>
<h3>Processes and the Cilk API</h3>


<table border="0" cellpadding="1" width="95%" align="center" summary="Processes and the Cilk API">

<tr>
<td WIDTH="16%"><a href="#shell">!</a></td>
<td WIDTH="84%">shells out to the operating system</td>
</tr>

<tr>
<td><a href="#abort">abort</a></td>
<td>aborts a child process started with <tt>spawn</tt></td>
</tr>

<tr>
<td><a href="#destroy">destroy</a></td>
<td>destroys a process created with <tt>fork</tt> or <tt>process</tt></td>
</tr>

<tr>
<td><a href="#exec">exec</a></td>
<td>runs a process, then reads from or writes to it</td>
</tr>

<tr>
<td><a href="#fork">fork</a></td>
<td>launches a newLISP child process</td>
</tr>

<tr>
<td><a href="#pipe">pipe</a></td>
<td>creates a pipe for interprocess communication</td>
</tr>

<tr>
<td><a href="#process">process</a></td>
<td>launches a child process, remapping standard I/O and standard error</td>
</tr>

<tr>
<td><a href="#receive">receive</a></td>
<td>receive a message from another process</td>
</tr>

<tr>
<td><a href="#semaphore">semaphore</a></td>
<td>creates and controls semaphores</td>
</tr>

<tr>
<td><a href="#send">send</a></td>
<td>send a message to another process</td>
</tr>


<tr>
<td><a href="#share">share</a></td>
<td>shares memory with other processes</td>
</tr>

<tr>
<td><a href="#spawn">spawn</a></td>
<td>launches a child process for Cilk process management</td>
</tr>

<tr>
<td><a href="#sync">sync</a></td>
<td>waits for child processes launched with <tt>spawn</tt> and collects results</td>
</tr>

<tr>
<td><a href="#wait-pid">wait-pid</a></td>
<td>waits for a child process to end</td>
</tr>

</table><br/>

<a name="directory_management"></a>
<h3>File and directory management</h3>


<table border="0" cellpadding="1" width="95%" align="center" summary="File and directory management">

<tr>
<td WIDTH="16%"><a href="#change-dir">change-dir</a>&nbsp;</td>
<td WIDTH="84%">changes to a different drive and directory</td>
</tr>

<tr>
<td><a href="#copy-file">copy-file</a></td>
<td>copies a file</td>
</tr>

<tr>
<td><a href="#delete-file">delete-file</a></td>
<td>deletes a file</td>
</tr>

<tr>
<td><a href="#directory">directory</a></td>
<td>returns a list of directory entries</td>
</tr>

<tr>
<td><a href="#file-info">file-info</a></td>
<td>gets file size, date, time, and attributes</td>
</tr>

<tr>
<td><a href="#make-dir">make-dir</a></td>
<td>makes a new directory</td>
</tr>

<tr>
<td><a href="#real-path">real-path</a></td>
<td>returns the full path of the relative file path</td>
</tr>

<tr>
<td><a href="#remove-dir">remove-dir</a></td>
<td>removes an empty directory</td>
</tr>

<tr>
<td><a href="#rename-file">rename-file</a></td>
<td>renames a file or directory</td>
</tr>

</table><br/>

<a name="http_api"></a>
<h3>HTTP networking API</h3>


<table border="0" cellpadding="1" width="95%" align="center" summary="HTTP networking API">


<tr>
<td width="16%"><a href="#base64-enc">base64-enc</a></td>
<td width="84%">encodes a string into BASE64 format</td>
</tr>

<tr>
<td><a href="#base64-dec">base64-dec</a></td>

<td>decodes a string from BASE64 format</td>
</tr>

<tr>
<td><a href="#delete-url">delete-url</a></td>
<td>deletes a file or page from the web</td>
</tr>

<tr>
<td><a href="#get-url">get-url</a></td>
<td>reads a file or page from the web</td>
</tr>

<tr>
<td><a href="#json-error">json-error</a></td>
<td>returns error information from a failed JSON translation.</td>
</tr>

<tr>
<td><a href="#json-parse">json-parse</a></td>
<td>parses JSON formatted data</td>
</tr>

<tr>
<td><a href="#post-url">post-url</a></td>
<td>posts info to a URL address</td>
</tr>

<tr>
<td><a href="#put-url">put-url</a></td>
<td>uploads a page to a URL address</td>
</tr>

<tr>
<td><a href="#xfer-event">xfer-event</a></td>
<td>registers an event handler for HTTP byte transfers</td>
</tr>

<tr>
<td><a href="#xml-error">xml-error</a></td>
<td>returns last XML parse error</td>
</tr>

<tr>
<td><a href="#xml-parse">xml-parse</a></td>

<td>parses an XML document</td>
</tr>

<tr>
<td><a href="#xml-type-tags">xml-type-tags</a>&nbsp;</td>
<td>shows or modifies XML type tags</td>
</tr>

</table><br/>

<a name="socket_tcpip"></a>
<h3>Socket TCP/IP, UDP and ICMP network API</h3>


<table border="0" cellpadding="1" width="95%" align="center" summary="Socket TCP/IP and UDP network API">


<tr>
<td WIDTH="16%"><a href="#net-accept">net-accept</a></td>
<td WIDTH="84%">accepts a new incoming connection</td>
</tr>

<tr>
<td><a href="#net-close">net-close</a></td>
<td>closes a socket connection</td>
</tr>

<tr>
<td><a href="#net-connect">net-connect</a></td>
<td>connects to a remote host</td>
</tr>

<tr>
<td><a href="#net-error">net-error</a></td>
<td>returns the last error</td>
</tr>

<tr>
<td><a href="#net-eval">net-eval</a></td>
<td>evaluates expressions on multiple remote newLISP servers</td>
</tr>

<tr>
<td><a href="#net-interface">net-interface</a></td>
<td>Sets the default interface IP address on multihomed computers.</td>
</tr>

<tr>
<td><a href="#net-ipv">net-ipv</a></td>
<td>Switches between IPv4 and IPv6 internet protocol versions.</td>
</tr>

<tr>
<td><a href="#net-listen">net-listen</a></td>
<td>listens for connections to a local socket</td>
</tr>

<tr>
<td><a href="#net-local">net-local</a></td>
<td>returns the local IP and port number for a connection</td>
</tr>

<tr>
<td><a href="#net-lookup">net-lookup</a></td>
<td>returns the name for an IP number</td>
</tr>

<tr>
<td><a href="#net-packet">net-packet</a></td>
<td>send a custom configured IP packet over raw sockets</td>
</tr>

<tr>
<td><a href="#net-peek">net-peek</a></td>
<td>returns the number of characters ready to be read from a network socket</td>
</tr>

<tr>
<td><a href="#net-peer">net-peer</a></td>
<td>returns the remote IP and port for a net connect</td>
</tr>


<tr>
<td><a href="#net-ping">net-ping</a></td>
<td>sends a ping packet (ICMP echo request) to one or more addresses</td>
</tr>

<tr>
<td><a href="#net-receive">net-receive</a></td>
<td>reads data on a socket connection</td>
</tr>

<tr>
<td><a href="#net-receive-from">net-receive-from</a>&nbsp;</td>
<td>reads a UDP on an open connection</td>
</tr>

<tr>
<td><a href="#net-receive-udp">net-receive-udp</a></td>
<td>reads a UDP and closes the connection</td>
</tr>

<tr>
<td><a href="#net-select">net-select</a></td>

<td>checks a socket or list of sockets for status</td>
</tr>

<tr>
<td><a href="#net-send">net-send</a></td>
<td>sends data on a socket connection</td>
</tr>

<tr>
<td><a href="#net-send-to">net-send-to</a></td>
<td>sends a UDP on an open connection</td>
</tr>

<tr>
<td><a href="#net-send-udp">net-send-udp</a></td>
<td>sends a UDP and closes the connection</td>
</tr>

<tr>
<td><a href="#net-service">net-service</a></td>
<td>translates a service name into a port number</td>
</tr>

<tr>
<td><a href="#net-sessions">net-sessions</a></td>

<td>returns a list of currently open connections </td>
</tr>

</table><br/>

<a name="JS"></a>
<h3>API for newLISP in a web browser</h3>

<table border="0" cellpadding="1" width="95%" align="center" summary="API for newLISP in a web browser">

<tr>
<td width="16%"><a href="#display-html">display-html</a></td>
<td width="84%">display an HTML page in a web browser</td>
</tr>

<tr>
<td><a href="#eval-string-js">eval-string-js</a></td>
<td>evaluate JavaScript in the current web browser page</td>
</tr>

</table><br/>


<a name="reflection"></a>
<h3>Reflection and customization</h3>

<table border="0" cellpadding="1" width="95%" align="center" summary="Reflection and customization">

<tr>
<td width="16%"><a href="#command-event">command-event</a></td>
<td width="84%">pre-processes the command-line and HTTP requests</td>
</tr>

<tr>
<td><a href="#error-event">error-event</a></td>
<td>defines an error handler</td>
</tr>

<tr>
<td><a href="#history">history</a></td>
<td>returns the call history of a function</td>
</tr>

<tr>
<td><a href="#last-error">last-error</a></td>
<td>report the last error number and text</td>
</tr>

<tr>
<td><a href="#macro">macro</a></td>
<td>create a reader expansion macro</td>
</tr>

<tr>
<td><a href="#ostype">ostype</a></td>
<td>contains a string describing the OS platform</td>
</tr>

<tr>
<td><a href="#prefix">prefix</a></td>
<td>Returns the context prefix of a symbol</td>
</tr>

<tr>
<td><a href="#prompt-event">prompt-event</a></td>
<td>customizes the interactive newLISP shell prompt</td>
</tr>

<tr>
<td><a href="#read-expr">read-expr</a></td>
<td>reads and translates s-expressions from source</td>
</tr>

<tr>
<td><a href="#reader-event">reader-event</a></td>
<td>preprocess expressions before evaluation event-driven</td>
</tr>

<tr>
<td><a href="#set-locale">set-locale</a></td>
<td>switches to a different locale</td>
</tr>

<tr>
<td><a href="#source">source</a></td>
<td>returns the source required to bind a symbol to a string</td>
</tr>

<tr>
<td><a href="#sys-error">sys-error</a></td>
<td>reports OS system error numbers</td>
</tr>

<tr>
<td><a href="#sys-info">sys-info</a></td>
<td>gives information about system resources</td>
</tr>

<tr>
<td><a href="#term">term</a></td>
<td>returns the term part of a symbol or its context as a string</td>
</tr>

</table><br/>

<a name="system_functions"></a>
<h3>System functions</h3>


<table border="0" cellpadding="1" width="95%" align="center" summary="System functions">

<tr>
<td width="16%"><a href="#systemsymbol">$</a></td>
<td width="84%">accesses system variables $0 -&gt; $15</td>
</tr>

<tr>
<td><a href="#callback">callback</a></td>
<td>registers a callback function for an imported library</td>
</tr>

<tr>
<td><a href="#catch">catch</a></td>
<td>evaluates an expression, catching errors and early returns</td>
</tr>

<tr>
<td><a href="#context">context</a></td>
<td>creates or switches to a different namespace</td>
</tr>

<tr>
<td><a href="#copy">copy</a></td>
<td>copies the result of an evaluation</td>
</tr>

<tr>
<td><a href="#debug">debug</a></td>
<td>debugs a user-defined function</td>
</tr>

<tr>
<td><a href="#delete">delete</a></td>
<td>deletes symbols from the symbol table</td>
</tr>

<tr>
<td><a href="#default">default</a></td>
<td>returns the contents of a default functor from a context</td>
</tr>

<tr>
<td><a href="#env">env</a></td>
<td>gets or sets the operating system's environment</td>
</tr>

<tr>
<td><a href="#exit">exit</a></td>
<td>exits newLISP, setting the exit value</td>
</tr>

<tr>
<td><a href="#global">global</a></td>
<td>makes a symbol accessible outside MAIN</td>
</tr>

<tr>
<td><a href="#import">import</a></td>
<td>imports a function from a shared library</td>
</tr>

<tr>
<td><a href="#main-args">main-args</a></td>
<td>gets command-line arguments</td>
</tr>

<tr>
<td><a href="#new">new</a></td>
<td>creates a copy of a context</td>
</tr>

<tr>
<td><a href="#pretty-print">pretty-print</a></td>
<td>changes the pretty-printing characteristics</td>
</tr>

<tr>
<td><a href="#read-expr">read-expr</a></td>
<td>translates a string to an s-expression without evaluating it</td>
</tr>

<tr>
<td><a href="#reset">reset</a></td>
<td>goes to the top level</td>
</tr>

<tr>
<td><a href="#signal">signal</a></td>
<td>sets a signal handler</td>
</tr>

<tr>
<td><a href="#sleep">sleep</a></td>
<td>suspends processing for specified milliseconds</td>
</tr>

<tr>
<td><a href="#sym">sym</a></td>
<td>creates a symbol from a string</td>
</tr>

<tr>
<td><a href="#symbols">symbols</a></td>
<td>returns a list of all symbols in the system</td>
</tr>

<tr>
<td><a href="#throw">throw</a></td>
<td>causes a previous <a href="#catch">catch</a> to return</td>
</tr>

<tr>
<td><a href="#throw-error">throw-error</a></td>
<td>throws a user-defined error</td>
</tr>

<tr>
<td><a href="#timer">timer</a></td>
<td>starts a one-shot timer, firing an event</td>
</tr>

<tr>
<td><a href="#trace">trace</a></td>
<td>sets or inquires about trace mode</td>
</tr>

<tr>
<td><a href="#trace-highlight">trace-highlight</a></td>
<td>sets highlighting strings in trace mode</td>
</tr>

</table><br/>

<a name="importing_libraries"></a>
<h3>Importing libraries</h3>


<table border="0" cellpadding="1" width="95%" align="center" summary="Importing libraries<">


<tr>
<td WIDTH="16%"><a href="#address">address</a></td>
<td WIDTH="84%">returns the memory address of a number or string</td>

</tr>

<tr>
<td><a href="#callback">callback</a></td>
<td>registers a callback function for an imported library</td>
</tr>

<tr>
<td><a href="#flt">flt</a></td>
<td>converts a number to a 32-bit integer representing a float</td>
</tr>

<tr>
<td><a href="#float">float</a></td>
<td>translates a string or integer into a floating point number</td>
</tr>

<tr>

<td><a href="#get-char">get-char</a></td>
<td>gets a character from a memory address</td>
</tr>

<tr>
<td><a href="#get-float">get-float</a></td>
<td>gets a double float from a memory address</td>
</tr>

<tr>
<td><a href="#get-int">get-int</a>&nbsp;&nbsp;</td>
<td>gets a 32-bit integer from a memory address</td>
</tr>

<tr>
<td><a href="#get-long">get-long</a>&nbsp;&nbsp;</td>
<td>gets a long 64-bit integer from a memory address</td>
</tr>

<tr>
<td><a href="#get-string">get-string</a></td>
<td>gets a string from a memory address</td>
</tr>

<tr>
<td><a href="#import">import</a></td>
<td>imports a function from a shared library</td>
</tr>

<tr>

<td><a href="#int">int</a></td>
<td>translates a string or float into an integer</td>
</tr>

<tr>
<td><a href="#pack">pack</a></td>
<td>packs newLISP expressions into a binary structure</td>
</tr>

<tr>
<td><a href="#struct">struct</a></td>
<td>Defines a data structure with C types</td>
</tr>

<tr>
<td><a href="#unpack">unpack</a></td>
<td>unpacks a binary structure into newLISP expressions</td>

</tr>
</table><br/>

<a name="internals"></a>
<h3>newLISP internals API</h3>


<table border="0" cellpadding="1" width="95%" align="center" summary="newLISP internals API">

<tr>
<td width="16%"><a href="#command-event">command-event</a></td>
<td width="84%">pre-processes the command-line and HTTP requests</td>
</tr>

<tr>
<td><a href="#cpymem">cpymem</a></td>
<td>copies memory between addresses</td>
</tr>

<tr>
<td><a href="#dump">dump</a></td>
<td>shows memory address and contents of newLISP cells</td>
</tr>

<tr>
<td><a href="#prompt-event">prompt-event</a></td>
<td>customizes the interactive newLISP shell prompt</td>
</tr>

<tr>
<td><a href="#read-expr">read-expr</a></td>
<td>reads and translates s-expressions from source</td>
</tr>

<tr>
<td><a href="#reader-event">reader-event</a></td>
<td>preprocess expressions before evaluation event-driven</td>
</tr>


</table><br/>

<br/>

<center>
<span class="divider">(&nbsp;<font color="#7ba9d4">&sect;</font>&nbsp;)</span>
</center>

<br/>

<a name="functions_alphabetical"></a>
<h2>4. Functions in alphabetical order</h2>

<br/>

<a name="shell"></a>
<h2><span class="function">!</span></h2>
<h4>syntax: (! <em>str-shell-command</em> [<em>int-flags</em>])</h4>

<p>Executes the command in <em>str-command</em> by shelling out to the 
operating system and executing.  This function returns a different value
depending on the host operating system.</p>

<!-- example -->

<pre>
(! "vi")  
(! "ls -ltr")
</pre>

<p>Use the <a href="#exec">exec</a> function to execute a shell command 
and capture the standard output or to feed standard input. 
The <a href="#process">process</a> function may be used to launch a 
non-blocking child process and redirect std I/O and std error to pipes.</p>

<p>On Ms Windows the optional <em>int-flags</em> parameter takes process
creation flags as defined for the Windows <tt>CreateProcessA</tt> function
to control various parameters of process creation. The inclusion of this
parameter &ndash; which also can be <tt>0</tt> &ndash; forces a different 
creation of the process without a command shell window. This parameter is 
ignored on Unix.</p>

<pre>
; on MS Windows
; close the console of the currently running newLISP process
(apply (import "kernel32" "FreeConsole")) 

; start another process and wait for it to finish
(! "notepad.exe" 0)

(exit)
</pre>

<p>Without the additional parameter, the <tt>!</tt> call would create a
new command window replacing the closed one.</p>

<p>Note that <tt>!</tt> (exclamation mark) can be also be used as 
a command-line shell operator by omitting the parenthesis and space 
after the <tt>!</tt>:</p>

<!-- example -->

<pre>
<b>&gt;</b> !ls -ltr    ; executed in the newLISP shell window
</pre>


<p>
	Used in this way, 
	the <tt>!</tt> operator 
	is not a newLISP function at all, 
	but rather a special feature of 
	the newLISP command shell. 
	The <tt>!</tt> must be entered 
	as the first character
	on the command-line.
</p>

<br/><br/>

<a name="systemsymbol"></a>
<h2><span class="function">$</span></h2>
<h4>syntax: ($ <em>int-idx</em>)</h4>

<p>
The functions that use regular expressions 	(<a href="#directory">directory</a>,
<a href="#ends-with">ends-with</a>, <a href="#find">find</a>, <a href="#find-all">find-all</a>, 
<a href="#parse">parse</a>, <a href="#regex">regex</a>, <a href="#search">search</a>, 
<a href="#starts-with">starts-with</a> and <a href="#replace">replace</a>) 
all bind their results to the predefined system variables <tt>$0</tt>, <tt>$1</tt>, 
<tt>$2</tt>&ndash;<tt>$15</tt> after or during the function's execution. System variables 
can be treated the same as any other symbol. As an alternative, the contents of these 
variables may also be accessed by using <tt>($ 0)</tt>, <tt>($ 1)</tt>, <tt>($ 2)</tt>, 
etc. This method allows indexed access (i.e., <tt>($ i)</tt>, where <tt>i</tt> is an integer).</p>

<!-- example -->

<pre>
(set 'str  "http://newlisp.org:80")
(find "http://(.*):(.*)" str 0)  <span class='arw'>&rarr;</span> 0
                                 
$0  <span class='arw'>&rarr;</span> "http://newlisp.org:80"
$1  <span class='arw'>&rarr;</span> "newlisp.org"
$2  <span class='arw'>&rarr;</span> "80"
                                 
($ 0)  <span class='arw'>&rarr;</span> "http://newlisp.org:80"
($ 1)  <span class='arw'>&rarr;</span> "newlisp.org"
($ 2)  <span class='arw'>&rarr;</span> "80"
</pre>

<br/><br/>

<a name="arithmetic"></a>
<h2><span class="function">+, -, *, / ,%</span>&nbsp;
<a href="#big_int"><font size="-1">bigint</font></a></h2>
<h4>syntax: (+ <em>int-1</em> [<em>int-2</em> ... ])</h4>

<p>Returns the sum of all numbers in <em>int-1</em> &mdash;.</p>

<h4>syntax: (- <em>int-1</em> [<em>int-2</em> ... ])</h4>

<p>Subtracts <em>int-2</em> from <em>int-1</em>, then the next <em>int-i</em> 
from the previous result. If only one argument is given, 
its sign is reversed. </p>

<h4>syntax: (* <em>int-1</em> [<em>int-2</em> ... ])</h4>

<p>The product is calculated for <em>int-1</em> to <em>int-i</em>.</p>

<h4>syntax: (/ <em>int-1</em> [<em>int-2</em> ... ])</h4>

<p>Each result is divided successively until the end of the list is reached. 
Division by zero causes an error.</p>

<h4>syntax: (% <em>int-1</em> [<em>int-2</em> ... ])</h4>

<p>Each result is divided successively by the next <em>int</em>, 
then the rest (modulo operation) is returned. Division by zero causes an error. 
For floating point numbers, use the <a href="#mod">mod</a> function.</p>

<!-- example -->

<pre>
(+ 1 2 3 4 5)        <span class='arw'>&rarr;</span> 15
(+ 1 2 (- 5 2) 8)    <span class='arw'>&rarr;</span> 14
(- 10 3 2 1)         <span class='arw'>&rarr;</span> 4
(- (* 3 4) 6 1 2)    <span class='arw'>&rarr;</span> 3
(- 123)              <span class='arw'>&rarr;</span> -123
(map - '(10 20 30))  <span class='arw'>&rarr;</span> (-10 -20 -30)
(* 1 2 3)            <span class='arw'>&rarr;</span> 6
(* 10 (- 8 2))       <span class='arw'>&rarr;</span> 60
(/ 12 3)             <span class='arw'>&rarr;</span> 4
(/ 120 3 20 2)       <span class='arw'>&rarr;</span> 1
(% 10 3)             <span class='arw'>&rarr;</span> 1
(% -10 3)            <span class='arw'>&rarr;</span> -1
(+ 1.2 3.9)          <span class='arw'>&rarr;</span> 4
</pre>


<p>Floating point values in arguments to 
<tt>+</tt>, <tt>-</tt>, <tt>*</tt>, <tt>/</tt>, and <tt>%</tt> 
are truncated to the integer value closest to <tt>0</tt> (zero).
</p>

<p>
Floating point values larger or smaller than
the maximum (<tt>9,223,372,036,854,775,807</tt>)
or minimum (<tt>-9,223,372,036,854,775,808</tt>) integer values 
are truncated to those values. This includes the values for
<tt>+Inf</tt> and <tt>-Inf</tt>.
</p>

<p>
Calculations resulting in values 
larger than <tt>9,223,372,036,854,775,807</tt> 
or smaller than <tt>-9,223,372,036,854,775,808</tt> 
wrap around from positive to negative 
or negative to positive.
</p>

<p>
Floating point values that evaluate to <tt>NaN</tt> (Not a Number), 
ar treated as <tt>0</tt> (zero). 
</p>

<br/><br/>

<a name="inci"></a>
<h2><span class="function">++</span>&nbsp;<a href="#destructive">!</a>&nbsp;
<a href="#big_int"><font size="-1">bigint</font></a></h2>
<h4>syntax: (++ <em>place</em> [<em>num</em> ... ])</h4>

<p>The <tt>++</tt> operator works like <a href="#inc">inc</a>, but performs
integer arithmetic. Without the optional argument in <em>num</em>,
<tt>++</tt> increments the number in <em>place</em> by <tt>1</tt>.</p>

<p>If floating point numbers are passed as arguments, their fractional part
gets truncated first.</p>

<p>Calculations resulting in numbers greater than 9,223,372,036,854,775,807 wrap 
around to negative numbers.  Results smaller than -9,223,372,036,854,775,808 
wrap around to positive numbers.</p>

<p><em>place</em> is either a symbol or a place in a list structure holding a
number, or a number returned by an expression.</p>

<!-- example -->

<pre>
(set 'x 1)    
(++ x)        <span class='arw'>&rarr;</span> 2
(set 'x 3.8)
(++ x)        <span class='arw'>&rarr;</span> 4
(++ x 1.3)    <span class='arw'>&rarr;</span> 5
(set 'lst '(1 2 3))
(++ (lst 1) 2))  <span class='arw'>&rarr;</span> 4
lst              <span class='arw'>&rarr;</span> (1 4 3)
</pre>

<p>If the symbol for <em>place</em> contains <tt>nil</tt>, it is treated
as if containing <tt>0</tt>.</p>

<p>See <a href="#deci">--</a> for decrementing numbers in integer mode.
See <a href="#inc">inc</a> for incrementing numbers in floating point mode.</p>

<br/><br/>

<a name="deci"></a>
<h2><span class="function">--</span>&nbsp;<a href="#destructive">!</a>&nbsp;
<a href="#big_int"><font size="-1">bigint</font></a></h2>
<h4>syntax: (-- <em>place</em> [<em>num</em> ... ])</h4>

<p>The <tt>--</tt> operator works like <a href="#inc">dec</a>, but performs
integer arithmetic. Without the optional argument in <em>num-2</em>,
<tt>--</tt> decrements the number in <em>place</em> by <tt>1</tt>.</p>

<p>If floating point numbers are passed as arguments, their fractional part
gets truncated first.</p>

<p>Calculations resulting in numbers greater than 9,223,372,036,854,775,807 wrap 
around to negative numbers.  Results smaller than -9,223,372,036,854,775,808 
wrap around to positive numbers.</p>

<p><em>place</em> is either a symbol or a place in a list structure holding a
number, or a number returned by an expression.</p>

<!-- example -->

<pre>
(set 'x 1)    
(-- x)        <span class='arw'>&rarr;</span> 0
(set 'x 3.8)
(-- x)        <span class='arw'>&rarr;</span> 2
(-- x 1.3)    <span class='arw'>&rarr;</span> 1

(set 'lst '(1 2 3))
(-- (lst 1) 2))  <span class='arw'>&rarr;</span> 0
lst              <span class='arw'>&rarr;</span> (1 0 3)
</pre>

<p>If the symbol for <em>place</em> contains <tt>nil</tt>, it is treated
as if containing <tt>0</tt>.</p>

<p>See <a href="#inci">++</a> for incrementing numbers in integer mode.
See <a href="#dec">dec</a> for decrementing numbers in floating point mode.</p>

<br/><br/>
<a name="logical"></a>
<h2><span class="function">&lt;, &gt;, =, &lt;=, &gt;=, !=</span>&nbsp;
<a href="#big_int"><font size="-1">bigint</font></a></h2>
<h4>syntax: (&lt; <em>exp-1</em> [<em>exp-2</em> ... ])<br/>
syntax: (&gt; <em>exp-1</em> [<em>exp-2</em> ... ])<br/>
syntax: (= <em>exp-1</em> [<em>exp-2</em> ... ])<br/>
syntax: (&lt;= <em>exp-1</em> [<em>exp-2</em> ... ])<br/>
syntax: (&gt;= <em>exp-1</em> [<em>exp-2</em> ... ])<br/>
syntax: (!= <em>exp-1</em> [<em>exp-2</em> ... ])</h4>

<p>
Expressions are evaluated and the results are compared successively. 
As long as the comparisons conform to the comparison operators, 
evaluation and comparison will continue until all arguments are tested 
and the result is <tt>true</tt>. As soon as one comparison fails, 
<tt>nil</tt> is returned.
</p>

<p>If only one argument is supplied, all comparison operators assume <tt>0</tt> (zero)
as a second argument. This can be used to check if a number is negative, positive, zero 
or not zero.</p>


<p>
All types of expressions can be compared: 
	atoms, numbers, symbols, and strings. 
	List expressions can also be compared 
	(list elements are compared recursively).
</p>

<p>
	When comparing lists, 
	elements at the beginning of the list 
	are considered more significant than the elements following 
	(similar to characters in a string). 
	When comparing lists of different lengths but equal elements, 
	the longer list is considered greater (see examples).
</p>

<p>
	In mixed-type expressions, 
	the types are compared from lowest to highest. 
	Floats and integers are compared by first
	converting them to the needed type, 
	then comparing them as numbers.
</p>

<blockquote>
<b>Atoms:</b> nil, true, integer or float, string, symbol, primitive<br/>
<b>Lists:</b> quoted list/expression, list/expression, lambda, lambda-macro
</blockquote>

<!-- example -->
<pre>
(&lt; 3 5 8 9)                     <span class='arw'>&rarr;</span> true
(&gt; 4 2 3 6)                     <span class='arw'>&rarr;</span> nil
(&lt; "a" "c" "d")                 <span class='arw'>&rarr;</span> true
(&gt;= duba aba)                   <span class='arw'>&rarr;</span> true
(&lt; '(3 4) '(1 5))               <span class='arw'>&rarr;</span> nil
(&gt; '(1 2 3) '(1 2))             <span class='arw'>&rarr;</span> true
(= '(5 7 8) '(5 7 8))           <span class='arw'>&rarr;</span> true
(!= 1 4 3 7 3)                  <span class='arw'>&rarr;</span> true
(&lt; 1.2 6 "Hello" 'any '(1 2 3))           <span class='arw'>&rarr;</span> true
(&lt; nil true)                              <span class='arw'>&rarr;</span> true
(&lt; '(((a b))) '(((b c))))                 <span class='arw'>&rarr;</span> true
(&lt; '((a (b c)) '(a (b d)) '(a (b (d)))))  <span class='arw'>&rarr;</span> true

; with single argument compares against 0

(&gt; 1)    <span class='arw'>&rarr;</span> true ; checks for positive
(&gt; -1)   <span class='arw'>&rarr;</span> nil ; checks for negative
(= 123)  <span class='arw'>&rarr;</span> nil ; checks for zero

(map &gt; '(1 3 -4 -3 1 2))   <span class='arw'>&rarr;</span> (true true nil nil true true)
</pre>

<br/><br/>

<a name="bit_shift"></a>
<h2><span class="function">&lt;&lt;, &gt;&gt;</span></h2>
<h4>syntax: (&lt;&lt; <em>int-1</em> <em>int-2</em> [<em>int-3</em> ... ])<br/>

syntax: (&gt;&gt; <em>int-1</em> <em>int-2</em> [<em>int-3</em> ... ])<br/>

syntax: (&lt;&lt; <em>int-1</em>)<br/>
syntax: (&gt;&gt; <em>int-1</em>)</h4>

<p>
	The number <em>int-1</em> is arithmetically shifted 
	to the left or right by the number of bits given as <em>int-2</em>, 
	then shifted by <em>int-3</em> and so on. 
	For example, 64-bit integers may be shifted up to 63 positions. 
	When shifting right, 
	the most significant bit is duplicated 
	(<em>arithmetic shift</em>):
</p>


<pre>
(&gt;&gt; 0x8000000000000000 1)  <span class='arw'>&rarr;</span> 0xC000000000000000  ; not 0x0400000000000000!
</pre>

<br/>
<!-- example -->

<pre>
(&lt;&lt; 1 3)      <span class='arw'>&rarr;</span>  8
(&lt;&lt; 1 2 1)    <span class='arw'>&rarr;</span>  8
(&gt;&gt; 1024 10)  <span class='arw'>&rarr;</span>  1
(&gt;&gt; 160 2 2)  <span class='arw'>&rarr;</span> 10

(&lt;&lt; 3)        <span class='arw'>&rarr;</span>  6
(&gt;&gt; 8)        <span class='arw'>&rarr;</span>  4
</pre>


<p>When <em>int-1</em> is the only argument <tt>&lt;&lt;</tt>
and <tt>&gt;&gt;</tt> shift by one bit.
</p>

<br/><br/>

<a name="bit_and"></a>
<h2><span class="function">&amp;</span></h2>
<h4>syntax: (&amp; <em>int-1</em> <em>int-2</em> [<em>int-3</em> ... ])</h4>

<p>
	A bitwise <tt>and</tt> operation is performed 
	on the number in <em>int-1</em> with the number in <em>int-2</em>, 
	then successively with <em>int-3</em>, etc.
</p>

<!-- example -->

<pre>
(&amp; 0xAABB 0x000F)  <span class='arw'>&rarr;</span> 11  ; which is 0xB
</pre>

<br/><br/>

<a name="bit_inclusive"></a>
<h2><span class="function">|</span></h2>
<h4>syntax: (| <em>int-1</em> <em>int-2</em> [<em>int-3</em> ... ])</h4>

<p>
	A bitwise <tt>or</tt> operation is performed 
	on the number in <em>int-1</em> with the number in <em>int-2</em>, 
	then successively with <em>int-3</em>, etc.
</p>

<!-- example -->

<pre>
(| 0x10 0x80 2 1)  <span class='arw'>&rarr;</span> 147
</pre>

<br/><br/>

<a name="bit_exclusive"></a>
<h2><span class="function">^</span></h2>
<h4>syntax: (^ <em>int-1</em> <em>int-2</em> [<em>int-3</em> ... ])</h4>

<p>
	A bitwise <tt>xor</tt> operation is performed 
	on the number in <em>int-1</em> with the number in <em>int-2</em>, 
	then successively with <em>int-3</em>, etc.
</p>

<!-- example -->

<pre>
(^ 0xAA 0x55)  <span class='arw'>&rarr;</span> 255
</pre>

<br/><br/>

<a name="bit_not"></a>
<h2><span class="function">~</span></h2>
<h4>syntax: (~ <em>int</em>)</h4>

<p>
	A bitwise <tt>not</tt> operation is performed 
	on the number in <em>int</em>,
	reversing all of the bits.
</p>

<!-- example -->

<pre>
(format "%X" (~ 0xFFFFFFAA))  <span class='arw'>&rarr;</span> "55"
(~ 0xFFFFFFFF)                <span class='arw'>&rarr;</span> 0
</pre>

<br/><br/>

<a name="colon"></a>
<h2><span class="function">:</span></h2>
<h4>syntax: (: <em>sym-function</em> <em>list-object</em> [ ... ])</h4>

<p>The colon is used not only as a syntactic separator between
namespace prefix  and the term inside but also as an operator.
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>

<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.
The class context implements the functions applicable to the object. 
No space is required between the colon and the symbol following it.</p>

<!-- example -->

<pre>
(define (Rectangle:area)
    (mul (self 3) (self 4)))

(define (Circle:area)
    (mul (pow (self 3) 2) (acos 0) 2))

(define (Rectangle:move dx dy)
    (inc (self 1) dx) 
	(inc (self 2) dy)) 

(define (Circle:move p dx dy)
    (inc (self 1) dx) (inc (self 2) dy)) 

(set 'myrect '(Rectangle 5 5 10 20)) ; x y width height
(set 'mycircle '(Circle 1 2 10)) ; x y radius

;; using the : (colon) operator to resolve to a specific context

(:area myrect)     <span class='arw'>&rarr;</span> 200
(:area mycircle)   <span class='arw'>&rarr;</span> 314.1592654

;; map class methods uses curry to enclose the colon operator and class function

(map (curry :area) (list myrect mycircle)) <span class='arw'>&rarr;</span> (200 314.1592654)

(map (curry :area) '((Rectangle 5 5 10 20) (Circle 1 2 10))) <span class='arw'>&rarr;</span> (200 314.1592654) 

;; change object attributes using a function and re-assigning
;; to the objects name

(:move myrect 2 3)       
myrect   <span class='arw'>&rarr;</span> (Rectangle 7 8 10 20)

(:move mycircle 4 5)   
mycircle <span class='arw'>&rarr;</span> (Circle 5 7 10)
</pre>

<p>Inside the FOOP methods the <a href="#self">self</a> function is used to access
the target object of the method.</p>

<br/><br/>

<a name="abort"></a>
<h2><span class="function">abort</span></h2>
<h4>syntax: (abort <em>int-pid</em>)<br/>
syntax: (abort)</h4>

<p>In the first form, <tt>abort</tt> aborts a specific child process of the
current parent process giving the process id in <em>int-pid</em>. The process
must have been started using <a href="#spawn">spawn</a>. For processes
started using <a href="#fork">fork</a>, use <a href="#destroy">destroy</a>
instead.</p>

<p>The function <tt>abort</tt> is not available on Windows.</p>


<!-- example -->

<pre>
(abort 2245)  <span class='arw'>&rarr;</span> true
</pre>


<p>To abort all child processes spawned from the current process use <tt>abort</tt>
without any parameters:</p>


<pre>
(abort)  <span class='arw'>&rarr;</span> true ; abort all
</pre>


<p>The function <tt>abort</tt> is part of the Cilk API for synchronizing
child processes and process parallelization. See the reference for the
function <a href="#spawn">spawn</a> for a full discussion of the Cilk API.</p>

<br/><br/>

<a name="abs"></a>
<h2><span class="function">abs</span>&nbsp;
<a href="#big_int"><font size="-1">bigint</font></a></h2>
<h4>syntax: (abs <em>num</em>)</h4>

<p>
	Returns the absolute value of the number in <em>num</em>.
</p>

<!-- example -->

<pre>
(abs -3.5)  <span class='arw'>&rarr;</span> 3.5
</pre>

<br/><br/>

<a name="acos"></a>
<h2><span class="function">acos</span></h2>
<h4>syntax: (acos <em>num-radians</em>)</h4>

<p>
	The arc-cosine function is calculated 
	from the number in <em>num-radians</em>.
</p>

<!-- example -->

<pre>
(acos 1)  <span class='arw'>&rarr;</span> 0
(cos (acos 1)) <span class='arw'>&rarr;</span> 1
</pre>

<br/><br/>

<a name="acosh"></a>
<h2><span class="function">acosh</span></h2>
<h4>syntax: (acosh <em>num-radians</em>)</h4>

<p>Calculates the inverse hyperbolic cosine of <em>num-radians</em>, 
the value whose hyperbolic cosine is <em>num-radians</em>. 
If <em>num-radians</em> is less than 1, 
<tt>acosh</tt> returns <tt>NaN</tt>.</p>

<!-- example -->

<pre>
(acosh 2)  <span class='arw'>&rarr;</span> 1.316957897
(cosh (acosh 2)) <span class='arw'>&rarr;</span> 2
(acosh 0.5) <span class='arw'>&rarr;</span> NaN
</pre>

<br/><br/>


<a name="add"></a>
<h2><span class="function">add</span></h2>
<h4>syntax: (add <em>num-1</em> [<em>num-2</em> ... ])</h4>

<p>
	All of the numbers in <em>num-1</em>, <em>num-2</em>, and on 
	are summed.
	<tt>add</tt> accepts float or integer operands, 
	but it always returns a floating point number. 
	Any floating point calculation with <tt>NaN</tt> 
	also returns <tt>NaN</tt>.
</p>

<!-- example -->

<pre>
(add 2 3.25 9)   <span class='arw'>&rarr;</span> 14.25
(add 1 2 3 4 5)  <span class='arw'>&rarr;</span> 15
</pre>

<br/><br/>

<a name="address"></a>
<h2><span class="function">address</span></h2>
<h4>syntax: (address <em>int</em>)<br/>

syntax: (address <em>float</em>)<br/>
syntax: (address <em>str</em>)</h4>

<p>
	Returns the memory address of the integer in <em>int</em>, 
	the double floating point number in <em>float</em>, 
	or the string in <em>str</em>. 
	This function is used for passing parameters to library functions 
	that have been imported using the <a href="#import">import</a> function.
</p>

<!-- example -->

<pre>
(set 's "\001\002\003\004")

(get-char (+ (address s) 3))   <span class='arw'>&rarr;</span> 4

(set 'x 12345) ; x is a 64-bit long int

; on a big-endian CPU, i.e. PPC or SPARC 
(get-long (address x))         <span class='arw'>&rarr;</span> 12345
; the 32-bit int is in high 32-bit part of the long int
(get-int (+ (address x) 4))    <span class='arw'>&rarr;</span> 12345

; on a little-endian CPU, i.e. Intel i386
; the 32-bit int is in the low 32-bit part of the long int
(get-int (address x))          <span class='arw'>&rarr;</span> 12345

; on both architectures (integers are 64 bit in newLISP)
(set 'x 1234567890)
(get-long (address x))         <span class='arw'>&rarr;</span>  1234567890

</pre>


<p>
When a string is passed to C library function the address of the string is 
used automatically, and it is not necessary to use the <tt>address</tt> 
function in that case. As the example shows, <tt>address</tt> can be used 
to do pointer arithmetic on the string's address.</p>

<p><tt>address</tt> should only be used on persistent addresses from
data objects referred to by a variable symbol, not from volatile intermediate
expression objects.</p>

<p>
	See also the <a href="#get-char">get-char</a>, <a href="#get-int">get-int</a>, 
	<a href="#get-long">get-long</a> and <a href="#get-float">get-float</a> functions.
</p>

<br/><br/>

<a name="amb"></a>
<h2><span class="function">amb</span></h2>

<h4>syntax: (amb <em>exp-1</em> [<em>exp-2</em> ... ])</h4>

<p>
	One of the expressions <em>exp-1</em> ... <em>n</em> is selected at random, 
	and the evaluation result is returned.
</p>

<!-- example -->

<pre>
(amb 'a 'b 'c 'd 'e)  <span class='arw'>&rarr;</span> one of: a, b, c, d, or e at random

(dotimes (x 10) (print (amb 3 5 7)))  <span class='arw'>&rarr;</span> 35777535755
</pre>


<p>
	Internally, newLISP uses the same function as <a href="#rand">rand</a> to pick a random number. 
	To generate random floating point numbers, 
	use <a href="#random">random</a>, 
	<a href="#randomize">randomize</a>, or <a href="#normal">normal</a>. 
	To initialize the pseudo random number generating process 
	at a specific starting point,
	use the <a href="#seed">seed</a> function.
</p>

<br/><br/>

<a name="and"></a>
<h2><span class="function">and</span></h2>
<h4>syntax: (and <em>exp-1</em> [<em>exp-2</em> ... ])</h4>

<p>
	The expressions <em>exp-1</em>, <em>exp-2</em>, <em>etc.</em> are evaluated in order,
	returning the result of the last expression.
	If any of the expressions yield <tt>nil</tt> or the empty list <tt>()</tt>, 
	evaluation is terminated and <tt>nil</tt> or the empty list <tt>()</tt> is returned.
</p>

<!-- example -->

<pre>
(set 'x 10)                       <span class='arw'>&rarr;</span> 10
(and (&lt; x 100) (&gt; x 2))           <span class='arw'>&rarr;</span> true
(and (&lt; x 100) (&gt; x 2) "passed")  <span class='arw'>&rarr;</span> "passed"
(and '())                         <span class='arw'>&rarr;</span> ()
(and true)                        <span class='arw'>&rarr;</span> true
(and)                             <span class='arw'>&rarr;</span> true
</pre>

<br/><br/>

<a name="append"></a>
<h2><span class="function">append</span></h2>
<h4>syntax: (append <em>list-1</em> [<em>list-2</em> ... ])<br/>
syntax: (append <em>array-1</em> [<em>array-2</em> ... ])<br/>
syntax: (append <em>str-1</em> [<em>str-2</em> ... ])</h4>

<p>In the first form, <tt>append</tt> works with lists, 
appending <em>list-1</em> through <em>list-n</em> to form a new list. 
The original lists are left unchanged.</p>

<!-- example -->

<pre>
(append '(1 2 3) '(4 5 6) '(a b))  <span class='arw'>&rarr;</span> (1 2 3 4 5 6 a b)

(set 'aList '("hello" "world"))    <span class='arw'>&rarr;</span> ("hello" "world")

(append aList '("here" "I am"))    <span class='arw'>&rarr;</span> ("hello" "world" "here" "I am")
</pre>


<p>In the second form <tt>append</tt> works on arrays:</p>

<!-- example -->

<pre>
(set 'A (array 3 2 (sequence 1 6)))
<span class='arw'>&rarr;</span> ((1 2) (3 4) (5 6))
(set 'B (array 2 2 (sequence 7 10)))
<span class='arw'>&rarr;</span> ((7 8) (9 10))

(append A B)
<span class='arw'>&rarr;</span> ((1 2) (3 4) (5 6) (7 8) (9 10))

(append B B B)
<span class='arw'>&rarr;</span> ((7 8) (9 10) (7 8) (9 10) (7 8) (9 10))

</pre>


<p>
In the third form, <tt>append</tt> works on strings.  The strings in 
<em>str-n</em> are concatenated into a new string and returned.</p>

<!-- example -->

<pre>
(set 'more " how are you")       <span class='arw'>&rarr;</span> " how are you"

(append "Hello " "world," more)  <span class='arw'>&rarr;</span> "Hello world, how are you"
</pre>


<p>
<tt>append</tt> is also suitable for processing binary strings containing zeroes.
The <a href="#string">string</a> function would cut off strings at zero bytes.</p>

<p>
Linkage characters or strings can be specified using the 
<a href="#join">join</a> function. Use the <a href="#string">string</a> 
function to convert arguments to strings and append in one step.</p>

<p>Use the functions <a href="#extend">extend</a> and <a href="#push">push</a>
to append to an existing list or string modifying the target.</p>

<br/><br/>

<a name="append-file"></a>
<h2><span class="function">append-file</span></h2>
<h4>syntax: (append-file <em>str-filename</em> <em>str-buffer</em>)</h4>

<p>
Works similarly to <a href="#write-file">write-file</a>, but the content 
in <em>str-buffer</em> is appended if the file in <em>str-filename</em> exists. 
If the file does not exist, it is created (in this case, <tt>append-file</tt> 
works identically to <a href="#write-file">write-file</a>). This function 
returns the number of bytes written.</p>

<p>On failure the function returns <tt>nil</tt>. For error information, 
use <a href="#sys-error">sys-error</a> when used on files. When used
on URLs <a href="#net-error">net-error</a> gives more error
information.</p>

<!-- example -->

<pre>
(write-file "myfile.txt" "ABC") 
(append-file "myfile.txt" "DEF")

(read-file "myfile.txt")  <span class='arw'>&rarr;</span> "ABCDEF"
</pre>


<p><tt>append-file</tt> can take a <tt>http://</tt> or <tt>file://</tt> URL
in <em>str-file-name</em>. In case of the <tt>http://</tt>  prefix ,
<tt>append-file</tt> works exactly like <a href="#put-url">put-url</a> with 
<tt>"Pragma: append\r\n"</tt> in the header option and can take the same 
additional parameters. The <tt>"Pragma: append\r\n"</tt> option is supplied 
automatically.</p>

<!-- example -->

<pre>
(append-file "http://asite.com/message.txt" "More message text.")
</pre>


<p>The file <tt>message.txt</tt> is appended at a remote
location <tt>http://asite.com</tt> with the contents of 
<em>str-buffer</em>. If the file does not yet exist, it
will be created. In this mode, <tt>append-file</tt> can also be used
to transfer files to remote newLISP server nodes.
</p>



<p>See also <a href="#read-file">read-file</a> and
<a href="#write-file">write-file</a>.
</p>

<br/><br/>

<a name="apply"></a>
<h2><span class="function">apply</span></h2>
<h4>syntax: (apply <em>func</em> <em>list</em> [<em>int-reduce</em>])<br/>
syntax: (apply <em>func</em>)</h4>

<p>Applies the contents of <em>func</em> (primitive, user-defined function, or 
lambda expression)  to the arguments in <em>list</em>. Only functions and
operators with standard evaluation of their arguments can be applied.</p>

<p>In the second syntax <tt>apply</tt> is used on functions without any 
arguments.</p>

<!-- example -->

<pre>
(apply + '(1 2 3 4))                   <span class='arw'>&rarr;</span> 10
(set 'aList '(3 4 5))                  <span class='arw'>&rarr;</span> (3 4 5)
(apply * aList)                        <span class='arw'>&rarr;</span> 60
(apply sqrt '(25))                     <span class='arw'>&rarr;</span> 5
(apply (lambda (x y) (* x y)) '(3 4))  <span class='arw'>&rarr;</span> 12
</pre>



<p>
	The <em>int-reduce</em> parameter can optionally contain 
	the number of arguments taken by the function in <em>func</em>. 
	In this case, 
	<em>func</em> will be repeatedly applied using the previous result 
	as the first argument and taking the other arguments required 
	successively from <em>list</em> 
	(in left-associative order). 
	For example, if <tt>op</tt> takes two arguments, then:
</p>


<pre>
(apply op '(1 2 3 4 5) 2)

;; is equivalent to

(op (op (op (op 1 2) 3) 4) 5)

;; find the greatest common divisor 
;; of two or more integers 
;; note that newLISP already has a gcd function

(define (gcd_ a b)
    (let (r (% b a))
        (if (= r 0) a (gcd_ r a))))

(define-macro (my-gcd)
    (apply gcd_ (map eval (args)) 2))

(my-gcd 12 18 6)    <span class='arw'>&rarr;</span> 6
(my-gcd 12 18 6 4)  <span class='arw'>&rarr;</span> 2
</pre>


<p>The last example shows how <tt>apply</tt>'s <em>reduce</em> functionality 
can be used to convert a two-argument function into one that takes multiple arguments. Note, that a built-in <a href="#gcd">gcd</a> is available.</p>

<p>
<tt>apply</tt> should only be used on functions and operators that evaluate all 
of their arguments, not on <em>special forms</em> like <a href="#dotimes">dotimes</a> 
or <a href="#case">case</a>, which evaluate only some of their arguments. 
Doing so will cause the function to fail.
</p>

<br/><br/>

<a name="args"></a>
<h2><span class="function">args</span></h2>
<h4>syntax: (args)<br/>
syntax: (args <em>int-idx-1</em> [<em>int-idx-2</em> ... ])</h4>

<p>
Accesses a list of all unbound arguments passed to the currently evaluating 
<a href="#define">define</a>, <a href="#define-macro">define-macro</a> 
lambda, or lambda-macro expression. Only the arguments of the current function 
or macro that remain after local variable binding has occurred are available. 
The <tt>args</tt> function is useful for defining functions or macros 
with a variable number of parameters.</p>

<p>
<tt>args</tt> can be used to define hygienic macros that avoid the danger of 
variable capture. See <a href="#define-macro">define-macro</a>.
</p>

<!-- example -->

<pre>
(define-macro (print-line)
    (dolist (x (args))
        (print x "\n")))
                        
(print-line "hello" "World")
</pre>

<p>
	This example prints a line-feed after each argument. 
	The macro mimics the effect of the built-in function 
	<a href="#println">println</a>.
</p>

<p>
	In the second syntax, 
	<tt>args</tt> can take one or more indices (<em>int-idx-n</em>).
</p>

<!-- example -->

<pre>
(define-macro (foo)
    (print (args 2) (args 1) (args 0)))

(foo x y z) 
<b>zyx</b> 

(define (bar)
	(args 0 2 -1))

(bar '(1 2 (3 4)))  <span class='arw'>&rarr;</span> 4
</pre>


<p>
	The function <tt>foo</tt> 
	prints out the arguments in reverse order. 
	The <tt>bar</tt> function 
	shows <tt>args</tt> being used 
	with multiple indices
	to access nested lists.
</p>

<p>
	Remember that <tt>(args)</tt> only contains the arguments 
	not already bound to local variables 
	of the current function or macro:
</p>

<!-- example -->

<pre>
(define (foo a b) (args))
  
(foo 1 2)        <span class='arw'>&rarr;</span> ()
                 
(foo 1 2 3 4 5)  <span class='arw'>&rarr;</span> (3 4 5)
</pre>


<p>
	In the first example, 
	an empty list is returned because 
	the arguments are bound to the 
	two local symbols, <tt>a</tt> and <tt>b</tt>.
	The second example demonstrates that, 
	after the first two arguments are bound 
	(as in the first example), three arguments remain 
	and are then returned by <tt>args</tt>.
</p>

<p>
	<tt>(args)</tt> can be used as an argument 
	to a built-in or user-defined function call, 
	but it should not be used as an argument to another macro, 
	in which case <tt>(args)</tt> would not be evaluated 
	and would therefore have the wrong
	contents in the new macro environment.
</p>

<br/><br/>

<a name="array"></a>
<h2><span class="function">array</span></h2>

<h4>syntax: (array <em>int-n1</em> [<em>int-n2</em> ... ] [<em>list-init</em>])</h4>

<p>Creates an array with <em>int-n1</em> elements, 
optionally initializing it with the contents of <em>list-init</em>. 
Up to sixteen dimensions may be specified for multidimensional arrays.</p>

<p>Internally, newLISP builds multidimensional arrays by using arrays as the 
elements of an array. newLISP arrays should be used whenever random indexing 
into a large list becomes too slow. Not all list functions may be used on arrays. 
For a more detailed discussion, see the chapter on <a href="#arrays">arrays</a>.</p>

<!-- example -->

<pre>
(array 5)                  <span class='arw'>&rarr;</span> (nil nil nil nil nil)

(array 5 (sequence 1  5))  <span class='arw'>&rarr;</span> (1 2 3 4 5)

(array 10 '(1 2))          <span class='arw'>&rarr;</span> (1 2 1 2 1 2 1 2 1 2)
</pre>



<p>Arrays can be initialized with objects of any type. If fewer initializers than 
elements are provided, the list is repeated until all elements of the array are 
initialized.</p>


<pre>

(set 'myarray (array 3 4 (sequence 1 12)))
<span class='arw'>&rarr;</span> ((1 2 3 4) (5 6 7 8) (9 10 11 12))
</pre>


<p>Arrays are modified and accessed using most of the same functions used for 
modifying lists:</p>


<pre>
(setf (myarray 2 3) 99) <span class='arw'>&rarr;</span> 99)
myarray <span class='arw'>&rarr;</span> ((1 2 3 4) (5 6 7 8) (9 10 11 99))

(setf (myarray 1 1) "hello")  <span class='arw'>&rarr;</span> "hello"

myarray <span class='arw'>&rarr;</span> ((1 2 3 4) (5 "hello" 7 8) (9 10 11 99))

(setf (myarray 1) '(a b c d)) <span class='arw'>&rarr;</span> (a b c d)
myarray <span class='arw'>&rarr;</span> ((1 2 3 4) (a b c d) (9 10 11 99))

(nth 1 myarray)     <span class='arw'>&rarr;</span> (a b c d)  ; access a whole row
                    
;; use implicit indexing and slicing on arrays
                    
(myarray 1)     <span class='arw'>&rarr;</span> (a b c d)
                    
(myarray 0 -1)  <span class='arw'>&rarr;</span> 4

(2 myarray)     <span class='arw'>&rarr;</span> ((9 10 11 99)) 

(-3 2 myarray)  <span class='arw'>&rarr;</span> ((1 2 3 4) (a b c d)) 
</pre>


<p>Care must be taken to use an array when replacing a whole row.
</p>

<p>
<a href="#array-list">array-list</a> can be used to convert arrays back into lists:
</p>


<pre>
(array-list myarray)  <span class='arw'>&rarr;</span> ((1 2 3 4) (a b c d) (1 2 3 99))
</pre>


<p>To convert a list back into an array, apply <a href="#flat">flat</a> to the list:
</p>


<pre>
(set 'aList '((1 2) (3 4)))             <span class='arw'>&rarr;</span> ((1 2) (3 4))

(set 'aArray (array 2 2 (flat aList)))  <span class='arw'>&rarr;</span> ((1 2) (3 4))
</pre>


<p>The <a href="#arrayp">array?</a> function 
can be used to check if an expression is an array:
</p>


<pre>
(array? myarray)               <span class='arw'>&rarr;</span> true
                               
(array? (array-list myarray))  <span class='arw'>&rarr;</span> nil
</pre>



<p>
When serializing arrays using the  function <a href="#source">source</a> 
or <a href="#save">save</a>, the generated code includes the <tt>array</tt> 
statement necessary to create them. This way, variables containing arrays are 
correctly serialized when saving with <a href="#save">save</a> or creating 
source strings using <a href="#source">source</a>.</p>



<pre>
(set 'myarray (array 3 4 (sequence 1 12)))

(save "array.lsp" 'myarray)

;; contents of file arraylsp ;;

(set 'myarray (array 3 4 (flat '(
  (1 2 3 4) 
  (5 6 7 8) 
  (9 10 11 12)))))
</pre>

<br/><br/>

<a name="array-list"></a>
<h2><span class="function">array-list</span></h2>
<h4>syntax: (array-list <em>array</em>)</h4>

<p>
	Returns a list conversion from <em>array</em>, 
	leaving the original array unchanged:
</p>

<!-- example -->

<pre>
(set 'myarray (array 3 4 (sequence 1 12)))
<span class='arw'>&rarr;</span> ((1 2 3 4) (5 6 7 8) (9 10 11 12))

(set 'mylist (array-list myarray))
<span class='arw'>&rarr;</span> ((1 2 3 4) (5 6 7 8) (9 10 11 12))

(list (array? myarray) (list? mylist))
<span class='arw'>&rarr;</span> (true true)
</pre>

<br/><br/>

<a name="arrayp"></a>
<h2><span class="function">array?</span></h2>
<h4>syntax: (array? <em>exp</em>)</h4>

<p>
	Checks if <em>exp</em> is an array:
</p>

<!-- example -->

<pre>
(set 'M (array 3 4 (sequence 1 4)))   
<span class='arw'>&rarr;</span> ((1 2 3 4) (1 2 3 4) (1 2 3 4)))


(array? M)               <span class='arw'>&rarr;</span> true

(array? (array-list M))  <span class='arw'>&rarr;</span> nil
</pre>

<br/><br/>

<a name="asin"></a>
<h2><span class="function">asin</span></h2>
<h4>syntax: (asin <em>num-radians</em>)</h4>

<p>
	Calculates the arcsine function from the number in <em>num-radians</em> 
	and returns the result.
</p>

<!-- example -->

<pre>
(asin 1)  <span class='arw'>&rarr;</span> 1.570796327
(sin (asin 1)) <span class='arw'>&rarr;</span> 1
</pre>

<br/><br/>

<a name="asinh"></a>
<h2><span class="function">asinh</span></h2>
<h4>syntax: (asinh <em>num-radians</em>)</h4>

<p>Calculates the inverse hyperbolic sine of <em>num-radians</em>, 
the value whose hyperbolic sine is <em>num-radians</em>.</p>

<!-- example -->

<pre>
(asinh 2)         <span class='arw'>&rarr;</span> 1.443635475
(sinh (asinh 2))  <span class='arw'>&rarr;</span> 2
</pre>

<br/><br/>

<a name="assoc"></a>
<h2><span class="function">assoc</span></h2>
<h4>syntax: (assoc <em>exp-key</em> <em>list-alist</em>)<br/>
syntax: (assoc <em>list-exp-key</em> <em>list-alist</em>)</h4>


<p>
In the first syntax the value of <em>exp-key</em> is used 
to search <em>list-alist</em> for a <em>member-list</em> 
whose first element matches the key value. 
If found, the <em>member-list</em> is returned;
otherwise, the result will be <tt>nil</tt>.
</p>

<!-- example -->

<pre>
(assoc 1 '((3 4) (1 2)))  <span class='arw'>&rarr;</span> (1 2)

(set 'data '((apples 123) (bananas 123 45) (pears 7)))

(assoc 'bananas data)  <span class='arw'>&rarr;</span> (bananas 123 45)
(assoc 'oranges data)  <span class='arw'>&rarr;</span> nil
</pre>

<p>Together with <a href="#setf">setf</a> <tt>assoc</tt> can be used
to change an association.</p>

<pre>
(setf (assoc 'pears data) '(pears 8))

data  <span class='arw'>&rarr;</span> ((apples 123) (bananas 123 45) (pears 8))
</pre>

<p>In the second syntax more then one key expressions can be specified
to search in nested, multilevel association lists:</p>

<!-- example -->

<pre>
(set 'persons '(
    (id001 (name "Anne") (address (country "USA") (city "New York")))
    (id002 (name "Jean") (address (country "France") (city "Paris")))
))

(assoc '(id001 address) persons) <span class='arw'>&rarr;</span> (address (country "USA") (city "New York"))
(assoc '(id001 address city) persons) <span class='arw'>&rarr;</span> (city "New York")
</pre>


<p>The list in <em>list-aList</em> can be a context which will be interpreted
as its <em>default functor</em>. This way very big lists can be passed by reference
for speedier access and less memory usage:</p>


<pre>
(set 'persons:persons '(
    (id001 (name "Anne") (address (country "USA") (city "New York")))
    (id002 (name "Jean") (address (country "France") (city "Paris")))
))

(define (get-city db id)
    (last (assoc (list id 'address 'city) db ))
)

(get-city persons 'id001) <span class='arw'>&rarr;</span> "New York"
</pre>


<p>
For making replacements in association lists, use the 
<a href="#setf">setf</a> together with the <tt>assoc</tt> function.
The <a href="#lookup">lookup</a> function is used to perform association lookup 
and element extraction in one step.</p>

<br/><br/>

<a name="atan"></a>
<h2><span class="function">atan</span></h2>
<h4>syntax: (atan <em>num-radians</em>)</h4>

<p>
	The arctangent of <em>num-radians</em> 
	is calculated and returned.
</p>

<!-- example -->

<pre>
(atan 1)        <span class='arw'>&rarr;</span> 0.7853981634
(tan (atan 1))  <span class='arw'>&rarr;</span> 1
</pre>

<br/><br/>

<a name="atan2"></a>
<h2><span class="function">atan2</span></h2>
<h4>syntax: (atan2 <em>num-Y-radians</em> <em>num-X-radians</em>)</h4>

<p>
	The <tt>atan2</tt> function computes 
	the principal value of 
	the arctangent of Y / X in radians. 
	It uses the signs of both arguments 
	to determine the quadrant of
	the return value. 
	<tt>atan2</tt> is useful for converting 
	Cartesian coordinates 
	into polar coordinates.
</p>

<!-- example -->

<pre>
(atan2 1 1)                       <span class='arw'>&rarr;</span> 0.7853981634
(div (acos 0) (atan2 1 1))        <span class='arw'>&rarr;</span> 2
(atan2 0 -1)                      <span class='arw'>&rarr;</span> 3.141592654
(= (atan2 1 2) (atan (div 1 2)))  <span class='arw'>&rarr;</span> true
</pre>

<br/><br/>

<a name="atanh"></a>
<h2><span class="function">atanh</span></h2>
<h4>syntax: (atanh <em>num-radians</em>)</h4>

<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>

<!-- example -->

<pre>
(atanh 0.5) <span class='arw'>&rarr;</span> 0.5493061443
(tanh (atanh 0.5)) <span class='arw'>&rarr;</span> 0.5
(atanh 1.1) <span class='arw'>&rarr;</span> NaN
(atanh 1) <span class='arw'>&rarr;</span> inf
</pre>

<br/><br/>

<a name="atomp"></a>
<h2><span class="function">atom?</span></h2>
<h4>syntax: (atom? <em>exp</em>)</h4>

<p>
	Returns <tt>true</tt> if the value of <em>exp</em> is an atom, 
	otherwise <tt>nil</tt>.	
	An expression is an atom if it evaluates to nil, 
	true, an integer, a float, a string, a symbol or a primitive. 
	Lists, lambda or lambda-macro expressions, 
	and quoted expressions are not atoms.
</p>

<!-- example -->

<pre>
(atom? '(1 2 3))      <span class='arw'>&rarr;</span> nil
(and (atom? 123)
     (atom? "hello")
     (atom? 'foo))    <span class='arw'>&rarr;</span> true
(atom? ''foo)         <span class='arw'>&rarr;</span> nil
</pre>

<br/><br/>

<a name="base64-dec"></a>
<h2><span class="function">base64-dec</span></h2>
<h4>syntax: (base64-dec <em>str</em>)</h4>

<p>
	The BASE64 string in <em>str</em> is decoded. 
	Note that <em>str</em> is not verified
	to be a valid BASE64 string. 
	The decoded string is returned.
</p>

<!-- example -->

<pre>
(base64-dec "SGVsbG8gV29ybGQ=")  <span class='arw'>&rarr;</span> "Hello World"
</pre>


<p>
	For encoding,
	use the <a href="#base64-enc">base64-enc</a> function.
</p>
	
<p> 
	newLISP's BASE64 handling is derived from 
	routines found in the Unix <a href="http://curl.haxx.se/">curl</a>
    utility and conforms to the RFC 4648 standard.
</p>

<br/><br/>

<a name="base64-enc"></a>
<h2><span class="function">base64-enc</span></h2>
<h4>syntax: (base64-enc <em>str</em> [<em>bool-flag</em>])</h4>

<p>
The string in <em>str</em> is encoded into BASE64 format. 
This format encodes groups of 3 * 8 = 24 input bits 
into 4 * 8 = 32 output bits, 
where each 8-bit output group 
represents 6 bits from the input string. 
The 6 bits are encoded into 64 possibilities
from the letters A&ndash;Z and a&ndash;z; 
the numbers 0&ndash;9; 
and the characters + (plus sign) and / (slash). 
The = (equals sign) is used as a filler 
in unused 3- to 4-byte translations. 
This function is helpful for converting binary content 
into printable characters.
</p>

<p>Without the optional <em>bool-flag</em> parameter the empty string <tt>""</tt> is
encoded into <tt>"===="</tt>. If <em>bool-flag</em>  evaluates to <tt>true</tt>, 
the empty string <tt>""</tt> is translated into <tt>""</tt>. Both translations
result in <tt>""</tt> when using <a href="base64-dec">base64-dec</a>.</p>

<p>
The encoded string is returned.
</p>

<p>
BASE64 encoding is used with many Internet protocols 
to encode binary data for inclusion in text-based messages
(e.g., XML-RPC).
</p>

<!-- example -->

<pre>
(base64-enc "Hello World")  <span class='arw'>&rarr;</span> "SGVsbG8gV29ybGQ="

(base64-enc "")             <span class='arw'>&rarr;</span> "===="
(base64-enc "" true)        <span class='arw'>&rarr;</span> ""
</pre>


<p>
	Note that <tt>base64-enc</tt> does not insert 
	carriage-return/line-feed pairs in longer BASE64 sequences 
	but instead returns a pure BASE64-encoded string.
</p>


<p>
	For decoding, 
	use the <a href="#base64-dec">base64-dec</a> function.
</p>
	
<p>
	newLISP's BASE64 handling is derived from routines 
	found in the Unix <a href="http://curl.haxx.se/">curl</a> 
    utility and conforms to the RFC 4648 standard.
</p>

<br/><br/>

<a name="bayes-query"></a>
<h2><span class="function">bayes-query</span></h2>
<h4>syntax: (bayes-query <em>list-L</em> <em>context-D</em> [<em>bool-chain</em> [<em>bool-probs</em>]])</h4>

<p>
Takes a list of tokens (<em>list-L</em>) and a trained dictionary (<em>context-D</em>) 
and returns a list of the combined probabilities of the tokens in one category 
(<em>A</em> or <em>Mc</em>) versus a category (<em>B</em>) or
against all other categories (<em>Mi</em>).  All tokens in <em>list-L</em> 
should occur in <em>context-D</em>. 
When using the default <em>R.A. Fisher inverse Chi&sup2;&nbsp;</em> mode, 
nonexistent tokens will skew results toward equal probability in all categories.
</p>

<p>
Non-existing tokens will not have any influence on the result when using the 
true <em>Chain Bayesian</em> mode with <em>bool-chain</em> set to <tt>true</tt>.  
The optional last flag, <em>bool-probs</em>, indicates whether frequencies or 
probability values are used in the data set. The <a href="#bayes-train">bayes-train</a> 
function is typically used to generate a data set's frequencies.
</p>

<p>
Tokens can be strings or symbols.  If strings are used, they are prepended 
with an underscore before being looked up in <em>context-D</em>.  If 
<a href="#bayes-train">bayes-train</a> was used to generate <em>context-D</em>'s 
frequencies, the underscore was automatically prepended during the learning process.
</p>

<p>
	Depending on the flag specified in <em>bool-probs</em>, 
	<a href="#bayes-query">bayes-query</a> employs either the 
	R. A. Fisher inverse Chi&sup2; method of compounding probabilities 
	or the Chain Bayesian method. 
	By default, when no flag or <tt>nil</tt> is specified in <em>bool-probs</em>,
	the inverse Chi&sup2; method of compounding probabilities is used. 
	When specifying <tt>true</tt> in <em>bool-probs</em>, 
	the Chain Bayesian method is used.
</p>

<p>
	If the inverse Chi&sup2; method is used, 
	the total number of tokens 
	in the different training set's categories 
	should be equal or similar. 
	Uneven frequencies in categories 
	will skew the results.
</p>

<p>
	For two categories <em>A</em> and <em>B</em>, 
	<tt>bayes-query</tt> uses the following formula:
</p>


<b><em>p(A|tkn) = p(tkn|A) * p(A) / ( p(tkn|A) * p(A) + p(tkn|B) * p(B) )</em></b>

   
<p>
	For <em>N</em> categories, the formula can be generalized to:
</p>
   

<b><em>p(Mc|tkn) = p(tkn|Mc) * p(Mc) / sum-i-N( p(tkn|Mi) * p(Mi) )</em></b>
 

<p>
	The probabilities (<em>p(Mi)</em> or <em>p(A)</em>, along with <em>p(B)</em>) 
	represent the <em>Bayesian prior probabilities</em>. 
	<em>p(Mc|tkn)</em> and <em>p(A|tkn)</em> are the 
	<em>posterior Bayesian</em> probabilities of a category or model.
    This <i>naive</i> Bayes formula does nor take into account dependencies
    between different categories. 
</p>

<p>
	Priors are handled differently, 
	depending on whether the R.A. Fisher inverse Chi&sup2; 
	or the Chain Bayesian method is used. 
	In Chain Bayesian mode, 
	posteriors from one token calculation get the priors in the next calculation. 
	In the default inverse Chi&sup2; method, 
	priors are not passed on via chaining, 
	but probabilities are compounded using the inverse Chi&sup2; method.
</p>

<p>
	In Chain Bayes mode, 
	tokens with zero frequency in one category 
	will effectively put the probability of that category to 0 (zero). 
	This also causes all posterior priors to be set to 0
	and the category to be completely suppressed in the result. 
	Queries resulting in zero probabilities for all categories 
	yield <em>NaN</em> values.
</p>

<p>
	The default inverse Chi&sup2; method 
	is less sensitive about zero frequencies 
	and still maintains a low probability for that token. 
	This may be an important feature in natural language processing 
	when using <em>Bayesian statistics</em>. 
	Imagine that five different language <em>corpus</em> categories have been trained, 
	but some words occurring in one category are not present in another. 
	When the pure Chain Bayesian method is used, 
	a sentence could never be classified into its correct category
	because the zero-count of just one word token could effectively exclude it 
	from the category to which it belongs.
</p>

<p>
	On the other hand, 
	the Chain Bayesian method offers exact results 
	for specific proportions in the data. 
	When using Chain Bayesian mode for natural language data,
	all zero frequencies should be removed from the trained dictionary first.
</p>

<p>
The return value of <tt>bayes-query</tt> is a list of probability values, 
one for each category. Following are two examples: the first for the 
default inverse Chi&sup2; mode, the second for a data set processed with the 
Chain Bayesian method.
</p>

<br/>
<h3>R.A. Fisher inverse Chi&sup2; method</h3>

<p>
	In the following example, 
	the two data sets are books from Project Gutenberg.
	We assume that different authors 
	use certain words with different frequencies 
	and want to determine if a sentence is more likely to occur in one 
	or the other author's writing.
	A similar method is frequently used to differentiate between spam 
	and legitimate email.
</p>


<pre>
;; from Project Gutenberg: http://www.gutenberg.org/catalog/
;; The Adventures of Sherlock Holmes - Sir Arthur Conan Doyle

(bayes-train (parse (lower-case (read-file "Doyle.txt")) 
                    "[^a-z]+" 0) '() 'DoyleDowson)

;; A Comedy of Masks - Ernest Dowson and Arthur Moore

(bayes-train '() (parse (lower-case (read-file "Dowson.txt")) 
                    "[^a-z]+" 0) 'DoyleDowson)

(save "DoyleDowson.lsp" 'DoyleDowson)
</pre>


<p>
	The two training sets are loaded, split into tokens, 
	and processed by the <a href="#bayes-train">bayes-train</a> function. 
	In the end, the <tt>DoyleDowson</tt> dictionary is saved to a file, 
	which will be used later with the <tt>bayes-query</tt> function.
</p>

<p>
	The following code illustrates how <tt>bayes-query</tt> is used 
	to classify a sentence as <em>Doyle</em> or <em>Dowson</em>:
</p>


<pre>
(load "DoyleDowson.lsp")
(bayes-query (parse "he was putting the last touches to a picture") 
    'DoyleDowson)
<span class='arw'>&rarr;</span> (0.0359554723158327 0.964044527684167) 

(bayes-query (parse "immense faculties and extraordinary powers of observation") 
    'DoyleDowson)
<span class='arw'>&rarr;</span> (0.983569359827141 0.0164306401728594) 
</pre>


<p>
	The queries correctly identify the first sentence as a <em>Dowson</em> sentence,
	and the second one as a <em>Doyle</em> sentence.
</p>
      
<br/>
      
<h3>Chain Bayesian method</h3>

<p>
	The second example is frequently found 
	in introductory literature on Bayesian statistics. 
	It shows the Chain Bayesian method of 
	using <tt>bayes-query</tt> on the data of a previously processed data set:
</p>

<!-- example -->

<pre>
(set 'Data:test-positive '(8 18))
(set 'Data:test-negative '(2 72))
(set 'Data:total '(10 90))
</pre>

   
<p>
	A disease occurs in 10 percent of the population. 
	A blood test developed to detect this disease 
	produces a false positive rate of 20 percent in the healthy population 
	and a false negative rate of 20 percent in the sick. 
	What is the probability of a person carrying 
	the disease after testing positive?</p>

<!-- example -->

<pre>
(bayes-query '(test-positive) Data true)
<span class='arw'>&rarr;</span> (0.3076923077 0.6923076923)

(bayes-query '(test-positive test-positive) Data true)
<span class='arw'>&rarr;</span> (0.64 0.36)

(bayes-query '(test-positive test-positive test-positive) Data true)
<span class='arw'>&rarr;</span> (0.8767123288 0.1232876712)
</pre>


<p>
	Note that the Bayesian formulas used 
	assume statistical independence of events 
	for the <tt>bayes-query</tt> to work correctly.
</p>

<p>
	The example shows that a person must test positive several times 
	before they can be confidently classified as sick.
</p>

<p>
	Calculating the same example using the R.A. Fisher Chi&sup2; method
	will give less-distinguished results.
</p> 

<br/>
<h3>Specifying probabilities instead of counts</h3>

<p>
	Often, data is already available as probability values 
	and would require additional work to reverse them into frequencies. 
	In the last example, the data were originally defined as percentages. 
	The additional optional <em>bool-probs</em> flag 
	allows probabilities to be entered directly 
	and should be used together with the Chain Bayesian mode 
	for maximum performance:
</p>

<!-- example -->

<pre>
(set 'Data:test-positive '(0.8 0.2))
(set 'Data:test-negative '(0.2 0.8))
(set 'Data:total '(0.1 0.9))

(bayes-query '(test-positive) Data true true)
<span class='arw'>&rarr;</span> (0.3076923077 0.6923076923)

(bayes-query '(test-positive test-positive) Data true true)
<span class='arw'>&rarr;</span> (0.64 0.36)

(bayes-query '(test-positive test-positive test-positive) Data true true)
<span class='arw'>&rarr;</span> (0.8767123288 0.1232876712)
</pre>


<p>
	As expected, the results are the same for probabilities 
	as they are for frequencies.
</p>

<br/><br/>

<a name="bayes-train"></a>
<h2><span class="function">bayes-train</span></h2>
<h4>syntax: (bayes-train <em>list-M1</em> [<em>list-M2</em> ... ] <em>sym-context-D</em>)</h4>

<p>
Takes one or more lists of tokens (<em>M1</em>, <em>M2&mdash;</em>) 
from a joint set of tokens. In newLISP, tokens can be symbols or strings 
(other data types are ignored). Tokens are placed in a common dictionary 
in <em>sym-context-D</em>, and the frequency is counted  for each token 
in each category <em>Mi</em>. If the context does not yet exist, 
it must be quoted.
</p>
   
<p> The <em>M</em> categories represent data models for which sequences of 
tokens can be classified  (see <a href="#bayes-query">bayes-query</a>). 
Each token in <em>D</em> is a content-addressable symbol 
containing a list of the frequencies for this token within each category. 
String tokens are prepended with an <tt>_</tt> (underscore) 
before being converted into symbols. A symbol named <tt>total</tt> is created
containing the total of each category. The <tt>total</tt> symbol cannot be part 
of the symbols passed as an <em>Mi</em> category.
</p>

<p>
The function returns a list of token frequencies found in the different categories 
or models.
</p>

<!-- example -->

<pre>
(bayes-train '(A A B C C) '(A B B C C C) 'L)  <span class='arw'>&rarr;</span> (5 6)

L:A      <span class='arw'>&rarr;</span> (2 1)
L:B      <span class='arw'>&rarr;</span> (1 2)
L:C      <span class='arw'>&rarr;</span> (2 3)
L:total  <span class='arw'>&rarr;</span> (5 6)

(bayes-train '("one" "two" "two" "three")
             '("three" "one" "three") 
             '("one" "two" "three") 'S)       
<span class='arw'>&rarr;</span> (4 3 3)

S:_one    <span class='arw'>&rarr;</span> (1 1 1)
S:_two    <span class='arw'>&rarr;</span> (2 0 1)
S:_three  <span class='arw'>&rarr;</span> (1 2 1)
S:total   <span class='arw'>&rarr;</span> (4 3 3)
</pre>


<p>The first example shows training with two lists of symbols. The second example 
illustrates how an <tt>_</tt> is prepended when training with strings.</p>

<p><tt>bayes-train</tt> creates symbols from strings prepending an underscore
character. This is the same way hashes are created and contexts populates with
symbols by <tt>bayes-train</tt> can be used like hashes:</p>


<pre>
; use a bayes-trained context namespace like a hash dictionary

(S "two")   <span class='arw'>&rarr;</span> (2 0 1)
(S "three") <span class='arw'>&rarr;</span> (1 2 1)

(S) <span class='arw'>&rarr;</span> (("one" (1 1 1)) ("three" (1 2 1)) ("two" (2 0 1)))
</pre>


	
<p>
Note that these examples are just for demonstration purposes. In reality, training 
sets may contain thousands or millions of words, especially when training natural 
language models. But small data sets may be used when the frequency of symbols 
just describe already-known proportions. In this case, it may be better to describe 
the model data set explicitly, without the <tt>bayes-train</tt> function:
</p>


<pre>
(set 'Data:tested-positive '(8 18))
(set 'Data:tested-negative '(2 72))
(set 'Data:total '(10 90))
</pre>


<p>
The last data are from a popular example used to describe the 
<a href="#bayes-query">bayes-query</a> function in introductory papers 
and books about <em>bayesian networks</em>.
</p>

<p>
Training can be done in different stages by using <tt>bayes-train</tt> on an 
existing trained context with the same number of categories. The new symbols 
will be added, then counts and totals will be correctly updated.</p>

<p>
Training in multiple batches may be necessary on big text corpora or documents 
that must be tokenized first. These corpora can be tokenized in small portions, 
then fed into <tt>bayes-train</tt> in multiple stages. Categories can also be 
singularly trained by specifying an empty list for the absent corpus:
</p>


<pre>
(bayes-train shakespeare1 '() 'data)
(bayes-train shakespeare2 '() 'data)
(bayes-train '() hemingway1 'data)
(bayes-train '() hemingway2 'data)
(bayes-train shakepeare-rest hemingway-rest 'data)
</pre>


<p>
<tt>bayes-train</tt> will correctly update word counts and totals.</p>

<p>
	Using <tt>bayes-train</tt> inside a context other than <tt>MAIN</tt> 
	requires the training contexts to have been created previously within 
	the <tt>MAIN</tt> context via the <a href="#context">context</a> function.
</p>

<p>
	<tt>bayes-train</tt> is not only useful with the <a href="#bayes-query">bayes-query</a> function, 
	but also as a function for counting in general.
	For instance, the resulting frequencies 
	could be analyzed using <a href="#prob-chi2">prob-chi2</a> 
	against a <em>null hypothesis</em> of proportional distribution 
	of items across categories.
</p>

<br/><br/>

<a name="begin"></a>
<h2><span class="function">begin</span></h2>
<h4>syntax: (begin <em>body</em>)</h4>

<p>
	The <tt>begin</tt> function is used to group a block of expressions. 
	The expressions in <em>body</em> are evaluated in sequence, and 
	the value of the last expression in <em>body</em> is returned.
</p>

<!-- example -->

<pre>
(begin
  (print "This is a block of 2 expressions\n")
  (print "================================"))
</pre>


<p>
	Some built-in functions like <a href="#cond">cond</a>, <a href="#define">define</a>,
	<a href="#doargs">doargs</a>, <a href="#dolist">dolist</a>, <a href="#dostring">dostring</a>, 
    <a href="#dotimes">dotimes</a>, <a href="#when">when</a> and <a href="#while">while</a> 
	already allow multiple expressions in their bodies,
	but <tt>begin</tt> is often used in an <a href="#if">if</a> expression.
</p>

<p>
	The <a href="#silent">silent</a> function works like <tt>begin</tt>, 
	but suppresses console output on return.
</p>

<br/><br/>

<a name="beta"></a>
<h2><span class="function">beta</span></h2>
<h4>syntax: (beta <em>cum-a</em> <em>num-b</em>)</h4>

<p>
	The <em>Beta</em> function, <tt>beta</tt>,  
	is derived from the <em>log Gamma</em> 
	<tt>gammaln</tt> function as follows:
</p>

<p><em><b>
beta = exp(gammaln(a) + gammaln(b) - gammaln(a + b))
</b></em></p>

<!-- example -->

<pre>
(beta 1 2)  <span class='arw'>&rarr;</span> 0.5
</pre>

<br/><br/>

<a name="betai"></a>
<h2><span class="function">betai</span></h2>

<h4>syntax: (betai <em>num-x</em> <em>num-a</em> <em>num-b</em>)</h4>

<p>
	The <em>Incomplete Beta</em> function, <tt>betai</tt>, 
	equals the cumulative probability of the <em>Beta</em> distribution, <tt>betai</tt>, 
	at <em>x</em> in <em>num-x</em>. 
	The cumulative binomial distribution is defined as the probability of an event, <em>pev</em>, 
	with probability <em>p</em> to occur <em>k</em> or more times in <em>N</em> trials:
</p>


<p><em><b> pev = Betai(p, k, N - k + 1) </b></em></p>

<!-- example -->

<pre>
(betai 0.5 3 8)  <span class='arw'>&rarr;</span> 0.9453125
</pre>


<p>
The example calculates the probability for an event 
with a probability of 0.5 to occur 3 or more times in 10 trials (8 = 10 - 3 + 1). 
The incomplete Beta distribution can be used to derive a variety of other functions 
in mathematics and statistics. 
See also the <a href="#binomial">binomial</a> function.
</p>

<br/><br/>


<a name="bigint"></a>
<h2><span class="function">bigint</span></h2>
<h4>syntax: (bigint <em>number</em>)<br/>
syntax: (bigint <em>string</em>)</h4>

<p>A floating point or integer number gets converted to big integer format.
When converting from floating point, rounding errors occur going back and forth
between decimal and binary arithmetic.</p>

<p>A string argument gets parsed to a number and converted to a big integer.</p>

<!-- example -->

<pre>
(bigint 12345)          <span class='arw'>&rarr;</span> 12345L

(bigint 1.234567890e30) <span class='arw'>&rarr;</span> 1234567889999999957361000000000L 

(set 'num 567890)
(bigint num)            <span class='arw'>&rarr;</span> 567890L

(bigint "-54321")       <span class='arw'>&rarr;</span> -54321L
(bigint "123.45")       <span class='arw'>&rarr;</span> 123L
(bigint "123hello")     <span class='arw'>&rarr;</span> 123L
</pre>

<p>See also the manual chapter <a href="#big_int">Big integer, unlimited precision arithmetic</a></p>

<br/><br/>

<a name="bigintp"></a>
<h2><span class="function">bigint?</span></h2>
<h4>syntax: (bigint? <em>number</em>)</h4>

<p>Check if a number is formatted as a big integer.</p>

<!-- example -->

<pre>
(set 'x 12345)
(set 'y 12345L)
(set 'z 123456789012345678901234567890)
(set 'p 1.2345e20)
(set 'q (bigint p))

(bigint? x)  <span class='arw'>&rarr;</span> nil
(bigint? y)  <span class='arw'>&rarr;</span> true
(bigint? z)  <span class='arw'>&rarr;</span> true
(bigint? p)  <span class='arw'>&rarr;</span> nil
(bigint? q)  <span class='arw'>&rarr;</span> true
</pre>

<p>See also the manual chapter <a href="#big_int">Big integer, unlimited precision arithmetic</a></p>

<br/><br/>

<a name="bind"></a>

<h2><span class="function">bind</span>&nbsp;<a href="#destructive">!</a></h2>
<h4>syntax: (bind <em>list-variable-associations</em> [<em>bool-eval</em>])</h4>

<p><em>list-variable-associations</em> contains an association list of 
symbols and their values. <tt>bind</tt> sets all symbols
to their associated values.</p>

<p>The associated values are evaluated if the <em>bool-eval</em> flag is <tt>true</tt>:</p>

<pre>
(set 'lst '((a (+ 3 4)) (b "hello")))

(bind lst)         <span class='arw'>&rarr;</span> "hello"

a    <span class='arw'>&rarr;</span> (+ 3 4)
b    <span class='arw'>&rarr;</span> "hello"

(bind lst true)    <span class='arw'>&rarr;</span> "hello"

a    <span class='arw'>&rarr;</span> 7
</pre>

<p>The return value of bind is the value of the last association.</p>

<p><tt>bind</tt> is often used to bind association lists returned
by <a href="#unify">unify</a>.</p>

<pre>
(bind (unify '(p X Y a) '(p Y X X)))    <span class='arw'>&rarr;</span> a

X    <span class='arw'>&rarr;</span> a
Y    <span class='arw'>&rarr;</span> a
</pre>

<p>This can be used for de-structuring:</p>

<pre>
(set 'structure '((one "two") 3 (four (x y z))))
(set 'pattern '((A B) C (D E)))
(bind (unify pattern structure))

A <span class='arw'>&rarr;</span> one
B <span class='arw'>&rarr;</span> "two"
C <span class='arw'>&rarr;</span> 3
D <span class='arw'>&rarr;</span> four
E <span class='arw'>&rarr;</span> (x y z)
</pre>


<p><a href="#unify">unify</a>  returns an association list and <tt>bind</tt> binds the 
associations.</p>

<br/><br/>

<a name="binomial"></a>

<h2><span class="function">binomial</span></h2>
<h4>syntax: (binomial <em>int-n</em> <em>int-k</em> <em>float-p</em>)</h4>

<p>
The binomial distribution function is defined as the probability for an event 
to occur <em>int-k</em> times in <em>int-n</em> trials if that event has a 
probability of <em>float-p</em> and all trials are independent of one another:</p>


<em><b>binomial = pow(p, k) * pow(1.0 - p, n - k) * n! / (k! * (n - k)!)</b></em>


<p>
	where <em>x!</em> is the factorial of <em>x</em> 
	and <em>pow(x, y)</em> is <em>x</em> raised to the power of <em>y</em>.
</p>

<br/>

<!-- example -->

<pre>
(binomial 10 3 0.5)  <span class='arw'>&rarr;</span> 0.1171875
</pre>


<p>
	The example calculates the probability for an event 
	with a probability of 0.5 to occur 3 times in 10 trials. 
	For a cumulated distribution, 
	see the <a href="#betai">betai</a> function.
</p>

<br/><br/>

<a name="bits"></a>
<h2><span class="function">bits</span></h2>
<h4>syntax: (bits <em>int</em> [<em>bool</em>])</h4>

<p>Transforms a number in <em>int</em> to a string of 1's and 0's or a 
list, if <em>bool</em> evaluates to anything not <tt>nil</tt>.</p>

<p>In string representation bits are in high to low order. In list
presentation 1's and 0's are represented as <tt>true</tt> and <tt>nil</tt>
and in order from the lowest to the highest bit. This allows direct
indexing and program control switching on the result.</p>

<!-- example -->

<pre>
(bits 1234)      <span class='arw'>&rarr;</span> "10011010010"

(int (bits 1234) 0 2) <span class='arw'>&rarr;</span> 1234

(bits 1234 true)     <span class='arw'>&rarr;</span> (nil true nil nil true nil true true nil nil true)

((bits 1234 true) 0) <span class='arw'>&rarr;</span> nil ; indexing of the result
</pre>


<p><a href="#int">int</a> with a base of 2 is the inverse function to <tt>bits</tt>.</p>

<br/><br/>

<a name="callback"></a>
<h2><span class="function"> callback </span></h2>
<h4>syntax: (callback <em>int-index</em> <em>sym-function</em>)<br/>
syntax: (callback <em>sym-function</em> <em>str-return-type</em> [<em>str_param_type</em> ...])<br/>
syntax: (callback <em>sym-function</em>)</h4>

<p>In the first <b>simple <tt>callback</tt> syntax</b> up to sixteen (0 to 15) <em>callback</em> 
functions for up to eight parameters can be registered with imported libraries. 
The <tt>callback</tt> function returns a procedure address that invokes a 
user-defined function in <em>sym-function</em>. The following example shows 
the usage of callback functions when importing the <a href="http://www.opengl.org">OpenGL</a> 
graphics library:</p>

<p>If more than sixteen callback functions are required, slots must be 
reassigned to a different callback function.</p>

<!-- example -->

<pre>
...
(define (draw)
    (glClear GL_COLOR_BUFFER_BIT )
    (glRotated rotx 0.0 1.0 0.0)
    (glRotated roty 1.0 0.0 0.0)
    (glutWireTeapot 0.5)
    (glutSwapBuffers))

(define (keyboard key x y)
    (if (= (&amp; key 0xFF) 27) (exit)) ; exit program with ESC
    (println "key:" (&amp; key 0xFF) " x:" x  " y:" y))

(define (mouse button state x y)
    (if (= state 0)
        (glutIdleFunc 0) ; stop rotation on button press
        (glutIdleFunc (callback 4 'rotation)))
    (println "button: " button " state:" state " x:" x " y:" y))

(glutDisplayFunc (callback 0 'draw))
(glutKeyboardFunc (callback 1 'keyboard))
(glutMouseFunc (callback 2 'mouse))
...
</pre>


<p>The address returned by <tt>callback</tt> is registered with the 
<a href="http://www.opengl.org/documentation/specs/glut/spec3/spec3.html">Glut</a> library. 
The above code is a snippet from the file <tt>opengl-demo.lsp</tt>, 
in the <tt>examples/</tt> directory of the source distribution of newLISP
and can also be downloaded from 
<a href="http://www.newlisp.org/downloads/OpenGL/">newlisp.org/downloads/OpenGL</a>.</p>

<p>In the second <b>extended <tt>callback</tt> syntax</b> type specifiers are used to 
describe the functions return and parameter value types when the function is called. 
An unlimited number of callback functions can be registered with the second syntax, and 
return values are passed back to the calling function. The symbol in <em>sym-function</em>
contains a newLISP defined function used as a callback function callable from a C program.</p>

<p>In the third syntax <tt>callback</tt> returns a previously returned C-callable
address for that symbol.</p>

<p>While the first simple <tt>callback</tt> syntax only handles integers and pointer
values, <tt>callback</tt> in the expanded syntax can also handle simple and double precision
floating point numbers passed in an out of the <tt>callback</tt> function.</p>

<p>Both the simple and extended syntax can be mixed inside the same program.</p>

<p>The following example shows the <a href="#import">import</a> of the <tt>qsort</tt>
C library function, which takes as one of it's arguments the address of a comparison
function. The comparison function in this case is written in newLISP and called into
by the imported <tt>qsort</tt> function:</p>

<pre>
; C void qsort(...) takes an integer array with number and width
; of array elements and a pointer to the comparison function
(import "libc.dylib" "qsort" "void" "void*" "int" "int" "void*")

(set 'rlist '(2 3 1 2 4 4 3 3 0 3))
; pack the list into an C readable 32-bit integer array
(set 'carray (pack (dup "ld " 10) rlist))

; the comparison callback function receives pointers to integers
(define (cmp a b) 
    (- (get-int a) (get-int b)))

; generate a C callable address for cmp
(set 'func (callback 'cmp "int" "void*" "void*"))

; sort the carray
(qsort carray 10 4 func)

; unpack the sorted array into a LISP list
(unpack (dup "ld" 10) carray)  <span class='arw'>&rarr;</span>  (0 1 2 2 3 3 3 3 4 4) 
</pre>

<p>As type specifiers the same string tags can be used as in the 
<a href="#import">import</a> function. All pointer types are passed as numbers in and
out of the <tt>callback</tt> function. The functions <a href="#get-char">get-char</a>,
<a href="#get-int">get-int</a>, <a href="#get-long">get-long</a> and 
<a href="#get-string">get-string</a> can be used to extract numbers of
different precision from parameters. Use <a href="#pack">pack</a> and 
<a href="#unpack">unpack</a> to extract data from binary buffers and structures.</p>

<p>Note that newLISP as already a fast built-in <a href="#sort">sort</a> function.</p>

<br/><br/>

<a name="case"></a>
<h2><span class="function">case</span></h2>
<h4>syntax: (case <em>exp-switch</em> (<em>exp-1</em> <em>body-1</em>) [(<em>exp-2</em> <em>body-2</em>) ... ])</h4>

<p>The result of evaluating <em>exp-switch</em> 
is compared to each of the <em>unevaluated</em> expressions 
<em>exp-1, exp-2,</em> &mdash;. If a match is found, the 
corresponding expressions in <em>body</em> 
are evaluated.  The result of the last body expression is returned 
as the result for the entire <tt>case</tt> expression. </p>


<!-- example -->

<pre>
(define (translate n)
  (case n
    (1 "one")
    (2 "two")          
    (3 "three")
    (4 "four")
    (true "Can't translate this")))

(translate 3)   <span class='arw'>&rarr;</span> "three"
(translate 10)  <span class='arw'>&rarr;</span> "Can't translate this"
</pre>


<p>
	The example shows how, 
	if no match is found, 
	the last expression in the body of a <tt>case</tt> function
	can be evaluated.
</p>

<br/><br/>

<a name="catch"></a>
<h2><span class="function">catch</span></h2>

<h4>syntax: (catch <em>exp</em>)<br/>
syntax: (catch <em>exp</em> <em>symbol</em>)</h4>

<p>
	In the first syntax, 
	<tt>catch</tt> will return the result of the evaluation of <em>exp</em> 
	or the evaluated argument of a <a href="#throw">throw</a> 
	executed during the evaluation of <em>exp</em>:
</p>

<!-- example -->

<pre>
(catch (dotimes (x 1000) 
  (if (= x 500) (throw x))))  <span class='arw'>&rarr;</span> 500
</pre>


<p>
	This form is useful for breaking out of iteration loops 
	and for forcing an early return 
	from a function or expression block:
</p>


<pre>
(define (foo x)
   &hellip;
  (if condition (throw 123))
    &hellip;
  456)

;; if condition is true

(catch (foo p))  <span class='arw'>&rarr;</span> 123

;; if condition is not true

(catch (foo p))  <span class='arw'>&rarr;</span> 456
</pre>



<p>
	In the second syntax, 
	<tt>catch</tt> evaluates the expression <em>exp</em>, 
	stores the result in <em>symbol</em>, 
	and returns <tt>true</tt>.  
	If an error occurs during evaluation, 
	<tt>catch</tt> returns <tt>nil</tt> 
	and stores the error message in <em>symbol</em>. 
	This form can be useful when errors are expected 
	as a normal potential outcome of a function 
	and are dealt with during program execution.
</p>

<!-- example -->

<pre>
(catch (func 3 4) 'result)  <span class='arw'>&rarr;</span> nil
result  
<span class='arw'>&rarr;</span> <span class='err'>"ERR: invalid function in function catch : (func 3 4)"</span>

(constant 'func +)          <span class='arw'>&rarr;</span> + &lt;4068A6&gt;
(catch (func 3 4) 'result)  <span class='arw'>&rarr;</span> true
result                      <span class='arw'>&rarr;</span> 7
</pre>


<p>
	When a <a href="#throw">throw</a> is executed during the evaluation of <em>exp</em>,
	<tt>catch</tt> will return <tt>true</tt>, 
	and the <tt>throw</tt> argument will be stored in <em>symbol</em>:
</p>


<pre>
(catch (dotimes (x 100) 
  (if (= x 50) (throw "fin"))) 'result)  <span class='arw'>&rarr;</span> true

result  <span class='arw'>&rarr;</span> "fin"
</pre>


<p>
	As well as being used for early returns from functions and 
	for breaking out of iteration loops (as in the first syntax), 
	the second syntax of <tt>catch</tt> can also be used to catch errors. 
	The <a href="#throw-error">throw-error</a> function may be used 
	to throw user-defined errors.
</p>

<br/><br/>

<a name="ceil"></a>
<h2><span class="function">ceil</span></h2>
<h4>syntax: (ceil <em>number</em>)</h4>

<p>
	Returns the next highest integer above <em>number</em> 
	as a floating point.
</p>

<!-- example -->

<pre>
(ceil -1.5)  <span class='arw'>&rarr;</span> -1
(ceil 3.4)   <span class='arw'>&rarr;</span> 4
</pre>


<p>See also the <a href="#floor">floor</a> function.
</p>

<br/><br/>


<a name="change-dir"></a>
<h2><span class="function">change-dir</span></h2>
<h4>syntax: (change-dir <em>str-path</em>)</h4>

<p>
	Changes the current directory to be the one given in <em>str-path</em>.
	If successful, <tt>true</tt> is returned; otherwise <tt>nil</tt> is returned.
</p>

<!-- example -->

<pre>
(change-dir "/etc")
</pre>


<p>
	Makes <tt>/etc</tt> the current directory.
</p>

<br/><br/>

<a name="char"></a>
<h2><span class="function">char</span>&nbsp;<font size="-1"><a href="#utf8_capable">utf8</a></font></h2>
<h4>syntax: (char <em>str</em> [<em>int-index</em> [true]])<br/>
syntax: (char <em>int</em>)</h4>

<p>Given a string argument, extracts the character at <em>int-index</em> from <em>str</em>,
returning either the ASCII value of that character or the Unicode value on UTF-8 enabled 
versions of newLISP.</p>

<p>If <em>int-index</em> is omitted, 0 (zero) is assumed. If <em>int-idx</em>
is followed by a boolean <tt>true</tt> value, than the index treats <em>str</em> as an 8-bit  byte
array instead of an array of multi-byte UTF-8 characters.</p>

<p>The empty string returns <tt>nil</tt>. Both <tt>(char 0)</tt> and <tt>(char nil)</tt> will 
return <tt>"\000"</tt>.</p>

<p>
See <a href="#indexing">Indexing elements of strings and lists</a>.
</p>

<p>
Given an integer argument, 
<tt>char</tt> returns a string containing the ASCII character 
with value <em>int</em>.
</p>

<p>
On UTF-8&ndash;enabled versions of newLISP, the value in <em>int</em> 
is taken as Unicode and a UTF-8 character is returned.
</p>

<!-- example -->

<pre>
(char "ABC")          <span class='arw'>&rarr;</span> 65  ; ASCII code for "A"
(char "ABC" 1)        <span class='arw'>&rarr;</span> 66  ; ASCII code for "B"
(char "ABC" -1)       <span class='arw'>&rarr;</span> 67  ; ASCII code for "C"
(char "B")            <span class='arw'>&rarr;</span> 66  ; ASCII code for "B"
(char "Ω")            <span class='arw'>&rarr;</span> 937 ; UTF-8 code for "Ω"
(char "Ω" 1 true)     <span class='arw'>&rarr;</span> 169 ; byte value at offset 1

(char 65)  <span class='arw'>&rarr;</span> "A"
(char 66)  <span class='arw'>&rarr;</span> "B"

(char (char 65))  <span class='arw'>&rarr;</span> 65      ; two inverse applications

(map char (sequence 1 255))  ; returns current character set

; The Zen of UTF-8
(char (&amp; (char "生") (char "死"))) <span class='arw'>&rarr;</span> 愛 ; by @kosh_bot
</pre>

<br/><br/>

<a name="chop"></a>
<h2><span class="function">chop</span>&nbsp;<font size="-1"><a href="#utf8_capable">utf8</a></font></h2>
<h4>syntax: (chop <em>str</em> [<em>int-chars</em>])<br/>
syntax: (chop <em>list</em> [<em>int-elements</em>])</h4>

<p>
	If the first argument evaluates to a string, 
	<tt>chop</tt> returns a copy of <em>str</em> 
	with the last <em>int-char</em> characters omitted.
	If the <em>int-char</em> argument is absent, 
	one character is omitted.
	<tt>chop</tt> does not alter <em>str</em>.</p>


<p>
	If the first argument evaluates to a list, 
	a copy of <em>list</em> is returned 
	with <em>int-elements</em> omitted 
	(same as for strings).
</p>

<!-- example -->

<pre>
(set 'str "newLISP")  <span class='arw'>&rarr;</span> "newLISP"
                      
(chop str)    <span class='arw'>&rarr;</span> "newLIS"
(chop str 2)  <span class='arw'>&rarr;</span> "newLI"
                      
str  <span class='arw'>&rarr;</span> "newLISP"

(set 'lst '(a b (c d) e))

(chop lst)    <span class='arw'>&rarr;</span> (a b (c d))
(chop lst 2)  <span class='arw'>&rarr;</span> (a b)
                      
lst  <span class='arw'>&rarr;</span> (a b (c d) e)
</pre>

<br/><br/>

<a name="clean"></a>
<h2><span class="function">clean</span></h2>
<h4>syntax: (clean <em>exp-predicate</em> <em>list</em>)</h4>

<p>
	The predicate <em>exp-predicate</em> is applied 
	to each element of <em>list</em>. 
	In the returned list, 
	all elements for which <em>exp-predicate</em> is <tt>true</tt> 
	are eliminated.
</p>

<p>
	<tt>clean</tt> works like <a href="#filter">filter</a> 
	with a negated predicate.
</p>

<!-- example -->

<pre>
(clean symbol? '(1 2 d 4 f g 5 h))   <span class='arw'>&rarr;</span> (1 2 4 5)

(filter symbol? '(1 2 d 4 f g 5 h))  <span class='arw'>&rarr;</span> (d f g h)

(define (big? x) (&gt; x 5))        <span class='arw'>&rarr;</span> (lambda (x) (&gt; x 5))

(clean big? '(1 10 3 6 4 5 11))  <span class='arw'>&rarr;</span> (1 3 4 5)

(clean &lt;= '(3 4 -6 0 2 -3 0))  <span class='arw'>&rarr;</span> (3 4 2)

(clean (curry match '(a *)) '((a 10) (b 5) (a 3) (c 8) (a 9)))
<span class='arw'>&rarr;</span>  ((b 5) (c 8))
</pre>


<p>
	The predicate may be a built-in predicate 
	or a user-defined function or lambda expression.
</p>

<p>
	For cleaning numbers from one list 
	using numbers from another, 
	use <a href="#difference">difference</a> 
	or <a href="#intersect">intersect</a> 
	(with the list mode option).
</p>

<p>
	See also the related function <a href="#index">index</a>, 
	which returns the indices of the remaining elements, 
	and <a href="#filter">filter</a>, 
	which returns all elements for which a predicate returns true.
</p>

<br/><br/>


<a name="close"></a>
<h2><span class="function">close</span></h2>
<h4>syntax: (close <em>int-file</em>)</h4>

<p>
	Closes the file specified by the file handle in <em>int-file</em>. 
	The handle would have been obtained 
	from a previous <a href="#open">open</a> operation. 
	If successful, <tt>close</tt> returns <tt>true</tt>; otherwise  <tt>nil</tt> is returned.
</p>

<!-- example -->

<pre>
(close (device))  <span class='arw'>&rarr;</span> true
(close 7)         <span class='arw'>&rarr;</span> true
(close aHandle)   <span class='arw'>&rarr;</span> true
</pre>


<p>
	Note that using <tt>close</tt> on <a href="#device">device</a> 
	automatically resets it to 0 (zero, the screen device).
</p>
	
<br/><br/>

<a name="collect"></a>
<h2><span class="function">collect</span></h2>
<h4>syntax: (collect <em>exp</em> [<em>int-max-count</em>])</h4>

<p>Evaluates the expression in <em>exp</em>  and collects the results in a list
until evaluation of <em>exp</em> returns <tt>nil</tt>.</p>

<p>Optionally a maximum count of elements can be specified in <em>int-max-count</em>.</p>

<pre>
; collect results until nil is returned
(set 'x 0)
(collect (if (&lt;= (inc x) 10) x)) <span class='arw'>&rarr;</span> (1 2 3 4 5 6 7 8 9 10)

; collect results until nil is returned or 6 results are collected
(set 'x 0)
(collect (if (&lt;= (inc x) 10) x) 6) <span class='arw'>&rarr;</span> (1 2 3 4 5 6)
</pre>

<br/><br/>

<a name="command-event"></a>
<h2><span class="function">command-event</span></h2>
<h4>syntax: (command-event <em>sym-event-handler</em> | <em>func-event-handler</em>)<br/>
syntax: (command-event nil)</h4>

<p>Specifies a user defined function for pre-processing the newLISP command-line
before it gets evaluated. This can be used to write customized interactive
 newLISP shells and to transform HTTP requests when running in server mode.</p>

<p><tt>command-event</tt> takes either a symbol of a user-defined function or a lambda 
function. The event-handler function must return a string or the command-line will be 
passed untranslated to newLISP.</p>

<p>To only force a prompt and disable command processing, the function should return 
the empty string <tt>""</tt>. To reset <tt>command-event</tt>, use the second syntax.</p>

<p>The following example makes the newLISP shell work like a normal Unix
shell when the command starts with a letter. But starting the line with an open
parenthesis or a space initiates a newLISP evaluation.</p>

<!-- example -->

<pre>
(command-event (fn (s) 
	(if (starts-with s "[a-zA-Z]" 0) (append "!" s) s)))
</pre>


<p>See also the related <a href="#prompt-event">prompt-event</a> which can be used
for further customizing interactive mode by modifying the newLISP prompt.</p>

<p>The following program can be used either stand-alone or included in newLISP's
<tt>init.lsp</tt> startup file:</p>

<pre>
#!/usr/local/bin/newlisp

; set the prompt to the current directory name
(prompt-event (fn (ctx) (append (real-path) "&gt; ")))

; pre-process the command-line
(command-event (fn (s) 
    (if 
        (starts-with s "cd") 
        (string " " (true? (change-dir (last (parse s " ")))))

        (starts-with s "[a-zA-Z]" 0)
        (append "!" s)

        true s)))
</pre> 

<p>In the definition of the command-line translation function the Unix
command <tt>cd</tt> gets a special treatment, to make sure that the directory
is changed for newLISP process too. This way when shelling out with <tt>!</tt> and
coming back, newLISP will maintain the changed directory.</p>

<p>Command lines for newLISP must start either with a space or an opening
parenthesis. Unix commands must start at the beginning of the line.</p>

<p>When newLISP is running in server mode either using the <tt>-c</tt> or
<tt>-http</tt> option, it receives HTTP requests similar to the following:</p>

<pre>
GET /index.html
</pre> 

<p>Or if a query is involved:</p>

<pre>
GET /index.cgi?userid=joe&amp;password=secret
</pre> 

<p>A function specified by <tt>command-event</tt> could filter and transform 
these request lines, e.g.: discovering all queries trying to perform CGI using
a file ending in <tt>.exe</tt>.&nbsp; Such a request would be translated into a
request for an error page:</p>

<pre>
;; httpd-conf.lsp
;;
;; filter and translate HTTP requests for newLISP
;; -c or -http server modes
;; reject query commands using CGI with .exe files

(command-event (fn (s)
    (let (request s)
        (when (find "?" s) ; is this a query
            (set 'request (first (parse s "?")))
            ; discover illegal extension in queries
            (when (ends-with request ".exe")
                (set 'request "GET /errorpage.html")) )
        request)
))
</pre> 

<p>When starting the server mode with <tt>newlisp httpd-conf.lsp -c -d80 -w ./httpdoc</tt>
newLISP will load the definition for <tt>command-event</tt> for filtering incoming
requests, and the query:</p>

<pre>
GET /cmd.exe?dir
</pre> 

<p>Would be translated into:</p>

<pre>
GET /errorpage.html
</pre> 

<p>The example shows a technique frequently used in the past by spammers on MS 
Windows based, bad configured web servers to gain control over servers.</p>

<p><tt>httpd-conf.lsp</tt> files can easily be debugged loading the file into an interactive
newLISP session and entering the HTTP requests manually. newLISP will translate the command
line and dispatch it to the built-in web server. The server output will appear in the shell
window.</p>

<p>Note, that the command line length as well as the line length in HTTP headers is limited to 512 characters for newLISP.</p>

<br/><br/>

<a name="cond"></a>
<h2><span class="function">cond</span></h2>

<h4>syntax: (cond (<em>exp-condition-1</em> <em>body-1</em>) [(<em>exp-condition-2</em> <em>body-2</em>) ... ])</h4>

<p>
	Like <tt>if</tt>, <tt>cond</tt> conditionally evaluates the expressions 
	within its body. 
	The <em>exp-condition</em>s are evaluated in turn, 
	until some <em>exp-condition-i</em> is found 
	that evaluates to anything other than <tt>nil</tt> 
	or an empty list <tt>()</tt>.
	The result of evaluating <em>body-i</em> 
	is then returned as the result of the entire <em>cond-expression</em>. 
	If all conditions evaluate to <tt>nil</tt> 
	or an empty list,
	<em>cond</em> returns the value of the last <em>cond-expression</em>.
</p>

<!-- example -->

<pre>
(define (classify x)
  (cond
    ((&lt; x 0) "negative")
    ((&lt; x 10) "small")
    ((&lt; x 20) "medium")
    ((&gt;= x 30) "big")))

(classify 15)   <span class='arw'>&rarr;</span> "medium"
(classify 22)   <span class='arw'>&rarr;</span> "nil"
(classify 100)  <span class='arw'>&rarr;</span> "big"
(classify -10)  <span class='arw'>&rarr;</span> "negative"
</pre>


<p>
	When a <em>body-n</em> is missing, 
	the value of the last <em>cond-expression</em> evaluated 
	is returned. 
	If no condition evaluates to <tt>true</tt>, 
	the value of the last conditional expression is returned
	(i.e., <tt>nil</tt> or an empty list).
</p>


<pre>
(cond ((+ 3 4)))  <span class='arw'>&rarr;</span> 7
</pre>


<p>
	When used with multiple arguments, 
	the function <a href="#if">if</a> 
	behaves like <tt>cond</tt>, 
	except it does not need extra parentheses 
	to enclose the condition-body pair 
	of expressions.
</p>

<br/><br/>

<a name="cons"></a>
<h2><span class="function">cons</span></h2>
<h4>syntax: (cons <em>exp-1</em> <em>exp-2</em>)</h4>

<p>
	If <em>exp-2</em> evaluates to a list, 
	then a list is returned with the result of evaluating <em>exp-1</em> 
	inserted as the first element. 
	If <em>exp-2 </em>evaluates to anything other than a list, 
	the results of evaluating <em>exp-1</em> and <em>exp-2</em> 
	are returned in a list. 
	Note that there is no <em>dotted pair</em> in newLISP:
	<em>cons</em>ing two atoms constructs a list, not a dotted pair.
</p>

<!-- example -->

<pre>
(cons 'a 'b)            <span class='arw'>&rarr;</span> (a b)
(cons 'a '(b c))        <span class='arw'>&rarr;</span> (a b c)
(cons (+ 3 4) (* 5 5))  <span class='arw'>&rarr;</span> (7 25)
(cons '(1 2) '(3 4))    <span class='arw'>&rarr;</span> ((1 2) 3 4)
(cons nil 1)            <span class='arw'>&rarr;</span> (nil 1)
(cons 1 nil)            <span class='arw'>&rarr;</span> (1 nil)
(cons 1)                <span class='arw'>&rarr;</span> (1)
(cons)			<span class='arw'>&rarr;</span> ()
</pre>


<p>
	Unlike other Lisps that return <tt>(s)</tt>
	as the result of the expression <tt>(cons 's nil)</tt>, 
	newLISP's <tt>cons</tt> returns <tt>(s nil)</tt>. 
	In newLISP, <tt>nil</tt> is a Boolean value 
	and is not equivalent to an empty list, 
	and a newLISP cell holds only one value.
</p>

<p>
	<tt>cons</tt> behaves like the inverse operation of <a href="#first">first</a>
and <a href="#rest">rest</a> 
	(or <a href="#first">first</a> and <a href="#last">last</a> if the list is a pair):
</p>


<pre>
(cons (first '(a b c)) (rest '(a b c)))  <span class='arw'>&rarr;</span> (a b c)

(cons (first '(x y)) (last '(x y)))      <span class='arw'>&rarr;</span> (x y)
</pre>

<br/><br/>

<a name="constant"></a>
<h2><span class="function">constant</span>&nbsp;<a href="#destructive">!</a></h2>
<h4>syntax: (constant <em>sym-1</em> <em>exp-1</em> [<em>sym-2</em> <em>exp-2</em>] ...)</h4>

<p>
	Identical to <a href="#set">set</a> in functionality,
	<tt>constant</tt> further protects the symbols from subsequent modification. 
	A symbol set with <tt>constant</tt> can only be modified 
	using the <tt>constant</tt> function again.  
	When an attempt is made to modify the contents of a symbol protected with <tt>constant</tt>, 
	newLISP generates an error message. 
	Only symbols from the current context can be used with <tt>constant</tt>. 
	This prevents the overwriting of symbols 
	that have been protected in their home context.
	The last <em>exp-n</em> initializer is always optional.
</p>

<p>
	Symbols initialized with <a href="#set">set</a>, <a href="#define">define</a>, 
	or <a href="#define-macro"> define-macro</a> can still be protected by using 
	the <tt>constant</tt> function:
</p>

<pre>
(constant 'aVar 123)  <span class='arw'>&rarr;</span> 123
(set 'aVar 999) 
<span class='err'>ERR: symbol is protected in function set: aVar</span>

(define (double x) (+ x x))

(constant 'double)

;; equivalent to

(constant 'double (fn (x) (+ x x)))
</pre>


<p>
	The first example defines a constant, <tt>aVar</tt>, 
	which can only be changed by using another <tt>constant</tt> statement. 
	The second example protects <tt>double</tt> from being changed
	(except by <tt>constant</tt>). 
	Because a function definition in newLISP 
	is equivalent to an assignment of a lambda function, 
	both steps can be collapsed into one, 
	as shown in the last statement line. 
	This could be an important technique 
	for avoiding protection errors 
	when a file is loaded multiple times.
</p>

<p>
	The last value to be assigned can be omitted. 
	<tt>constant</tt> returns the contents of
	the last symbol set and protected.
</p>

<p>
	Built-in functions can be assigned to symbols 
	or to the names of other built-in functions, 
	effectively redefining them as different functions.
	There is no performance loss when renaming functions.
</p>


<pre>
(constant 'squareroot sqrt)  <span class='arw'>&rarr;</span> sqrt &lt;406C2E&gt;
(constant '+ add)            <span class='arw'>&rarr;</span> add &lt;4068A6&gt;
</pre>


<p>
	<tt>squareroot</tt> will behave like <tt>sqrt</tt>. 
	The <tt>+</tt> (plus sign) is redefined 
	to use the mixed type floating point mode of <tt>add</tt>. 
	The hexadecimal number displayed in the result 
	is the binary address of the built-in function 
	and varies on different platforms and OSes.
</p>

<br/><br/>

<a name="context"></a>
<h2><span class="function">context</span></h2>
<h4>syntax: (context [<em>sym-context</em>])<br/>
syntax: (context <em>sym-context</em> <em>str | sym</em> [<em>exp-value</em>])</h4>

<p> In the first syntax, <tt>context</tt> is used to switch to a different context namespace. 
Subsequent <a href="#load">load</a>s of newLISP source or functions like 
<a href="#eval-string">eval-string</a> and <a href="#sym">sym</a> will put newly created 
symbols and function definitions in the new context.</p>

<p>If the context still needs to be created, the symbol for the new context should be specified. 
When no argument is passed to <tt>context</tt>, then the symbol for the current context is returned. </p>

<p>Because contexts evaluate to themselves, a quote is not necessary 
to switch to a different context if that context already exists.
</p>

<!-- example -->

<pre>
(context 'GRAPH)          ; create / switch context GRAPH

(define (foo-draw x y z)  ; function resides in GRAPH
  (&hellip;))
                                
(set 'var 12345)
(symbols)  <span class='arw'>&rarr;</span> (foo-draw var)  ; GRAPH has now two symbols

(context MAIN)               ; switch back to MAIN (quote not required)

(print GRAPH:var) <span class='arw'>&rarr;</span> 12345    ; contents of symbol in GRAPH

(GRAPH:foo-draw 10 20 30)    ; execute function in GRAPH
(set 'GRAPH:var 6789)        ; assign to a symbol in GRAPH
</pre>


<p>
	If a context symbol is referred to before the context exists, 
	the context will be created implicitly.
</p>


<pre>
(set 'person:age 0)       ; no need to create context first
(set 'person:address "")  ; useful for quickly defining data structures
</pre>


<p>
	Contexts can be copied:
</p>


<pre>
(new person 'JohnDoe)  <span class='arw'>&rarr;</span>  JohnDoe

(set 'JohnDoe:age 99)
</pre>


<p>
	Contexts can be referred to by a variable:
</p>


<pre>
(set 'human JohnDoe)

human:age  <span class='arw'>&rarr;</span> 99

(set 'human:address "1 Main Street")

JohnDoe:address  <span class='arw'>&rarr;</span> "1 Main Street"
</pre>



<p>An evaluated context (no quote) can be given as an argument:
</p>


<pre>
<b>&gt;</b> (context 'FOO)
<b>FOO</b>
<b>FOO></b> (context MAIN)
<b>MAIN</b>
<b>&gt;</b> (set 'old FOO)
FOO
<b>&gt;</b> (context 'BAR)
<b>BAR</b>
<b>BAR></b> (context MAIN:old)
<b>FOO</b>
<b>FOO></b> 
</pre>



<p>
	If an identifier with the same symbol already exists, 
	it is redefined to be a context.
</p>

<p>
	Symbols within the current context 
	are referred to simply by their names, 
	as are built-in functions and special symbols 
	like <tt>nil</tt> and <tt>true</tt>. 
	Symbols outside the current context 
	are referenced by prefixing the symbol name 
	with the context name and a <tt>:</tt> (colon). 
	To quote a symbol in a different context, 
	prefix the context name with a <tt>'</tt> (single quote).
</p>

<p>
	Within a given context, symbols may be created 
	with the same name as built-in functions 
	or context symbols in MAIN.
	This overwrites the symbols in MAIN 
	when they are prefixed with a context:
</p>


<pre>
(context 'CTX)
(define (CTX:new var)
    (&hellip;))
    
(context 'MAIN)
</pre>


<p><tt>CTX:new</tt> will overwrite new in MAIN.</p>

<p> In the second syntax, <tt>context</tt> can be used to create symbols in a namespace.
Note that this should not be used for creating hashes or dictionaries. For a shorter,
more convenient method to use namespaces as hash-like dictionaries, see the chapter 
<a href="#hash">Hash functions and dictionaries</a>.
</p>


<pre>
;; create a symbol and store data in it
(context 'Ctx "abc" 123)   <span class='arw'>&rarr;</span> 123
(context 'Ctx 'xyz 999)    <span class='arw'>&rarr;</span> 999

;; retrieve contents from  symbol
(context 'Ctx "abc")       <span class='arw'>&rarr;</span> 123
(context 'Ctx 'xyz)        <span class='arw'>&rarr;</span> 999
Ctx:abc                    <span class='arw'>&rarr;</span> 123
Ctx:xyz                    <span class='arw'>&rarr;</span> 999
</pre>


<p>
The first three statements create a symbol and store a value of any data type inside. 
The first statement also creates the context named <tt>Ctx</tt>.
When a symbol is specified for the name, the name is taken
from the symbol and creates a symbol with the same name
in the context <tt>Ctx</tt>.
</p>

<p>
Symbols can contain spaces or any other special characters 
not typically allowed in newLISP symbols being used as variable names. 
This second syntax of <tt>context</tt> only creates the new symbol 
and returns the value contained in it.  It does not switch to the new namespace.
</p>

<br/><br/>

<a name="contextp"></a>
<h2><span class="function">context?</span></h2>

<h4>syntax: (context? <em>exp</em>)<br/>
syntax: (context? <em>exp</em> <em>str-sym</em>)</h4>

<p>
	In the first syntax, 
	<em>context?</em> is a predicate that returns <tt>true</tt> 
	only if <em>exp</em> evaluates to a context; 
	otherwise, it returns <tt>nil</tt>.
</p>

<!-- example -->

<pre>
(context? MAIN)  <span class='arw'>&rarr;</span> true
(set 'x 123)
(context? x)     <span class='arw'>&rarr;</span> nil

(set 'FOO:q "hola")  <span class='arw'>&rarr;</span> "hola"
(set 'ctx FOO)
(context? ctx)       <span class='arw'>&rarr;</span> true  ; ctx contains context foo
</pre>


<p>
	The second syntax checks for the existence of a symbol in a context. 
	The symbol is specified by its name string in <em>str-sym</em>.
</p>


<pre>
(context? FOO "q")  <span class='arw'>&rarr;</span> true
(context? FOO "p")  <span class='arw'>&rarr;</span> nil
</pre>


<p>
	Use <a href="#context">context</a> to change and create namespaces 
	and to create hash symbols in contexts.
</p>

<br/><br/>

<a name="copy"></a>
<h2><span class="function">copy</span></h2>
<h4>syntax: (copy <em>exp</em>)<br/>
syntax: (copy <em>int-addr</em> [<em>bool-flag</em>])</h4>

<p>The first syntax makes a copy from evaluating expression in <em>exp</em>. 
Some built-in functions are <a href="#destructice">destructive</a>, changing 
the original contents of a list, array or string they are working on. 
With <tt>copy</tt> their behavior can be made non-destructive.</p>

<pre>
(set 'aList '(a b c d e f))

(replace 'c (copy aList)) <span class='arw'>&rarr;</span> (a b d e f)

aList <span class='arw'>&rarr;</span> (a b c d e f)

(set 'str "newLISP") <span class='arw'>&rarr;</span> "newLISP"

(rotate (copy str)) <span class='arw'>&rarr;</span> "PnewLIS"

str <span class='arw'>&rarr;</span> "newLISP" 
</pre>

<p>Using <tt>copy</tt> the functions <a href="#replace">replace</a> and
<a href="#rotate">rotate</a> are prevented from changing the data.
A modified version of the data is returned.</p>

<p>The second syntax, marked by the <tt>true</tt> in <em>bool-flag</em>,
copies a newLISP expression from a memory address.The following two
expressions are equivalent:</p>

<pre>
(set 'x "hello world")
(copy x)  <span class='arw'>&rarr;</span> "hello world"
(copy (first (dump x)) true) <span class='arw'>&rarr;</span> "hello world"
</pre>

<p>The second syntax can be useful when interfacing with C-code generating
newLISP expressions.</p>


<br/><br/>

<a name="copy-file"></a>
<h2><span class="function">copy-file</span></h2>
<h4>syntax: (copy-file <em>str-from-name</em> <em>str-to-name</em>)</h4>

<p>
	Copies a file from a path-filename given in <em>str-from-name</em> 
	to a path-filename given in <em>str-to-name</em>. 
	Returns <tt>true</tt> if the copy was successful or <tt>nil</tt>, 
	if the copy was unsuccessful.
</p>

<!-- example -->

<pre>
(copy-file "/home/me/newlisp/data.lsp" "/tmp/data.lsp")
</pre>

<br/><br/>

<a name="corr"></a>
<h2><span class="function">corr</span></h2>
<h4>syntax: (corr <em>list-vector-X</em> <em>list-vector-Y</em>)</h4>

<p>Calculates the <em>Pearson</em> product-moment correlation coefficient as a measure
of the linear relationship between the two variables in  <em>list-vector-X</em>
and  <em>list-vector-Y</em>. Both lists must be of same length.</p>

<p><tt>corr</tt> returns a list containing the following values:</p>

<table>
<tr align="left"><th>name</th><th>description</th></tr>
<tr><td>r</td><td>Correlation coefficient</td></tr>
<tr><td>b0</td><td>Regression coefficient offset</td></tr>
<tr><td>b1</td><td>Regression coefficient slope</td></tr>
<tr><td>t</td><td>t - statistic for significance testing</td></tr>
<tr><td>df</td><td>Degrees of freedom for t</td></tr>
<tr><td>p</td><td>Two tailed probability of t under the null hypothesis</td></tr>
</table>
<br />
<!-- example -->

<pre>
(set 'study-time '(90 100 130 150 180 200 220 300 350 400))
(set 'test-errors '(25 28 20 20 15 12 13 10 8 6))

(corr study-time test-errors) <span class='arw'>&rarr;</span> (-0.926 29.241 -0.064 -6.944 8 0.0001190)
</pre>

<p>The negative correlation of <tt>-0.926</tt> between study time and test errors is 
highly significant with a two-tailed <tt>p</tt> of about <tt>0.0001</tt> under the null hypothesis.</p>

<p>The regression coefficients <tt>b0 = 29.241</tt> and <tt>b1 = -0.064</tt>
can be used to estimate values of the Y variable (test errors) from values in X (study time)
using the equation <tt><em><b>Y = b0 + b1 * X</b></em></tt>.</p>

<br/><br/>

<a name="cos"></a>
<h2><span class="function">cos</span></h2>
<h4>syntax: (cos <em>num-radians</em>)</h4>

<p>
	Calculates the cosine of <em>num-radians</em>
	and returns the result.
</p>

<!-- example -->

<pre>
(cos 1)                     <span class='arw'>&rarr;</span> 0.5403023059
(set 'pi (mul 2 (acos 0)))  <span class='arw'>&rarr;</span> 3.141592654
(cos pi)                    <span class='arw'>&rarr;</span> -1
</pre>

<br/><br/>

<a name="cosh"></a>
<h2><span class="function">cosh</span></h2>
<h4>syntax: (cosh <em>num-radians</em>)</h4>

<p>Calculates the hyperbolic cosine of <em>num-radians</em>. 
The hyperbolic cosine is defined mathematically as: 
<em>(exp (x) + exp (-x)) / 2</em>.
An overflow to <tt>inf</tt> may occur 
if <em>num-radians</em> is too large.</p>

<!-- example -->

<pre>
(cosh 1)     <span class='arw'>&rarr;</span> 1.543080635
(cosh 10)    <span class='arw'>&rarr;</span> 11013.23292
(cosh 1000)  <span class='arw'>&rarr;</span> inf
(= (cosh 1) (div (add (exp 1) (exp -1)) 2))  <span class='arw'>&rarr;</span> true
</pre>

<br/><br/>

<a name="count"></a>
<h2><span class="function">count</span></h2>
<h4>syntax: (count <em>list-1</em> <em>list-2</em>)</h4>

<p>
	Counts elements of <em>list-1</em> in <em>list-2</em> 
	and returns a list of those counts.
</p>

<!-- example -->

<pre>
(count '(1 2 3) '(3 2 1 4 2 3 1 1 2 2))  <span class='arw'>&rarr;</span> (3 4 2)
(count '(z a) '(z d z b a z y a))        <span class='arw'>&rarr;</span> (3 2)

(set 'lst (explode (read-file "myFile.txt")))
(set 'letter-counts (count (unique lst) lst))
</pre>

<p>
	The second example counts all occurrences 
	of different letters in <tt>myFile.txt</tt>.
</p>

<p>
	The first list in <tt>count</tt>, 
	which specifies the items to be counted in the second list, 
	should be unique. 
	For items that are not unique, 
	only the first instance will carry a count; 
	all other instances will display <tt>0</tt> (zero).
</p>

<br/><br/>

<a name="cpymem"></a>
<h2><span class="function">cpymem</span>&nbsp; 
<a href="#shared-lib"><font size="+2">&#x26A0;</font></a></h2>
<h4>syntax: (cpymem <em>int-from-address</em> <em>int-to-address</em> <em>int-bytes</em>)</h4>

<p>Copies <em>int-bytes</em> of memory from <em>int-from-address</em> 
to <em>int-to-address</em>. This function can be used for 
direct memory writing/reading or for hacking newLISP internals
(e.g., type bits in newLISP cells, or building functions with binary 
executable code on the fly).</p>

<p>Note that this function should only be used when familiar with newLISP internals.
<tt>cpymem</tt> can crash the system or make it unstable if used incorrectly.</p>

<!-- example -->

<pre>
(set 's "0123456789")

(cpymem "xxx" (+ (address s) 5) 3)

s  <span class='arw'>&rarr;</span> "01234xxx89")
</pre>


<p>The example copies a string directly into a string variable.</p>

<p>The following example creates a new function from scratch, 
runs a piece of binary code, and adds up two numbers. 
This assembly language snippet shows the x86 (Intel CPU) code 
to add up two numbers and return the result:</p>


<pre>
 55       push ebp
 8B EC    mov  ebp, esp
 8B 45 08 mov  eax, [ebp+08]
 03 45 0C add  eax, [ebp+0c]
 5D       pop  ebp
 C3       ret

 ; for Win32/stdcall change last line
 C2 08 00 ret 
</pre>


<p>The binary representation is attached to a new function created 
in newLISP:</p>


<pre>
; set up 32-bit version of machine code
; on Windows use 32-bit version of newLISP
(set 'foo-code (append
     (pack "bbbbbbbbbb" 0x55 0x8B 0xEC 0x8B 0x45 0x08 0x03 0x45 0x0C 0x5D)
     (if (= ostype "Windows") (pack "bbb" 0xC2 0x08 0x00) (pack "b" 0xC3))))

; put a function cell template into foo, protect symbol from deletion
(constant 'foo print)

; put the correct type, either 'stdcall' or 'cdecl'
(cpymem (pack "ld" (if (= ostype "Windows") 8456 4360)) (first (dump foo)) 4)

; put the address of foo-code into the new function cell
(cpymem (pack "ld" (address foo-code)) (+ (first (dump foo)) 12) 4)

; take the name address from the foo symbol, copy into function cell
(set 'sym-name (first (unpack "lu" (+ (address 'foo) 8))))
(cpymem (pack "ld" sym-name) (+ (first (dump foo)) 8) 4)

; test the new function
(println "3 * 4 -> " (foo 3 4))
</pre>

<p>The last example will not work on all hardware platforms and OSs.</p>

<p>Use the <a href="#dump">dump</a> function to retrieve binary addresses 
and the contents from newLISP cells.</p>


<br/><br/>

<a name="crc32"></a>
<h2><span class="function">crc32</span></h2>
<h4>syntax: (crc32 <em>str-data</em>)</h4>

<p>
	Calculates a running 32-bit CRC (Circular Redundancy Check) sum 
	from the buffer in <em>str-data</em>, 
	starting with a CRC of <tt>0xffffffff</tt> for the first byte. 
	<tt>crc32</tt> uses an algorithm published 
	by <a href="http://www.w3.org">www.w3.org</a>.
</p>

<!-- example -->

<pre>
(crc32 "abcdefghijklmnopqrstuvwxyz")  <span class='arw'>&rarr;</span> 1277644989
</pre>


<p>
	<tt>crc32</tt> is often used to verify data integrity 
	in unsafe data transmissions.
</p>

<br/><br/>

<a name="crit-chi2"></a>
<h2><span class="function">crit-chi2</span></h2>

<h4>syntax: (crit-chi2 <em>num-probability</em> <em>int-df</em>)</h4>

<p>Calculates the critical minimum <em>Chi&sup2;&nbsp;</em> for a given confidence probability 
<em>num-probability</em> under the null hypothesis and the degrees of freedom in
<em>int-df&nbsp;</em> for testing the significance of a statistical null hypothesis.</p>

<p>Note that versions prior to 10.2.0 took <em>(1.0 - p)</em> for the probability
instead of <em>p</em>.</p>

<!-- example -->

<pre>
(crit-chi2 0.01 4)  <span class='arw'>&rarr;</span> 13.27670443
</pre>


<p>
	See also the inverse function <a href="#prob-chi2">prob-chi2</a>.
</p> 

<br/><br/>

<a name="crit-f"></a>
<h2><span class="function">crit-f</span></h2>

<h4>syntax: (crit-f <em>num-probability</em> <em>int-df1</em> <em>int-df2</em>)</h4>

<p>Calculates the critical minimum <em>F&nbsp;</em> for a given confidence probability
<em>num-probability</em> under the null hypothesis and the degrees of freedom 
given in <em>int-df1</em> and <em>int-df2</em> for testing the significance of a 
statistical null hypothesis using the <em>F-test</em>.</p>

<!-- example -->

<pre>
(crit-f 0.05 10 12)  <span class='arw'>&rarr;</span> 2.753386727
</pre>

<p>
See also the inverse function <a href="#prob-f">prob-f</a>.
</p> 

<br/><br/>

<a name="crit-t"></a>
<h2><span class="function">crit-t</span></h2>

<h4>syntax: (crit-t <em>num-probability</em> <em>int-df</em>)</h4>

<p>Calculates the critical minimum <em>Student's t</em> for a given confidence probability 
<em>num-probability</em> under the null hypothesis and the degrees of freedom in
<em>int-df&nbsp;</em> for testing the significance of a statistical null hypothesis.
</p>

<!-- example -->

<pre>
(crit-t 0.05 14)  <span class='arw'>&rarr;</span> 1.761310142
</pre>


<p>
See also the inverse function <a href="#prob-t">prob-t</a>.
</p> 

<br/><br/>


<a name="crit-z"></a>
<h2><span class="function">crit-z</span></h2>
<h4>syntax: (crit-z <em>num-probability</em>)</h4>

<p>Calculates the critical normal distributed Z value 
of a given cumulated probability <em>num-probability</em> 
for testing of statistical significance and confidence intervals.</p>

<!-- example -->

<pre>
(crit-z 0.999)  <span class='arw'>&rarr;</span> 3.090232372
</pre>


<p>
	See also the inverse function <a href="#prob-z">prob-z</a>.
</p> 

<br/><br/>

<a name="current-line"></a>
<h2><span class="function">current-line</span></h2>
<h4>syntax: (current-line)</h4>

<p>
	Retrieves the contents of the last 
	<a href="#read-line">read-line</a> operation. 
	<tt>current-line</tt>'s contents are also implicitly used 
	when <a href="#write-line">write-line</a> 
	is called without a string parameter.
</p>

<p>
	The following source shows the typical code pattern 
	for creating a Unix command-line filter:
</p>

<!-- example -->

<pre>
#!/usr/local/bin/newlisp
 
(set 'inFile (open (main-args 2) "read"))
(while (read-line inFile) 
  (if (starts-with (current-line) ";;")
    (write-line)))
(exit)
</pre>


<p>
	The program is invoked:
</p>


<pre>
./filter myfile.lsp
</pre>


<p>
	This displays all comment lines starting with <tt>;;</tt> 
	from a file given as a command-line argument 
	when invoking the script <tt>filter</tt>.
</p>

<br/><br/>

<a name="curry"></a>

<h2><span class="function">curry</span></h2>
<h4>syntax: (curry <em>func</em> <em>exp</em>)</h4>

<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 macro in that it does not evaluate its arguments. 
Instead, they are evaluated during the application of <em>func</em>.</p>


<!-- example -->

<pre>
(set 'f (curry + 10))  <span class='arw'>&rarr;</span> (lambda ($x) (+ 10 $x))

(f 7)  <span class='arw'>&rarr;</span> 17

(filter (curry match '(a *)) '((a 10) (b 5) (a 3) (c 8) (a 9)))
<span class='arw'>&rarr;</span>  ((a 10) (a 3) (a 9))

(clean (curry match '(a *)) '((a 10) (b 5) (a 3) (c 8) (a 9)))
<span class='arw'>&rarr;</span>  ((b 5) (c 8))

(map (curry list 'x) (sequence 1 5))
<span class='arw'>&rarr;</span>  ((x 1) (x 2) (x 3) (x 4) (x 5))
</pre>


<p><tt>curry</tt> can be used on all functions taking two arguments.</p>

<br/><br/>

<a name="date"></a>

<h2><span class="function">date</span>&nbsp;<font size="-1"><a href="#utf8_capable">utf8</a></font></h2>
<h4>syntax: (date)<br/>
syntax: (date <em>int-secs</em> [<em>int-offset</em>])<br/>
syntax: (date <em>int-secs</em> <em>int-offset</em> <em>str-format</em>)</h4>

<p>
The first syntax returns the local time zone's 
current date and time as a string representation.
If <em>int-secs</em> is out of range, <tt>nil</tt> is returned.    
</p>

<p>
In the second syntax, <tt>date</tt> translates the number of seconds 
in <em>int-secs</em> into its date/time string representation 
for the local time zone. 
The number in <em>int-secs</em> is usually retrieved from the system 
using <a href="#date-value">date-value</a>. 
Optionally, a time-zone offset (in minutes) can be specified 
in <em>int-offset</em>, which is added 
or subtracted before conversion of <em>int-sec</em> to a string.
If <em>int-secs</em> is out of range or an invalid <em>str-format</em>
is specified, an empty string <tt>""</tt> is returned.
</p>


<!-- example -->

<pre>
(date)                   <span class='arw'>&rarr;</span> "Fri Oct 29 09:56:58 2004"

(date (date-value))      <span class='arw'>&rarr;</span> "Sat May 20 11:37:15 2006" 
(date (date-value) 300)  <span class='arw'>&rarr;</span> "Sat May 20 16:37:19 2006"  ; 5 hours offset
(date 0)                 <span class='arw'>&rarr;</span> "Wed Dec 31 16:00:00 1969"
(date 0 (now 0 -2))      <span class='arw'>&rarr;</span> "Thu Jan  1 00:00:00 1970"  ; Unix epoch
</pre>

<p>The way the date and time are presented in a string 
depends on the underlying operating system.</p>

<p>The second example would show 1-1-1970 0:0 when in the Greenwich time zone, 
but it displays a time lag of 8 hours when in Pacific Standard Time (PST).
<tt>date</tt> assumes the <em>int-secs</em> given are in Coordinated Universal 
Time (UTC; formerly Greenwich Mean Time (GMT)) and converts it according to the 
local time-zone.</p>

<p>The third syntax makes the date string fully customizable by using a format 
specified in <em>str-format</em>.  This allows the day and month names to be 
translated into results appropriate for the current locale:</p>

<!-- example -->

<pre>
(set-locale "german") <span class='arw'>&rarr;</span> "de_DE"      

; on Linux - no leading 0 on day with %-d
(date (date-value) 0 "%A %-d. %B %Y")  <span class='arw'>&rarr;</span> "Montag  7. M&auml;rz 2005" 

(set-locale "C")  ; default POSIX

(date (date-value) 0 "%A %B %d %Y")    <span class='arw'>&rarr;</span> "Monday March 07 2005"

; suppressing leading 0 on MS Windows using #
(date (date-value) 0 "%a %#d %b %Y")   <span class='arw'>&rarr;</span> "Mon 7 Mar 2005" 

(set-locale "german")

(date (date-value) 0 "%x") <span class='arw'>&rarr;</span> "07.03.2005"   ; day month year

(set-locale "C")

(date (date-value) 0 "%x") <span class='arw'>&rarr;</span> "03/07/05"     ; month day year
</pre>


<p>The following table summarizes all format specifiers available 
on both MS Windows and Linux/Unix platforms.  More format options are 
available on Linux/Unix. For details, consult the manual page for 
the C function <tt>strftime()</tt> of the individual platform's C library.
</p>

<table width="98%"  summary="date formatting">
<tr align="left"><th>format</th><th>description</th></tr>
<tr><td>%a</td><td>abbreviated weekday name according to the current locale</td></tr>

<tr><td>%A</td><td>full weekday name according to the current locale</td></tr>
<tr><td>%b</td><td>abbreviated month name according to the current locale</td></tr>
<tr><td>%B</td><td>full month name according to the current locale</td></tr>
<tr><td>%c</td><td>preferred date and time representation for the current locale</td></tr>
<tr><td>%d</td><td>day of the month as a decimal number (range 01&ndash;31)</td></tr>
<tr><td>%H</td><td>hour as a decimal number using a 24-hour clock (range 00&ndash;23)</td></tr>

<tr><td>%I</td><td>hour as a decimal number using a 12-hour clock (range 01&ndash;12)</td></tr>
<tr><td>%j</td><td>day of the year as a decimal number (range 001&ndash;366)</td></tr>
<tr><td>%m</td><td>month as a decimal number (range 01&ndash;12)</td></tr>
<tr><td>%M</td><td>minute as a decimal number</td></tr>
<tr><td>%p</td><td>either 'am' or 'pm' according to the given time value or
the corresponding strings for the current locale</td></tr>
<tr><td>%S</td><td>second as a decimal number 0&ndash;61 (60 and 61 to account
for occasional leap seconds)</td></tr>

<tr><td>%U</td><td>week number of the current year as a decimal number,
starting with the first Sunday as the first day of the first week</td></tr>
<tr><td>%w</td><td>day of the week as a decimal, Sunday being 0</td></tr>
<tr><td>%W</td><td>week number of the current year as a decimal number,
starting with the first Monday as the first day of the first week</td></tr>
<tr><td>%x</td><td>preferred date representation for the current locale
without the time</td></tr>
<tr><td>%X</td><td>preferred time representation for the current locale
without the date</td></tr>
<tr><td>%y</td><td>year as a decimal number without a century (range 00&ndash;99)</td></tr>

<tr><td>%Y</td><td>year as a decimal number including the century</td></tr>
<tr><td>%z</td><td>time zone or name or abbreviation (same as %Z on MS Windows,
different on Unix)</td></tr>
<tr><td>%Z</td><td>time zone or name or abbreviation (same as %z on MS Windows,
different on Unix)</td></tr>
<tr><td>%%</td><td>a literal '%' character</td></tr>
</table><br/>

<p>
Leading zeroes in the display of decimal day numbers can be suppressed 
using <tt>"%-d"</tt> on Linux and FreeBSD and using <tt>"%e"</tt> 
on OpenBSD, SunOS/Solaris and macOS.  On MS Windows use <tt>"%#d"</tt>.
</p>

<p>See also <a href="#date-value">date-value</a>, <a href="#date-list">date-list</a>,
<a href="#date-parse">date-parse</a>, 
<a href="#time-of-day">time-of-day</a>, 
<a href="#time">time</a>, and <a href="#now">now</a>.
</p>

<br/><br/>

<a name="date-list"></a>
<h2><span class="function">date-list</span></h2>
<h4>syntax: (date-list <em>int-seconds</em> [<em>int-index</em>])<br/>
syntax: (date-list)</h4>

<p>Returns a list of year, month, date, hours, minutes, seconds, day of year 
and day of week from a time value given in seconds after January 1st, 1970 00:00:00.
The date and time values aren given as UTC, which may differ from the local timezone.
</p>
<p>When no parameters are given <tt>date-list</tt> generates the list from the
number of seconds for the current time, return of <tt>(date-value)</tt>.</p>

<p>The week-day value ranges from 1 to 7 for Monday thru Sunday.</p>

<pre>
(date-list 1282479244)      <span class='arw'>&rarr;</span> (2010 8 22 12 14 4 234 1)
(date-list 1282479244 0)    <span class='arw'>&rarr;</span> 2010 ; year
(date-list 1282479244 -2)   <span class='arw'>&rarr;</span> 234  ; day of year

(date-value (date-list 1282479244)) <span class='arw'>&rarr;</span> 1282479244

(date-list 0)   <span class='arw'>&rarr;</span> (1970 1 1 0 0 0 1 4) ; Thursday 1st, Jan 1970
</pre>

<p>A second optional <em>int-index</em> parameter can be used to return
a specific member of the list.</p>

<p><tt>date-list</tt> is the inverse operation of <a href="#date-value">date-value</a>.</p>

<br/><br/>

<a name="date-parse"></a>
<h2><span class="function">date-parse</span></h2>
<h4>syntax: (date-parse <em>str-date</em> <em>str-format</em>)</h4>

<p>Parses a date from a text string in <em>str-date</em>
using a format as defined in <em>str-format</em>, which uses
the same formatting rules found in <a href="#date">date</a>.
The function <tt>date-parse</tt> returns the number of UTC seconds passed   
since January 1st, 1970 UTC starting with 0 and up to 2147472000 for a date 
of January 19th, 2038.</p> 

<p>This function is not available on MS Windows platforms. The function was
named <tt>parse-date</tt> in previous versions. The old form is deprecated.</p>

<!-- example -->

<pre>
(date-parse "2007.1.3" "%Y.%m.%d")    <span class='arw'>&rarr;</span> 1167782400
(date-parse "January 10, 07" "%B %d, %y")    <span class='arw'>&rarr;</span> 1168387200

; output of date-parse as input value to date-list produces the same date 

(date-list (date-parse "2010.10.18 7:00" "%Y.%m.%d %H:%M"))
<span class='arw'>&rarr;</span> (2010 10 18 7 0 0 290 1)
</pre>


<p>See the <a href="#date">date</a> function for all possible format descriptors.</p>

<br/><br/>
<a name="date-value"></a>
<h2><span class="function">date-value</span></h2>

<h4>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>])<br/> 
syntax: (date-value <em>list-date-time</em>)<br/> 
syntax: (date-value)</h4>

<p>In the first syntax, <tt>date-value</tt> returns the time 
in seconds since 1970-1-1 00:00:00 for a given date and time.  
The parameters for the hour, minutes and seconds are optional. 
The time is assumed to be Coordinated Universal Time (UTC), 
not adjusted for the current time zone.</p>
<p>In the second syntax the same data can be given in a list.
As with the first syntax, numbers for the hour, minutes 
and seconds are optional.</p>

<p>In the third syntax, <tt>date-value</tt> returns the time value 
in seconds for the current time.</p>

<!-- example -->

<pre>
(date-value 2002 2 28)       <span class='arw'>&rarr;</span> 1014854400
(date-value '(2002 2 28))    <span class='arw'>&rarr;</span> 1014854400
(date-value 1970 1 1 0 0 0)  <span class='arw'>&rarr;</span> 0
                                 
(date (date-value (now)))    <span class='arw'>&rarr;</span> "Wed May 24 10:02:47 2006" 
(date (date-value))          <span class='arw'>&rarr;</span> "Wed May 24 10:02:47 2006"
(date)                       <span class='arw'>&rarr;</span> "Wed May 24 10:02:47 2006"
</pre>


<p>The function <a href="#date-list">date-list</a> can be used to transform 
a <tt>date-value</tt> back into a list:</p>


<pre>
(date-list 1014854400)  <span class='arw'>&rarr;</span> (2002 2 28 0 0 0)
(date-value (date-list 1014854400))  <span class='arw'>&rarr;</span> 1014854400
</pre>


<p>See also <a href="#date">date</a>, 
<a href="#date-list">date-list</a>, <a href="#date-parse">date-parse</a>, 
<a href="#time-of-day">time-of-day</a>, <a href="#time">time</a>, and 
<a href="#now">now</a>.</p>

<br/><br/>

<a name="debug"></a>
<h2><span class="function">debug</span></h2>
<h4>syntax: (debug <em>func</em>)</h4>

<p>
Calls <a href="#trace">trace</a> and begins evaluating the user-defined 
function in <em>func</em>. <tt>debug</tt> is a shortcut for executing 
<tt>(trace true)</tt>, then entering the function to be debugged.</p>

<!-- example -->

<pre>
;; instead of doing
(trace true)
(my-func a b c)
(trace nil)

;; use debug as a shortcut
(debug (my-func a b c))
</pre>

<p>When in <tt>debug</tt> or <a href="#trace">trace</a> mode, error messages
will be printed. The function causing the exception will return either
<tt>0</tt> or <tt>nil</tt> and processing will continue. This way, variables 
and the current state of the program can still be inspected while debugging.</p>

<p>See also the <a href="#trace">trace</a> function.</p>

<br/><br/>

<a name="dec"></a>
<h2><span class="function">dec</span>&nbsp;<a href="#destructive">!</a></h2>
<h4>syntax: (dec <em>place</em> [<em>num</em>])</h4>

<p>
The number in <em>place</em> is decremented by <tt>1.0</tt> or the optional number 
<em>num</em> and returned.  <tt>dec</tt> performs float arithmetic and converts
integer numbers passed into floating point type.</p>

<p><em>place</em> is either a symbol or a place in a list structure holding a
number, or a number returned by an expression.</p>

<!-- example -->

<pre>
(set x 10)    <span class='arw'>&rarr;</span> 10
(dec x)       <span class='arw'>&rarr;</span> 9
x             <span class='arw'>&rarr;</span> 9
(dec x 0.25)  <span class='arw'>&rarr;</span> 8.75
x             <span class='arw'>&rarr;</span> 8.75
</pre>


<p>If the symbol for <em>place</em> contains <tt>nil</tt>, it is treated
as if containing <tt>0.0</tt>:</p>


<pre>
z             <span class='arw'>&rarr;</span> nil
(dec z)       <span class='arw'>&rarr;</span> -1

(set z nil)
(dec z 0.01)  <span class='arw'>&rarr;</span> -0.01
</pre>


<p>Places in a list structure or a number returned by another expression
can be updated too:</p>


<pre>
(set 'l '(1 2 3 4))

(dec (l 3) 0.1) <span class='arw'>&rarr;</span> 3.9

(dec (first l)) <span class='arw'>&rarr;</span> 0

l <span class='arw'>&rarr;</span> (0 2 3 3.9)

(dec (+ 3 4)) <span class='arw'>&rarr;</span> 6
</pre>

<p>Use the <a href="#deci">--</a> function to decrement in integer mode.
Use the <a href="#inc">inc</a> function to increment numbers floating point mode.</p>

<br/><br/>

<a name="def-new"></a>
<h2><span class="function">def-new</span></h2>
<h4>syntax: (def-new <em>sym-source</em> [<em>sym-target</em>])</h4>

<p>
	This function works similarly to <a href="#new">new</a>, 
	but it only creates a copy of one symbol 
	and its contents from the symbol in <em>sym-source</em>. 
	When <em>sym-target</em> is not given, 
	a symbol with the same name is created 
	in the current context. 
	All symbols referenced inside <em>sym-source</em> 
	will be translated into symbol references into the current context,
    which must not be MAIN.</p>
<p>
If an argument is present in <em>sym-target</em>, the copy will be made
into a symbol and context as referenced by the symbol in <em>sym-target</em>. 
In addition to allowing renaming of the function while copying, this also 
enables the copy to be placed in a different context.  All symbol references 
in <em>sym-source</em> with the same context as <em>sym-source</em> will 
be translated into symbol references of the target context.
</p>

<p>
	<tt>def-new</tt> returns the symbol created:
</p>

<!-- example -->

<pre>
&gt; (set 'foo:var '(foo:x foo:y))
<b>(foo:x foo:y)</b>

&gt; (def-new 'foo:var 'ct:myvar)
<b>ct:myvar</b>

&gt; ct:myvar
<b>(ct:x ct:y)</b>

&gt; (context 'K)

K&gt; (def-new 'foo:var)
<b>var</b>

K&gt; var
<b>(x y)</b>
</pre>

<p>The following example shows how a statically scoped function can
be created by moving it its own namespace:</p>

<pre>
&gt; (set 'temp (lambda (x) (+ x x)))
<b>(lambda (x) (+ x x))</b>
&gt; (def-new 'temp 'double:double)
<b>double:double</b>
&gt; (double 10)
<b>20</b>
&gt; double:double
<b>(lambda (double:x) (+ double:x double:x))</b>
</pre>

<p>The following definition of <tt>def-static</tt> can be used to
create functions living in their own lexically protected name-space:</p>
<pre>
(define (def-static s body) 
      (def-new 'body (sym s s)))

(def-static 'acc (lambda (x)
          (inc sum x)))

&gt; (acc 1)
<b>1</b>
&gt; (acc 1)
<b>2</b>
&gt; (acc 8)
<b>10</b>
&gt;
</pre>

<p>The function <tt>def-new</tt> can also be used to configure contexts 
or context objects in a more granular fashion than is possible 
with <a href="#new">new</a>, which copies a whole context.</p>

<br/><br/>

<a name="default"></a>
<h2><span class="function">default</span></h2>
<h4>syntax: (default <em>context</em>)</h4>

<p>Return the contents of the default functor in <em>context</em>.</p>

<!-- example -->

<pre>
(define Foo:Foo 123)

(default Foo) <span class='arw'>&rarr;</span> 123

(setf (default Foo) 456)
(set 'ctx Foo)

(default ctx) <span class='arw'>&rarr;</span> 456
Foo:Foo       <span class='arw'>&rarr;</span> 456
</pre>


<p>In many situations newLISP defaults automatically to the default functor
when seeing a context name. In circumstances where this is not the case,
the <tt>default</tt> function can be used.</p>

<br/><br/>

<a name="define"></a>
<h2><span class="function">define</span>&nbsp;<a href="#destructive">!</a></h2>
<h4>syntax: (define (<em>sym-name</em> [<em>sym-param-1</em> ... ]) [<em>body-1</em> ... ])<br/>
syntax: (define (<em>sym-name</em> [(<em>sym-param-1</em> <em>exp-default</em>) ... ]) [<em>body-1</em> ... ])<br/>
syntax: (define <em>sym-name</em> <em>exp</em>)</h4>

<p>
	Defines the new function <em>sym-name</em>, 
	with optional parameters <em>sym-param-1</em>&mdash;. 
	<tt>define</tt> is equivalent to assigning 
	a lambda expression to <em>sym-name</em>. 
	When calling a defined function, 
	all arguments are evaluated and assigned 
	to the variables in <em>sym-param-1</em>&mdash;, 
	then the <em>body-1&mdash;	</em> expressions are evaluated. 
	When a function is defined, the lambda expression 
	bound to <em>sym-name</em> is returned.
</p>

<p>
	All parameters defined are optional. 
	When a user-defined function is called without arguments, 
	those parameters assume the value <tt>nil</tt>. 
<!-- 8.9.4 -->If those parameters have a default value 
	specified in <em>exp-default</em>,
	they assume that value.
</p>

<p>
	The return value of <tt>define</tt> 
	is the assigned <em>lambda</em> expression. 
	When calling a user-defined function, 
	the return value is the last expression evaluated 
	in the function body.
</p>

<!-- example -->

<pre>
(define (area x y) (* x y))  <span class='arw'>&rarr;</span> (lambda (x y) (* x y))
(area 2 3)                   <span class='arw'>&rarr;</span> 6
</pre>


<p>
	As an alternative, <tt>area</tt> could be defined 
	as a function without using <tt>define</tt>.
</p>


<pre>
(set 'area (lambda (x y) (* x y))
</pre>


<p>
	<em>lambda</em> or <em>fn</em> expressions may be used by themselves 
	as <em>anonymous</em> functions without being defined as a symbol:
</p>


<pre>
((lambda ( x y) (* x y)) 2 3)  <span class='arw'>&rarr;</span> 6
((fn ( x y) (* x y)) 2 3)      <span class='arw'>&rarr;</span> 6
</pre>


<p>
	<tt>fn</tt> is just a shorter form of writing <tt>lambda</tt>.
</p>
	
<!-- 8.9.4 -->
<p>
	Parameters can have default values specified:
</p>


<pre>
(define (foo (a 1) (b 2))
  (list a b))
    
(foo)      <span class='arw'>&rarr;</span> (1 2)
(foo 3)    <span class='arw'>&rarr;</span> (3 2)
(foo 3 4)  <span class='arw'>&rarr;</span> (3 4)
</pre>


<p>
	Expressions in <em>exp-default</em> 
	are evaluated in the function's
	current environment.
</p>


<pre>
(define (foo (a 10) (b (div a 2))) 
  (list a b))

(foo)      <span class='arw'>&rarr;</span> (10 5)
(foo 30)   <span class='arw'>&rarr;</span> (30 15)
(foo 3 4)  <span class='arw'>&rarr;</span> (3 4)
</pre>


<p>
	The second version of <tt>define</tt> 
	works like the <a href="#set">set</a> function.
</p>

<!-- example -->

<pre>
(define x 123)  <span class='arw'>&rarr;</span>   123
;; is equivalent to
(set 'x 123)    <span class='arw'>&rarr;</span>   123

(define area (lambda ( x y) (* x y)))
;; is equivalent to
(set 'area (lambda ( x y) (* x y)))
;; is equivalent to
(define (area x y) (* x y))
</pre>


<p>
	Trying to redefine a protected symbol will cause an error message.
</p>

<br/><br/>

<a name="define-macro"></a>
<h2><span class="function">define-macro</span></h2>
<h4>syntax: (define-macro (<em>sym-name</em> [<em>sym-param-1</em> ... ]) <em>body</em>)<br/>
syntax: (define-macro (<em>sym-name</em> [(<em>sym-param-1</em> <em>exp-default</em>) ... ]) <em>body</em>)</h4>

<p>Functions defined using <tt>define-macro</tt> are called <i>fexpr</i>
in other LISPs as they don't do variable expansion. In newLISP they are still
called macros, because they are written with the same purpose of creating
special syntax forms with non-standard evaluation patterns of arguments. 
Functions created using <tt>define-macro</tt> can be combined with template 
expansion using <a href="#expand">expand</a> or <a href="#letex">letex</a>.</p>

<p>Since v.10.5.8, newLISP also has expansion macros using <a href="#macro">macro</a>.</p>

<p>Defines the new fexpr <em>sym-name</em>, with optional arguments <em>sym-param-1</em>. 
<tt>define-macro</tt> is equivalent to assigning a lambda-macro expression to a symbol. 
When a <tt>define-macro</tt> function is called, unevaluated arguments are assigned to 
the variables in <em>sym-param-1 ...</em>. Then the <em>body</em> expressions are evaluated.  
When evaluating the <tt>define-macro</tt> function, the lambda-macro expression is returned.
</p>

<!-- example -->

<pre>
(define-macro (my-setq p1 p2) (set p1 (eval p2))) 
<span class='arw'>&rarr;</span> (lambda-macro (p1 p2) (set p1 (eval p2)))

(my-setq x 123)  <span class='arw'>&rarr;</span> 123
x                <span class='arw'>&rarr;</span> 123
</pre>


<p>New functions can be created to behave like built-in functions
that delay the evaluation of certain arguments.  Because fexprs can 
access the arguments inside a parameter list, they can be used to 
create flow-control functions like those already built-in to newLISP.</p>

<p>All parameters defined are optional.  When a macro is called without 
arguments, those parameters assume the value <tt>nil</tt>. 
If those parameters have a default value specified in <em>exp-default</em>,
they assume that default value.</p>
	

<pre>
(define-macro (foo (a 1) (b 2))
  (list a b))
    
(foo)      <span class='arw'>&rarr;</span> (1 2)
(foo 3)    <span class='arw'>&rarr;</span> (3 2)
(foo 3 4)  <span class='arw'>&rarr;</span> (3 4)
</pre>


<p>Expressions in <em>exp-default</em> are evaluated in the function's 
current environment.</p>


<pre>
(define-macro (foo (a 10) (b (div a 2))) 
  (list a b))

(foo)      <span class='arw'>&rarr;</span> (10 5)
(foo 30)   <span class='arw'>&rarr;</span> (30 15)
(foo 3 4)  <span class='arw'>&rarr;</span> (3 4)
</pre>


<p>Note that in <em>fexprs</em>, the danger exists of passing a parameter 
with the same variable name as used in the <tt>define-macro</tt> definition. 
In this case, the <em>fexpr's</em> internal variable would end up 
receiving <tt>nil</tt> instead of the intended value:</p>


<pre>
;; not a good definition!

(define-macro (my-setq x y) (set x (eval y)))  

;; symbol name clash for x

(my-setq x 123)  <span class='arw'>&rarr;</span> 123
x                <span class='arw'>&rarr;</span> nil
</pre>


<p>There are several methods that can be used 
to avoid this problem, known as <em>variable capture</em>,
by writing <em>hygienic</em> <tt>define-macro</tt>s:</p>

<ul>
<li>
Put the definition into its own lexically closed namespace context. 
If the function has the same name as the context, it can be 
called by using the context name alone.  A function with this 
characteristic is called a <a href="#default_function">
<em>default function</em></a>. This is the preferred method in 
newLISP to write <tt>define-macro</tt>s.
</li>
<br/>
<li>Use <a href="#args">args</a> to access arguments passed by the 
function.</li>
</ul>

<!-- example -->

<pre>
;; a define-macro as a lexically isolated function
;; avoiding variable capture in passed parameters

(context 'my-setq)

(define-macro (my-setq:my-setq x y) (set x (eval y)))  

(context MAIN)

(my-setq x 123)  <span class='arw'>&rarr;</span> 123  ; no symbol clash
x                <span class='arw'>&rarr;</span> 123
</pre>


<p>
	The definition in the example is lexically isolated, 
	and no variable capture can occur. 
	Instead of the function being called using <tt>(my-setq:my-setq &hellip;)</tt>, 
	it can be called with just <tt>(my-setq &hellip;)</tt> 
	because it is a <a href="#default_function"><em>default function</em></a>.
</p>

<p>
	The second possibility is to refer to passed parameters 
	using <a href="#args">args</a>:
</p>

<!-- example -->

<pre>
;; avoid variable capture in macros using the args function

(define-macro (my-setq) (set (args 0) (eval (args 1))))
</pre>

<p>See also the <a href="#macro">macro</a> expansion function not
susceptible to variable capture.</p>

<br/><br/>

<a name="delete"></a>
<h2><span class="function">delete</span>&nbsp;
<a href="#shared-lib"><font size="+2">&#x26A0;</font></a></h2>
<h4>syntax: (delete <em>symbol</em> [<em>bool</em>])<br/>

syntax: (delete <em>sym-context</em> [<em>bool</em>])</h4>

<p>In the first syntax deletes a symbol <em>symbol</em> and references to 
the symbol in other expressions will be changed to <tt>nil</tt>.</p>

<p>In the second syntax all symbols of the namespace referred to by 
<em>sym-context</em> will be deleted and references to them in other
espressions will be changed to <tt>nil</tt>. The context symbol 
<em>sym-context</em> will be changed to a normal symbol 
containing <tt>nil</tt>.</p>

<p>When the expression in <em>bool</em> evaluates 
to <tt>true</tt>, symbols are only deleted when they are not referenced.
</p>

<p>
When the expression in <em>bool</em> evaluates 
to <tt>nil</tt>, symbols will be deleted without any reference checking.
Note that this mode should only be used, if no references to the symbol
exist outside it's namespace. If external references exist, this mode
can lead to system crashes, as the external reference is not set to
<tt>nil</tt> when using this mode. This mode can be used to delete
namespace hashes and to delete namespaces in object systems, where variables are
strictly treated as private.</p>

<p>
Protected symbols of built-in functions and special symbols 
like <tt>nil</tt> and <tt>true</tt> cannot be deleted.
</p>

<p>
<tt>delete</tt> returns <tt>true</tt> if the symbol was deleted 
successfully or <tt>nil</tt> if the symbol was not deleted.
</p>

<p>When deleting a context symbol, the first <tt>delete</tt> removes the context 
namespace contents and demotes the context symbol to a normal mono-variable symbol. 
A second <tt>delete</tt> will remove the symbol from the symbol table.</p>

<!-- example -->

<pre>
(set 'lst '(a b aVar c d))

(delete 'aVar)  ; aVar deleted, references marked nil

lst  <span class='arw'>&rarr;</span> (a b nil c d)

(set 'lst '(a b aVar c d))

(delete 'aVar true)  
<span class='arw'>&rarr;</span> nil ; protect aVar if referenced

lst  <span class='arw'>&rarr;</span> (a b aVar c d)

;; delete all symbols in a context
(set 'foo:x 123)
(set 'foo:y "hello")

(delete 'foo)  <span class='arw'>&rarr;</span> foo:x, foo:y deleted
</pre>


<p>In the last example only the symbols inside context <tt>foo</tt>
will be deleted but not the context symbol <tt>foo</tt> itself. It
will be converted to a normal unprotected symbol and contain <tt>nil</tt>.
</p>

<p>
Note that deleting a symbol that is part of an expression 
which is currently executing can crash the system 
or have other unforeseen effects.
</p>

<br/><br/>

<a name="delete-file"></a>
<h2><span class="function">delete-file</span></h2>
<h4>syntax: (delete-file <em>str-file-name</em>)</h4>

<p>Deletes a file given in <em>str-file-name</em>. 
Returns <tt>true</tt> if the file was deleted 
successfully.</p>

<p>On failure the function returns <tt>nil</tt>. For error information, 
use <a href="#sys-error">sys-error</a> when used on files. When used
on URLs <a href="#net-error">net-error</a> gives more error
information.</p>

<p>The file name can be given as a URL.</p>

<!-- example -->

<pre>
(delete-file "junk")

(delete-file "http://asite.com/example.html")

(delete-file "file://aFile.txt")
</pre>

<p>
The first example deletes the file <tt>junk</tt> in the current directory.
The second example shows how to use a URL to specify the file. 
In this form, additional parameters can be given. 
See <a href="#delete-url">delete-url</a> for details.
</p>

<br/><br/>

<a name="delete-url"></a>
<h2><span class="function">delete-url</span></h2>
<h4>syntax: (delete-url <em>str-url</em>)</h4>

<p>This function deletes the file on a remote HTTP server specified in <em>str-url</em>.
The HTTP <tt>DELETE</tt> protocol must be enabled on the target web server, 
or an error message string may be returned. The target file must also have  
access permissions set accordingly. Additional parameters such as timeout and custom headers 
are available exactly as in the <a href="#get-url">get-url</a> function.</p>

<p>If <em>str-url</em> starts with <tt>file://</tt> a file on the local file system
is deleted.</p>

<p>This feature is also available when the <a href="#delete-file">delete-file</a>
function is used and a URL is specified for the filename.</p>

<!-- example -->

<pre>
(delete-url "http://www.aserver.com/somefile.txt")
(delete-url "http://site.org:8080/page.html" 5000)

; delete on the local file system
(delete-url "file:///home/joe/somefile.txt")
</pre>


<p>The second example configures a timeout option of five seconds. 
Other options such as special HTTP protocol headers 
can be specified, as well. 
See the <a href="#get-url">get-url</a> function for details.</p>

<p><tt>delete-url</tt> requests are also understood by newLISP server nodes, but will
not be served when the server is started in <tt>-http-safe</tt> mode.</p>

<br/><br/>

<a name="destroy"></a>
<h2><span class="function">destroy</span></h2>
<h4>syntax: (destroy <em>int-pid</em>)<br/>
syntax: (destroy <em>int-pid</em> <em>int-signal</em>)</h4>

<p>Destroys a process with process id in <em>int-pid</em> and returns <tt>true</tt>
on success or <tt>nil</tt> on failure. The process id is normally obtained from a 
previous call to <a href="#fork">fork</a> on macOS and other Unix or 
<a href="#process">process</a> on all platforms. On Unix, <tt>destroy</tt> works like 
the system utility <em>kill</em> using the SIGKILL signal.</p>

<p>CAUTION! If <em>int-pid</em> is <tt>0</tt> the signal is sent to all processes whose 
group ID is equal to the process group ID of the sender. If <em>int-pid</em> is <tt>-1</tt> 
all processes with the current user id will be killed, if newLISP is started with 
super user privileges, all processes except system processes are destroyed.
</p>

<p>When specifying <em>int-signal</em>, <tt>destroy</tt> works like a Unix <tt>kill</tt> 
command sending the specified Unix signal to the process in <em>int-pid</em>. 
This second syntax is not available on MS Windows.</p>

<!-- example -->

<pre>
(set 'pid (process "/usr/local/bin/bc" bcin bcout)) 
(destroy pid)

(set 'pid (fork (dotimes (i 1000) (println i) (sleep 10))))
(sleep 100) (destroy pid)
</pre>

<br/><br/>

<a name="det"></a>
<h2><span class="function">det</span></h2>
<h4>syntax: (det <em>matrix</em> [<em>float-pivot</em>])</h4>

<p>Returns the determinant of a square matrix.  A matrix can either 
be a nested list or an <a href="#array">array</a>.</p>

<p>Optionally <tt>0.0</tt> or a very small value can be specified
in <em>float-pivot</em>. This value substitutes pivot elements in
the LU-decomposition algorithm, which result in zero when
the algorithm deals with a singular matrix.</p>

<!-- example -->

<pre>
(set 'A '((-1 1 1) (1 4 -5) (1 -2 0)))
(det A)  <span class='arw'>&rarr;</span> -1

; treatment of singular matrices
(det '((2 -1) (4 -2)))        <span class='arw'>&rarr;</span> nil
(det '((2 -1) (4 -2)) 0)      <span class='arw'>&rarr;</span> -0
(det '((2 -1) (4 -2)) 1e-20)  <span class='arw'>&rarr;</span> -4e-20
</pre>

<p>If the matrix is singular and <em>float-pivot</em> is not
specified, <tt>nil</tt> is returned.</p>

<p>See also the other matrix operations 
<a href="#invert">invert</a>, <a href="#mat">mat</a>, 
<a href="#multiply">multiply</a> and <a href="#transpose">transpose</a>.
</p>

<br/>

<a name="device"></a>
<h2><span class="function">device</span></h2>
<h4>syntax: (device [<em>int-io-handle</em>])</h4>

<p><em>int-io-handle</em> is an I/O device number, which is set to 0 (zero)
for the default STD I/O pair of handles, 0 for <i>stdin</i>, 1
for <i>stdout</i> and 2 for <i>stderr</i>. <em>int-io-handle</em> may also 
be a file handle previously obtained using <a href="#open">open</a>. In this 
case both, input and output are channeled through this handle.
When no argument is supplied, the current I/O device number is returned. 
</p>

<p>The I/O channel specified by <tt>device</tt> is used internally 
by the functions <a href="#print">print</a>, <a href="#println">println</a>,
<a href="#write">write</a>, <a href="#write-line">write-line</a> and
<a href="#read-char">read-char</a>, <a href="#read-line">read-line</a>. 
When the current I/O device is 0 or 1, <a href="#print">print</a> 
sends output to the console window and <a href="#read-line">read-line</a> 
accepts input from the keyboard. If the current I/O device has been set 
by opening a file, then <a href="#print">print</a> and <a href="#read-line">read-line</a> 
work on that file.</p>

<p>Note, that on Unix like operating systems, stdin channel 0 can also be used
for output and stdout channel 1 can also be used for reading input. This is
not the case on Windows, where 0 is strictly for input and stdout 1 strictly
for output.</p>
 
<!-- example -->

<pre>
(device (open "myfile" "write"))  <span class='arw'>&rarr;</span> 5
(print "This goes in myfile")     <span class='arw'>&rarr;</span> "This goes in myfile"
(close (device))                  <span class='arw'>&rarr;</span> true
</pre>


<p>Note that using <a href="#close">close</a> on <tt>device</tt> 
automatically resets <tt>device</tt> to 0 (zero).</p>

<br/><br/>

<a name="difference"></a>
<h2><span class="function">difference</span></h2>
<h4>syntax: (difference <em>list-A</em> <em>list-B</em>)<br/>
syntax: (difference <em>list-A</em> <em>list-B</em> <em>bool</em>)</h4>

<p>
	In the first syntax, <tt>difference</tt> returns 
	the <em>set</em> difference between <em>list-A</em> and <em>list-B</em>. 
	The resulting list only has elements occurring in <em>list-A</em>, 
	but not in <em>list-B</em>. 
	All elements in the resulting list are unique, 
	but <em>list-A</em> and <em>list-B</em> need not be unique. 
	Elements in the lists can be any type of Lisp expression.
</p>

<!-- example -->

<pre>
(difference '(2 5 6 0 3 5 0 2) '(1 2 3 3 2 1))  <span class='arw'>&rarr;</span> (5 6 0)
</pre>


<p>
	In the second syntax, <tt>difference</tt> works in <em>list</em> mode. 
	<em>bool</em> specifies <tt>true</tt> 
	or an expression not evaluating to <tt>nil</tt>. 
	In the resulting list, all elements of <em>list-B</em> 
	are eliminated in <em>list-A</em>, 
	but duplicates of other elements in <em>list-A</em> are left.
</p>
<!-- example -->

<pre>
(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)
</pre>



<p>
	See also the set functions <a href="#intersect">intersect</a>,
	<a href="#unique">unique</a> and <a href="#union">union</a>.
</p>

<br/><br/>

<a name="directory"></a>
<h2><span class="function">directory</span></h2>
<h4>syntax: (directory [<em>str-path</em>])<br/>
syntax: (directory <em>str-path</em> <em>str-pattern</em> [<em>regex-option</em>])</h4>

<p>
	A list of directory entry names is returned 
	for the directory path given in <em>str-path</em>. 
	On failure, <tt>nil</tt> is returned. 
	When <em>str-path</em> is omitted, 
	the list of entries in the current directory is returned.
</p>

<!-- example -->

<pre>
(directory "/bin")

(directory "c:/")
</pre>


<p>
	The first example returns the directory of <tt>/bin</tt>, 
	the second line returns a list of directory entries 
	in the root directory of drive C:. 
	Note that on MS Windows systems, 
	a forward slash (<tt>/</tt>) can be included in path names. 
	When used, a backslash (<tt>\</tt>) must be 
	preceded by a second backslash.
</p>

<p>
	In the second syntax, <tt>directory</tt> can take 
	a regular expression pattern in <em>str-pattern</em>. 
	Only filenames matching the pattern will be returned 
	in the list of directory entries. 
	In <em>regex-option</em>, special regular expression options 
	can be specified; see <a href="#regex">regex</a> for details.
</p>

<!-- example -->

<pre>
(directory "." "\\.c")  <span class='arw'>&rarr;</span> ("foo.c" "bar.c")
;; or using braces as string pattern delimiters
(directory "." {\.c})  <span class='arw'>&rarr;</span> ("foo.c" "bar.c")

; show only hidden files (starting with dot)
(directory "." "^[.]")   <span class='arw'>&rarr;</span> ("." ".." ".profile" ".rnd" ".ssh")</pre>


<p>
	The regular expression forces <tt>directory</tt> 
	to return only file names containing the string <tt>".c"</tt>.
</p>

<p>
	Other functions that use regular expressions 
	are <a href="#find">find</a>, <!-- 8.9.4 --><a href="#find-all">find-all</a>,
	<a href="#parse">parse</a>, 
	<a href="#regex">regex</a>, <a href="#replace">replace</a>, 
	and <a href="#search">search</a>.
</p>

<br/><br/>

<a name="directoryp"></a>
<h2><span class="function">directory?</span></h2>
<h4>syntax: (directory? <em>str-path</em>)</h4>

<p>
	Checks if <em>str-path</em> is a directory. 
	Returns <tt>true</tt> or <tt>nil</tt> depending on the outcome.
</p>


<pre>
(directory? "/etc")             <span class='arw'>&rarr;</span> true
(directory? "/usr/local/bin/emacs/")  <span class='arw'>&rarr;</span> nil
</pre>

<br/><br/>

<a name="display-html"></a>
<h2><span class="function">display-html
<a href="#JS"><font size="-1">JS</font></a></span></h2>
<h4>syntax: (display-html <em>str-html</em>)<br/>
syntax: (display-html <em>str-html</em> <em>bool-flag</em>)</h4>

<p>Using the first syntax, the function replaces the current page in 
the browser with the HTML page found in <em>str-html</em>.</p> 

<p>If <em>bool-flag</em> evaluates to <tt>true</tt>, the page gets
opened in a new browser tab and the current page is not affected.</p>

<p>This function is only available on newLISP compiled to JavaScript.</p>

<pre>
(set 'page [text]
&lt;html&gt;
&lt;head&gt;
&lt;title&gt;Hello App&lt;/title&gt;
&lt;/head&gt;
&lt;body&gt;
&lt;h2&gt;Hello World&lt;/h2&gt;
&lt;/body&gt;
&lt;/html&gt;
[/text])

; open the page in a new browser tab
(display-html page true) <span class='arw'>&rarr;</span> "92"
</pre>

<p>The function returns the length of the HTML document displayed as a string.
</p>

<p>See also the function <a href="#eval-string-js">eval-string-js</a> for
evaluation of JavaScript in the current page.</p>

<br/><br/>

<a name="div"></a>
<h2><span class="function">div</span></h2>
<h4>syntax: (div <em>num-1</em> <em>num-2</em> [<em>num-3</em> ... ])<br/>
syntax: (div <em>num-1</em>)</h4>

<p>
	Successively divides <em>num-1</em>
	by the number in <em>num-2&mdash;</em>. 
	<tt>div</tt> can perform mixed-type arithmetic, 
	but it always returns floating point numbers. 
	Any floating point calculation 
	with <tt>NaN</tt> also returns <tt>NaN</tt>.
</p>
	

<!-- example -->

<pre>
(div 10 3)                 <span class='arw'>&rarr;</span> 3.333333333
(div 120 (sub 9.0 6) 100)  <span class='arw'>&rarr;</span> 0.4

(div 10)                   <span class='arw'>&rarr;</span> 0.1
</pre>


<p>
	When <em>num-1</em> is the only argument,
	<tt>div</tt> calculates the inverse of <em>num-1</em>.
</p>

<br/><br/>

<a name="do-until"></a>

<h2><span class="function">do-until</span></h2>
<h4>syntax: (do-until <em>exp-condition</em> [<em>body</em>])</h4>

<p>
	The expressions in <em>body</em> are evaluated 
	before <em>exp-condition</em> is evaluated. 
	If the evaluation of <em>exp-condition</em> is not <tt>nil</tt>, 
	then the <tt>do-until</tt> expression is finished; 
	otherwise, the expressions in <em>body</em> get evaluated again. 
	Note that <tt>do-until</tt> evaluates the conditional expression 
	<em>after</em> evaluating the body expressions, 
	whereas <a href="#until">until</a> checks the condition 
	<em>before</em> evaluating the body. 
	The return value of the <tt>do-until</tt> expression 
	is the last evaluation of the <em>body</em> expression.
	If <em>body</em> is empty, the last result of <em>exp-condition</em>
    is returned.
</p>

<p><tt>do-until</tt> also updates the system iterator symbol <tt>$idx</tt>.</p>

<!-- example -->

<pre>
(set 'x 1)
(do-until (&gt; x 0) (inc x))
x  <span class='arw'>&rarr;</span> 2

(set 'x 1)
(until (&gt; x 0) (inc x))
x  <span class='arw'>&rarr;</span> 1
</pre>


<p>
	While <tt>do-until</tt> goes through the loop at least once, 
	<a href="#until">until</a> never enters the loop.
</p>

<p>
	See also the functions <a href="#while">while</a> 
	and <a href="#do-while">do-while</a>.
</p>

<br/><br/>

<a name="do-while"></a>
<h2><span class="function">do-while</span></h2>
<h4>syntax: (do-while <em>exp-condition body</em>)</h4>

<p>
	The expressions in <em>body</em> are evaluated 
	before <em>exp-condition</em> is evaluated. 
	If the evaluation of <em>exp-condition</em> is <tt>nil</tt>, 
	then the <tt>do-while</tt> expression is finished; 
	otherwise the expressions in <em>body</em> get evaluated again. 
	Note that <tt>do-while</tt> evaluates the conditional expression 
	<em>after</em> evaluating the body expressions, 
	whereas <a href="#while">while</a> checks the condition 
	<em>before</em> evaluating the body. 
	The return value of the <tt>do-while</tt> expression 
	is the last evaluation of the <em>body</em> expression.
</p>

<p><tt>do-while</tt> also updates the system iterator symbol <tt>$idx</tt>.</p>

<!-- example -->

<pre>
(set 'x 10)
(do-while (&lt; x 10) (inc x))
x  <span class='arw'>&rarr;</span> 11

(set 'x 10)
(while (&lt; x 10) (inc x)) 
x  <span class='arw'>&rarr;</span> 10
</pre>


<p>
	While <tt>do-while</tt> goes through the loop at least once, 
	<a href="#while">while</a> never enters the loop.
</p>

<p>
	See also the functions <a href="#until">until</a> 
	and <a  href="#do-until">do-until</a>.
</p>

<br/><br/>

<a name="doargs"></a>
<h2><span class="function">doargs</span></h2>
<h4>syntax: (doargs (<em>sym</em> [<em>exp-break</em>])<em> body</em>)</h4>

<p>Iterates through all members of the argument list 
inside a user-defined function or macro. This function or macro can be defined using <a href="#define">define</a>, 
<a href="#define-macro">define-macro</a>, <a href="#lambda">lambda</a>, or
<a href="#lambda-macro">lambda-macro</a>.
The variable in <em>sym</em> is set sequentially to all members in the argument list 
until the list is exhausted or an optional break expression 
(defined in <em>exp-break</em>) evaluates to <tt>true</tt> or a logical true value. 
The <tt>doargs</tt> expression always returns the result of the last evaluation.</p>

<p><tt>doargs</tt> also updates the system iterator symbol <tt>$idx</tt>.</p>

<!-- example -->

<pre>
(define (foo)
    (doargs (i) (println i)))

<b>&gt;</b> (foo 1 2 3 4)
<b>1
2
3
4</b>
</pre>


<p>The optional break expression causes <tt>doargs</tt> 
to interrupt processing of the arguments:</p>


<pre>
(define-macro (foo)
    (doargs (i (= i 'x)) 
        (println i)))

<b>&gt;</b> (foo a b x c d e)
<b>a
b
true</b>
</pre>


<p>Use the <a href="#args">args</a> function to access the entire argument list at once.</p>

<br/><br/>

<a name="dolist"></a>
<h2><span class="function">dolist</span></h2>
<h4>syntax: (dolist (<em>sym</em>  <em>list</em>|<em>array</em> [<em>exp-break</em>])<em> body</em>)</h4>

<p>
	The expressions in <em>body</em> are evaluated 
	for each element in <em>list</em> or <em>array</em>. 
	The variable in <em>sym</em> is set to each of the elements 
	before evaluation of the body expressions. 
	The variable used as loop index is local 
	and behaves according to the rules of dynamic scoping.
</p>

<p>
	Optionally, a condition for early loop exit 
	may be defined in <em>exp-break</em>. 
	If the break expression evaluates to any non-<tt>nil</tt> value, 
	the <tt>dolist</tt> loop returns with the value of <em>exp-break</em>. 
	The break condition is tested before evaluating <em>body.</em></p>

<!-- example -->

<pre>
(set 'x 123)
(dolist (x '(a b c d e f g))  ; prints: abcdefg
    (print x))  <span class='arw'>&rarr;</span> g          ; return value

(dolist (x '(a b c d e f g) (= x 'e))  ; prints: abcd
    (print x))

;; x is local in dolist
;; x has still its old value outside the loop

x  <span class='arw'>&rarr;</span> 123  ; x has still its old value
</pre>


<p>
	This example prints <tt>abcdefg</tt> in the console window. 
	After the execution of <tt>dolist</tt>,
	the value for <tt>x</tt> remains unchanged 
	because the <tt>x</tt> in <tt>dolist</tt> has local scope. 
	The return value of <tt>dolist</tt> is the result 
	of the last evaluated expression.
</p>

<p>
	The internal system variable <tt>$idx</tt> 
	keeps track of the current offset 
	into the list passed to <tt>dolist</tt>,
	and it can be accessed during its execution:
</p>


<pre>
(dolist (x '(a b d e f g))
  (println $idx ":" x))  <span class='arw'>&rarr;</span> g

<b>0:a
1:b
2:d
3:e
4:f
5:g</b>
</pre>


<p>
	The console output is shown in boldface. 
	<tt>$idx</tt> is protected and cannot be changed by the user.
</p>

<br/><br/>

<a name="dostring"></a>
<h2><span class="function">dostring</span>&nbsp;<font size="-1"><a href="#utf8_capable">utf8</a></font></h2>
<h4>syntax: (dostring (<em>sym</em>  <em>string</em> [<em>exp-break</em>]) <em>body</em>)</h4>

<p>
	The expressions in <em>body</em> are evaluated 
	for each character in <em>string</em>. 
	The variable in <em>sym</em> is set to each ASCII or UTF-8 integer value of the characters 
	before evaluation of the body expressions. 
	The variable used as loop index is local 
	and behaves according to the rules of dynamic scoping.
</p>

<p>
	Optionally, a condition for early loop exit 
	may be defined in <em>exp-break</em>. 
	If the break expression evaluates to any non-<tt>nil</tt> value, 
	the <tt>dolist</tt> loop returns with the value of <em>exp-break</em>. 
	The break condition is tested before evaluating <em>body.</em>
</p>

<!-- example -->

<pre>
; ASCII example
(set 'str "abcdefg")
(dostring (c str) (println c " - " (char c)))

<b>97 - a
98 - b
99 - c
100 - d
101 - e
102 - f
103 - g</b>

; UTF8 example
(set 'utf8str "我能吞下玻璃而不伤身体。")
(dostring (c utf8str) (println c " - " (char c)))

<b>25105 - 我
33021 - 能
21534 - 吞
 ...
20307 - 体
12290 - 。 </b>
</pre>


<p>
	This example prints the value of each character
  in the console window. In UTF-8 enabled versions of newLISP,
  individual characters may be longer than one byte and the
  number in the loop variable may exceed 255.
	The return value of <tt>dostring</tt> is the result 
	of the last evaluated expression.
</p>

<p>
	The internal system variable <tt>$idx</tt> 
	keeps track of the current offset 
	into the string passed to <tt>dostring</tt>,
	and it can be accessed during its execution.
</p>

<br/><br/>

<a name="dotimes"></a>
<h2><span class="function">dotimes</span></h2>
<h4>syntax: (dotimes (<em>sym-var</em> <em>int-count</em> [<em>exp-break</em>]) <em>body</em>)</h4>

<p>
	The expressions in <em>body</em> are evaluated <em>int</em> times. 
	The variable in <em>sym</em> is set from 0 (zero) to (<em>int</em> - 1) 
	each time before evaluating the body expression(s). 
	The variable used as the loop index is local to the <tt>dotimes</tt> 
	expression and behaves according the rules of dynamic scoping. 
	The loop index is of integer type. 
	<tt>dotimes</tt> returns the result of 
	the last expression evaluated in <em>body</em>.
	After evaluation of the <tt>dotimes</tt>
    statement <em>sym</em> assumes its previous
    value.
</p>

<p>
	Optionally, a condition for early loop exit 
	may be defined in <em>exp-break</em>. 
	If the break expression evaluates to any non-<tt>nil</tt> value, 
	the <tt>dotimes</tt> loop returns with the value of <em>exp-break</em>. 
	The break condition is tested before evaluating <em>body</em>.
</p>

<!-- example -->

<pre>
(dotimes (x 10)
  (print x))  <span class='arw'>&rarr;</span> 9  ; return value
</pre>


<p>
	This prints <tt>0123456789</tt> to the console window.
</p>

<br/><br/>

<a name="dotree"></a>
<h2><span class="function">dotree</span></h2>
<h4>syntax: (dotree (<em>sym</em> <em>sym-context</em> [<em>bool</em>]) <em>body</em>)</h4>

<p>The expressions in <em>body</em> are evaluated for all symbols in <em>sym-context</em>. 
The symbols are accessed in a sorted order.  Before each evaluation of the body expression(s),
the variable in <em>sym</em> is set to the next symbol from <em>sym-context</em>. 
The variable used as the loop index is local to the <tt>dotree</tt> expression 
and behaves according the rules of dynamic scoping.</p>

<p>When the optional <em>bool</em> expression evaluates to not <tt>nil</tt>, only symbols 
starting with an underscore character <tt>_</tt> are accessed. Symbol names starting with 
an <tt>_</tt> underscore are used for <a href="#hash">hash keys</a> and symbols created by 
<a href="#bayes-train">bayes-train</a>.</p>

<p><tt>dotree</tt> also updates the system iterator symbol <tt>$idx</tt>.</p>

<!-- example -->

<pre>
;; faster and less memory overhead
(dotree (s SomeCTX) (print s " "))

;; slower and higher memory usage
(dolist (s (symbols SomeCTX)) (print s " "))
</pre>


<p>
This example prints the names of all symbols inside SomeCTX to the console window.
</p>

<br/><br/>

<a name="dump"></a>
<h2><span class="function">dump</span></h2>
<h4>syntax: (dump [<em>exp</em>])</h4>

<p>
	Shows the binary contents of a newLISP cell. 
	Without an argument, this function outputs 
	a listing of all Lisp cells to the console. 
	When <em>exp</em> is given, 
	it is evaluated and the contents 
	of a Lisp cell are returned in a list.
</p>

<!-- example -->

<pre>
(dump 'a)   <span class='arw'>&rarr;</span> (9586996 5 9578692 9578692 9759280)

(dump 999)  <span class='arw'>&rarr;</span> (9586996 130 9578692 9578692 999)
</pre>


<p>
	The list contains the following memory addresses and information:
</p>

<table summary="dump data types">
<tr align="left"><th>offset</th><th>description</th></tr>
<tr><td>0</td><td>memory address of the newLISP cell</td></tr>
<tr><td>1</td><td>cell-&gt;type: major/minor type, see newlisp.h for details</td></tr>
<tr><td>2</td><td>cell-&gt;next: linked list ptr</td></tr>
<tr><td>3</td><td>cell-&gt;aux:<br/>
&nbsp;&nbsp;&nbsp;&nbsp;string length+1 or <br/>
&nbsp;&nbsp;&nbsp;&nbsp;low (little endian) or high (big endian) word of 64-bit integer or<br/>
&nbsp;&nbsp;&nbsp;&nbsp;low word of IEEE 754 double float</td></tr>
<tr><td>4</td><td>cell-&gt;contents:<br/>
&nbsp;&nbsp;&nbsp;&nbsp;string/symbol address or<br/> 
&nbsp;&nbsp;&nbsp;&nbsp;high (little endian) or low (big endian) word of 64-bit integer or<br/>
&nbsp;&nbsp;&nbsp;&nbsp;high word of IEEE 754 double float</td></tr>
</table><br/>

<p>
	This function is valuable for changing type bits in cells 
	or hacking other parts of newLISP internals. 
	See the function <a href="#cpymem">cpymem</a> 
	for a comprehensive example.
</p>

<br/><br/>

<a name="dup"></a>
<h2><span class="function">dup</span></h2>

<h4>syntax: (dup <em>exp</em> <em>int-n</em> [<em>bool</em>])<br/>
syntax: (dup <em>exp</em>)</h4>

<p>
	If the expression in <em>exp</em> evaluates to a string, 
	it will be replicated <em>int-n</em> times within a string and returned. 
	When specifying an expression evaluating 
	to anything other than <tt>nil</tt> in <em>bool</em>, 
	the string will not be concatenated 
	but replicated in a list like any other data type.
</p>

<p>
	If <em>exp</em> contains any data type other than string, 
	the returned list will contain <em>int-n</em> evaluations of <em>exp</em>.
</p>

<p>Without the repetition parameter, <tt>dup</tt> assumes 2.</p>

<!-- example -->

<pre>
(dup "A" 6)       <span class='arw'>&rarr;</span> "AAAAAA"
(dup "A" 6 true)  <span class='arw'>&rarr;</span> ("A" "A" "A" "A" "A" "A")
(dup "A" 0)       <span class='arw'>&rarr;</span> ""
(dup "AB" 5)      <span class='arw'>&rarr;</span> "ABABABABAB"
(dup 9 7)         <span class='arw'>&rarr;</span> (9 9 9 9 9 9 9)
(dup 9 0)         <span class='arw'>&rarr;</span> ()
(dup 'x 8)        <span class='arw'>&rarr;</span> (x x x x x x x x)
(dup '(1 2) 3)    <span class='arw'>&rarr;</span> ((1 2) (1 2) (1 2))
(dup "\000" 4)    <span class='arw'>&rarr;</span> "\000\000\000\000"

(dup "*")         <span class='arw'>&rarr;</span> "**"
</pre>


<p>
	The last example shows handling of binary information, 
	creating a string filled with four binary zeroes.
</p>

<p>
	See also the functions <a href="#sequence">sequence</a> 
	and <a href="#series">series</a>.
</p>

<br/><br/>

<a name="emptyp"></a>
<h2><span class="function">empty?</span></h2>
<h4>syntax: (empty? <em>exp</em>)<br/>
syntax: (empty? <em>str</em>)</h4>


<p>
	<em>exp</em> is tested for an empty list 
	(or <em>str</em> for an empty string). 
	Depending on whether the argument contains elements, 
	<tt>true</tt> or <tt>nil</tt> is returned.
</p>

<!-- example -->

<pre>
(set 'var '())
(empty? var)         <span class='arw'>&rarr;</span> true
(empty? '(1 2 3 4))  <span class='arw'>&rarr;</span> nil
(empty? "hello")     <span class='arw'>&rarr;</span> nil
(empty? "")          <span class='arw'>&rarr;</span> true
</pre>


<p>
	The first example checks a list, 
	while the second two examples check a string.
</p>

<br/><br/>

<a name="encrypt"></a>
<h2><span class="function">encrypt</span></h2>
<h4>syntax: (encrypt <em>str-source</em> <em>str-pad</em>)</h4>

<p>
Performs a <a href="http://en.wikipedia.org/wiki/One-time_pad">one-time pad</a> (OTP)
encryption of <em>str-source</em> using the encryption pad in <em>str-pad</em>. 
The longer <em>str-pad</em> is and the more random the bytes are, 
the safer the encryption.  If the pad is as long as the source text, 
is fully random, and is used only once, then one-time&ndash;pad encryption 
is virtually impossible to break, since the encryption seems to contain only 
random data.  To retrieve the original, the same function and pad 
are applied again to the encrypted text:
</p>

<!-- example -->

<pre>
(set 'secret 
  (encrypt "A secret message" "my secret key")) 
<span class='arw'>&rarr;</span> ",YS\022\006\017\023\017TM\014\022\n\012\030E"

(encrypt secret "my secret key")  <span class='arw'>&rarr;</span> "A secret message"
</pre>


<p>
	The second example encrypts a whole file:
</p>



<pre>
(write-file "myfile.enc" 
  (encrypt (read-file "myfile") "29kH67*"))
</pre>


<br/><br/>

<a name="ends-with"></a>
<h2><span class="function">ends-with</span></h2>
<h4>syntax: (ends-with <em>str-data</em> <em>str-key</em> [<em>num-option</em>])<br/>
syntax: (ends-with <em>list</em> <em>exp</em>)</h4>

<p>In the first syntax, <tt>ends-with</tt> tests the string in <em>str-data</em> to see if it
ends with the string specified in <em>str-key</em>.  It returns <tt>true</tt> or <tt>nil</tt> 
depending on the outcome. </p>
	
<p>If a regular expression <em>option</em> number is 
specified, <em>str-key</em> contains a regular expression pattern. See
<a href="#regex">regex</a> for valid numbers for <em>option</em>.
</p>

<!-- example -->

<pre>
(ends-with "newLISP" "LISP")         <span class='arw'>&rarr;</span> true
(ends-with "newLISP" "lisp")         <span class='arw'>&rarr;</span> nil
;; use regular expressions
(ends-with "newLISP" "lisp|york" 1)  <span class='arw'>&rarr;</span> true
</pre>


<p>
	In the second syntax, 
	<tt>ends-with</tt> checks if a list 
	ends with the list element in <em>exp</em>. 
	<tt>true</tt> or <tt>nil</tt> is returned depending on outcome.
</p>

<!-- example -->

<pre>
(ends-with '(1 2 3 4 5) 5)             <span class='arw'>&rarr;</span> true
(ends-with '(a b c d e) 'b)            <span class='arw'>&rarr;</span> nil
(ends-with '(a b c (+ 3 4)) '(+ 3 4))  <span class='arw'>&rarr;</span> true
</pre>


<p>
	The last example shows that <em>exp</em> could be a list by itself.
</p>

<p>
	See also the <a href="#starts-with">starts-with</a> function.
</p>

<br/><br/>

<a name="env"></a>

<h2><span class="function">env</span></h2>
<h4>syntax: (env)<br/>
syntax: (env <em>var-str</em>)<br/>
syntax: (env <em>var-str</em> <em>value-str</em>)</h4>

<p>In the first syntax (without arguments), the operating system's environment is 
retrieved as an association list in which each entry is a key-value pair of
environment variable and value.</p>

<!-- example -->

<pre>
(env)  
<span class='arw'>&rarr;</span> (("PATH" "/bin:/usr/bin:/sbin") ("TERM" "xterm-color") ... ))
</pre>


<p>In the second syntax, the name of an environment variable 
is given in <em>var-str</em>. <tt>env</tt> returns the value 
of the variable or <tt>nil</tt> if the variable does not exist 
in the environment.</p>

<!-- example -->

<pre>
(env "PATH")  <span class='arw'>&rarr;</span> "/bin:/usr/bin:/usr/local/bin"
</pre>


<p>The third syntax (variable name in <em>var-str</em> 
and value pair in <em>value-str</em>) sets or creates 
an environment variable. If <em>value-str</em> is the 
empty string <tt>""</tt>, then the variable is completely
removed from the environment except when running on Solaris,
where the variable stays with an empty string.</p>

<!-- example -->

<pre>
(env "NEWLISPBIN" "/usr/local/bin/")  <span class='arw'>&rarr;</span> true
(env "NEWLISPBIN")              <span class='arw'>&rarr;</span> "/usr/bin/"
(env "NEWLISPBIN" "")           <span class='arw'>&rarr;</span> true
(env "NEWLISPBIN")              <span class='arw'>&rarr;</span> nil
</pre>

<br/><br/>

<a name="erf"></a>
<h2><span class="function">erf</span></h2>
<h4>syntax: (erf <em>num</em>)</h4>

<p>
	<tt>erf</tt> calculates the error function 
	of a number in <em>num</em>. 
	The error function is defined as:
</p>

<p><b><em>erf (x) = 2/sqrt(pi) * integral from 0 to x of exp(-t^2) dt</em></b></p>

<!-- example -->

<pre>
(map erf (sequence 0.0 6.0 0.5))
<span class='arw'>&rarr;</span> 
(0 0.5204998778 0.8427007929 0.9661051465 0.995322265 0.999593048 
 0.9999779095 0.9999992569 0.9999999846 0.9999999998 1 1 1) 
</pre>

<br/><br/>

<a name="error-event"></a>
<h2><span class="function">error-event</span></h2>
<h4>syntax: (error-event <em>sym-event-handler | func-event-handler</em>)<br/>
syntax: (error-event nil)</h4>

<p><em>sym-event-handler</em> contains a user-defined function for handling errors. 
Whenever an error occurs, the system performs a <a href="#reset">reset</a> 
and executes the user-defined error handler.  The error handler can use the 
built-in function <a href="#last-error">last-error</a> to retrieve the number 
and text of the error. The event handler is specified as either a quoted
symbol or a lambda function.</p>

<p>To cancel <tt>error-event</tt>, use the second syntax.</p>

<!-- example -->

<pre>
(define (my-handler)    
  (print "error # " (first (last-error)) " has occurred\n") )

(error-event 'my-handler)  <span class='arw'>&rarr;</span> my-handler

;; specify a function directly

(error-event my-handler)  <span class='arw'>&rarr;</span> $error-event

(error-event 
  (fn () (print "error # " (first (last-error)) " has occurred\n")))

(error-event exit)  <span class='arw'>&rarr;</span> $error-event
</pre>


<p>For a different way of handling errors, see the <a href="#catch">catch</a> function. 
Use <a href="#throw-error">throw-error</a> to throw user-defined errors.</p>

<br/><br/>

<a name="eval"></a>
<h2><span class="function">eval</span></h2>
<h4>syntax: (eval <em>exp</em>)</h4>

<p><em>eval</em> evaluates the result of evaluating <em>exp</em> in the current 
variable environment.</p>

<!-- example -->

<pre>
(set 'expr '(+ 3 4))  <span class='arw'>&rarr;</span> (+ 3 4)
(eval expr)           <span class='arw'>&rarr;</span> 7
(eval (list + 3 4))   <span class='arw'>&rarr;</span> 7
(eval ''x)            <span class='arw'>&rarr;</span> x
(set 'y 123)          
(set 'x 'y)           
x            <span class='arw'>&rarr;</span> y
(eval x)     <span class='arw'>&rarr;</span> 123
</pre>


<p>As usual, evaluation of variables happens in the current variable environment:</p>


<pre>
; eval in global (top level) environment
(set 'x 3 'y 4)
(eval '(+ x y))          <span class='arw'>&rarr;</span> 7

; eval in local environment
(let ( (x 33) (y 44) ) 
    (eval '(+ x y)))     <span class='arw'>&rarr;</span> 77

; old environment after leaving local let environment
(eval '(+ x y))          <span class='arw'>&rarr;</span> 7
</pre>


<p>
	newLISP passes all arguments by value. 
	Using a quoted symbol, 
	expressions can be passed 
	by reference through the symbol. 
	<tt>eval</tt> can be used 
	to access the original contents of the symbol:
</p>


<pre>
(define (change-list aList) (push 999 (eval aList)))

(set 'data '(1 2 3 4 5))

(change-list 'data)  <span class='arw'>&rarr;</span> (999 1 2 3 4 5)
</pre>


<p>
In the example, the parameter <tt>'data </tt> is quoted, 
so <tt>push</tt> can work on the original list.
</p>

<p>
There is a safer method to pass arguments by reference in newLISP 
by enclosing the data inside context objects. 
See the chapter <a href="#pass_big">Passing data by reference</a>.
Passing references into user defined
function using namespace ids avoids <em>variable capture</em> of
the passed symbol, in case the symbol passed is the same used as a
parameter in the function.</p>

<br/><br/>

<a name="eval-string"></a>
<h2><span class="function">eval-string</span></h2>
<h4>syntax: (eval-string <em>str-source</em> [<em>sym-context</em> [<em>exp-error</em> [<em>int-offset</em>]]])</h4>

<p>
The string in <em>str-source</em> is compiled into newLISP's internal format
and then evaluated. The evaluation result is returned. If the string contains 
more than one expression, the result of the last evaluation is returned.
</p>

<p>An optional second argument can be used to specify the context to which 
the string should be parsed and translated.</p>

<p>If an error occurs while parsing and evaluating <em>str-source</em> then
<em>exp-error</em> will be evaluated and the result returned.</p>

<p><em>int-offset</em> specifies an optional offset into <em>str-source</em>, 
where to start evaluation.</p>

<!-- example -->

<pre>
(eval-string "(+ 3 4)")  <span class='arw'>&rarr;</span> 7
(set 'X 123)             <span class='arw'>&rarr;</span> 123
(eval-string "X")        <span class='arw'>&rarr;</span> 123

(define (repl) ; read print eval loop
  (while true
    (println "=&gt; " (eval-string (read-line) MAIN (last-error)))
  )
)

(set 'a 10)
(set 'b 20)
(set 'foo:a 11)
(set 'foo:b 22)

(eval-string "(+ a b)")       <span class='arw'>&rarr;</span> 30
(eval-string "(+ a b)" 'foo)  <span class='arw'>&rarr;</span> 33
</pre>


<p>The second example shows a simple newLISP interpreter eval loop.</p> 

<p>The last example shows how to specify a target context for translation. The symbols 
<tt>a</tt> and <tt>b</tt> now refer to symbols and their values in context <tt>foo</tt> instead of 
<tt>MAIN</tt>.</p>
	
<p>See also the function <a href="#read-expr">read-expr</a> which translates a string
without evaluating it.</p>

<br/><br/>

<a name="eval-string-js"></a>
<h2><span class="function">eval-string-js
<a href="#JS"><font size="-1">JS</font></a></span></h2>
<h4>syntax: (eval-string-js <em>str-JavaScript-source</em>)</h4>
<p>The function takes a program source in <em>str-JavaScript-source</em>
and returns the result in a string.</p>

<p>This function is only available on newLISP compiled to JavaScript.</p>

<pre>
(eval-string-js "window.prompt('Enter some text:', '')")

; for single and double quotes inside a string passed to a
; JavaScropt function, single and double quotes must be
; preceded by a backslash \ and the whole string passed
; to eval-string-js limited by [text], [/text] tags.

(eval-string-js [text]alert('A double quote: \" and a single quote: \' ')[/text])

(eval-string-js "6 * 7")
</pre>

<p>The first expression will pop up a dialog box to enter text. The function
will return the text string entered. The second expression will return the
string <tt>42</tt>.</p>

<p>See also the function <a href="#display-html">display-html</a> for displaying
an HTML page in the browser.</p>

<br/><br/>

<a name="evenp"></a>
<h2><span class="function">even?</span>&nbsp;
<a href="#big_int"><font size="-1">bigint</font></a></h2>
<h4>syntax: (even? <em>int-number</em>)</h4>

<p>Checks if an integer number is <em>even divisible</em> by <tt>2</tt>, without remainder. 
When a floating point number is passed for <em>int-number</em>, it will be converted to an
integer by cutting off its fractional part.</p>

<pre>
(even? 123)  <span class='arw'>&rarr;</span> nil
(even? 8)    <span class='arw'>&rarr;</span> true
(even? 8.7)  <span class='arw'>&rarr;</span> true
</pre>

<p>Use <a href="#oddp">odd?</a> to check if an integer is not divisible by <tt>2</tt>.</p>

<br/><br/>

<a name="exec"></a>
<h2><span class="function">exec</span></h2>
<h4>syntax: (exec <em>str-process</em>)<br/>
syntax: (exec <em>str-process</em> [<em>str-stdin</em>])</h4>

<p>In the first form, <tt>exec</tt> launches a process described in <em>str-process</em>
and returns all standard output as a list of strings 
(one for each line in standard out (STDOUT)).  <tt>exec</tt> returns <tt>nil</tt>
if the process could not be launched. If the process could be launched but 
only returns and error and no valid output, the empty list will be returned.
</p> 


<!-- example -->

<pre>
(exec "ls *.c")  <span class='arw'>&rarr;</span> ("newlisp.c" "nl-math.c" "nl-string.c")
</pre>


<p>
	The example starts a process and performs the shell command <tt>ls</tt>,
	capturing the output in an array of strings.
</p>

<p>
	In the second form, 
	<tt>exec</tt> creates a process pipe, 
	starts the process in <em>str-process</em>, 
	and receives from <em>str-stdin</em> 
	standard input for this process.
	The return value is <tt>true</tt> 
	if the process was successfully launched; 
	otherwise it is <tt>nil</tt>.
</p>

<!-- example -->

<pre>
(exec "cgiProc" query)
</pre>


<p>
	In this example, 
	cgiProc could be a cgi processor (e.g., Perl or newLISP) 
	that receives and processes standard input supplied by a string 
	contained in the variable query.
</p>

<br/><br/>

<a name="exists"></a>
<h2><span class="function">exists</span></h2>
<h4>syntax: (exists <em>func-condition</em> <em>list</em>)</h4>

<p>Successively applies <em>func-condition</em> 
to the elements of <em>list</em> 
and returns the first element 
that meets the condition in <em>func-condition</em>. 
If no element meets the condition, 
<tt>nil</tt> is returned.</p>

<!-- example -->

<pre>
(exists string? '(2 3 4 6 "hello" 7))       <span class='arw'>&rarr;</span> "hello"

(exists string? '(3 4 2 -7 3 0))            <span class='arw'>&rarr;</span> nil

(exists zero? '(3 4 2 -7 3 0))              <span class='arw'>&rarr;</span> 0 ; check for 0 or 0.0

(exists &lt; '(3 4 2 -7 3 0))                  <span class='arw'>&rarr;</span> -7 ; check for negative

(exists (fn (x) (&gt; x 3)) '(3 4 2 -7 3 0))   <span class='arw'>&rarr;</span> 4

(exists (fn (x) (= x 10)) '(3 4 2 -7 3 0))  <span class='arw'>&rarr;</span> nil 
</pre>


<p>If <em>func-condition</em> is <tt>nil?</tt>, the result <tt>nil</tt> is ambiguous.
In this case <a href="#index">index</a> or <a href="#find">find</a> are the better 
method when looking for <tt>nil</tt>.</p>

<p>Use the <a href="#for-all">for-all</a> function 
to check if a condition is met for all elements in a list.</p>

<br/><br/>

<a name="exit"></a>
<h2><span class="function">exit</span></h2>
<h4>syntax: (exit [<em>int</em>])</h4>

<p>
	Exits newLISP. 
	An optional exit code, <em>int</em>, may be supplied. 
	This code can be tested by the host operating system. 
	When newLISP is run in <a href="#daemon">daemon server mode</a> 
 	using <tt>-d</tt> as a command-line option, 
	only the network connection is closed, 
	while newLISP stays resident, 
	listening for a new connection.
</p>

<!-- example -->

<pre>
(exit 5)
</pre>

<br/><br/>

<a name="exp"></a>
<h2><span class="function">exp</span></h2>
<h4>syntax: (exp <em>num</em>)</h4>

<p>The expression in <em>num</em> is evaluated, and the exponential function 
is calculated based on the result.  <tt>exp</tt> is the inverse function of 
<a href="#log">log</a>.
</p>

<!-- example -->

<pre>
(exp 1)        <span class='arw'>&rarr;</span> 2.718281828
(exp (log 1))  <span class='arw'>&rarr;</span> 1
</pre>

<br/><br/>

<a name="expand"></a>
<h2><span class="function">expand</span></h2>

<h4>syntax: (expand <em>exp</em> <em>sym-1</em> [<em>sym-2</em> ... ])<br/>
syntax: (expand <em>exp</em> <em>list-assoc</em> [<em>bool</em>])<br/>
syntax: (expand <em>exp</em>)</h4>

<p>In the first syntax, one symbol in <em>sym</em> 
(or more in <em>sym-2</em> through <em>sym-n</em>) 
is looked up in a simple or nested expression <em>exp</em>. 
They are then expanded to the current binding of the symbol 
and the expanded expression is returned. The original list remains unchanged.
</p>

<!-- example -->

<pre>
(set 'x 2 'a '(d e))
(set 'foo 'a)
(expand foo 'a)               <span class='arw'>&rarr;</span> (d e)
(expand '(a x b) 'x)           <span class='arw'>&rarr;</span> (a 2 b)
(expand '(a x (b c x)) 'x)     <span class='arw'>&rarr;</span> (a 2 (b c 2))
(expand '(a x (b c x)) 'x 'a)  <span class='arw'>&rarr;</span> ((d e) 2 (b c 2))
</pre>


<p><tt>expand</tt> is useful when composing lambda expressions 
and doing variable expansion as in rewrite macros.</p>


<pre>
(define (raise-to power)
  (expand (fn (base) (pow base power)) 'power))

(define square (raise-to 2))
(define cube (raise-to 3))

(square 5)  <span class='arw'>&rarr;</span> 25
(cube 5)    <span class='arw'>&rarr;</span> 125
</pre>


<p>
	If more than one symbol is present, 
	<tt>expand</tt> will work in an incremental fashion:
</p>


<pre>
(set 'a '(b c))
(set 'b 1)

(expand '(a b c) 'a 'b)  <span class='arw'>&rarr;</span> ((1 c) 1 c) 
</pre>


<p>
	Like the <a href="#apply">apply</a> function, 
	<tt>expand</tt> <em>reduces</em> its argument list.
</p>

<h4>syntax: (expand <em>list</em> <em>list-assoc</em> [<em>bool</em>])</h4>

<p>The second syntax of <tt>expand</tt> allows expansion bindings to be specified 
on the fly, without performing a <a href="#set">set</a> on the participating variables:
</p>

<p>If the <em>bool</em> evaluates to <tt>true</tt>, the value parts in the
association list are evaluated.</p>

<!-- example -->

<pre>
(expand '(a b c) '((a 1) (b 2)))                <span class='arw'>&rarr;</span> (1 2 c)
(expand '(a b c) '((a 1) (b 2) (c (x y z))))    <span class='arw'>&rarr;</span> (1 2 (x y z))
(expand '(a b) '((a (+ 1 2)) (b (+ 3 4))))      <span class='arw'>&rarr;</span> ((+ 1 2) (+ 3 4))
(expand '(a b) '((a (+ 1 2)) (b (+ 3 4))) true) <span class='arw'>&rarr;</span> (3 7)
</pre>


<p>
	Note that the contents of the variables 
	in the association list will not change. 
	This is different from the <a href="#letex">letex</a> function, 
	where variables are set by evaluating 
	and assigning their association parts.
</p>

<p>
	This form of <tt>expand</tt> is frequently used 
	in logic programming, 
	together with the <a href="#unify">unify</a> function.
</p>

<h4>syntax: (expand <em>list</em>)</h4>

<p>
	A third syntax is used to expand only the contents 
	of variables starting with an uppercase character. 
	This PROLOG mode may also be used 
	in the context of logic programming. 
	As in the first syntax of <tt>expand</tt>, 
	symbols must be preset. 
	Only uppercase variables and those bound 
	to anything other than <tt>nil</tt> 
	will be expanded:
</p>


<!-- example -->

<pre>
(set 'A 1 'Bvar 2 'C nil 'd 5 'e 6)
(expand '(A (Bvar) C d e f))  <span class='arw'>&rarr;</span> (1 (2) C d e f)
</pre>


<p>
	Only the symbols <tt>A</tt> and <tt>Bvar</tt> are expanded 
	because they have capitalized names 
	and non-<tt>nil</tt> contents.
</p>

<p>
	The <em>currying</em> function in the example 
	demonstrating the first syntax of <tt>expand</tt> 
	can now be written even more simply 
	using an uppercase variable:
</p>


<pre>
(define (raise-to Power) 
  (expand (fn (base) (pow base Power))))

&gt; (define cube (raise-to 3))
<b>(lambda (base) (pow base 3))</b>

&gt; (cube 4)
<b>64</b>

&gt; _
</pre>


<p>
	See the <a href="#letex">letex</a> function, 
	which also provides an expansion mechanism, 
	and the function <a href="#unify">unify</a>, 
	which is frequently used together with <tt>expand</tt>.
</p>

<br/><br/>

<a name="explode"></a>
<h2><span class="function">explode</span>&nbsp;<font size="-1"><a href="#utf8_capable">utf8</a></font></h2>
<h4>syntax: (explode <em>str</em> [<em>int-chunk</em> [<em>bool</em>]])<br/>
syntax: (explode <em>list</em> [<em>int-chunk</em> [<em>bool</em>]])</h4>

<p>
In the first syntax, 
<tt>explode</tt> transforms the string (<em>str</em>)
into a list of single-character strings. 
Optionally, a chunk size can be specified in <em>int-chunk</em> 
to break the string into multi-character chunks. 
When specifying a value for <em>bool</em> other than <tt>nil</tt>,
the last chunk will be omitted 
if it does not have the full length specified 
in <em>int-chunk</em>.
</p>

<!-- example -->

<pre>
(explode "newLISP")  <span class='arw'>&rarr;</span> ("n" "e" "w" "L" "I" "S" "P")

(join (explode "keep it together"))  <span class='arw'>&rarr;</span> "keep it together"

(explode "newLISP" 2)    <span class='arw'>&rarr;</span> ("ne" "wL" "IS" "P")

(explode "newLISP" 3)    <span class='arw'>&rarr;</span> ("new" "LIS" "P")

; omit last chunk if too short
(explode "newLISP" 3 true)    <span class='arw'>&rarr;</span> ("new" "LIS")
</pre>


<p>
Only on non UTF8&ndash; enabled versions, <tt>explode</tt> also works on binary content:
</p>


<pre>
(explode "\000\001\002\003") 
<span class='arw'>&rarr;</span> ("\000" "\001" "\002" "\003")
</pre>

<p>
When called in UTF-8&ndash;enabled versions of newLISP, 
<tt>explode</tt> will work on character boundaries rather than byte boundaries. 
In UTF-8&ndash;encoded strings, characters may contain more than one byte.
Processing will stop when a zero byte character is found.
</p>

<p>To explode binary contents on UTF-8&ndash;enabled versions of newLISP
use <a href="#unpack">unpack</a> as shown in the following example:</p>

<pre>
(set 'str "\001\002\003\004") <span class='arw'>&rarr;</span> "\001\002\003\004"

(unpack (dup "c" (length str)) str) <span class='arw'>&rarr;</span> (1 2 3 4)
(unpack (dup "s" (length str)) str) <span class='arw'>&rarr;</span> ("\001" "\002" "\003" "\004")
</pre>

<p>
In the second syntax, 
<tt>explode</tt> explodes a list (<em>list</em>)
into sublists of chunk size <em>int-chunk</em>, 
which is 1 (one) by default.
</p>

<p>
The following shows an example of the last chunk being omitted 
when the value for <em>bool</em> is other than <tt>nil</tt>,
and the chunk does not have the full length specified 
in <em>int-chunk</em>.
</p>

<!-- example -->

<pre>
(explode '(a b c d e f g h))    <span class='arw'>&rarr;</span> ((a) (b) (c) (d) (e) (f) (g) (h))
(explode '(a b c d e f g) 2)  <span class='arw'>&rarr;</span> ((a b) (c d) (e f) (g))

; omit last chunk if too short
(explode '(a b c d e f g) 2 true)  <span class='arw'>&rarr;</span> ((a b) (c d) (e f))

(transpose (explode '(a b c d e f g h) 2)) 
<span class='arw'>&rarr;</span> ((a c e g) (b d f h))
</pre>


<p>
The <a href="#join">join</a> and <a href="#append">append</a> functions
are inverse operations of <tt>explode</tt>.
</p>

<br/><br/>

<a name="extend"></a>
<h2><span class="function">extend</span>&nbsp;<a href="#destructive">!</a></h2>
<h4>syntax: (extend <em>list-1</em> [<em>list-2</em> ... ])<br/>
syntax: (extend <em>string-1</em> [<em>string-2</em> ... ])</h4>

<p>The list in <em>list-1</em> is extended by appending <em>list-2</em>. More
than one list may be appended.</p>

<p>The string in <em>string-1</em> is extended by appending <em>string-2</em>. More
than one string may be appended. The string can contain binary <tt>0</tt> (zero) 
characters.</p>

<p>The first parameter can be an un-initialized variable.</p>

<p>The extended list or string is returned.</p>

<!-- example -->

<pre>
; extending lists

(extend lst '(a b) '(c d)) <span class='arw'>&rarr;</span> (a b c d)
(extend lst '(e f g)) <span class='arw'>&rarr;</span> (a b c d e f)
lst <span class='arw'>&rarr;</span> (a b c d e f g)

; extending strings

(extend str "ab" "cd") <span class='arw'>&rarr;</span> "abcd"
(extend str "efg") <span class='arw'>&rarr;</span> "abcdefg"
str <span class='arw'>&rarr;</span> "abcdefg"

; extending in place

(set 'L '(a b "CD" (e f)))
(extend (L 2) "E")
L <span class='arw'>&rarr;</span> (a b "CDE" (e f))

(extend (L 3) '(g))
L <span class='arw'>&rarr;</span> (a b "CDE" (e f g))
</pre>

<p>For a non-destructive list or string extension see <a href="#append">append</a>.</p>

<br/><br/>

<a name="factor"></a>
<h2><span class="function">factor</span></h2>
<h4>syntax: (factor <em>int</em>)</h4>

<p>Factors the number in <em>int</em> into its prime components. 
When floating point numbers  are passed, they are truncated to 
their integer part first.</p>

<!-- example -->

<pre>
(factor 123456789123456789)  <span class='arw'>&rarr;</span> (3 3 7 11 13 19 3607 3803 52579)

;; check correctness of factoring
(= (apply * (factor 123456789123456789)) 123456789123456789)
<span class='arw'>&rarr;</span> true

;; factor the biggest integer
(factor 9223372036854775807)  <span class='arw'>&rarr;</span> (7 7 73 127 337 92737 649657)

;; primes.lsp - return all primes in a list, up to n 

(define (primes n , p)
  (dotimes (e n) 
    (if (= (length (factor e)) 1) 
      (push e p -1))) p)
           
(primes 20)  <span class='arw'>&rarr;</span> (2 3 5 7 11 13 17 19)         
</pre>


<p>
	<tt>factor</tt> returns <tt>nil</tt> 
	for numbers smaller than <tt>2</tt>.
	For numbers larger than 9,223,372,036,854,775,807
	(the largest 64-bit integer)
	converted from floating point numbers, 
	the largest integer is factored.
</p>

<br/><br/>

<a name="fft"></a>
<h2><span class="function">fft</span></h2>
<h4>syntax: (fft <em>list-num</em>)</h4>

<p>
	Calculates the discrete Fourier transform 
	on the list of complex numbers in <em>list-num</em> 
	using the FFT method (Fast Fourier Transform). 
	Each complex number is specified by its real part 
	followed by its imaginary part. 
	If only real numbers are used, 
	the imaginary part is set to <tt>0.0</tt> (zero). 
	When the number of elements in <em>list-num</em> 
	is not a power of 2, 
	<tt>fft</tt> increases the number of elements 
	by padding the list with zeroes. 
	When the imaginary part of a complex number is <tt>0</tt>, 
	simple numbers can be used instead.
</p>

<!-- example -->

<pre>
(ifft (fft '((1 0) (2 0) (3 0) (4 0)))) 
<span class='arw'>&rarr;</span> ((1 0) (2 0) (3 0) (4 0))

;; when imaginary part is 0, plain numbers work too
;; plain numbers and complex numbers can be intermixed

(fft '(1 2 3 4))      <span class='arw'>&rarr;</span> ((10 0) (-2 -2) (-2 0) (-2 2))
(fft '(1 2 (3 0) 4))  <span class='arw'>&rarr;</span> ((10 0) (-2 -2) (-2 0) (-2 2))
</pre>


<p>
	The inverse operation of <tt>fft</tt> 
	is the <a href="#ifft">ifft</a> function.
</p>

<br/><br/>

<a name="file-info"></a>
<h2><span class="function">file-info</span></h2>
<h4>syntax: (file-info <em>str-name</em> [<em>int-index</em> [<em>bool-flag</em>]])</h4>

<p>Returns a list of information about the file or directory in <em>str_name</em>. 
The optional index specifies the list member to return.  When no <em>bool-flag</em>
is specified or when <em>bool-flag</em> evaluates to <tt>nil</tt> information about
the link is returned if the file is a link to an original file. If <em>bool-flag</em>
evaluates to anything else than <tt>nil</tt>, information about the original file
referenced by the link is returned.</p>

<table   summary="file attributes">
<tr align="left"><th>offset</th><th>contents</th></tr>
<tr><td>0</td><td>size</td></tr>
<tr><td>1</td><td>mode (differs with <tt>true</tt> flag)</td></tr>
<tr><td>2</td><td>device mode</td></tr>
<tr><td>3</td><td>user ID</td></tr>

<tr><td>4</td><td>group ID</td></tr>
<tr><td>5</td><td>access time</td></tr>
<tr><td>6</td><td>modification time</td></tr>
<tr><td>7</td><td>status change time</td></tr>
</table><br/>

<p>Depending on <em>bool-flag</em> set, the function reports on either
the link (no flag or <tt>nil</tt> flag) or on the original linked file 
(<tt>true</tt> flag).</p>

<!-- example -->

<pre>
(file-info ".bashrc")   
<span class='arw'>&rarr;</span> (124 33188 0 500 0 920951022 920951022 920953074)

(file-info ".bashrc" 0)  <span class='arw'>&rarr;</span> 124

(date (file-info "/etc" -1))  <span class='arw'>&rarr;</span> "Mon Mar 8 18:23:17 2005"
</pre>


<p> In the second example, the last status change date 
for the directory <em>/etc</em> is retrieved.</p>

<p><tt>file-info</tt> gives file statistics (size) for a linked file,
not the link, except for the <em>mode</em> field.</p>

<br/><br/>

<a name="filep"></a>
<h2><span class="function">file?</span></h2>

<h4>syntax: (file? <em>str-path-name</em> [<em>bool</em>])</h4>

<p>Checks for the existence of a file in <em>str-name</em>. Returns <tt>true</tt> 
if the file exists; otherwise, it returns <tt>nil</tt>.  This function will also return 
<tt>true</tt> for directories. If the optional <em>bool</em> value is <tt>true</tt>,
the file must not be a directory and <em>str-path-name</em> is returned or <tt>nil</tt>
if the file is a directory. The existence of a file does not imply anything about its 
read or write permissions for the current user.</p>

<!-- example -->

<pre>
(if (file? "afile") (set 'fileNo (open "afile" "read")))

(file? "/usr/local/bin/newlisp" true) <span class='arw'>&rarr;</span> "/usr/local/bin/newlisp"
(file? "/usr/bin/foo" true)     <span class='arw'>&rarr;</span> nil
</pre>

<br/><br/>

<a name="filter"></a>
<h2><span class="function">filter</span></h2>
<h4>syntax: (filter <em>exp-predicate</em> <em>exp-list</em>)</h4>

<p>
	The predicate <em>exp-predicate</em> is applied 
	to each element of the list <em>exp-list</em>. 
	A list is returned containing the elements 
	for which <em>exp-predicate</em> is true. 
	<tt>filter</tt> works like <a href="#clean">clean</a>, 
	but with a negated predicate.
</p>

<!-- example -->

<pre>
(filter symbol? '(1 2 d 4 f g 5 h))  <span class='arw'>&rarr;</span> (d f g h)

(define (big? x) (&gt; x 5))  <span class='arw'>&rarr;</span> (lambda (x) (&gt; x 5))

(filter big? '(1 10 3 6 4 5 11))  <span class='arw'>&rarr;</span> (10 6 11)

; filter with comparison functor
(set 'L '((a 10 2 7) (b 5) (a 8 3) (c 8) (a 9)))

(filter (curry match '(a *)) L)   <span class='arw'>&rarr;</span> ((a 10 2 7) (a 8 3) (a 9))

(filter (curry match '(? ?)) L)   <span class='arw'>&rarr;</span> ((b 5) (c 8) (a 9))

(filter (curry match '(* 8 *)) L) <span class='arw'>&rarr;</span> ((a 8 3) (c 8))
</pre>


<p>
The predicate may be a built-in predicate, a user-defined function, 
or a lambda expression.
</p>

<p>
For filtering a list of elements with the elements from another list, 
use the <a href="#difference"> difference</a> function or 
<a href="#intersect">intersect</a> (with the <em>list</em> option).
</p>

<p>
See also the related function <a href="#index">index</a>, which returns the 
indices of the filtered elements and <a href="#clean">clean</a>, 
which returns all elements of a list for which a predicate is false.
</p>

<br/><br/>

<a name="find"></a>
<h2><span class="function">find</span></h2>
<h4>syntax: (find <em>exp-key</em> <em>list</em> [<em>func-compare</em> | <em>regex-option</em>])<br/>
syntax: (find <em>str-key</em> <em>str-data</em> [<em>regex-option</em> [<em>int-offset</em>]])</h4>


<h3>Find an expression in a list</h3>

<p>If the second argument evaluates to a <em>list</em>, then <tt>find</tt> returns 
the index position (offset) of the element derived from evaluating <em>exp-key</em>.</p>

<p>
Optionally, an operator or user-defined function can be specified in <em>func-compare</em>. 
If the <em>exp-key</em> is a string, a regular expression option
can be specified with the <em>regex-option</em> parameter.</p>

<p>When using regular expressions or comparison functors the system
variable <tt>$0</tt> is set to the last element found.</p>

<!-- example -->

<pre>
; find an expression in a list
(find '(1 2) '((1 4) 5 6 (1 2) (8 9)))  <span class='arw'>&rarr;</span> 3

(find "world" '("hello" "world"))       <span class='arw'>&rarr;</span> 1
(find "hi" '("hello" "world"))          <span class='arw'>&rarr;</span> nil

(find "newlisp" '("Perl" "Python" "newLISP") 1)  <span class='arw'>&rarr;</span> 2
; same with string option
(find "newlisp" '("Perl" "Python" "newLISP") "i")  <span class='arw'>&rarr;</span> 2

; use the comparison functor
(find 3 '(8 4 3  7 2 6) &gt;)  <span class='arw'>&rarr;</span> 4
$0 <span class='arw'>&rarr;</span> 2

(find "newlisp" '("Perl" "Python" "newLISP") 
                 (fn (x y) (regex x y 1))) <span class='arw'>&rarr;</span> 2
$0 <span class='arw'>&rarr;</span> "newLISP"

(find 5 '((l 3) (k 5) (a 10) (z 22)) 
         (fn (x y) (= x (last y))))  <span class='arw'>&rarr;</span> 1
$0 <span class='arw'>&rarr;</span> (k 5)

(find '(a ?) '((l 3) (k 5) (a 10) (z 22)) match)  <span class='arw'>&rarr;</span> 2
$0 <span class='arw'>&rarr;</span> (a 10)

(find '(X X) '((a b) (c d) (e e) (f g)) unify)  <span class='arw'>&rarr;</span> 2
$0 <span class='arw'>&rarr;</span> (e e)

; define the comparison functor first for better readability
(define (has-it-as-last x y) (= x (last y)))

(find 22 '((l 3) (k 5) (a 10) (z 22)) has-it-as-last)  <span class='arw'>&rarr;</span> 3
$0 <span class='arw'>&rarr;</span> (z 22)
</pre>


<p>
Using <a href="#match">match</a> and <a href="#unify">unify</a>, 
list searches can be formulated which are as powerful 
as regular expression searches are for strings.
</p>

<h3>Find a string in a string</h3>

<p>If the second argument, <em>str-data</em>, 
evaluates to a string, then the offset position 
of the string <em>str-key</em> (found in the first argument, 
<em>str-data</em>) is returned.  In this case, <tt>find</tt> 
also works on binary <em>str-data</em>. The offset position
returned is always based on counting single byte characters
even when running the UTF-8 enabled version of newLISP.</p>

<p>The presence of a third parameter specifies a search 
using the regular expression pattern specified in <em>str-pattern</em>, 
as well as an option number specified in <em>regex-option</em>
(i.e., 1 (one) for case-insensitive search or <tt>0</tt> (zero) 
for no special options). If <em>regex-option</em> is specified
an optional <em>int-offset</em> argument can be specified too
to start the search not at the beginning but at the offset given.
In any case the position returned by <tt>find</tt> is calculated
relative to the beginning of the string.</p>

<p>To specify <em>int-offset</em> in a simple string search without regular
expressions, specify <tt>nil</tt> for <em>regex-option</em>.</p>

<p>In newLISP, regular expressions are standard 
Perl Compatible Regular Expression (PCRE) searches. 
Found expressions or subexpressions are returned 
in the system variables <tt>$0</tt>, <tt>$1</tt>, <tt>$2</tt>, etc., 
which can be used like any other symbol. 
As an alternative, 
the contents of these variables 
can also be accessed 
by using <tt>($ 0)</tt>, <tt>($ 1)</tt>, <tt>($ 2)</tt>, etc. 
This method allows indexed access 
(i.e., <tt>($ i)</tt>, where <tt>i</tt> is an integer).
</p> 
	
<p>See <a href="#regex">regex</a> for the meaning of the  
option numbers and more information on regular expression searching.
</p> 
	
<!-- example -->

<pre>
; simple string search
(find "world" "Hello world")  <span class='arw'>&rarr;</span> 6
(find "WORLD" "Hello woRLd")  <span class='arw'>&rarr;</span> nil

; case-insensitive regex

(find "WorlD" "Hello woRLd" 1)  <span class='arw'>&rarr;</span> 6   
; or
(find "WorlD" "Hello woRLd" "i")  <span class='arw'>&rarr;</span> 6   
                                
(find "hi" "hello world")       <span class='arw'>&rarr;</span> nil
(find "Hello" "Hello world")    <span class='arw'>&rarr;</span> 0

; regex with default options

(find "cat|dog" "I have a cat" 0)  <span class='arw'>&rarr;</span> 9 
$0                                 <span class='arw'>&rarr;</span> "cat"
(find "cat|dog" "my dog" 0)        <span class='arw'>&rarr;</span> 3
$0                                 <span class='arw'>&rarr;</span> "dog"
(find "cat|dog" "MY DOG" 1)        <span class='arw'>&rarr;</span> 3
$0                                 <span class='arw'>&rarr;</span> "DOG"

; use an optional offset
(find "cat|dog" "I have a cat and a dog" 0)    <span class='arw'>&rarr;</span> 9
(find "cat|dog" "I have a cat and a dog" 0 12) <span class='arw'>&rarr;</span> 19

;; find with subexpressions in regular expression
;; and access with system variables

(set 'str  "http://nuevatec.com:80")

(find "http://(.*):(.*)" str 0)  <span class='arw'>&rarr;</span> 0
                                 
$0  <span class='arw'>&rarr;</span> "http://nuevatec.com:80"
$1  <span class='arw'>&rarr;</span> "nuevatec.com"
$2  <span class='arw'>&rarr;</span> "80"

;; system variables as an indexed expression (since 8.0.5)
($ 0)  <span class='arw'>&rarr;</span> "http://nuevatec.com:80"
($ 1)  <span class='arw'>&rarr;</span> "nuevatec.com"
($ 2)  <span class='arw'>&rarr;</span> "80"
</pre>


<p>
	For other functions using regular expressions, 
	see <a href="#directory">directory</a>, 
    <a href="#find-all">find-all</a>,
	<a href="#parse">parse</a>, 
	<a href="#regex">regex</a>, 
	<a href="#replace">replace</a>, 
	and <a href="#search">search</a>.
</p>

<p>
	To find expressions in nested 
	or multidimensional lists, 
	use the <a href="#ref">ref</a> and <a href="#ref-all">ref-all</a> functions.
</p>

<br/><br/>

<a name="find-all"></a>
<h2><span class="function">find-all</span></h2>
<h4>syntax: (find-all <em>str-regex-pattern</em> <em>str-text</em> [<em>exp</em> [<em>regex-option</em>]])<br/>
syntax: (find-all <em>list-match-pattern</em> <em>list</em> [<em>exp</em>])<br/>
syntax: (find-all <em>exp-key</em> <em>list</em> [<em>exp</em> [<em>func-compare</em>]])</h4>

<p>
In the first syntax, <tt>find-all</tt> finds all occurrences of <em>str-regex-pattern</em> 
in the text <em>str-text</em>, returning a list containing all matching strings. 
The empty list <tt>()</tt> is returned if no matches are found. In the first syntax
string searches are always done using regular expression patterns, even if no
<em>regex-option</em> is specified. The system variable <tt>$count</tt> is updated
with the number of matches found.</p>

<p>
Optionally, an expression can be specified to process the found string or regular subexpressions 
before placing them into the returned list. An additional option, <em>regex-option</em>, 
specifies special regular expression options 
(see <a href="#regex">regex</a> for further details).
</p>


<!-- example -->

<pre>
(find-all {\d+} "lkjhkljh34ghfdhgfd678gfdhfgd9")
<span class='arw'>&rarr;</span> ("34" "678" "9")

$count <span class='arw'>&rarr;</span> 3

(find-all {(new)(lisp)} "newLISPisNEWLISP" (append $2 $1) 1)
<span class='arw'>&rarr;</span> ("LISPnew" "LISPNEW")

(unique (sort 
    (find-all {[a-zA-Z]+} 
        (replace "&lt;[^&gt;]+&gt;" (get-url "http://newlisp.org") "" 0) )
))
<span class='arw'>&rarr;</span> ("A" "ACC" "AI" "API" "About" "All" "Amazing" "Apps"
...
"where" "whole" "width" "wiki" "will" "with" "work" "written")

; use $count in evaluated expr
(find-all "a" "ababab" (string $count $it)) <span class='arw'>&rarr;</span> ("1a" "2a" "3a")
</pre>


<p>
The first example discovers all numbers in a text. 
The second example shows how an optional expression in <em>exp</em> 
can work on subexpressions found by the regular expression pattern 
in <em>str-pattern</em>. The last example retrieves a web page, 
cleans out all HTML tags, and then collects all words 
into a unique and sorted list.
</p>

<p>
Note that <tt>find-all</tt> with strings always performs a regular expression search, 
even if the option in <em>regex-option</em> is omitted.
</p>

<p>In the second syntax, <tt>find-all</tt> searches for all list 
<a href="#match">match</a> patterns <em>list-match-pattern</em> in 
<em>list</em>. As in <tt>find-all</tt> for strings, an expression can 
be specified in <em>exp</em> to process further the matched sublist found in 
<em>list</em>. The system variable <tt>$count</tt> is updated with the number
 of matches found.</p>

<!-- example -->

<pre>
(find-all '(? 2) '((a 1) (b 2) (a 2) (c 4))) <span class='arw'>&rarr;</span> ((b 2) (a 2))

(find-all '(? 2) '((a 1) (b 2) (a 2) (c 4)) (first $it)) <span class='arw'>&rarr;</span> (b a)

$count <span class='arw'>&rarr;</span> 2
</pre>


<p><tt>find-all</tt> for list matches always uses <a href="#match">match</a> to compare when
searching for sublists and always needs a list for the pattern expression.</p>

<p>In the third syntax, <tt>find-all</tt> can specify a built-in or user-defined
function used for comparing list elements with the key expression in <em>exp-key</em>:</p>


<!-- example -->

<pre>
(find-all 5 '(2 7 4 5 9 2 4 9 7 4 8) $it &lt;) <span class='arw'>&rarr;</span> (7 9 9 7 8)

; process the found element available in $it

(find-all 5 '(2 7 4 5 9 2 4 9 7 4 8) (* 3 $it) &lt;) <span class='arw'>&rarr;</span> (21 27 27 21 24)
; same as
(find-all 5 '(2 7 4 5 9 2 4 9 7 4 8) (* 3 $it) (fn (x y) (&lt; x y))) <span class='arw'>&rarr;</span> (21 27 27 21 24)


(find-all 5 '(2 7 4 5 9 2 4 9 7 4 8) ("abcdefghijk" $it) &lt;) <span class='arw'>&rarr;</span> ("h" "j" "j" "h" "i")

$count <span class='arw'>&rarr;</span> 5

; use $count
(find-all 'a '(a b a b a b) (list $count $it)) <span class='arw'>&rarr;</span> ((1 a) (2 a) (3 a))
</pre>


<p>Any type of expression can be searched for or can be contained in the list. <tt>find-all</tt>
in this syntax works similar to <a href="#filter">filter</a> but with the added benefit of
being able to define a processing expression for the found element.</p>

<p>If no <em>func-compare</em> is defined and <em>exp-key</em> is a list, then
<a href="#match">match</a> will be used for comparison, as in the second syntax.</p>

<br/><br/>

<a name="first"></a>
<h2><span class="function">first</span>&nbsp;<font size="-1"><a href="#utf8_capable">utf8</a></font></h2>
<h4>syntax: (first <em>list</em>)<br/>
syntax: (first <em>array</em>)<br/>
syntax: (first <em>str</em>)</h4>

<p>
Returns the first element of a list or the first character of a string.
The operand is not changed.  This function is equivalent to <em>car</em>
or <em>head</em> in other Lisp dialects.</p>

<!-- example -->

<pre>
(first '(1 2 3 4 5))       <span class='arw'>&rarr;</span> 1
(first '((a b) c d))       <span class='arw'>&rarr;</span> (a b)
(set 'aList '(a b c d e))  <span class='arw'>&rarr;</span> (a b c d e)
(first aList)              <span class='arw'>&rarr;</span> a
aList                      <span class='arw'>&rarr;</span> (a b c d e)
(set 'A (array 3 2 (sequence 1 6)))
<span class='arw'>&rarr;</span>  ((1 2) (3 4) (5 6))
(first A)                  <span class='arw'>&rarr;</span> (1 2)

(first '())                <span class='arw'>&rarr;</span> <span class='err'>ERR: list is empty</span>
</pre>


<p>In the third syntax, the first character is returned 
from the string in <em>str</em> as a string.</p>

<!-- example -->

<pre>
(first "newLISP")         <span class='arw'>&rarr;</span> "n"
(first (rest "newLISP"))  <span class='arw'>&rarr;</span> "e"
</pre>


<p>
	Note that <a href="#first">first</a> works on character boundaries 
	rather than byte boundaries 
	when the UTF-8&ndash;enabled version of newLISP is used.
	See also the functions <a href="#last">last</a> 
	and <a href="#rest">rest</a>.
</p>

<br/><br/>

<a name="flat"></a>
<h2><span class="function">flat</span></h2>
<h4>syntax: (flat <em>list</em> [<em>int-level</em>])</h4>

<p>Returns a flattened list from a list:</p>

<!-- example -->

<pre>
(set 'lst '(a (b (c d))))
(flat lst)  <span class='arw'>&rarr;</span> (a b c d)

; extract a list of index vectors of all elements

(map (fn (x) (ref x lst)) (flat lst)) 
<span class='arw'>&rarr;</span> ((0) (1 0) (1 1 0) (1 1 1))
</pre>

<p>The optional <em>int-level</em> parameter can be used to limit
the recursion level when flattening the list:</p>

<!-- example -->

<pre>
(flat '(a b (c d (e f)) (g h (i j))) )   <span class='arw'>&rarr;</span> (a b c d e f g h i j)

(flat '(a b (c d (e f)) (g h (i j))) 1)  <span class='arw'>&rarr;</span> (a b c d (e f) g h (i j))

(flat '(a b (c d (e f)) (g h (i j))) 2)  <span class='arw'>&rarr;</span> (a b c d e f g h i j)
</pre>

<p>If <em>int-level</em> is <tt>0</tt>, no flattening will occur.</p>

<p><tt>flat</tt> can be used to iterate through nested lists.</p>


<br/><br/>

<a name="float"></a>
<h2><span class="function">float</span></h2>
<h4>syntax: (float <em>exp</em> [<em>exp-default</em>])</h4>

<p>
	If the expression in <em>exp</em> 
	evaluates to a number or a string, 
	the argument is converted to a float 
	and returned. 
	If <em>exp</em> cannot be converted to a float 
	then <tt>nil</tt> or, if specified, 
	the evaluation of <em>exp-default</em> 
	will be returned.
	This function is mostly used to convert strings 
	from user input or when reading and parsing text. 
	The string must start with a digit 
	or the <tt>+</tt> (plus sign), <tt>-</tt> (minus sign), 
	or <tt>.</tt> (period). 
	If <em>exp</em> is invalid,
	<tt>float</tt> returns <tt>nil</tt> 
	as a default value.
</p>

<p>
	Floats with exponents larger than 1e308 
	or smaller than -1e308 
	are converted to +INF or -INF, respectively. 
	The display of +INF and -INF 
	differs on different platforms and compilers.
</p>

<!-- example -->

<pre>
(float "1.23")       <span class='arw'>&rarr;</span> 1.23
(float " 1.23")      <span class='arw'>&rarr;</span> 1.23
(float ".5")         <span class='arw'>&rarr;</span> 0.50
(float "-1.23")      <span class='arw'>&rarr;</span> -1.23
(float "-.5")        <span class='arw'>&rarr;</span> nil
(float "#1.23")      <span class='arw'>&rarr;</span> nil
(float "#1.23" 0.0)  <span class='arw'>&rarr;</span> 0

(float? 123)          <span class='arw'>&rarr;</span> nil
(float? (float 123))  <span class='arw'>&rarr;</span> true

(float '(a b c))    <span class='arw'>&rarr;</span> nil
(float '(a b c) 0)  <span class='arw'>&rarr;</span> 0
(float nil 0)       <span class='arw'>&rarr;</span> 0

(float "abc" "not a number")  <span class='arw'>&rarr;</span> "not a number"
(float "1e500")               <span class='arw'>&rarr;</span> inf
(float "-1e500")              <span class='arw'>&rarr;</span> -inf

(print "Enter a float num:")
(set 'f-num (float (read-line)))
</pre>


<p>
	Use the <a href="#int">int</a> function 
	to parse integer numbers.
</p>

<br/><br/>

<a name="floatp"></a>
<h2><span class="function">float?</span></h2>
<h4>syntax: (float? <em>exp</em>)</h4>

<p>
	<tt>true</tt> is returned only 
	if <em>exp</em> evaluates to a floating point number;
	otherwise, <tt>nil</tt> is returned.
</p>

<!-- example -->

<pre>
(set 'num 1.23)
(float? num)  <span class='arw'>&rarr;</span> true
</pre>

<br/><br/>

<a name="floor"></a>
<h2><span class="function">floor</span></h2>
<h4>syntax: (floor <em>number</em>)</h4>

<p>
	Returns the next lowest integer below <em>number</em> 
	as a floating point.
</p>

<!-- example -->

<pre>
(floor -1.5)  <span class='arw'>&rarr;</span> -2
(floor 3.4)   <span class='arw'>&rarr;</span> 3
</pre>


<p>
	See also the <a href="#ceil">ceil</a> function.
</p>

<br/><br/>

<a name="flt"></a>
<h2><span class="function">flt</span></h2>
<h4>syntax: (flt <em>number</em>)</h4>

<p>
	Converts <em>number</em> to a 32-bit float 
	represented by an integer. 
	This function is used when passing 32-bit floats 
	to library routines.
	newLISP floating point numbers 
	are 64-bit and are passed as 64-bit floats 
	when calling imported C library routines.
</p>


<!-- example -->

<pre>
(flt 1.23)  <span class='arw'>&rarr;</span> 1067282596

;; pass 32-bit float to C-function: foo(float value) 
(import "mylib.so" "foo")
(foo (flt 1.23))

(get-int (pack "f" 1.23))  <span class='arw'>&rarr;</span> 1067282596

(unpack "f" (pack "ld" (flt 1.2345)))  <span class='arw'>&rarr;</span> (1.234500051)
</pre>


<p>
	The last two statements illustrate 
	the inner workings of <tt>flt</tt>.
</p>

<p>
	Use the <a href="#import">import</a> function 
	to import libraries.
</p>

<br/><br/>

<a name="fn"></a>
<h2><span class="function">fn</span></h2> 
<h4>syntax: (fn (<em>list-parameters</em>) <em>exp-body</em>)</h4>

<p>
<tt>fn</tt> or <tt>lambda</tt> are used to define anonymous functions, 
which are frequently used in <a href="#map">map</a>, <a href="#sort">sort</a>, 
and all other expressions where functions can be used as arguments.
The <tt>fn</tt> or <tt>lambda</tt> word does not exist on its own as a symbol,
but indicates a special list type: the <em>lambda list</em>. Together with <tt>fn-macro</tt>
and <tt>lambda-macro</tt> these terms are recognized during source parsing. They indicate a 
specialized type of list which can be used and applied like a function or operator. 
</p>

<p>
Using an anonymous function eliminates the need to define a new function with 
<a href="#define">define</a>. Instead, a function is defined on the fly:
</p>

<!-- example -->

<pre>
(map (fn (x) (+ x x)) '(1 2 3 4 5)) <span class='arw'>&rarr;</span> (2 4 6 8 10)

(sort '(".." "..." "." ".....") (fn (x y) (&gt; (length x) (length y))))
<span class='arw'>&rarr;</span> ("....." "..." ".." ".")
</pre>


<p>
The example defines the function <em>fn(x)</em>, which takes an integer 
(<em>x</em>) and doubles it.  The function is <em>mapped</em> onto a list of 
arguments using <a href="#map">map</a>. The second example shows strings being 
sorted by length.
</p>

<p>
The <a href="#lambda">lambda</a> function (the longer, traditional form of writing)
can be used in place of <tt>fn</tt>.
</p>

<br/><br/>

<a name="for"></a>
<h2><span class="function">for</span></h2>
<h4>syntax: (for (<em>sym</em> <em>num-from</em> <em>num-to</em> [<em>num-step</em> [<em>exp-break</em>]]) <em>body</em>)</h4>

<p>
	Repeatedly evaluates the expressions in <em>body</em> 
	for a range of values specified
	in <em>num-from</em> and <em>num-to</em>, inclusive.  
	A step size may be specified with <em>num-step</em>.  
	If no step size is specified, <tt>1</tt> is assumed.
</p>

<p>
	Optionally, a condition for early loop exit
	may be defined in <em>exp-break</em>. 
	If the break expression evaluates 
	to any non-<tt>nil</tt> value, 
	the <tt>for</tt> loop returns with 
	the value of <em>exp-break</em>. 
	The break condition is tested 
	before evaluating <em>body</em>. If a
	break condition is defined, <em>num-step</em>
	must be defined, too.
</p>

<p>
	The symbol <em>sym</em> 
	is local in dynamic scope 
	to the <tt>for</tt> expression.
	It takes on each value successively 
	in the specified range as an integer value 
	if no step size is specified, or
	as a floating point value when a step size is
	present. After evaluation of the <tt>for</tt>
    statement <em>sym</em> assumes its previous
    value.
</p>

<!-- example -->

<pre>
&gt; (for (x 1 10 2) (println x))
<b>1
3
5
7
9</b>

&gt; (for (x 8 6 0.5) (println x))
<b>8
7.5
7
6.5
6</b>

&gt; (for (x 1 100 2 (&gt; (* x x) 30)) (println x))
<b>1
3
5
true</b>
&gt; _
</pre>


<p>
	The second example uses 
	a range of numbers 
	from highest to lowest. 
	Note that the step size 
	is always a positive number. 
	In the third example, 
	a break condition is tested.
</p>

<p>
	Use the <a href="#sequence">sequence</a> function
	to make a sequence of numbers.
</p>

<br/><br/>

<a name="for-all"></a>
<h2><span class="function">for-all</span></h2>

<h4>syntax: (for-all <em>func-condition</em> <em>list</em>)</h4>

<p>Applies the function in <em>func-condition</em> 
to all elements in <em>list</em>.
If all elements meet the condition in <em>func-condition</em>,
the result is <tt>true</tt>;
otherwise, <tt>nil</tt> is returned.</p>

<!-- example -->

<pre>
(for-all number? '(2 3 4 6 7))                 <span class='arw'>&rarr;</span> true

(for-all number? '(2 3 4 6 "hello" 7))         <span class='arw'>&rarr;</span> nil

(for-all (fn (x) (= x 10)) '(10 10 10 10 10))  <span class='arw'>&rarr;</span> true
</pre>


<p>Use the <a href="#exists">exists</a> function
to check if at least one element in a list 
meets a condition.</p>

<br/><br/>

<a name="fork"></a>
<h2><span class="function">fork</span></h2>

<h4>syntax: (fork <em>exp</em>)</h4>

<p>
The expression in <em>exp</em> is launched as a newLISP child process-thread 
of the platforms OS. The new process inherits the entire address space, 
but runs independently so symbol or variable contents changed in the child process 
will not affect the parent process or vice versa. The child process ends 
when the evaluation of <em>exp</em> finishes.
</p>

<p>
On success, <tt>fork</tt> returns with the child process ID; on failure, 
<tt>nil</tt> is returned. See also the <a href="#wait-pid">wait-pid</a> function, 
which waits for a child process to finish.
</p>

<p>
This function is only available on Linux/Unix versions of newLISP 
and is based on the <tt>fork()</tt> implementation of the underlying OS. </p>

<p>A much simpler automated method to launch processes and collect
results is available with <a href="#spawn">spawn</a> and the <a href="#cilk">Cilk API</a>.</p>

<!-- example -->

<pre>
&gt; (set 'x 0)
<b>0</b>
&gt; (fork (while (&lt; x 20) (println (inc x)) (sleep 1000)))
<b>176</b>

&gt; <b>1
2
3
4
5
6</b>
</pre>


<p>
The example illustrates how the child process-thread inherits the symbol space 
and how it is independent of the parent process. The <tt>fork</tt> statement 
returns immediately with the process ID <tt>176</tt>. The child process increments 
the variable <tt>x</tt> by one each second and prints it to standard out (boldface). 
In the parent process, commands can still be entered. Type <tt>x</tt> to see that 
the symbol <tt>x</tt> still has the value <tt>0</tt> (zero) in the parent process. 
Although statements entered will mix with the display of the child process output, 
they will be correctly input to the parent process.</p>

<p>
The second example illustrates how <a href="#pipe">pipe</a> can be used 
to communicate between processes.</p>

<!-- example -->

<pre>
#!/usr/local/bin/newlisp

(define (count-down-proc x channel)
  (while (!= x 0)
      (write-line channel (string x))
      (dec x)))

(define (observer-proc channel)
  (do-until (= i "1")
    (println "process " (setq i (read-line channel)))))

(map set '(in out) (pipe))
(set 'observer (fork (observer-proc in)))
(set 'counter (fork (count-down-proc 5 out)))

; avoid zombies
(wait-pid observer)
(wait-pid counter)

(exit)
</pre>


<p>The following output is generated by observer-proc</p>


<pre>
<b>process 5
process 4
process 3
process 2
process 1</b>
</pre>


<p>
The <tt>count-down-proc</tt> writes numbers to the communication pipe, 
where they are picked up by the <tt>observer-process</tt> and displayed.
</p>

<p>A forked process can either exit by itself or it can be destroyed using
the <a href="#destroy">destroy</a> function.</p>


<pre>
(define (fork-destroy-demo)
    (set 'pid (fork (dotimes (i 1000) (println i) (sleep 10))))
    (sleep 50)
    (destroy pid) 
)

&gt; (fork-destroy-demo)
<b>0
1
2
3
4
true</b>
&gt; 
</pre>


<p>The process started by <tt>fork-destroy-demo</tt> will not finish but is
destroyed 50 milli-seconds after start by a call to <a href="#destroy">destroy</a>.
</p> 

<p>
Use the <a href="#semaphore">semaphore</a> function for synchronizing processes 
and <a href="#share">share</a> for sharing memory between processes.
</p>

<p>See <a href="#spawn">spawn</a> for a much simpler and automated way to
synchronize processes and collect results.</p>

<br/><br/>

<a name="format"></a>
<h2><span class="function">format</span></h2>
<h4>syntax: (format <em>str-format exp-data-1</em> [<em>exp-data-2</em> ... ])<br/>
syntax: (format <em>str-format</em> <em>list-data</em>)</h4>

<p>Constructs a formatted string from <em>exp-data-1</em> 
using the format specified in the evaluation of <em>str-format</em>. 
The format specified is identical to the format used for the <tt>printf()</tt> 
function in the ANSI C language.  Two or more <em>exp-data</em> arguments 
can be specified for more than one format specifier in <em>str-format</em>.</p>

<p>In an alternative syntax, the data to be formatted 
can be passed inside a list in <em>list-data</em>.</p>

<p><tt>format</tt> checks for a valid format string, 
matching data type, and the correct number of arguments. 
Wrong formats or data types result in error messages. 
<a href="#int">int</a>, <a href="#float">float</a>, 
or <a href="#string">string</a> can be used 
to ensure correct data types and to avoid error messages.</p>

<p>The format string has the following general format:</p>


<b>"%w.pf"</b>

<p>The <tt>%</tt> (percent sign) starts a format specification. 
To display a <tt>%</tt> inside a format string, double it: <tt>%%</tt></p>

<p>On Linux the percent sign can be followed by a single quote <tt>%'</tt>
to insert thousand's separators in number formats.</p>


<p>The <tt>w</tt> represents the width field. Data is right-aligned, except when 
preceded by a minus sign, in which case it is left-aligned. If preceded by a 
<tt>+</tt> (plus sign), positive numbers are displayed with a <tt>+</tt>.  
When preceded by a <tt>0</tt> (zero), the unused space is filled with leading 
zeroes. The width field is optional and serves all data types.</p>

<p>The <tt>p</tt> represents the precision number of decimals (floating point only) 
or strings and is separated from the width field by a period. Precision is 
optional. When using the precision field on strings, the number of characters 
displayed is limited to the number in <tt>p</tt>.</p>

<p>The <tt>f</tt> represents a type flag and is essential; 
it cannot be omitted.</p>

<p>Below are the types in <tt>f</tt>:</p>

<table summary="format characters">
<tr align="left"><th>format</th><th>description</th></tr>
<tr><td>s</td><td>text string</td></tr>
<tr><td>c</td><td>character (value 1 - 255)</td></tr>
<tr><td>d</td><td>decimal (32-bit)</td></tr>
<tr><td>u</td><td>unsigned decimal (32-bit)</td></tr>
<tr><td>x</td><td>hexadecimal lowercase</td></tr>
<tr><td>X</td><td>hexadecimal uppercase</td></tr>
<tr><td>o</td><td>octal (32-bits) (not supported on all of newLISP flavors)</td></tr>
<tr><td>f</td><td>floating point</td></tr>
<tr><td>e</td><td>scientific floating point</td></tr>
<tr><td>E</td><td>scientific floating point</td></tr>
<tr><td>g</td><td>general floating point</td></tr>
</table><br/>

<p>Formatting 64-bit numbers using the 32-bit format specifiers from above table 
will truncate and format the lower 32 bits of the number on 64-bit systerms and overflow to
<tt>0xFFFFFFFF</tt> on 32-bit systems.</p>

<p>For 32-bit and 64-bit numbers use the following format 
strings. 64-bit numbers will be truncated to 32-bit on
32-bit platforms:</p>

<table summary="format characters">
<tr align="left"><th>format</th><th>description</th></tr>
<tr><td>ld</td><td>decimal (32/64-bit)</td></tr>
<tr><td>lu</td><td>unsigned decimal (32/64-bit)</td></tr>
<tr><td>lx</td><td>hexadecimal (32/64-bit)</td></tr>
<tr><td>lX</td><td>hexadecimal uppercase (32/64-bit)</td></tr>
</table><br/>

<p>For 64-bit numbers use the following format strings on Unix-like 
operating systems and on MS Windows (not supported on TRU64):</p>

<table summary="format characters">
<tr align="left"><th>format</th><th>description</th></tr>
<tr><td>lld</td><td>decimal (64-bit)</td></tr>
<tr><td>llu</td><td>unsigned decimal (64-bit)</td></tr>
<tr><td>llx</td><td>hexadecimal (64-bit)</td></tr>
<tr><td>llX</td><td>hexadecimal uppercase(64-bit)</td></tr>
</table><br/>

<p>On Windows platforms only the following characters apply 
for 64 bit numbers:</p>

<table summary="format characters">
<tr align="left"><th>format</th><th>description</th></tr>
<tr><td>I64d</td><td>decimal (64-bit)</td></tr>
<tr><td>I64u</td><td>unsigned decimal (64-bit)</td></tr>
<tr><td>I64x</td><td>hexadecimal (64-bit)</td></tr>
<tr><td>I64X</td><td>hexadecimal uppercase(64-bit)</td></tr>
</table><br/>

<p>
	Other text may occur between, 
	before, or after the format specs.
</p>
	
<p>Note that on Tru64 Unix the format character <tt>i</tt> can be used instead
of <tt>d</tt>.
</p>

<br/><br/>

<!-- example -->

<pre>
(format "&gt;&gt;&gt;%6.2f&lt;&lt;&lt;" 1.2345)     <span class='arw'>&rarr;</span> "&gt;&gt;&gt;  1.23&lt;&lt;&lt;"
(format "&gt;&gt;&gt;%-6.2f&lt;&lt;&lt;" 1.2345)    <span class='arw'>&rarr;</span> "&gt;&gt;&gt;1.23  &lt;&lt;&lt;"
(format "&gt;&gt;&gt;%+6.2f&lt;&lt;&lt;" 1.2345)    <span class='arw'>&rarr;</span> "&gt;&gt;&gt; +1.23&lt;&lt;&lt;"
(format "&gt;&gt;&gt;%+6.2f&lt;&lt;&lt;" -1.2345)   <span class='arw'>&rarr;</span> "&gt;&gt;&gt; -1.23&lt;&lt;&lt;"
(format "&gt;&gt;&gt;%-+6.2f&lt;&lt;&lt;" -1.2345)  <span class='arw'>&rarr;</span> "&gt;&gt;&gt;-1.23 &lt;&lt;&lt;"

(format "%e" 123456789)        <span class='arw'>&rarr;</span> "1.234568e+08"
(format "%12.10E" 123456789)   <span class='arw'>&rarr;</span> "1.2345678900E+08"

(format "%10g" 1.23)   <span class='arw'>&rarr;</span> "      1.23"
(format "%10g" 1.234)  <span class='arw'>&rarr;</span> "     1.234"

(format "Result = %05d" 2)  <span class='arw'>&rarr;</span> "Result = 00002"

(format "%14.2f" 12345678.12)   <span class='arw'>&rarr;</span> "   12345678.12"
; on UNIX glibc compatible platforms only (Linux, MAC OS X 10.9) on some locales
(format "%'14.2f" 12345678.12) <span class='arw'>&rarr;</span> " 12,345,678.12"

(format "%8d" 12345)   <span class='arw'>&rarr;</span> "   12345"
; on UNIX glibc compatible platforms only (Linux, MAC OS X 10.9) on some locales
(format "%'8d" 12345)  <span class='arw'>&rarr;</span> "  12,345"

(format "%-15s" "hello")        <span class='arw'>&rarr;</span> "hello          "
(format "%15s %d" "hello" 123)  <span class='arw'>&rarr;</span> "          hello 123"
(format "%5.2s" "hello")        <span class='arw'>&rarr;</span> "   he"
(format "%-5.2s" "hello")       <span class='arw'>&rarr;</span> "he   "

(format "%o" 80)    <span class='arw'>&rarr;</span> "120"
                                
(format "%x %X" -1 -1)  <span class='arw'>&rarr;</span> "ffffffff FFFFFFFF"

; 64 bit numbers on Windows
(format "%I64X" 123456789012345678)  <span class='arw'>&rarr;</span> "1B69B4BA630F34E"

; 64 bit numbers on Unix (except TRU64)
(format "%llX" 123456789012345678)   <span class='arw'>&rarr;</span> "1B69B4BA630F34E"
                                
(format "%c" 65)  <span class='arw'>&rarr;</span> "A"
</pre>


<p>
	The data to be formatted 
	can be passed inside a list:
</p>


<pre>
(set 'L '("hello" 123))
(format "%15s %d" L)  <span class='arw'>&rarr;</span> "          hello 123"
</pre>


<p>
	If the format string requires it, 
	newLISP's <tt>format</tt> will 
	automatically convert integers 
	into floating points 
	or floating points into integers:
</p>


<pre>
(format "%f" 123)      <span class='arw'>&rarr;</span> 123.000000
                       
(format "%d" 123.456)  <span class='arw'>&rarr;</span> 123
</pre>

<br/><br/>

<a name="fv"></a>
<h2><span class="function">fv</span></h2>
<h4>syntax: (fv <em>num-rate</em> <em>num-nper</em> <em>num-pmt</em> <em>num-pv</em> [<em>int-type</em>])</h4>

<p>Calculates the future value of a loan with constant payment <em>num-pmt</em> 
and constant interest rate <em>num-rate</em> after <em>num-nper</em> period of 
time and a beginning principal value of <em>num-pv</em>.  If payment is at the 
end of the period, <em>int-type</em> is <tt>0</tt> (zero) or <em>int-type</em> is
omitted; for payment at the beginning of each period, <em>int-type</em> is 1. 
</p>

<!-- example -->

<pre>
(fv (div 0.07 12) 240 775.30 -100000)  <span class='arw'>&rarr;</span> -0.5544645052
</pre>


<p>
The example illustrates how a loan of $100,000 is paid down to a residual 
of $0.55 after 240 monthly payments at a yearly interest rate of 7 percent.
</p>

<p>
	See also the functions <a href="#irr">irr</a>, 
	<a href="#nper">nper</a>, <a href="#npv">npv</a>, 
	<a href="#pmt">pmt</a>, and <a href="#pv">pv</a>.
</p>

<br/><br/>

<a name="gammai"></a>
<h2><span class="function">gammai</span></h2>
<h4>syntax: (gammai <em>num-a</em> <em>num-b</em>)</h4>

<p>
	Calculates the incomplete Gamma function 
	of values <em>a</em> and <em>b</em> in <em>num-a</em> and <em>num-b</em>,
	respectively.
</p>

<!-- example -->

<pre>
(gammai 4 5)  <span class='arw'>&rarr;</span> 0.7349740847
</pre>


<p>
	The incomplete Gamma function is used to derive 
	the probability of Chi&sup2; to exceed a 
	given value for a degree of freedom, df, as follows:
</p>

<BLOCKQUOTE>
<em><b>Q(Chi&sup2;|df) = Q(df/2, Chi&sup2;/2) = gammai(df/2, Chi&sup2;/2)</b></em>
</BLOCKQUOTE>

<p>
	See also the <a href="#prob-chi2">prob-chi2</a> function.
</p>

<br/><br/>

<a name="gammaln"></a>
<h2><span class="function">gammaln</span></h2>
<h4>syntax: (gammaln <em>num-x</em>)</h4>

<p>
	Calculates the log Gamma function of the value <em>x</em> in <em>num-x</em>.
</p>

<!-- example -->

<pre>
(exp (gammaln 6))  <span class='arw'>&rarr;</span> 120
</pre>


<p>
	The example uses the equality of <em>n! = gamma(n + 1)</em> 
	to calculate the factorial value of 5.
</p>

<p>
	The log Gamma function is also related to the Beta function, 
	which can be derived from it:
</p>

<BLOCKQUOTE>
<em><b>Beta(z,w) = Exp(Gammaln(z) + Gammaln(w) - Gammaln(z+w))</b></em>

</BLOCKQUOTE>

<br/><br/>

<a name="gcd"></a>
<h2><span class="function">gcd</span>&nbsp;
<a href="#big_int"><font size="-1">bigint</font></a></h2>
<h4>syntax: (gcd <em>int-1</em> [<em>int-2</em> ... ])</h4>

<p>
Calculates the greatest common divisor 
of a group of integers.
The greatest common divisor of two integers 
that are not both zero 
is the largest integer that divides both numbers.
<tt>gcd</tt> will calculate the greatest common divisor 
for the first two integers in <em>int-i</em> 
and then further reduce the argument list 
by calculating the greatest common divisor of the result 
and the next argument in the parameter list.
</p>

<!-- example -->

<pre>
(gcd 0)        <span class='arw'>&rarr;</span> 0
(gcd 0 0)      <span class='arw'>&rarr;</span> 0
(gcd 10)       <span class='arw'>&rarr;</span> 10
(gcd 12 36)    <span class='arw'>&rarr;</span> 12
(gcd 15 36 6)  <span class='arw'>&rarr;</span> 3 
</pre>


<p>
See 
<a href="http://en.wikipedia.org/wiki/Greatest_common_divisor">Wikipedia</a>
for details and theory about gcd numbers in mathematics.
</p>

<br/><br/>

<a name="get-char"></a>
<h2><span class="function">get-char</span>&nbsp;
<a href="#shared-lib"><font size="+2">&#x26A0;</font></a></h2>
<h4>syntax: (get-char <em>int-address</em>)</h4>

<p>
Gets an 8-bit character from an address 
specified in <em>int-address</em>. 
This function is useful when using 
imported shared library functions 
with <a href="#import">import</a>.
</p>

<!-- example -->

<pre>
char * foo(void)
{
char * result;
result = "ABCDEFG";
return(result);
}
</pre>


<p>
Consider the above C function 
from a shared library, which returns a 
character pointer (address to a string).
</p>


<pre>
(import "mylib.so" "foo")
(print (get-char (foo) ))       <span class='arw'>&rarr;</span>  65 ; ASCII "A"
(print (get-char (+ (foo) 1)))  <span class='arw'>&rarr;</span>  66 ; ASCII "B"
</pre>



<p>
Note that it is unsafe to use the <tt>get-char</tt> function 
with an incorrect address in <em>int-address</em>. Doing so 
could result in the system crashing or becoming unstable.
</p>

<p>
See also the <a href="#address">address</a>, 
<a href="#get-int">get-int</a>, 
<a href="#get-long">get-long</a>, 
<a href="#get-float">get-float</a>, 
<a href="#get-string">get-string</a>, 
<a href="#pack">pack</a>, and <a href="#unpack">unpack</a> functions.
</p>

<br/><br/>

<a name="get-float"></a>
<h2><span class="function">get-float</span>&nbsp;
<a href="#shared-lib"><font size="+2">&#x26A0;</font></a></h2>
<h4>syntax: (get-float <em>int-address</em>)</h4>

<p>
Gets a 64-bit double float from an address 
specified in <em>int-address</em>.
This function is helpful when using 
imported shared library functions (with <tt>import</tt>)
that return an address pointer to a double float 
or a pointer to a structure containing double floats.
</p>

<!-- example -->

<pre>
double float * foo(void)
{
double float * result;
&hellip;
*result = 123.456;
return(result);
}
</pre>


<p>
The previous C function is compiled 
into a shared library.
</p>


<pre>
(import "mylib.so" "foo")
(get-float (foo))  <span class='arw'>&rarr;</span> 123.456
</pre>


<p>
<tt>foo</tt> is imported and returns a pointer 
to a double float when called.
Note that <tt>get-float</tt> is unsafe when used 
with an incorrect address in <em>int-address</em> 
and may result in the system crashing or becoming unstable.
</p>

<p>
See also the <a href="#address">address</a>, 
<a href="#get-int">get-int</a>, 
<a href="#get-long">get-long</a>,
<a href="#get-char">get-char</a>, 
<a href="#get-string">get-string</a>,
<a href="#pack">pack</a>, 
and <a href="#unpack">unpack</a> functions.
</p>

<br/><br/>

<a name="get-int"></a>
<h2><span class="function">get-int</span>&nbsp;
<a href="#shared-lib"><font size="+2">&#x26A0;</font></a></h2>
<h4>syntax: (get-int <em>int-address</em>)</h4>

<p>
Gets a 32-bit integer from 
the address specified in <em>int-address</em>.
This function is handy when using 
imported shared library functions with <tt>import</tt>,
a function returning an address pointer 
to an integer, or a pointer to a structure containing integers.
</p>

<!-- example -->

<pre>
int * foo(void)
{
int * result;
&hellip;
*result = 123;
return(result);
}

int foo-b(void)
{
int result;
&hellip;
result = 456;
return(result);
}
</pre>


<p>
Consider the C function <tt>foo</tt> (from a shared library), 
which returns an integer pointer (address of an integer).
</p>


<pre>
(import "mylib.so" "foo")
(get-int (foo))  <span class='arw'>&rarr;</span> 123
(foo-b)          <span class='arw'>&rarr;</span> 456
</pre>


<p>
Note that using <tt>get-int</tt> with an incorrect address 
in <em>int-address</em> is unsafe and could result 
in the system crashing or becoming unstable.
</p>

<p>
See also the <a href="#address">address</a>, 
<a href="#get-char">get-char</a>, 
<a href="#get-float">get-float</a>, 
<a href="#get-long">get-long</a>,
<a href="#get-string">get-string</a>,
<a href="#pack">pack</a>, 
and <a href="#unpack">unpack</a> functions.
</p>

<br/><br/>

<a name="get-long"></a>
<h2><span class="function">get-long</span>&nbsp;
<a href="#shared-lib"><font size="+2">&#x26A0;</font></a></h2>
<h4>syntax: (get-long <em>int-address</em>)</h4>

<p>
Gets a 64-bit integer from 
the address specified in <em>int-address</em>.
This function is handy when using <tt>import</tt>
to import shared library functions, 
a function returning an address pointer to a long integer, 
or a pointer to a structure containing long integers.
</p>

<!-- example -->

<pre>
long long int * foo(void)
{
int * result;
&hellip;
*result = 123;
return(result);
}

long long int foo-b(void)
{
int result;
&hellip;
result = 456;
return(result);
}
</pre>


<p>
Consider the C function <tt>foo</tt> (from a shared library), 
which returns an integer pointer (address of an integer).
</p>


<pre>
(import "mylib.so" "foo")
(get-int (foo))  <span class='arw'>&rarr;</span> 123
(foo-b)          <span class='arw'>&rarr;</span> 456
</pre>


<p>
Note that using <tt>get-long</tt> with an incorrect address 
in <em>int-address</em> is unsafe and could result 
in the system crashing or becoming unstable.
</p>

<p>
See also the <a href="#address">address</a>, 
<a href="#get-char">get-char</a>, 
<a href="#get-float">get-float</a>, 
<a href="#get-int">get-int</a>,
<a href="#get-string">get-string</a>,
<a href="#pack">pack</a>, 
and <a href="#unpack">unpack</a> functions.
</p>

<br/><br/>

<a name="get-string"></a>
<h2><span class="function">get-string</span>&nbsp;
<a href="#shared-lib"><font size="+2">&#x26A0;</font></a></h2>
<h4>syntax: (get-string <em>int-address</em> [<em>int-bytes</em> [<em>str-limit</em>])</h4>

<p>Copies a character string from the address specified in <em>int-address</em>.
This function is helpful when using imported shared library functions with 
<a href="#import">import</a> and a C-function returns the address to a memory buffer.</p>

<!-- example -->

<pre>
char * foo(void)
{
char * result;
result = "ABCDEFG";
return(result);
}
</pre>


<p>
Consider the above C function from a shared library, 
which returns a character pointer (address to a string).
</p>


<pre>
(import "mylib.so" "foo")
(print (get-string (foo)))  <span class='arw'>&rarr;</span> "ABCDEFG"
</pre>


<p>
When a string is passed as an argument, 
<tt>get-string</tt> will take its address as the argument. 
Without the optional <em>int-bytes</em> argument <tt>get-string</tt> breaks off 
at the first first <tt>\000</tt> (null character) it encounters. This works for
retrieving ASCII strings from raw memory addresses:</p>

<!-- example -->

<pre>
(set 'buff "ABC\000\000\000DEF")  <span class='arw'>&rarr;</span> "ABC\000\000\000DEF"

(length buff)  <span class='arw'>&rarr;</span> 9

(get-string buff)  <span class='arw'>&rarr;</span> "ABC"

(length (get-string buff))  <span class='arw'>&rarr;</span> 3

; get a string from offset into a buffer
(get-string (+ (address buff) 6)) <span class='arw'>&rarr;</span> "DEF"
</pre>

<p>When specifyung the number of bytes in the optional <em>int-bytes</em>
parameter, reading does not stpop at the first zero byte found, but
copies exactly <em>int-bytes</em> number of bytes from the address or string
buffer:</p>

<pre>
(set 'buff "ABC\000\000\000DEF")  <span class='arw'>&rarr;</span> "ABC\000\000\000DEF"

; without specifying the number of bytes
; buff is equivalent to (address buff)
(get-string buff)  <span class='arw'>&rarr;</span> "ABC"

; specifying the number of bytes to get
(get-string buff 9) <span class='arw'>&rarr;</span> "ABC\000\000\000DEF"
</pre>

<p>The addtional <em>str-limit</em> parameter can be used to limit reading
the buffer at a certain string. If <em>int-bytes</em> are read before
<em>str-limit</em> is found, only <em>int-bytes</em> are read:</p>

<pre>
(set 'buff "ABC\000\000EFG\000DQW") <span class='arw'>&rarr;</span> "ABC\000\000EFG\000DQW"

; buff is eqivalent to (address buff)
(get-string buff 4 "FG") <span class='arw'>&rarr;</span> "ABC\000"

(get-string buff 10) <span class='arw'>&rarr;</span> "ABC\000\000EFG\000D"

(get-string buff 10 "FG") <span class='arw'>&rarr;</span> "ABC\000\000E"
</pre>
 
<p>Although UTF-16 and UTF-32 encoding does not specify string termination characters,
the sequences "\000\000" and "\000\000\000\000" are used often to terminate UTF-16
and UTF-32 encodings. The additional optional  <em>str-limit</em> can be used to limit
the string when reading from the buffer address:</p>
<pre>
(set 'utf32 (unicode "我能吞下玻璃而不伤身体。"))

(set 'addr (address utf32)) <span class='arw'>&rarr;</span> 140592856255712

; get-string automatically takes the address when a buffer is passed
; utf32 is equivalent to (address utf32) for get-string

(get-string utf32 80 "\000\000\000\000")
<span class='arw'>&rarr;</span> "\017b\000\000??\000\000\030T\000\000\011N\ 000\000?s\
000\000?t\000\000\f?\000\000\rN\000\000$O\000\000??\000\000SO\000\000\0020\000\000"
</pre>

<p>When using  "\000\000" or "\000\000\000\000" as limit strings, the search for these
limits is aligned to a 2-byte or 4-byte border.</p>

<p>
See also the <a href="#get-char">get-char</a>, 
<a href="#get-int">get-int</a>,
<a href="#get-float">get-float</a>,
<a href="#pack">pack</a>,
and <a href="#unpack">unpack</a> functions.
</p>

<p>
Note that <tt>get-string</tt> can crash the system 
or make it unstable if the wrong address is specified.
</p>

<br/><br/>

<a name="get-url"></a>
<h2><span class="function">get-url</span></h2>
<h4>syntax: (get-url <em>str-url</em> [<em>str-option</em>] [<em>int-timeout</em> [<em>str-header</em>]])</h4>

<p>Reads a web page or file specified by the URL in <em>str-url</em> using 
the HTTP GET protocol.  Both <tt>http://</tt> and <tt>file://</tt>
URLs are handled.  <tt>"header"</tt> can be specified in the optional argument 
<em>str-option</em> to retrieve only the header.  The  option <tt>"list"</tt> 
causes header and page information to be returned as separate strings in a list
and also includes the server status code as the third list member (since 10.6.4).
The <tt>"raw"</tt> option (since 10.6.4), which can be used alone or combined
with other options, suppresses header location redirection.</p>

<p>A <tt>"debug"</tt> option can be specified either alone or after the
<tt>"header"</tt> or <tt>"list"</tt> option separated by one character, 
i.e. <tt>"header debug"</tt> or <tt>"list debug"</tt>. Including "debug" 
outputs all outgoing information to the console window.</p>

<p>The optional argument <em>int-timeout</em> can specify a value in milliseconds.
If no data is available from the host after the specified timeout, <tt>get-url</tt> 
returns the string <tt>ERR: timeout</tt>. When other error conditions occur, 
<tt>get-url</tt> returns a string starting with <tt>ERR:</tt> and the description 
of the error.</p>

<p><tt>get-url</tt> handles redirection if it detects a <tt>Location:</tt> spec 
in the received header and automatically does a second request.
<tt>get-url</tt> also understands the <tt>Transfer-Encoding: chunked</tt> 
format and will unpack data into an unchunked format.</p>

<p><tt>get-url</tt> requests are also understood by newLISP server nodes.
</p>

<!-- example -->

<pre>
(get-url "http://www.nuevatec.com")
(get-url "http://www.nuevatec.com" 3000)
(get-url "http://www.nuevatec.com" "header")
(get-url "http://www.nuevatec.com" "header" 5000)
(get-url "http://www.nuevatec.com" "list")

(get-url "file:///home/db/data.txt") ; access local file system

(env "HTTP_PROXY" "http://ourproxy:8080")
(get-url "http://www.nuevatec.com/newlisp/")
</pre>


<p>
The index page from the site specified 
in <em>str-url</em> is returned as a string.
In the third line, 
only the HTTP header 
is returned in a string. 
Lines 2 and 4 show a 
timeout value being used.
</p>

<p> The second example shows usage of a <tt>file://</tt> URL
to access <tt>/home/db/data.txt</tt> on the local file system.</p>

<p>
The third example illustrates 
the use of a proxy server. 
The proxy server's URL must be 
in the operating system's environment. 
As shown in the example, 
this can be added using 
the <a href="#env">env</a> 
function.
</p>

<p>
The <em>int-timeout</em> can be followed 
by an optional custom header in <em>str-header</em>:
</p>

<h3>Custom header</h3>

<p>The custom header may contain options 
for browser cookies or other directives to the server. 
When no <em>str-header</em> is specified, 
newLISP sends certain header information by default. 
After the following request:
</p>


<pre>
(get-url "http://somehost.com" 5000)
</pre>


<p>
newLISP will configure and send 
the request and header below:
</p>


<pre>
GET / HTTP/1.1        
Host: somehost.com
User-Agent: newLISP v10603
Connection: close
</pre>


<p>
As an alternative, the <em>str-header</em> 
option could be used:
</p>


<pre>
(get-url "http://somehost.com" 5000 
"User-Agent: Mozilla/4.0\r\nCookie: name=fred\r\n")
</pre>


<p>
newLISP will now send the 
following request and header:
</p>


<pre>
GET / HTTP/1.1        
Host: somehost.com
User-Agent: Mozilla/4.o
Cookie: name=fred
Connection: close
</pre>


<p>
Note that when using a custom header, 
newLISP will only supply the <tt>GET</tt> request line, 
as well as the <tt>Host:</tt> and <tt>Connection:</tt> header entries. 
newLISP inserts all other entries supplied in the custom header 
between the <tt>Host:</tt> and <tt>Connection:</tt> entries. 
Each entry must end with a carriage return 
line-feed pair: <tt>\r\n</tt>.

</p>

<p>
See an HTTP transactions reference 
for valid header entries.
</p>

<p>
Custom headers can also be used 
in the <a href="#put-url">put-url</a> 
and <a href="#post-url">post-url</a> functions.
</p>

<br/><br/>

<a name="global"></a>
<h2><span class="function">global</span></h2>

<h4>syntax: (global <em>sym-1</em> [<em>sym-2</em> ... ])</h4>

<p>
One or more symbols in <em>sym-1</em> [<em>sym-2</em> ... ] 
can be made globally accessible from contexts other than MAIN. 
The statement has to be executed in the MAIN context, 
and only symbols belonging to MAIN can be made global. 
<tt>global</tt> returns the last symbol made global.
</p>

<!-- example -->

<pre>
(global 'aVar 'x 'y 'z)  <span class='arw'>&rarr;</span> z

(define (foo x) 
(&hellip;))

(constant (global 'foo))
</pre>


<p>
The second example shows how <a href="#constant">constant</a> 
and <tt>global</tt> can be combined into one statement, 
protecting and making a previous function definition global.
</p>

<br/><br/>

<a name="globalp"></a>
<h2><span class="function">global?</span></h2>

<h4>syntax: (global? <em>sym</em>)</h4>

<p>Checks if symbol in <em>sym</em> is global. Built-in functions, context
symbols, and all symbols made global using the function <a href="#global">global</a>
are global:</p>

<!-- example -->

<pre>
global? 'print)   <span class='arw'>&rarr;</span> true
(global 'var)     <span class='arw'>&rarr;</span> var
(global? 'var)    <span class='arw'>&rarr;</span> true

(constant (global 'foo))

(global? 'foo)    <span class='arw'>&rarr;</span> true
</pre>

<br/><br/>

<a name="history"></a>
<h2><span class="function">history</span></h2>

<h4>syntax: (history [<em>bool-params</em>])</h4>

<p><em>history</em> returns a list of the call history of the enclosing function.
Without the optional <em>bool-params</em>, a list of function symbols is returned.
The first symbol is the name of the enclosing function. When the optional 
<em>bool-params</em> evaluates to <em>true</em>, the call arguments are included 
with the symbol.</p>
<br/><br/>

<pre>
(define (foo x y) 
    (bar (+ x 1) (* y 2)))

(define (bar a b) 
    (history))

; history returns names of calling functions
(foo 1 2) <span class='arw'>&rarr;</span> (bar foo)

; the addtional 'true' forces inclusion of callpatterns
(define (bar a b) 
    (history true))

(foo 1 2) <span class='arw'>&rarr;</span> ((bar (+ x 1) (* y 2)) (foo 1 2))
</pre>

<br/><br/>

<a name="if"></a>
<h2><span class="function">if</span></h2>

<h4>syntax: (if <em>exp-condition</em> <em>exp-1</em> [<em>exp-2</em>])<br/>

syntax: (if <em>exp-cond-1</em> <em>exp-1</em>  <em>exp-cond-2</em> <em>exp-2</em> [ ... ])</h4>

<p>If the value of <em>exp-condition</em> is neither <tt>nil</tt> nor an empty list, 
the result of evaluating <em>exp-1</em> is returned; otherwise, the value of 
<em>exp-2</em> is returned.  If <em>exp-2</em> is absent, the value of 
<em>exp-condition</em> is returned.</p>

<p><tt>if</tt> also sets the anaphoric system variable <tt>$it</tt> to the value
of the conditional expression in <tt>if</tt>.</p>

<!-- example -->

<pre>
(set 'x 50)                   <span class='arw'>&rarr;</span> 50
(if (&lt; x 100) "small" "big")  <span class='arw'>&rarr;</span> "small"
(set 'x 1000)                 <span class='arw'>&rarr;</span> 1000
(if (&lt; x 100) "small" "big")  <span class='arw'>&rarr;</span> "big"
(if (&gt; x 2000) "big")         <span class='arw'>&rarr;</span> nil

; more than one statement in the true or false
; part must be blocked with (begin ...)
(if (= x y)
  (begin
    (some-func x)
    (some-func y))
  (begin
    (do-this x y)
    (do-that x y))
)

; if also sets the anaphoric system variable $it
(set 'lst '(A B C))
(if lst (println (last $it)))  <span class='arw'>&rarr;</span> C
</pre>


<p>
The second form of <tt>if</tt> works similarly 
to <a href="#cond">cond</a>, except it does not take 
parentheses around the condition-body pair of expressions. 
In this form, <tt>if</tt> can have 
an unlimited number of arguments.
</p>

<!-- example -->

<pre>
(define (classify x)
(if
(&lt; x 0) "negative"
(&lt; x 10) "small"
(&lt; x 20) "medium"
(&gt;= x 30) "big"
"n/a"))

(classify 15)   <span class='arw'>&rarr;</span> "medium"
(classify 100)  <span class='arw'>&rarr;</span> "big"
(classify 22)   <span class='arw'>&rarr;</span> "n/a"
(classify -10)  <span class='arw'>&rarr;</span> "negative"
</pre>


<p>The last expression, <tt>"n/a"</tt>, is optional. When this option 
is omitted, the evaluation of <tt>(&gt;= x 30)</tt> is returned, behaving 
exactly like a traditional <a href="#cond">cond</a> but without requiring 
parentheses around the condition-expression pairs.</p>

<p> In any case, the whole <tt>if</tt> expression 
always returns the last expression or condition evaluated.</p>

<p>
See also the <a href="#when">when</a> and <a href="#unless">unless</a> functions.
</p>

<br/><br/>

<!--
<a name="if-not"></a>
<h2><span class="function">if-not</span></h2>
<h4>syntax: (if-not <em>exp-condition</em> <em>exp-1</em> [<em>exp-2</em>])</h4>

<p>
<tt>if-not</tt> is equivalent to (<a href="#if">if</a> (<a href="#not">not</a> 
<em>exp-condition</em> <em>exp-1</em> [<em>exp-2</em>])).
If the value of <em>exp-condition</em> is <tt>nil</tt> 
or the empty list <tt>()</tt>, <em>exp-1</em> is evaluated;
otherwise, the optional <em>exp-2</em> is evaluated.
</p>	

<p>Contrary to the <a href="#if">if</a> function, <tt>if-not</tt> does
not permit multiple consequent and alternative clauses.</p>

<pre>
(set 'x 50)                       <span class='arw'>&rarr;</span> 50 
(if-not (&lt; x 100) "big" "small")  <span class='arw'>&rarr;</span> "small"
(set 'x 1000)                     <span class='arw'>&rarr;</span> 1000 
(if-not (&lt; x 100) "big" "small")  <span class='arw'>&rarr;</span> "big" 
</pre>

<br/><br/>
-->

<a name="ifft"></a>
<h2><span class="function">ifft</span></h2>
<h4>syntax: (ifft <em>list-num</em>)</h4>

<p>
Calculates the inverse discrete Fourier transform 
on a list of complex numbers in <em>list-num</em> 
using the FFT method (Fast Fourier Transform). 
Each complex number is specified by its real part, 
followed by its imaginary part. 
In case only real numbers are used, 
the imaginary part is set to <tt>0.0</tt> (zero). 
When the number of elements in <em>list-num</em> 
is not an integer power of 2, 
<tt>ifft</tt> increases the number of elements 
by padding the list with zeroes. 
When complex numbers are <tt>0</tt> in the imaginary part, 
simple numbers can be used.
</p>

<!-- example -->

<pre>
(ifft (fft '((1 0) (2 0) (3 0) (4 0)))) 
<span class='arw'>&rarr;</span> ((1 0) (2 0) (3 0) (4 0))

;; when imaginary part is 0, plain numbers work too

(ifft (fft '(1 2 3 4))) 
<span class='arw'>&rarr;</span> ((1 0) (2 0) (3 0) (4 0))
</pre>


<p>
The inverse operation of <tt>ifft</tt> 
is the <a href="#fft">fft</a> function.
</p>

<br/><br/>

<a name="import"></a>
<h2><span class="function">import</span>&nbsp;
<a href="#shared-lib"><font size="+2">&#x26A0;</font></a></h2>
<h4>syntax: (import <em>str-lib-name</em> <em>str-function-name</em> ["cdecl"])<br/>
syntax: (import <em>str-lib-name</em> <em>str-function-name</em> <em>str-return-type</em> [<em>str-param-type</em> . . .])<br/>
syntax: (import <em>str-lib-name</em>)</h4>

<p>Imports the function specified in <em>str-function-name</em> 
from a shared library named in <em>str-lib-name</em>. Depending on the syntax used, string 
labels for return and parameter types can be specified</p>

<p>If the library in <em>str-lib-name</em> is not in the system's library path, the
full path name should be specified.</p>

<p>A function can be imported only once. A repeated import of the same function
will simply return the same - already allocated - function address.</p>

<p>Note, that the first simple syntax is available on <u>all</u> versions of newLISP, even those compiled without <em>libffi</em> support. On <em>libffi</em> enabled versions - capable of the second extended syntax -
imported symbols are protected against change and can only be modified using
<a href="#constant">constant</a>.</p>

<p>The third syntax - on OSX, Linux and other Unix only -  allows pre-loading libraries 
without importing functions. This is necessary when other library imports need access 
internally to other functions from pre-loaded libraries.</p>

<p>Incorrectly using <tt>import</tt> can cause a system bus error or a segfault can occur 
and crash newLISP or leave it in an unstable state.</p>

<h3>The simple <tt>import</tt> syntax</h3>
<p>Most library functions can be imported using the simpler first syntax. 
This form is present on <u>all</u> compile flavors of newLISP. The API expects
all function arguments to be passed on the stack in either <em>cdecl</em> or <em>stdcall</em> 
conventions. On 32-bit platforms, integers, pointers to strings and buffers sometimes floating 
point values can be passed as parameters. On 64-bit platforms only 
integers  can be passed but no floating point values. 
As return values only 32-bit or 64-bit values and pointers are allowed. 
No floating point numbers can be returned. Strings must be retrieved with the
<a href="#get-string">get-string</a> helper function. Regardless of these 
limitations, most  modules included in the distribution use 
this simple import API.</p>

<p>If pointers are returned to strings or structures the following helper functions
can be used extract data:
<a href="#get-char">get-char</a>, 
<a href="#get-int">get-int</a>, 
<a href="#get-float">get-float</a>, 
<a href="#get-string">get-string</a>, 
<a href="#unpack">unpack</a> </p>

<p>To pass pointers for data structures the following functions help to pack data
and calculate addresses:
<a href="#address">address</a>, 
<a href="#pack">pack</a>.</p>

<p>To transform newLISP data types into the data types needed by the 
imported function, use the functions 
<a href="#float">float</a> for 64-bit double floats, 
<a href="#flt">flt</a> for 32-bit floats, 
and <a href="#int">int</a> for 32-bit integers. 
By default, newLISP passes floating point numbers as 64-bit double floats, 
integers as 32-bit integers, and strings as 32-bit integers for string 
addresses (pointers in C). Floats can only be used with 32-bit versions
of newLISP and libraries. To use floating point numbers in a 64-bit
environment use the <a href="#extended_import">extended <tt>import</tt> syntax</a>. 
</p>

<!-- example -->

<pre>
;; define LIBC platform independent

(define LIBC (lookup ostype '(
("Windows" "msvcrt.dll")
("OSX" "libc.dylib")

(import LIBC "printf")
(printf "%g %s %d %c\n" 1.23 "hello" 999 65)
<b>1.23 hello 999 A</b>
<span class='arw'>&rarr;</span> 17 ; return value

;; import MS Windows DLLs in 32-bit versions 

(import "kernel32.dll" "GetTickCount")  <span class='arw'>&rarr;</span> GetTickCount
(import "user32.dll" "MessageBoxA")     <span class='arw'>&rarr;</span> MessageBoxA
(GetTickCount)                          <span class='arw'>&rarr;</span> 3328896
</pre>

<p>In the first example, the string "1.23 hello 999 A" 
is printed as a side effect, and the value 17 (number of 
characters printed) is returned. Any C function can be imported 
from any shared library in this way.
</p>

<p>The message box example pops up a Windows dialog box, which may be hidden 
behind the console window.  The console prompt does not return until the 
'OK' button is pressed in the message box.</p>

<pre>
;;this pops up a message box

(MessageBoxA 0 "This is the body" "Caption" 1) 
</pre>

<p>The other examples show several imports of MS Windows DLL functions and 
the details of passing values <em>by value</em> or <em>by reference</em>. 
Whenever strings or numbers are passed by reference, space must be 
reserved beforehand.</p>


<pre>
(import "kernel32.dll" "GetWindowsDirectoryA")

;; allocating space for a string return value
(set 'str (dup "\000" 64))  ; reserve space and initialize

(GetWindowsDirectoryA str (length str))

str  <span class='arw'>&rarr;</span> "C:\\WINDOWS\000\000\000 ... "

;; use trim or get-string to cut of trailing binary zeros
(get-string str)  <span class='arw'>&rarr;</span> "C:\\WINDOWS"
(trim str)        <span class='arw'>&rarr;</span> "C:\\WINDOWS"

(import "kernel32.dll" "GetComputerNameA")

;; allocate memory and initialize to zeros
(set 'str (dup "\000" 64))
(set 'len (length str)

;; call the function
;; the length of the string is passed as address reference 
;; string str is automatically past by address (C pointer)
(GetComputerNameA str (address len)) 

str  <span class='arw'>&rarr;</span> "LUTZ-PC\000\000 ... "

(trim str)  <span class='arw'>&rarr;</span> "LUTZ-PC"
</pre>

<p><tt>import</tt> returns the address of the function, which can be 
used to assign a different name to the imported function.</p>

<pre>
(set 'imprime (import "libc.so.6" "printf")) 
<span class='arw'>&rarr;</span> printf@400862A0

(imprime "%s %d" "hola" 123)                 
<span class='arw'>&rarr;</span> "hola 123"
</pre>

<p>The MS Windows and Cygwin versions of newLISP uses standard call <em>stdcall</em> conventions 
to call DLL library routines by default.  This is necessary for calling DLLs that belong 
to the MS Windows operating system.  Most third-party DLLs are compiled for 
C declaration <em>cdecl</em> calling conventions and may need to specify the string 
<tt>"cdecl"</tt> as an additional last argument when importing functions. 
newLISP compiled for macOS, Linux and other Unix systems uses the 
<em>cdecl</em> calling conventions by default and ignores any additional string.</p>

<pre>
;; force cdecl calling conventions on MS Windows
(import "sqlite.dll" "sqlite_open" "cdecl")  <span class='arw'>&rarr;</span> sqlite_open &lt;673D4888&gt;
</pre>

<p>Imported functions may take up to fourteen arguments. Note that 
floating point arguments take up two spaces each
(e.g., passing five floats takes up ten of the fourteen parameters).
</p>

<a name="extended_syntax"></a>
<a name="extended_import"></a>
<h3>The extended <tt>import</tt> syntax</h3>

<p>The extended import API works with the second syntax. It is based on the popular 
<tt>libffi</tt> library which is pre-installed on most OS platforms. The startup banner
of newLISP should show the word <tt>libffi</tt> indicating the running version
of newLISP is compiled to use the extended <tt>import</tt> API. The function
<a href="#sys-info">sys-info</a> can also be used to check for <tt>libffi</tt>-support.</p>

<p>The API works with all atomic C data types for passed parameters and return values. 
The extended API requires that parameter types are specified in the <tt>import</tt> 
statement as string type labels. Programs written with extended import API will run 
without change on 32-bit and 64-bit newLISP and libraries. Integers, floating point 
values and strings can be returned without using helper functions.</p>

<p>The following types can be specified for the return value in <em>str-return-type</em>
and for function parameters in <em>str-param-type</em>:</p>

<table summary="data types">
<tr align="left"><th>label</th><th>C type for return value and arguments</th><th>newLISP return and argument type</th></tr>
<tr><td>"void"</td><td>void</td><td><tt>nil</tt> is returned for return type</td></tr>
<tr><td>"byte"</td><td>byte unsigned 8 bit</td><td>integer</td></tr>
<tr><td>"char"</td><td>char signed 8 bit</td><td>integer</td></tr>
<tr><td>"unsigned short int"</td><td>unsigned short int 16 bit</td><td>integer</td></tr>
<tr><td>"short int"</td><td>short int signed 16 bit</td><td>integer</td></tr>
<tr><td>"unsigned int"</td><td>unsigned int 32 bit</td><td>integer</td></tr>
<tr><td>"int"</td><td>int signed 32 bit</td><td>integer</td></tr>
<tr><td>"long"</td><td>long signed 32 or 64 bit depending on platform</td><td>integer</td></tr>
<tr><td>"long long"</td><td>long long signed 64 bit</td><td>integer</td></tr>
<tr><td>"float"</td><td>float 32 bit</td><td>IEEE-754 64 bit float cut to 32-bit precision</td></tr>
<tr><td>"double"</td><td>double 64 bit</td><td>IEEE-754 64 bit float</td></tr>
<tr><td>"char*"</td><td>char* 32 or 64 bit ptr depending on platform</td><td>displayable string return (zero terminated)<br/>string buffer arg (no addr. since 10.4.2)</td></tr>
<tr><td>"void*"</td><td>void* 32 or 64 bit ptr depending on platform</td><td>integer address return<br/>either string buffer or integer address arg</td></tr>
</table>

<p>The types <tt>"char*"</tt> and <tt>"void*</tt> can be interchanged and are treated 
identical inside <tt>libffi</tt>. Depending on the type of arguments passed and the type
of return values, one or the other is used.</p>

<p>Aggregate types can be composed using the <a href="#struct">struct</a> function and 
can be used for arguments and return values.</p>

<p>The following examples show how the extended <tt>import</tt> syntax can
handle return values of floating point values and strings:</p>

<pre>
;; return a float value, LIBC was defined earlier
;             name   return   arg
(import LIBC "atof" "double" "char*")
(atof "3.141") <span class='arw'>&rarr;</span> 3.141

;; return a copied string
;             name     return  arg-1   arg-2
(import LIBC "strcpy" "char*" "char*" "char*")
(set 'from "Hello World")

(set 'to (dup "\000" (length from))) ; reserve memory
(strcpy to from) <span class='arw'>&rarr;</span> "Hello World"
</pre>

<p>The <tt>char*</tt> type takes a string buffer only. The <tt>"void*</tt> type can take either
a string buffer or a memory address number as input. When using <tt>"void*"</tt>
as a return type the address number of the result buffer will be returned. This is
useful when returning pointers to data structures. These pointers can then
be used with <a href="#unpack">unpack</a> and <a href="#struct">struct</a> for destructuring. 
In the following example the return type is changed to <tt>void*</tt>:</p>

<pre>
(import LIBC "strcpy" "void*" "char*" "char*")
(set 'from "Hello World")
(set 'to (dup "\000" (length from)))

(strcpy to from)       <span class='arw'>&rarr;</span> 2449424
(address to)           <span class='arw'>&rarr;</span> 2449424
(unpack "s11" 2449424) <span class='arw'>&rarr;</span> "Hello World"
(get-string 2449424)   <span class='arw'>&rarr;</span> "Hello World"
to                     <span class='arw'>&rarr;</span> "Hello World"
</pre>

<p>A newLISP string is always passed by it's address reference.</p>


<p>For a more complex example see this
<a href="http://www.newlisp.org/syntax.cgi?code/opengl-demo-ffi-lsp.txt">OpenGL demo</a>.</p>

<h3>Memory management</h3>

<p>Any allocation performed by imported foreign functions has to be 
de-allocated manually if there's no call in the imported API to do so.
See the <a href="http://www.newlisp.org/CodePatterns.html">Code Patterns in newLISP</a>
document for an example.</p>

<p>In case of calling foreign functions with passing by reference, 
memory for variables needs to be allocated beforehand by newLISP
&mdash; see import of <tt>GetWindowsDirectoryA</tt> above &mdash; 
and hence, memory needs not be deallocated manually, because it is
managed automatically by newLISP.</p>

<br/><br/>

<a name="inc"></a>
<h2><span class="function">inc</span>&nbsp;<a href="#destructive">!</a></h2>
<h4>syntax: (inc <em>place</em> [<em>num</em>])</h4>

<p>
Increments the number in <em>place</em> by <tt>1.0</tt> or by the optional 
number <em>num</em> and returns the result. <tt>inc</tt> performs float 
arithmetic and converts integer numbers passed into floating point type.</p>

<p><em>place</em> is either a symbol or a place in a list structure holding a
number, or a number returned by an expression.</p>

<!-- example -->

<pre>
(set 'x 0)    <span class='arw'>&rarr;</span> 0
(inc x)       <span class='arw'>&rarr;</span> 1
x             <span class='arw'>&rarr;</span> 1
(inc x 0.25)  <span class='arw'>&rarr;</span> 1.25
x             <span class='arw'>&rarr;</span> 1.25
(inc x)       <span class='arw'>&rarr;</span> 2.25
</pre>


<p>If a symbol  for <em>place</em> contains <tt>nil</tt>, it is treated
as if containing  <tt>0.0</tt>:</p>


<pre>
z             <span class='arw'>&rarr;</span> nil
(inc z)       <span class='arw'>&rarr;</span> 1

(set 'z nil)
(inc z 0.01)  <span class='arw'>&rarr;</span> 0.01
</pre>


<p>Places in a list structure or a number returned by another expression
can be updated too:</p>


<pre>
(set 'l '(1 2 3 4))

(inc (l 3) 0.1) <span class='arw'>&rarr;</span> 4.1

(inc (first l)) <span class='arw'>&rarr;</span> 2

l <span class='arw'>&rarr;</span> (2 2 3 4.1)

(inc (+ 3 4)) <span class='arw'>&rarr;</span> 8
</pre>


<p>Use the <a href="#inci">++</a> function for incrementing numbers in
integer mode. Use <a href="#dec">dec</a> to decrement numbers in floating point mode.</p>


<br/><br/>

<a name="index"></a>
<h2><span class="function">index</span></h2>
<h4>syntax: (index <em>exp-predicate</em> <em>exp-list</em>)</h4>

<p>Applies the predicate <em>exp-predicate</em> to each element of the 
list <em>exp-list</em> and returns a list containing the indices of the elements 
for which <em>exp-predicate</em> is true.</p>

<!-- example -->

<pre>
(index symbol? '(1 2 d 4 f g 5 h))  <span class='arw'>&rarr;</span> (2 4 5 7)

(define (big? x) (&gt; x 5))  <span class='arw'>&rarr;</span> (lambda (x) (&gt; x 5))

(index big? '(1 10 3 6 4 5 11))  <span class='arw'>&rarr;</span> (1 3 6)

(select '(1 10 3 6 4 5 11) '(1 3 6)) <span class='arw'>&rarr;</span> (10 6 11) 
</pre>


<p>
The predicate may be a built-in predicate, 
a user-defined function, or a lambda expression.
</p>

<p>
Use the <a href="#filter">filter</a> function 
to return the elements themselves.
</p>

<br/><br/>

<a name="infp"></a>
<h2><span class="function">inf?</span></h2>
<h4>syntax: (inf? <em>float</em>)</h4>

<p>If the value in <em>float</em> is infinite the function returns
<tt>true</tt> else <tt>nil</tt>.</p>

<!-- example -->

<pre>
(inf? (div 1 0)) <span class='arw'>&rarr;</span> true

(div 0 0) <span class='arw'>&rarr;</span> NaN
</pre>


<p>Note that an integer division by zero e.g. <tt>(/ 1 0)</tt> will
throw an "division by zero" error and not yield infinity. See also
<a href="#NaNp">NaN?</a> to check if a floating point number is valid.</p>

<br/><br/>

<a name="int"></a>
<h2><span class="function">int</span></h2>

<h4>syntax: (int <em>exp</em> [<em>exp-default</em> [<em>int-base</em>]])</h4>

<p>
If the expression in <em>exp</em> evaluates to a number or a string, the result 
is converted to an integer and returned.  If <em>exp</em> cannot be converted 
to an integer, then <tt>nil</tt> or the evaluation of <em>exp-default</em> will 
be returned.  This function is mostly used when translating strings from user 
input or from parsing text. If <em>exp</em> evaluates to a string, the string 
must start with a digit; one or more spaces; or the <tt>+</tt> or <tt>-</tt> sign.
The string must begin with '<tt>0x</tt>' for hexadecimal strings or '<tt>0</tt>' 
(zero) for octal strings.  If <em>exp</em> is invalid, <tt>int</tt> returns 
<tt>nil</tt> as a default value if not otherwise specified.
</p>

<p>A second optional parameter can be used to force the number base 
of conversion to a specific value.</p>

<p>Integers larger than 9,223,372,036,854,775,807 are truncated to 
9,223,372,036,854,775,807.  Integers smaller than -9,223,372,036,854,775,808 
are truncated to -9,223,372,036,854,775,808.</p>

<p>When converting from a float (as in the second form of <tt>int</tt>), 
floating point values larger or smaller than the integer maximum or minimum 
are also truncated. A floating point expression evaluating to <tt>NaN</tt> 
is converted to <tt>0</tt> (zero).</p>


<!-- example -->

<pre>
(int "123")          <span class='arw'>&rarr;</span> 123
(int " 123")         <span class='arw'>&rarr;</span> 123
(int "a123" 0)       <span class='arw'>&rarr;</span> 0
(int (trim " 123"))  <span class='arw'>&rarr;</span> 123
(int "0xFF")         <span class='arw'>&rarr;</span> 255
(int "0b11111")      <span class='arw'>&rarr;</span> 31
(int "055")          <span class='arw'>&rarr;</span> 45
(int "1.567")        <span class='arw'>&rarr;</span> 1
(int 1.567)          <span class='arw'>&rarr;</span> 1

(integer? 1.00)        <span class='arw'>&rarr;</span> nil
(integer? (int 1.00))  <span class='arw'>&rarr;</span> true

(int "1111" 0 2)  <span class='arw'>&rarr;</span> 15   ; base 2 conversion
(int "0FF" 0 16)  <span class='arw'>&rarr;</span> 255  ; base 16 conversion

(int 'xyz)     <span class='arw'>&rarr;</span> nil
(int 'xyz 0)   <span class='arw'>&rarr;</span> 0
(int nil 123)  <span class='arw'>&rarr;</span> 123

(int "abc" (throw-error "not a number"))  
<span class='arw'>&rarr;</span> <span class='err'>ERR: user error : not a number</span>

(print "Enter a num:")
(set 'num (int (read-line)))

(int (bits 12345) 0 2) <span class='arw'>&rarr;</span> 12345
</pre>


<p>The inverse function to <tt>int</tt> with base <tt>2</tt> is
<a href="#bits">bits</a>.</p>

<p>Use the <a href="#float">float</a> function 
to convert arguments to floating point numbers.</p>

<br/><br/>

<a name="integerp"></a>
<h2><span class="function">integer?</span></h2>
<h4>syntax: (integer? <em>exp</em>)</h4>

<p>
Returns <tt>true</tt> only if the value 
of <em>exp</em> is an integer; 
otherwise, it returns <tt>nil</tt>.
</p>

<!-- example -->

<pre>
(set 'num 123)  <span class='arw'>&rarr;</span> 123
(integer? num)  <span class='arw'>&rarr;</span> true
</pre>

<br/><br/>

<a name="intersect"></a>
<h2><span class="function">intersect</span></h2>
<h4>syntax: (intersect <em>list-A</em> <em>list-B</em>)<br/>

syntax: (intersect <em>list-A</em> <em>list-B</em> <em>bool</em>)</h4>

<p>
In the first syntax, 
<tt>intersect</tt> returns a list 
containing one copy of each element 
found both in <em>list-A</em> and <em>list-B</em>.
</p>

<!-- example -->

<pre>
(intersect '(3 0 1 3 2 3 4 2 1) '(1 4 2 5))  
<span class='arw'>&rarr;</span> (2 4 1)
</pre>


<p>
In the second syntax, 
<tt>intersect</tt> returns a list of all elements 
in <em>list-A</em> that are also in <em>list-B</em>, 
without eliminating duplicates in <em>list-A</em>. 
<em>bool</em> is an expression evaluating to <tt>true</tt> 
or any other value not <tt>nil</tt>.
</p>

<!-- example -->

<pre>
(intersect '(3 0 1 3 2 3 4 2 1) '(1 4 2 5) true)
<span class='arw'>&rarr;</span> (1 2 4 2 1)
</pre>


<p>
See also the set functions 
<a href="#difference">difference</a>, <a href="#unique">unique</a>
and <a href="#union">union</a>.
</p>

<br/><br/>

<a name="invert"></a>
<h2><span class="function">invert</span></h2>
<h4>syntax: (invert <em>matrix</em> [<em>float-pivot</em>])</h4>

<p>Returns the inversion of a two-dimensional matrix in <em>matrix</em>. 
The matrix must be square, with the same number 
of rows and columns, and <em>non-singular</em> (invertible). 
Matrix inversion can be used to solve systems of linear equations 
(e.g., multiple regression in statistics).  newLISP uses LU-decomposition of 
the matrix to find the inverse.</p>

<p>Optionally <tt>0.0</tt> or a very small value can be specified
in <em>float-pivot</em>. This value substitutes pivot elements in
the LU-decomposition algorithm, which result in zero when
the algorithm deals with a singular matrix.</p>

<p>The dimensions of a matrix are defined by the number of rows 
times the number of elements in the first row.  For missing elements 
in non-rectangular matrices, <tt>0.0</tt> (zero) is assumed.  
A matrix can either be a nested list or an <a href="#array">array</a>.
</p> 

<!-- example -->

<pre>
(set 'A '((-1 1 1) (1 4 -5) (1 -2 0)))
(invert A)  <span class='arw'>&rarr;</span> ((10 2 9) (5 1 4) (6 1 5))
(invert (invert A)) <span class='arw'>&rarr;</span> ((-1 1 1) (1 4 -5) (1 -2 0))

; solve Ax = b for x
(multiply (invert A) '((1) (2) (3))) <span class='arw'>&rarr;</span> ((41) (19) (23))

; treatment of singular matrices
(invert '((2 -1) (4 -2)))        <span class='arw'>&rarr;</span> nil
(invert '((2 -1) (4 -2)) 0.0)    <span class='arw'>&rarr;</span> ((inf -inf) (inf -inf))
(invert '((2 -1) (4 -2)) 1e-20)  <span class='arw'>&rarr;</span> ((5e+19 -2.5e+19) (1e+20 -5e+19)) 
</pre>

<p><tt>invert</tt> will return <tt>nil</tt> if the matrix is <i>singular</i> 
and cannot be inverted, and <em>float-pivot</em> is not specified. </p>


<p>
All operations shown here on lists 
can be performed on arrays, as well.
</p>

<p>
See also the matrix functions <a href="#det">det</a>,
<a href="#mat">mat</a>, <a href="#multiply">multiply</a>
and <a href="#transpose">transpose</a>.
</p>

<br/><br/>

<a name="irr"></a>
<h2><span class="function">irr</span></h2>
<h4>syntax: (irr <em>list-amounts</em> [<em>list-times</em> [<em>num-guess</em>]])</h4>

<p>
Calculates the internal rate of return 
of a cash flow per time period. 
The internal rate of return is the interest rate 
that makes the present value of a cash flow equal to <tt>0.0</tt> (zero). 
In-flowing (negative values) and out-flowing (positive values) 
amounts are specified in  <em>list-amounts</em>. 
If no time periods are specified in <em>list-times</em>, 
amounts in <em>list-amounts</em> correspond to 
consecutive time periods increasing by 1 (1, 2, 3&mdash;). 
The algorithm used is iterative, 
with an initial guess of 0.5 (50 percent). 
Optionally, a different 
initial guess can be specified. 
The algorithm returns when a precision 
of 0.000001 (0.0001 percent) is reached. 
<tt>nil</tt> is returned if the algorithm 
cannot converge after 50 iterations.
</p>

<p>
<em>irr</em> is often used to decide 
between different types of investments.
</p>

<!-- example -->

<pre>
(irr '(-1000 500 400 300 200 100))  
<span class='arw'>&rarr;</span> 0.2027

(npv 0.2027 '(500 400 300 200 100)) 
<span class='arw'>&rarr;</span> 1000.033848 ; ~ 1000

(irr '(-1000 500 400 300 200 100) '(0 3 4 5 6 7)) 
<span class='arw'>&rarr;</span> 0.0998

(irr '(-5000 -2000 5000 6000) '(0 3 12 18)) 
<span class='arw'>&rarr;</span> 0.0321
</pre>


<p>
If an initial investment of 1,000 
yields 500 after the first year, 
400 after two years, and so on, 
finally reaching <tt>0.0</tt> (zero) after five years, 
then that corresponds to a yearly return 
of about 20.2 percent. 
The next line demonstrates the relation 
between <tt>irr</tt> and <a href="#npv">npv</a>. 
Only 9.9 percent returns are necessary when making 
the first withdrawal after three years.
</p>

<p>
In the last example, securities 
were initially purchased for 5,000, 
then for another 2,000 three months later. 
After a year, securities for 5,000 are sold. 
Selling the remaining securities 
after 18 months renders 6,000. 
The internal rate of return is 3.2 percent per month, 
or about 57 percent in 18 months.
</p>

<p>
See also the <a href="#fv">fv</a>, 
<a href="#nper">nper</a>, 
<a href="#npv">npv</a>, 
<a href="#pmt">pmt</a>, 
and <a href="#pv">pv</a> functions.
</p> 

<br/><br/>

<a name="json-error"></a>
<h2><span class="function">json-error</span></h2>
<h4>syntax: (json-error)</h4>

<p>When <a href="#json-parse">json-parse</a> returns <tt>nil</tt> due
to a failed JSON data translation, this function retrieves an error
description and the last scan position of the parser.</p>

<pre>
; failed parse returns nil
(json-parse [text]{"address" "http://example.com"}[/text]) <span class='arw'>&rarr;</span> nil

; inspect the error information
(json-error) <span class='arw'>&rarr;</span> ("missing : colon" 11)
</pre>

<br/><br/>

<a name="json-parse"></a>
<h2><span class="function">json-parse</span></h2>
<h4>syntax: (json-parse <em>str-json-data</em>)</h4>

<p>This function parses JSON formatted text and translates it to newLISP S-expressions.
All data types conforming to the ECMA-262 standard are translated. The JSON values 
<tt>false</tt> and <tt>null</tt> will be represented by the symbols <tt>false</tt> 
and <tt>null</tt> in the symbolic newLISP expressions. Arrays in JSON will be represented 
by lists in newLISP. The resulting lists from JSON object data can be processed using 
<a href="#assoc">assoc</a>, <a href="#lookup">lookup</a> and <a href="#ref">ref</a>.</p>

<p>For JSON attribute values not recognized or wrong JSON syntax, <tt>json-parse</tt> 
returns <tt>nil</tt> and <a href="#json-error">json-error</a> can be used to retrieve
the error text.</p>

<p>The following example shows a nested JSON object from a file <tt>person.json</tt>:</p>

<!-- example -->

<pre>
{
"name": "John Smith",
"age": 32,
"employed": true,
"address": {
"street": "701 First Ave.",
"city": "Sunnyvale, CA 95125",
"country": "United States"
},
"children": [
{
    "name": "Richard",
    "age": 7
},
{
    "name": "Susan",
    "age": 4
},
{
    "name": "James",
    "age": 3
}
]
}
</pre>
<p>The file is read, parsed and the resulting S-expression stored in <tt>jsp</tt>:</p>

<pre>
(set 'jsp (json-parse (read-file "person.json")))
<span class='arw'>&rarr;</span>
( ("name" "John Smith") 
("age" 32) 
("employed" true) 
("address" ( ("street" "701 First Ave.") 
       ("city" "Sunnyvale, CA 95125") 
       ("country" "United States")) ) 
("children" (
(("name" "Richard") ("age" 7)) 
(("name" "Susan") ("age" 4)) 
(("name" "James") ("age" 3))) )
)
</pre>

<p>Data can be extracted using <a href="#assoc">assoc</a>, <a href="#lookup">lookup</a> 
or <a href="#ref">ref</a>:</p>

<pre>
; the address
(lookup "address" jsp)
<span class='arw'>&rarr;</span> (("street" "701 First Ave.") ("city" "Sunnyvale, CA 95125") ("country" "United States"))

; the city of the address
(lookup "city" (lookup "address" jsp)) 
<span class='arw'>&rarr;</span> "Sunnyvale, CA 95125"

; a child named Susan
(ref '(( * "Susan") *) jsp match true) 
<span class='arw'>&rarr;</span> (("name" "Susan") ("age" 4))

; all names
(map last (ref-all '("name" *) jsp match true)) 
<span class='arw'>&rarr;</span> ("John Smith" "Richard" "Susan" "James")

; only names of children
(map last (ref-all '("name" *) (lookup "children" jsp) match true))
<span class='arw'>&rarr;</span>
("Richard" "Susan" "James")

; names of children other method
(map last (map first (lookup "children" jsp)))
<span class='arw'>&rarr;</span>
("Richard" "Susan" "James")
</pre>

<p>Although most of the time JSON object types are parsed, all JSON data
types can be parsed directly, without occurring as part of a JSON object.
The following examples show parsing of a JSON array:</p>

<pre>
; parse a JSON array data type

(json-parse "[1, 2, 3, 4, 5]") <span class='arw'>&rarr;</span> (1 2 3 4 5)
</pre>

<p>When the UTF-8 capable version of newLISP is used, JSON formatted Unicode
gets translated into UTF-8:</p>

<pre>
; parse a JSON object data type ands Unicode
; the outer {,} are newLISP string delimiters [text],[/text] tags could also be used
; the inner {,} are JSON object delimiters

(json-parse { {"greek letters" : "\u03b1\u03b2\u03b3\u03b4"} }) <span class='arw'>&rarr;</span> (("greek letters" "αβγδ"))

; strings longer than 2047 bytes should be delimted with [text], [/text] tags

(json-parse [text]{"greek letters" : "\u03b1\u03b2\u03b3\u03b4"}[/text]) <span class='arw'>&rarr;</span> (("greek letters" "αβγδ"))
</pre>

<p>The hex-code representation of Unicoder characters in JSON is the same as can be used in
UTF-8 enabled newLISP.</p>

<p>Because JSON objects contain <tt>{,},"</tt> characters, quotes should not be used
to limit JSON data, or all quotes inside the JSON data would need a preceding backslash <tt>\</tt>.
<tt>{,}</tt> braces can be used as long as braces inside the JSON data are balanced.
The safest delimiter are <tt>[text], [/text]</tt> tags &mdash; they suppress all special processing
of the string when read by newLISP and are suitable to delimit large data sizes greater
2047 bytes.</p>

<br/><br/>

<a name="join"></a>
<h2><span class="function">join</span></h2>
<h4>syntax: (join <em>list-of-strings</em> [<em>str-joint</em> [<em>bool-trail-joint</em>]])</h4>

<p>
Concatenates the given   
list of strings 
in <em>list-of-strings</em>. 
If <em>str-joint</em> is present, 
it is inserted between each string in the join.
If <em>bool-trail-joint</em> is <tt>true</tt>
then a joint string is also appended to the last string.
</p>

<!-- example -->

<pre>
(set 'lst '("this" "is" "a" "sentence"))

(join lst " ")  <span class='arw'>&rarr;</span> "this is a sentence"

(join (map string (slice (now) 0 3)) "-")  <span class='arw'>&rarr;</span> "2003-11-26"

(join (explode "keep it together"))  <span class='arw'>&rarr;</span> "keep it together"

(join '("A" "B" "C") "-")         <span class='arw'>&rarr;</span> "A-B-C"
(join '("A" "B" "C") "-" true)    <span class='arw'>&rarr;</span> "A-B-C-"
</pre>


<p>
See also the <a href="#append">append</a>, 
<a href="#string">string</a>, 
and <a href="#explode">explode</a> functions, 
which are the inverse of the <tt>join</tt> operation.
</p>

<br/><br/>

<a name="kmeans-query"></a>
<h2><span class="function">kmeans-query</span></h2>
<h4>syntax: (kmeans-query <em>list-data</em> <em>matrix-centroids</em>)<br/>
syntax: (kmeans-query <em>list-data</em> <em>matrix-data)</em></h4>

<p>In the first usage, <tt>kmeans-query</tt> calculates the Euclidian distances
from the data vector given in <em>list-data</em> to the centroids given in
<em>matrix-centroids</em>. The data vector in <em>list-data</em> has <i>m</i> 
elements. The 2-dimensional list in <em>matrix-centroids</em>, result from a previous
<a href="#kmeans-train">kmeans-train</a> clustering, has <i>k</i> rows and <i>m</i> 
columns for <i>k</i> centroids measuring <i>m</i> features.</p>

<pre>
; centroids from previous kmeans-train
K:centroids <span class='arw'>&rarr;</span>
( (6.39 7.188333333 5.935) 
(7.925714286 3.845714286 9.198571429) 
(2.207142857 2.881428571 0.8885714286) )

(kmeans-query '(1 2 3) K:centroids) <span class='arw'>&rarr;</span>
(8.036487279 9.475994267 2.58693657) ; distances to cluster 1, 2 and 3
</pre>

<p>The data record <tt>(1 2 3)</tt> shows the smallest distance to the 3rd
cluster centroid and would be classified as belonging to that cluster.</p>

<p>In the second application <tt>kmeans-query</tt> calculates Euclidian distances to a list
of other data points which are not centroids. The following example
calculates distances of the <tt>(1 2 3)</tt> data vector to all original points
from the original <a href="#kmeans-train">kmeans-train</a> data analysis.</p>

<p>The data in <em>matrix-data</em> can be either a nested list or a 2-dimensional
array.</p>

<p>This vector could be sorted for a subsequent kNN (k Nearest Neighbor)
analysis:</p>

<pre>
(kmeans-query '(1 2 3) data) <span class='arw'>&rarr;</span>
(10.91671196 3.190626898 9.19723328 3.014415366 9.079763213 
6.83130295 8.533111976 9.624816881 6.444261013 2.013107051 
3.186549858 9.475199206 9.32936761 2.874786949 7.084638311 
10.96221237 10.50080473 3.162419959 2.423674896 9.526436899)

; show distances to members in each cluster

; for cluster labeled 1
(select (kmeans-query '(1 2 3) data) (K:clusters 0)) <span class='arw'>&rarr;</span> 
(9.079763213 6.83130295 9.624816881 6.444261013 7.084638311 10.50080473)

; for cluster labeled 2
(select (kmeans-query '(1 2 3) data) (K:clusters 1)) <span class='arw'>&rarr;</span>
(10.91671196 9.19723328 8.533111976 9.475199206 9.32936761 10.96221237 9.526436899)

; for cluster labeled 3
(select (kmeans-query '(1 2 3) data) (K:clusters 2)) <span class='arw'>&rarr;</span>
(3.190626898 3.014415366 2.013107051 3.186549858 2.874786949 3.162419959 2.423674896)
</pre>

<p>We see that the smallest distances are shown for the data points in
the 3rd cluster at offset 2.</p>

<p>If the numbers of elements - features - in records of <em>list-data</em> 
is different from the number of columns in the data or centroid matrix, 
then the smaller is taken for calculating the Euclidian distances. This 
is useful when the last column of the data matrix does not contain feature 
data, but labels identifying the cluster membership of a data point.</p>

<br/><br/>

<a name="kmeans-train"></a>
<h2><span class="function">kmeans-train</span></h2>
<h4>syntax: (kmeans-train <em>matrix-data</em> <em>int-k</em> <em>context</em> [<em>matrix-centroids</em>])</h4>

<p>The function performs Kmeans cluster analysis on <em>matrix-data</em>. 
All <i>n</i> data records in <em>matrix-data</em> are partitioned into a number 
of <em>int-k</em> different groups. </p>

<p>Both, the <i>n * m</i> <em>matrix-data</em> and the optional <i>k * m</i>
<em>matrix-centroids</em> can be either nested lists or 2-dimensional arrays.</p>

<p>The Kmeans algorithm tries to minimize the sum of squared inner cluster 
distances (SSQ) from the cluster centroid. With each iteration the centroids get 
moved closer to their final position. On some data sets, the end result can depend 
on the starting centroid points.  The right choice of initial centroids can speed 
up the process and avoid not wanted local minima.</p>

<p>When no optional <em>matrix-centroids</em> are given, <tt>kmeans-train</tt> will 
assign an initial random cluster membership to each data row and calculate starting 
centroids. </p>

<p><tt>kmeans-train</tt> returns a vector of total SSQs, the sum of squared inner distances
from the centroid inside the cluster for all clusters. The Iterating algorithm stops when the
change of SSQ from one to the next iteration is less than 1e-10.</p>

<p>Other results of the analysis are stored as lists in variables of <em>context</em>.</p>

<p>The following example analyses 20 data records measuring <i>m = 3</i> features 
and tries to partition data into <i>k = 3</i> clusters. Other numbers than <i>k = 3</i> 
could be tried. The target is a result with few clusters of high density measured by the
average inner cluster distances.</p>

<pre>
(set 'data '(
(6.57 4.96 11.91) 
(2.29 4.18 1.06) 
(8.63 2.51 8.11) 
(1.85 1.89 0.11) 
(7.56 7.93 5.06) 
(3.61 7.95 5.11) 
(7.18 3.46 8.7) 
(8.17 6.59 7.49) 
(5.44 5.9 5.57) 
(2.43 2.14 1.59) 
(2.48 2.26 0.19) 
(8.16 3.83 8.93) 
(8.49 5.31 7.47) 
(3.12 3.1 1.4) 
(6.77 6.04 3.76) 
(7.01 4.2 11.9) 
(6.79 8.72 8.62) 
(1.17 4.46 1.02) 
(2.11 2.14 0.85) 
(9.44 2.65 7.37)))

(kmeans-train data 3 'MAIN:K) <span class='arw'>&rarr;</span> 
(439.7949357 90.7474276 85.06633163 82.74597619)

; cluster membership
K:labels <span class='arw'>&rarr;</span> (2 3 2 3 1 1 2 1 1 3 3 2 2 3 1 2 1 3 3 2)

; the centroid for each cluster
K:centroids <span class='arw'>&rarr;</span>
( (6.39 7.188333333 5.935) 
(7.925714286 3.845714286 9.198571429) 
(2.207142857 2.881428571 0.8885714286) )
</pre>

<p>The returned list of SSQs shows how in each iteration the sum of inner squared
distances decreases. The list in <tt>K:labels</tt> shows the membership fo each
data point in the same order as in the data.</p>

<p>The centroids in <tt>K:centroids</tt> can be used for later classification
of new data records using <a href="#kmeans-query">kmeans-query</a>. When the
number of clusters specified in <em>int-k</em> is too big, <tt>kmeans-train</tt>
will produce unused centroids with <tt>nan</tt> or <tt>NaN</tt> data. When
unused cluster centroids are present, the number in <em>int-k</em> should be
reduced. </p>

<p>The average inner <tt>K:deviations</tt> from cluster members to their centroid
show how dense a cluster is packed. Formally, deviations are calculated similarly
to Euclidian distances and to standard deviations in conventional statistics. 
Squaring the deviations and multiplying each with their cluster size 
(number of members in the cluster) shows the inner SSQ of each cluster:</p>

<pre>
; average inner deviations of cluster members to the centroid
; deviation = sqrt(ssq-of-cluster / n-of-cluster)
K:deviations  <span class='arw'>&rarr;</span> (2.457052209 2.260089397 1.240236975)

; calculating inner SSQs from cluster deviations
(map mul '(6 7 7) (map mul K:deviations K:deviations)) <span class='arw'>&rarr;</span>
(36.22263333 35.75602857 10.76731429) ; inner SSQs

; SSQ from last iteration as sum of inner SSQs
(apply add '(36.22263333 35.75602857 10.76731429)) <span class='arw'>&rarr;</span> 82.74597619
</pre>

<p><tt>K:clusters</tt> gives indices of data records into the original data
for each cluster. With these, individual clusters can be extracted from the
data for further analysis:</p>

<pre>
; ceach of the result clusters with indices into the data set
K:clusters <span class='arw'>&rarr;</span> 
( (4 5 7 8 14 16) 
(0 2 6 11 12 15 19) 
(1 3 9 10 13 17 18) )

; cluster of data records labeled 1 at offset 0
(select data (K:clusters 0)) <span class='arw'>&rarr;</span>
( (7.56 7.93 5.06) 
(3.61 7.95 5.11) 
(8.17 6.59 7.49) 
(5.44 5.9 5.57) 
(6.77 6.04 3.76) 
(6.79 8.72 8.62) )

; cluster of data records labeled 2 at offset 1
(select data (K:clusters 1)) <span class='arw'>&rarr;</span>
( (6.57 4.96 11.91) 
(8.63 2.51 8.11) 
(7.18 3.46 8.7) 
(8.16 3.83 8.93) 
(8.49 5.31 7.47) 
(7.01 4.2 11.9) 
(9.44 2.65 7.37) )

; cluster of data records labeled 3 at offset 2
(select data (K:clusters 2)) <span class='arw'>&rarr;</span>
( (2.29 4.18 1.06) 
(1.85 1.89 0.11) 
(2.43 2.14 1.59) 
(2.48 2.26 0.19) 
(3.12 3.1 1.4) 
(1.17 4.46 1.02) 
(2.11 2.14 0.85) )
</pre>


<p>In the last example the cluster labels (from 1 to 3) are added
to the data:</p>

<pre>
; append a cluster label to each data record
(set 'labeled-data (transpose (push K:labels (transpose data) -1)))

labeled-data: <span class='arw'>&rarr;</span>
( (6.57 4.96 11.91 2) 
(2.29 4.18 1.06 3) 
(8.63 2.51 8.11 2) 
(1.85 1.89 0.11 3) 
(7.56 7.93 5.06 1) 
(3.61 7.95 5.11 1) 
... ...
(2.11 2.14 0.85 3) 
(9.44 2.65 7.37 2) )
</pre>

<p>The result context should be prefixed with <tt>MAIN</tt> when code is
written in a namespace context. If the context does not exists already, it
will be created.</p>

<p>Results in <tt>K:labels</tt>, <tt>K:clusters</tt>, <tt>K:centroids</tt>
and <tt>K:deviations</tt> will be overwritten, if already present from previous 
runs of <tt>kmeans-train</tt>.</p>

<br/><br/>


<a name="lambda"></a>

<h2><span class="function">lambda</span></h2>

<p>See the description of <a href="#fn">fn</a>, which is a shorter form of writing <tt>lambda</tt>.</p>

<br/><br/>

<a name="lambda-macro"></a>

<h2><span class="function">lambda-macro</span></h2>

<p>See the description of <a href="#define-macro">define-macro</a>.</p>

<br/><br/>

<a name="lambdap"></a>
<h2><span class="function">lambda?</span></h2>
<h4>syntax: (lambda? <em>exp</em>)</h4>

<p>Returns <tt>true</tt> only if the value of <em>exp</em> is a lambda expression;
otherwise, returns <tt>nil</tt>.
</p>

<!-- example -->

<pre>
(define (square x) (* x x)) <span class='arw'>&rarr;</span> (lambda (x) (* x x))

square <span class='arw'>&rarr;</span> (lambda (x) (* x x))

(lambda? square)  <span class='arw'>&rarr;</span> true
</pre>


<p>See <a href="#define">define</a> and <a href="#define-macro">define-macro</a> for
more information about <em>lambda</em> expressions.
</p>
<br/><br/>

<a name="last"></a>

<h2><span class="function">last</span>&nbsp;<font size="-1"><a href="#utf8_capable">utf8</a></font></h2>
<h4>syntax: (last <em>list</em>)<br/>
syntax: (last <em>array</em>)<br/>
syntax: (last <em>str</em>)</h4>

<p>Returns the last element of a list or a string.
</p>

<!-- example -->

<pre>
(last '(1 2 3 4 5))  <span class='arw'>&rarr;</span> 5
(last '(a b (c d)))  <span class='arw'>&rarr;</span> (c d)

(set 'A (array 3 2 (sequence 1 6)))
<span class='arw'>&rarr;</span> ((1 2) (3 4) (5 6))
(last A)             <span class='arw'>&rarr;</span> (5 6)

(last '())           <span class='arw'>&rarr;</span> <span class='err'>ERR: list is empty</span>
</pre>


<p>In the second version the last character in the string <em>str</em> is returned as a
string.
</p>

<!-- example -->

<pre>
(last "newLISP")  <span class='arw'>&rarr;</span> "P"
</pre>


<p>
Note that <a href="#last">last</a> works on character boundaries 
rather than byte boundaries 
when the UTF-8&ndash;enabled version of newLISP is used.
See also <a href="#first">first</a>, <a href="#rest">rest</a> and <a href="#nth">nth</a>.
</p>

<br/><br/>

<a name="last-error"></a>
<h2><span class="function">last-error</span></h2>
<h4>syntax: (last-error)<br/>
syntax: (last-error <em>int-error</em>)</h4>

<p>Reports the last error generated by newLISP due to syntax errors or exhaustion of 
some resource. For a summary of all possible errors see the chapter 
<a href="#error_codes">Error codes</a> in the appendix.</p>

<p>If no error has occurred since the newLISP session was started,
<tt>nil</tt> is returned.</p>

<p>When <em>int-error</em> is specified, a list of the number and the error 
text is returned.</p>

<!-- example -->

<pre>
(last-error)  <span class='arw'>&rarr;</span> nil

(abc)

<span class='err'>ERR: invalid function : (abc)</span>

(last-error) <span class='arw'>&rarr;</span> (24 "ERR: invalid function : (abc)")

(last-error 24) <span class='arw'>&rarr;</span> (24 "invalid function")
(last-error 1) <span class='arw'>&rarr;</span> (1 "not enough memory")
(last-error 12345) <span class='arw'>&rarr;</span> (12345 "Unknown error")
</pre>


<p>For error numbers out of range the string <tt>"Unknown error"</tt> is
given for the error text.</p>

<p>Errors can be trapped by <a href="#error-event">error-event</a> 
and user defined error handlers.</p>

<p>See also <a href="#net-error">net-error</a> for errors generated by
networking conditions and <a href="#sys-error">sys-error</a> for errors
generated by the operating system.</p>

<br/><br/>

<a name="legalp"></a>
<h2><span class="function">legal?</span></h2>
<h4>syntax: (legal? <em>str</em>)</h4>

<p>
The token in <em>str</em> is verified as a legal newLISP symbol. 
Non-legal symbols can be created using the <a href="#sym">sym</a> function
(e.g. symbols containing spaces, quotes, or other characters not normally allowed). 
Non-legal symbols are created frequently 
when using them for associative data access:
</p>

<!-- example -->

<pre>
(symbol? (sym "one two"))  <span class='arw'>&rarr;</span> true

(legal? "one two")         <span class='arw'>&rarr;</span> nil  ; contains a space

(set (sym "one two") 123)  <span class='arw'>&rarr;</span> 123

(eval (sym "one two"))     <span class='arw'>&rarr;</span> 123
</pre>


<p>The example shows that the string <tt>"one two"</tt> does not contain a legal
symbol although a symbol can be created from this string and treated like a
variable.
</p>

<br/><br/>

<a name="length"></a>
<h2><span class="function">length</span>&nbsp;
<a href="#big_int"><font size="-1">bigint</font></a></h2>
<h4>syntax: (length <em>exp</em>)</h4>

<p>Returns the number of elements in a list, the number of rows in
an array and the number of bytes in a string or in a symbol name.</p>

<p>Applied to a number, <tt>length</tt> returns the number of digits for 
normal and big integers and the number of digits before the decimal 
separator for floats.</p>

<p><tt>length</tt> returns <tt>0</tt> on all other types.</p>

<p>Before version 10.5.6 <tt>length</tt> returned the storage size in bytes
for integers (4 or 8) and floats (8).</p>

<!-- example -->

<pre>
; number of top level elements in a list
(length '(a b (c d) e))         <span class='arw'>&rarr;</span> 4
(length '())                    <span class='arw'>&rarr;</span> 0
(set 'someList '(q w e r t y))  <span class='arw'>&rarr;</span> (q w e r t y)
(length someList)               <span class='arw'>&rarr;</span> 6

; number of top level elements in an array
(set 'ary (array 2 4 '(0)))  <span class='arw'>&rarr;</span> ((1 2 3 4) (5 6 7 8))
(length ary)                 <span class='arw'>&rarr;</span> 2

; number of bytes in a string or byte buffer
(length "Hello World")  <span class='arw'>&rarr;</span> 11
(length "")             <span class='arw'>&rarr;</span> 0
(length "\000\001\003") <span class='arw'>&rarr;</span> 3

; number of bytes in a symbol name string
(length 'someVar)  <span class='arw'>&rarr;</span> 7

; number of int digits in a number
(length 0)         <span class='arw'>&rarr;</span> 0
(length 123)       <span class='arw'>&rarr;</span> 3
(length 1.23)      <span class='arw'>&rarr;</span> 1
(length 1234567890123456789012345L) <span class='arw'>&rarr;</span> 25 
</pre>

<p>Use <a href="#utf8len">utf8len</a> to calculate the number of UTF-8 characters 
in a string.</p>

<br/><br/>

<a name="let"></a>
<h2><span class="function">let</span></h2>
<h4>syntax: (let ((<em>sym1</em> [<em>exp-init1</em>]) [(<em>sym2</em> [<em>exp-init2</em>]) ... ]) <em>body</em>)<br/>
syntax: (let (<em>sym1</em> <em>exp-init1</em> [<em>sym2</em> <em>exp-init2</em> ... ]) <em>body</em>)</h4>

<p>One or more variables <em>sym1</em>, <em>sym2</em>, ... are declared locally and
initialized with expressions in <em>exp-init1</em>, <em>exp-init2</em>, etc.
In the fully parenthesized first syntax, initializers are optional and assumed 
<tt>nil</tt> if missing.</p>

<p>When the local variables are initialized, the initializer expressions evaluate
 using symbol bindings as before the <tt>let</tt> statement. To incrementally use
symbol bindings as evaluated during the initialization of locals in <tt>let</tt>,
use <a href="#letn">letn</a>.</p>

<p>One or more expressions in <em>exp-body</em> are evaluated using the local
definitions of <em>sym1</em>, <em>sym2</em> etc. <tt>let</tt> is useful for
breaking up complex expressions by defining local variables close to the
place where they are used. The second form omits the parentheses around the
variable expression pairs but functions identically.</p>

<!-- example -->

<pre>
(define (sum-sq a b)
    (let ((x (* a a)) (y (* b b)))
        (+ x y)))

(sum-sq 3 4) <span class='arw'>&rarr;</span> 25

(define (sum-sq a b)           ; alternative syntax
    (let (x (* a a) y (* b b))
        (+ x y)))
</pre>


<p>The variables <tt>x</tt> and <tt>y</tt> are initialized, then the expression

<tt>(+ x y)</tt> is evaluated. The let form is just an optimized version and syntactic
convenience for writing:
</p>


<pre>
((lambda (<em>sym1</em> [<em>sym2</em> ... ]) <em>exp-body</em> ) <em>exp-init1</em> [ <em>exp-init2</em> ])
</pre>


<p>See also <a href="#letn">letn</a> for an incremental or nested form of
<tt>let</tt> and local for initializing to <tt>nil</tt>. See <a href="#local">local</a>
for automatic initialization of variables to <tt>nil</tt>.</p>

<br/><br/>

<a name="letex"></a>
<h2><span class="function">letex</span></h2>
<h4>syntax: (letex ((<em>sym1</em> [<em>exp-init1</em>]) [(<em>sym2</em> [<em>exp-init2</em>]) ... ]) <em>body</em>)<br/>

syntax: (letex (<em>sym1</em> <em>exp-init1</em> [<em>sym2</em> <em>exp-init2</em> ... ]) <em>body</em>)</h4>

<p>This function combines <a href="#let">let</a> and <a href="#expand">expand</a> to 
expand local variables into an expression before evaluating it. In the fully parenthesized 
first syntax initializers are optional and assumed <tt>nil</tt> if missing.</p>

<p>Both forms provide the same functionality, but in the second form the parentheses 
around the initializers can be omitted:
</p>

<!-- example -->

<pre>
(letex (x 1 y 2 z 3) '(x y z))    <span class='arw'>&rarr;</span> (1 2 3)

(letex ( (x 1) (y '(a b c)) (z "hello") ) '(x y z)) 

<span class='arw'>&rarr;</span> (1 (a b c) "hello")
</pre>

<p>Before the expression <tt>'(x y z)</tt> gets evaluated, <tt>x, y</tt> and <tt>z</tt>
are literally replaced with the initializers from the <tt>letex</tt> initializer list.
The final expression which gets evaluated is <tt>'(1 2 3)</tt>.
</p>

<p>In the second example a function <tt>make-adder</tt> is defined
for making adder functions:</p>

<pre>
(define (make-adder n)
    (letex (c n) (lambda (x) (+ x c))))

(define add3 (make-adder 3)) <span class='arw'>&rarr;</span> (lambda (x) (+ x 3))

(add3 10) <span class='arw'>&rarr;</span> 13

; letex can expand symbols into themselves
; the following form also works

(define (make-adder n)
     (letex (n n) (lambda (x) (+ x n))))

</pre>

<p><tt>letex</tt> evaluates <tt>n</tt> to the constant <tt>3</tt> and replaces <tt>c</tt>
with it in the lambda expression. The second examples shows, how a <tt>letex</tt>
variable can be expanded into itself.</p>
<br/><br/>

<a name="letn"></a>
<h2><span class="function">letn</span></h2>
<h4>syntax: (letn ((<em>sym1</em> [<em>exp-init1</em>]) [(<em>sym2</em> [<em>exp-init2</em>]) ... ]) <em>body</em>)<br/>
syntax: (letn (<em>sym1</em> <em>exp-init1</em> [<em>sym2</em> <em>exp-init2</em> ... ]) <em>body</em>)</h4>

<p><tt>letn</tt> is like a <em>nested let</em> and works similarly to <a href="#let">let</a>, 
but will incrementally use the new symbol bindings when evaluating the initializer expressions 
as if several <a href="#let">let</a> were nested. In the fully parenthesized first syntax, 
initializers are optional and assumed <tt>nil</tt> if missing.</p>

<p>The following comparison
of <a href="#let">let</a> and <tt>letn</tt> show the difference:
</p>

<!-- example -->

<pre>
(set 'x 10)
(let ((x 1) (y (+ x 1))) 
(list x y))           <span class='arw'>&rarr;</span> (1 11)

(letn ((x 1) (y (+ x 1))) 
(list x y))          <span class='arw'>&rarr;</span> (1 2)
</pre>


<p>While in the first example using <a href="#let">let</a> the variable <tt>y</tt> is
calculated using the binding of <tt>x</tt> before the <a href="#let">let</a> expression,
in the second example using <tt>letn</tt> the variable <tt>y</tt> is calculated using 
the new local binding of <tt>x</tt>.
</p>


<pre>
(letn  (x 1 y x) 
    (+ x y))     <span class='arw'>&rarr;</span>  2

;; same as nested let's

(let (x 1)
    (let (y x)
      (+ x y)))  <span class='arw'>&rarr;</span>  2
</pre>


<p><tt>letn</tt> works like several <em>nested</em> <a href="#let">let</a>. The parentheses
around the initializer expressions can be omitted.
</p>

<br/><br/>

<a name="list"></a>
<h2><span class="function">list</span></h2>
<h4>syntax: (list <em>exp-1</em> [<em>exp-2</em> ... ])</h4>

<p>The <em>exp</em> are evaluated and the values used to construct a new list.
Note that arguments of array type are converted to lists. See the chapter 
<a href="#arrays">Arrays</a> for dealing with multidimensional lists.
</p>

<!-- example -->

<pre>
(list 1 2 3 4 5)                <span class='arw'>&rarr;</span> (1 2 3 4 5)
(list 'a '(b c) (+ 3 4) '() '*) <span class='arw'>&rarr;</span> (a (b c) 7 () *)
</pre>


<p>See also <a href="#cons">cons</a> and <a href="#push">push</a> for other
forms of building lists.
</p>

<br/><br/>

<a name="listp"></a>
<h2><span class="function">list?</span></h2>
<h4>syntax: (list? <em>exp</em>)</h4>

<p>Returns <tt>true</tt> only if the value of <em>exp</em> is a list; otherwise
returns <tt>nil</tt>.  Note that lambda and lambda-macro
expressions are also recognized as special instances of a list expression.
</p>

<!-- example -->

<pre>
(set 'var '(1 2 3 4))    <span class='arw'>&rarr;</span> (1 2 3 4)
(list? var)              <span class='arw'>&rarr;</span> true

(define (double x) (+ x x))

(list? double)           <span class='arw'>&rarr;</span> true
</pre>

<br/><br/>

<a name="load"></a>

<h2><span class="function">load</span></h2>
<h4>syntax: (load <em>str-file-name-1</em> [<em>str-file-name-2</em> ... ] [<em>sym-context</em>])</h4>

<p>Loads and translates newLISP from a source file specified in one or more <em>str-file-name</em> 
and evaluates the expressions contained in the file(s). When loading is successful,
<tt>load</tt> returns the result of the last expression in the last file evaluated. If a file 
cannot be loaded, <tt>load</tt> throws an error.
</p>

<p>
An optional <em>sym-context</em> can be specified, 
which becomes the context of evaluation, 
unless such a context switch is already present 
in the file being loaded. 
By default, 
files which do not contain <a href="#context">context</a> switches 
will be loaded into the <tt>MAIN</tt> context.
</p>

<p>The <em>str-file-name</em> specs can contain URLs. Both <tt>http://</tt> and <tt> file://</tt>
URLs are supported.
</p>

<!-- example -->

<pre>
(load "myfile.lsp")    

(load "a-file.lsp" "b-file.lsp") 

(load "file.lsp" "http://mysite.org/mypro")

(load "http://192.168.0.21:6000//home/test/program.lsp")

(load "a-file.lsp" "b-file.lsp" 'MyCTX)

(load "file:///usr/local/share/newlisp/mysql.lsp")
</pre>


<p>In case expressions evaluated during the <tt>load</tt> are changing the 
<a href="#context">context</a>, this will not influence the programming
module doing the <tt>load</tt>. </p>

<p>The current context after the <tt>load</tt> statement will always be 
the same as before the <tt>load</tt>.</p>

<p>Normal file specs and URLs can be mixed in the same load command.</p>

<p><tt>load</tt> with <tt>HTTP</tt> URLs can also be used to load code
remotely from newLISP server nodes running on a Unix-like operating system. 
In this mode, <tt>load</tt> will issue
an HTTP GET request to the target URL. Note that a double backslash is required 
when path names are specified relative to the root directory. <tt>load</tt>
in <tt>HTTP</tt> mode will observe a 60-second timeout.</p>

<p>The second to last line causes the files to be loaded into the context <tt>MyCTX</tt>.
The quote forces the context to be created if it did not exist.
</p>

<p>The <tt>file://</tt> URL is followed by a third <tt>/</tt> for the directory spec.
</p>

<br/><br/>

<a name="local"></a>
<h2><span class="function">local</span></h2>
<h4>syntax: (local (<em>sym-1</em> [<em>sym-2</em> ... ]) <em>body</em>)</h4>

<p>
Initializes one or more symbols 
in <em>sym-1&mdash;</em> to <tt>nil</tt>, 
evaluates the expressions in <em>body</em>, 
and returns the result of the last evaluation.
</p>

<p>
<tt>local</tt> works similarly to <a href="#let">let</a>,
but local variables are all initialized to <tt>nil</tt>.
</p>

<p>
<tt>local</tt> provides a simple way 
to localize variables 
without explicit initialization.
</p>

<br/><br/>

<a name="log"></a>
<h2><span class="function">log</span></h2>
<h4>syntax: (log <em>num</em>)<br/>

syntax: (log <em>num</em> <em>num-base</em>)</h4>

<p>In the first syntax, the expression in <em>num</em> is evaluated and the natural
logarithmic function is calculated from the result.
</p>

<!-- example -->

<pre>
(log 1)         <span class='arw'>&rarr;</span> 0
(log (exp 1))   <span class='arw'>&rarr;</span> 1
</pre>


<p>In the second syntax, an arbitrary base can be specified in <em>num-base</em>.
</p>

<!-- example -->

<pre>
(log 1024 2)             <span class='arw'>&rarr;</span> 10
(log (exp 1) (exp 1))    <span class='arw'>&rarr;</span>  1
</pre>


<p>See also <a href="#exp">exp</a>, which is the inverse function to <tt>log</tt> with
base <b><em>e</em></b> (2.718281828).</p>

<br/><br/>

<a name="lookup"></a>
<h2><span class="function">lookup</span></h2>
<h4>syntax: (lookup <em>exp-key</em> <em>list-assoc</em> [<em>int-index</em> [<em>exp-default</em>]])</h4>

<p>Finds in <em>list-assoc</em> an association, the key element of which
has the same value as <em>exp-key</em>, and returns the <em>int-index</em> element of
association (or the last element if <em>int-index</em> is absent).</p>

<p>Optionally, <em>exp-default</em> can be specified, which is returned if an association matching
<em>exp-key</em> cannot be found. If the <em>exp-default</em> is absent and no association
has been found, <tt>nil</tt> is returned.</p>

<p>See also <a href="#indexing">Indexing elements of strings and lists</a>.
</p>

<p><tt>lookup</tt> is similar to <a href="#assoc">assoc</a> but goes one step further 
by extracting a specific element found in the list.
</p>

<!-- example -->

<pre>
(set 'params '(
    (name "John Doe") 
    (age 35) 
    (gender "M") 
    (balance 12.34)
))

(lookup 'age params)             <span class='arw'>&rarr;</span> 35

; use together with setf to modify and association list
(setf (lookup 'age params) 42)   <span class='arw'>&rarr;</span> 42
(lookup 'age params)             <span class='arw'>&rarr;</span> 42

(set 'persons '(
    ("John Doe" 35 "M" 12.34) 
    ("Mickey Mouse" 65 "N" 12345678)
))

(lookup "Mickey Mouse" persons 2)    <span class='arw'>&rarr;</span> "N"
(lookup "Mickey Mouse" persons -3)   <span class='arw'>&rarr;</span> 65
(lookup "John Doe" persons 1)        <span class='arw'>&rarr;</span> 35 
(lookup "John Doe" persons -2)       <span class='arw'>&rarr;</span> "M"

(lookup "Jane Doe" persons 1 "N/A")  <span class='arw'>&rarr;</span> "N/A"
</pre>

<p>See also <a href="#assoc">assoc</a></p>

<br/><br/>

<a name="lower-case"></a>
<h2><span class="function">lower-case</span>&nbsp;<font size="-1"><a href="#utf8_capable">utf8</a></font></h2>
<h4>syntax: (lower-case <em>str</em>)</h4>

<p>
Converts the characters of the string 
in <em>str</em> to lowercase. 
A new string is created, 
and the original is left unaltered.
</p> 


<!-- example -->

<pre>
(lower-case "HELLO WORLD")  <span class='arw'>&rarr;</span> "hello world"
(set 'Str "ABC")
(lower-case Str)  <span class='arw'>&rarr;</span> "abc"
Str               <span class='arw'>&rarr;</span> "ABC"
</pre>


<p>
See also the <a href="#upper-case">upper-case</a> and 
<a href="#title-case">title-case</a> functions.
</p>

<br/><br/>

<a name="macro"></a>
<h2><span class="function">macro</span></h2>
<h4>syntax: (macro (<em>sym-name</em> [<em>sym-param-1</em> ... ]) [<em>body-1</em> ... ])</h4>

<p>The <tt>macro</tt> function is used to define expansion macros. The syntax 
of <tt>macro</tt> is identical to the syntax of <a href="#define-macro">define-macro</a>.
But while <tt>define-macro</tt> defines are <em>fexprs</em> functions to be evaluated 
at run-time, <tt>macro</tt> defines a function to be used during the source loading 
and reading process to transform certain expression call patterns into different call 
patterns.</p>

<p>Symbols defined with <tt>macro</tt> are protected from re-definition.</p>

<pre>
(macro (double X) (+ X X)) <span class='arw'>&rarr;</span> (lambda-macro (X) (expand '(+ X X)))

(double 123) <span class='arw'>&rarr;</span> 246

(protected? 'double) <span class='arw'>&rarr;</span> true
</pre>

<p>Internally all <tt>macro</tt> defined symbol call patterns are translated using
the <a href="#expand">expand</a> expression during source reading. This can be shown using
the <a href="#read-expr">read-expr</a> function:</p>

<pre>
(read-expr "(double 123)") <span class='arw'>&rarr;</span> (+ 123 123)
</pre>

<p>All variable names to be expanded must start in upper-case. Macros can be nested containing 
other macros defined earlier. But <tt>macro</tt> definitions cannot be repeated for the same 
symbol during the same newLISP session. To redefine a macro, e.g. for reading source with a 
different definition of an exisiting <tt>macro</tt> definition, use the 
<a href="#constant">constant</a> function in the following way:</p>

<pre>
; change existing macro 'double' to allow floating point parameters
; use upper-case for variables for expansion

(constant 'double (lambda-macro (X) (expand '(add X X))))
<span class='arw'>&rarr;</span> (lambda-macro (X) (expand '(add X X)))

(double 1.23) <span class='arw'>&rarr;</span> 2.46
</pre>

<p>Note, that <a href="#constant">constant</a> can be used only to re-define macros, not
to create new macros. Internally newLISP knows that <tt>macro</tt> defined symbols
are executed during source reading, not evaluation.</p>

<p>The redefinition will only affect future read code, it will not affect
code already load and translated by the reader routines.</p>

<h3>Using <tt>map</tt> and <tt>apply</tt> with <tt>macro</tt></h3>

<p>When mapping macros using <a href="#map">map</a> or <a href="#apply">apply</a>
the expansion function is mapped:</p>

<pre>
<b>&gt;</b> (macro (double X) (+ X X))
<b>(lambda-macro (X) (expand '(+ X X)))</b>

<b>&gt;</b> (map double '(1 2 3 4 5))
<b>((+ 1 1) (+ 2 2) (+ 3 3) (+ 4 4) (+ 5 5))

&gt;</b> (map eval (map double '(1 2 3 4 5)))
<b>(2 4 6 8 10)</b>

<b>&gt;</b> (apply double '(10))
<b>(+ 10 10)
&gt;</b>
</pre>
<p>This is useful to find out how the expansion mechanism of our <tt>macro</tt>
definition works during source load time.</p>

<h3>Differences between <tt>macro</tt> and <tt>define-macro</tt> and potential problems.</h3>

<p><tt>macro</tt> definitions are not susceptible to <em>variable capture</em> as 
are fexprs made with <a href="define-macro">define-macro</a>:</p>

<pre>
(define-macro (fexpr-add A B) 
    (+ (eval A) (eval B)))

(macro (mac-add A B) 
    (+ A B))

(set 'A 11 'B 22)

; variable capture when using the same symbols 
; used as locals in define-macro for callling

(fexpr-add A B) <span class='arw'>&rarr;</span>
; or
(fexpr-add B A) <span class='arw'>&rarr;</span>
<span class="err">ERR: value expected : A
called from user defined function fexpr-add</span>

; no variable capture when doing the same with 
; expansion macros

(mac-add A B) <span class='arw'>&rarr;</span> 33

(mac-add B A) <span class='arw'>&rarr;</span> 33
</pre>

<p>But expansion macros using <tt>macro</tt> are susceptible to unwanted double
evaluation, just like <tt>define-macro is</tt>:</p>

<pre>
(define-macro (fexpr-double X) 
    (+ (eval X) (eval X)))

(macro (mac-double X) 
    (+ X X))

(set 'a 10)
(fexpr-double (inc a)) <span class='arw'>&rarr;</span> 23 ; not 22 as expected

(set 'a 10)
(mac-double (inc a)) <span class='arw'>&rarr;</span> 23 ; not 22 as expected
</pre>

<p>In both cases the incoming expression <tt>(inc a)</tt> gets evaulated twice.
This must be considered when writing both, <tt>macro</tt> or <tt>define-macro</tt>
expressions and symbols occur more than once in the body of the definition.</p> 

<p>See also <a href="#reader-event">reader-event</a> for general preprocessing
of expressions during reading of source code.</p>

<br/><br/>

<a name="macrop"></a>
<h2><span class="function">macro?</span></h2>
<h4>syntax: (macro? <em>exp</em>)</h4>

<p>Returns <tt>true</tt> if <em>exp</em> evaluates to a lambda-macro expression.
If <em>exp</em> evaluates to a symbol and the symbol contains
a macro-expansion expression made with the <a href="#macro">macro</a> function,
<tt>true</tt> is also returned. In all other cases <tt>nil</tt> is returned.</p>

<!-- example -->

<pre>
(define-macro (mysetq lv rv) (set lv (eval rv)))

(macro? mysetq)  <span class='arw'>&rarr;</span> true

(macro (my-setq Lv Rv) (set 'Lv Rv)) 
<span class='arw'>&rarr;</span> (lambda-macro (Lv Rv) (expand '(set 'Lv Rv)))

; my-setq contains a lambda-macro expression
(macro? my-setq)   <span class='arw'>&rarr;</span> true

; my-setq symbol was created with macro function
(macro? 'my-setq)   <span class='arw'>&rarr;</span> true
</pre>

<br/><br/>

<a name="main-args"></a>
<h2><span class="function">main-args</span></h2>
<h4>syntax: (main-args)<br/>

syntax: (main-args <em>int-index</em>)</h4>

<p>
<tt>main-args</tt> returns a list 
with several string members, 
one for program invocation 
and one for each of 
the command-line arguments.
</p>

<!-- example -->

<pre>
newlisp 1 2 3

&gt; (main-args)
<b>("/usr/local/bin/newlisp" "1" "2" "3")</b>
</pre>


<p>
After <tt>newlisp 1 2 3</tt> is executed at the command prompt, 
<tt>main-args</tt> returns a list containing the name of 
the invoking program and three command-line arguments.
</p>

<p>
Optionally, <tt>main-args</tt> can take 
an <em>int-index</em> for indexing into the list.
Note that an index out of range will cause <tt>nil</tt>
to be returned, not the last element of the list like
in list-indexing.
</p>


<pre>
newlisp a b c

&gt; (main-args 0)   
<b>"/usr/local/bin/newlisp"</b>
&gt; (main-args -1)  
<b>"c"</b>
&gt; (main-args 2)   
<b>"b"</b>
&gt; (main-args 10)
<b>nil</b>
</pre>


<p>
Note that when newLISP is executed from a script, 
<tt>main-args</tt> also returns the <em>name</em> 
of the script as the second argument:
</p>


<pre>
#!/usr/local/bin/newlisp
# 
# script to show the effect of 'main-args' in script file

(print (main-args) "\n")
(exit)

# end of script file

;; execute script in the OS shell:

script 1 2 3

<b>("/usr/local/bin/newlisp" "./script" "1" "2" "3")</b>
</pre>


<p>
Try executing this script with different 
command-line parameters.
</p>

<br/><br/>

<a name="make-dir"></a>
<h2><span class="function">make-dir</span></h2>
<h4>syntax: (make-dir <em>str-dir-name</em> [<em>int-mode</em>])</h4>

<p>
Creates a directory as specified in <em>str-dir-name</em>, 
with the optional access mode <em>int-mode</em>. 
Returns <tt>true</tt> or <tt>nil</tt> 
depending on the outcome. 
If no access mode is specified, 
most Unix systems default to <tt>drwxr-xr-x</tt>.
</p>

<p>
On Unix systems, the access mode specified 
will also be masked by the OS's <em>user-mask</em> 
set by the system administrator. 
The <em>user-mask</em> can be retrieved 
on Unix systems using the command <tt>umask</tt> 
and is usually <tt>0022</tt> (octal),
which masks write (and creation) permission 
for non-owners of the file.
</p>

<!-- example -->

<pre>
;; 0 (zero) in front of 750 makes it an octal number

(make-dir "adir" 0750)  
</pre>


<p>
This example creates a directory named <tt>adir</tt> 
in the current directory with an access mode of 
<tt>0750</tt> (octal 750 = <tt>drwxr-x---</tt>).
</p>
<br/><br/>

<a name="map"></a>

<h2><span class="function">map</span></h2>
<h4>syntax: (map <em>exp-functor</em> <em>list-args-1</em> [<em>list-args-2</em> ... ])</h4>

<p>Successively applies the primitive function, defined function, or lambda expression 
<em>exp-functor</em> to the arguments specified in <em>list-args-1 list-args-2&mdash;</em>, 
returning all results in a list. Since version 10.5.5 <em>list-args</em>
can also be array vectors, but the returned result will always be a list.</p>

<!-- example -->

<pre>
(map + '(1 2 3) '(50 60 70))  <span class='arw'>&rarr;</span> (51 62 73)

(map if '(true nil true nil true) '(1 2 3 4 5) '(6 7 8 9 10))
<span class='arw'>&rarr;</span> '(1 7 3 9 5)

(map (fn (x y) (* x y)) '(3 4) '(20 10))
<span class='arw'>&rarr;</span> (60 40)
</pre>

<p>
The second example shows how to dynamically 
create a function for <tt>map</tt>:
</p>

<pre>
(define (foo op p) 
    (append (lambda (x)) (list (list op p 'x))))
</pre>

<p>We can also use the shorter <tt>fn</tt>:</p>

<pre>
(define (foo op p) 
    (append (fn (x)) (list (list op p 'x))))
</pre>

<p><tt>foo</tt> now works like a function-maker:</p>

<pre>
(foo 'add 2)  <span class='arw'>&rarr;</span> (lambda (x) (add 2 x))

(map (foo add 2) '(1 2 3 4 5))  <span class='arw'>&rarr;</span> (3 4 5 6 7)

(map (foo mul 3) '(1 2 3 4 5))  <span class='arw'>&rarr;</span> (3 6 9 12 15)
</pre>

<p>
Note that the quote before the operand can be omitted 
because primitives evaluate to themselves in newLISP.
</p>

<p>By incorporating <tt>map</tt> into the function definition, 
we can do the following:</p>

<pre>
(define (list-map op p lst) 
    (map (lambda (x) (op p x)) lst))

(list-map + 2 '(1 2 3 4))  <span class='arw'>&rarr;</span> (3 4 5 6)

(list-map mul 1.5 '(1 2 3 4))  <span class='arw'>&rarr;</span> (1.5 3 4.5 6)
</pre>

<p><tt>map</tt> also sets the internal list index <tt>$idx</tt>.</p>

<pre>
(map (fn (x) (list $idx x)) '(a b c)) <span class='arw'>&rarr;</span> ((0 a) (1 b) (2 c))
</pre>

<p>
The number of arguments used is determined by the length of the first argument list. 
Arguments missing in other argument lists cause map to stop collecting parameters
for that level of arguments. This ensures that the nth parameter list gets converted
to the nth column during the transposition occurring. If an argument list contains too 
many elements, the extra ones will be ignored.
</p>

<p>
Special forms which use parentheses as syntax cannot be mapped 
(i.e. <a href="#case">case</a>).</p>

<br/><br/>

<a name="mat"></a>
<h2><span class="function">mat</span></h2>
<h4>syntax: (mat <em>+</em> | <em>-</em> | <em>*</em> | <em>/</em> <em>matrix-A matrix-B</em>)<br/>
syntax: (mat <em>+</em> | <em>-</em> | <em>*</em> | <em>/</em> <em>matrix-A number</em>)</h4>

<p>Using the first syntax, this function performs fast floating point 
scalar operations on two-dimensional matrices in <em>matrix-A</em> or <em>matrix-B</em>. 
The type of operation is specified by one of the four arithmetic operators 
<tt>+</tt>, <tt>-</tt>, <tt>*</tt>, or <tt>/</tt>. 
This type of arithmetic operator is typically used for integer 
operations in newLISP. In the case of <tt>mat</tt>, however,
all operations will be performed as floating point operations
(<tt>add</tt>, <tt>sub</tt>, <tt>mul</tt>, <tt>div</tt>).</p>

<p>Matrices in newLISP are two-dimensional lists or arrays. 
Internally, newLISP translates lists and arrays into fast, accessible 
C-language data objects. 
This makes matrix operations in newLISP 
as fast as those coded directly in C. 
The same is true for the matrix operations 
<a href="#multiply">multiply</a> and <a href="#invert">invert</a>.</p>

<!-- example -->

<pre>
(set 'A '((1 2 3) (4 5 6)))
(set 'B A)

(mat + A B)    <span class='arw'>&rarr;</span> ((2 4 6) (8 10 12))
(mat - A B)    <span class='arw'>&rarr;</span> ((0 0 0) (0 0 0))
(mat * A B)    <span class='arw'>&rarr;</span> ((1 4 9) (16 25 36))
(mat / A B)    <span class='arw'>&rarr;</span> ((1 1 1) (1 1 1))

; specify the operator in a variable

(set 'op +)
(mat op A B)    <span class='arw'>&rarr;</span> ((2 4 6) (8 10 12)) 
</pre>


<p>Using the second syntax, all cells in <em>matrix-A</em> 
are operated on with a scalar in <em>number</em>:</p>


<pre>
(mat + A 5)    <span class='arw'>&rarr;</span> ((6 7 8) (9 10 11))
(mat - A 2)    <span class='arw'>&rarr;</span> ((-1 0 1) (2 3 4))
(mat * A 3)    <span class='arw'>&rarr;</span> ((3 6 9) (12 15 18))
(mat / A 10)   <span class='arw'>&rarr;</span> ((.1 .2 .3) (.4 .5 .6))
</pre>


<p>See also the other matrix operations <a href="#det">det</a>, 
<a href="#invert">invert</a>, <a href="#multiply">multiply</a>,
and <a href="#transpose">transpose</a>.</p>

<br/><br/>

<a name="match"></a>
<h2><span class="function">match</span></h2>
<h4>syntax: (match <em>list-pattern</em> <em>list-match</em> [<em>bool</em>])</h4>

<p>
The pattern in <em>list-pattern</em> is matched 
against the list in <em>list-match</em>, 
and the matching expressions are returned in a list. 
The three wildcard characters <tt>?</tt>, <tt>+</tt>, 
and <tt>*</tt> can be used in <em>list-pattern</em>.
</p>

<p>
Wildcard characters may be nested. 
<tt>match</tt> returns a 
list of matched expressions. 
For each <tt>?</tt> (question mark), 
a matching expression element is returned. 
For each <tt>+</tt> (plus sign) or 
<tt>*</tt> (asterisk), a list containing 
the matched elements is returned. 
If the pattern cannot be matched 
against the list in <em>list-match</em>, 
<tt>match</tt> returns <tt>nil</tt>.
If no wildcard characters are present
in the pattern an empty list is returned.
</p>

<p>Optionally, the Boolean value <tt>true</tt> (or any other expression not 
evaluating to <tt>nil</tt>) can be supplied as a third argument.  This 
causes <tt>match</tt> to show all elements in the returned result.</p>

<p>
<tt>match</tt> is frequently employed as a functor parameter
in <a href="#find">find</a>, <a href="#ref">ref</a>,
<a href="#ref-all">ref-all</a> and <a href="#replace">replace</a> and
is internally used by <a href="#find-all">find-all</a> for lists.</p>

<!-- example -->

<pre>
(match '(a ? c) '(a b c))  <span class='arw'>&rarr;</span> (b)

(match '(a ? ?) '(a b c))  <span class='arw'>&rarr;</span> (b c)

(match '(a ? c) '(a (x y z) c))  <span class='arw'>&rarr;</span> ((x y z))

(match '(a ? c) '(a (x y z) c) true)  <span class='arw'>&rarr;</span> (a (x y z) c)

(match '(a ? c) '(a x y z c))  <span class='arw'>&rarr;</span> nil


(match '(a * c) '(a x y z c))  <span class='arw'>&rarr;</span> ((x y z))

(match '(a (b c ?) x y z) '(a (b c d) x y z))  <span class='arw'>&rarr;</span> (d)

(match '(a (*) x ? z) '(a (b c d) x y z))  <span class='arw'>&rarr;</span> ((b c d) y)


(match '(+) '())  <span class='arw'>&rarr;</span> nil

(match '(+) '(a))  <span class='arw'>&rarr;</span> ((a))

(match '(+) '(a b))  <span class='arw'>&rarr;</span> ((a b))

(match '(a (*) x ? z) '(a () x y z))  <span class='arw'>&rarr;</span> (() y)

(match '(a (+) x ? z) '(a () x y z))  <span class='arw'>&rarr;</span> nil 
</pre>


<p>Note that the <tt>*</tt> operator tries to grab the fewest number of 
elements possible, but <tt>match</tt> backtracks and grabs more elements 
if a match cannot be found.</p>

<p>The <tt>+</tt> operator works similarly to the <tt>*</tt> operator, 
but it requires at least one list element.</p>

<p>The following example shows how the matched expressions can be bound 
to variables.</p>


<pre>
(map set '(x y) (match '(a (? c) d *) '(a (b c) d e f)))

x  <span class='arw'>&rarr;</span> b
y  <span class='arw'>&rarr;</span> (e f)
</pre>


<p>
Note that <tt>match</tt> for strings has been eliminated. 
For more powerful string matching, use <a href="#regex">regex</a>, 
<a href="#find">find</a>, <a href="#find-all">find-all</a> 
or <a href="#parse">parse</a>.
</p>

<p> <a href="#unify">unify</a> is another function for matching 
expressions in a PROLOG like manner.</p>

<br/><br/>

<a name="max"></a>
<h2><span class="function">max</span></h2>
<h4>syntax: (max <em>num-1</em> [<em>num-2</em> ... ])</h4>

<p>Evaluates the expressions <em>num-1</em>&mdash; and returns 
the largest number.</p>

<!-- example -->

<pre>
(max 4 6 2 3.54 7.1)  <span class='arw'>&rarr;</span> 7.1
</pre>


<p>
See also the <a href="#min">min</a> function.
</p>

<br/><br/>

<a name="member"></a>
<h2><span class="function">member</span></h2>
<h4>syntax: (member <em>exp</em> <em>list</em>)<br/>
syntax: (member <em>str-key</em> <em>str</em> [<em>num-option</em>])</h4>
<p>
In the first syntax, 
<tt>member</tt> searches 
for the element <em>exp</em> 
in the list <em>list</em>. 
If the element is a member of the list, 
a new list starting with the element found 
and the rest of the original list 
is constructed and returned. 
If nothing is found, 
<tt>nil</tt> is returned. 
When specifying <em>num-option</em>,
<tt>member</tt> performs a regular expression search.
</p>

<!-- example -->

<pre>
(set 'aList '(a b c d e f g h))  <span class='arw'>&rarr;</span> (a b c d e f g h)
(member 'd aList)                <span class='arw'>&rarr;</span> (d e f g h)
(member 55 aList)                <span class='arw'>&rarr;</span> nil
</pre>


<p>
In the second syntax, 
<tt>member</tt> searches 
for <em>str-key</em> in <em>str</em>. 
If <em>str-key</em> is found, all of <em>str</em> 
(starting with <em>str-key</em>) is returned. 
<tt>nil</tt> is returned if nothing is found.
</p>

<!-- example -->

<pre>
(member "LISP" "newLISP")  <span class='arw'>&rarr;</span> "LISP"
(member "LI" "newLISP")    <span class='arw'>&rarr;</span> "LISP"
(member "" "newLISP")      <span class='arw'>&rarr;</span> "newLISP"
(member "xyz" "newLISP")   <span class='arw'>&rarr;</span> nil
(member "li" "newLISP" 1)  <span class='arw'>&rarr;</span> "LISP"
</pre>


<p>
See also the related functions 
<a href="#slice">slice</a> and 
<a href="#find">find</a>.
</p>

<br/><br/>

<a name="min"></a>
<h2><span class="function">min</span></h2>
<h4>syntax: (min <em>num-1</em> [<em>num-2</em> ... ])</h4>

<p>
Evaluates the expressions <em>num-1</em>&mdash; 
and returns the smallest number.
</p>

<!-- example -->

<pre>
(min 4 6 2 3.54 7.1)  <span class='arw'>&rarr;</span> 2
</pre>

<p>
See also the <a href="#max">max</a> function.
</p>

<br/><br/>

<a name="mod"></a>
<h2><span class="function">mod</span></h2>
<h4>syntax: (mod <em>num-1</em> <em>num-2</em> [<em>num-3</em> ... ])<br/>
syntax: (mod <em>num-1</em>)</h4>

<p>
Calculates the modular value of the 
numbers in <em>num-1</em> and <em>num-2</em>. 
<tt>mod</tt> computes the remainder 
from the division of the numerator <em>num-i</em> 
by the denominator <em>num-i + 1</em>. 
Specifically, the return value is 
<em>numerator - n * denominator</em>, 
where <tt>n</tt> is the quotient 
of the numerator divided by the denominator, 
rounded towards zero to an integer. 
The result has the same sign as 
the numerator and its magnitude 
is less than the magnitude 
of the denominator.</p>

<p>In the second syntax <tt>1</tt> is assumed for <em>num-2</em> and the
result is the fractional part of <em>num-1</em>.</p>

<!-- example -->

<pre>
(mod 10.5 3.3)   <span class='arw'>&rarr;</span>  0.6
(mod -10.5 3.3)  <span class='arw'>&rarr;</span> -0.6
(mod -10.5)      <span class='arw'>&rarr;</span> -0.5
</pre>


<p>
Use the <a href="#arithmetic">%</a> (percent sign) 
function when working with integers only.
</p>

<br/><br/>

<a name="mul"></a>
<h2><span class="function">mul</span></h2>
<h4>syntax: (mul <em>num-1</em> <em>num-2</em> [<em>num-3</em> ... ])</h4>

<p>
Evaluates all expressions <em>num-1</em>&mdash;, 
calculating and returning the product. 
<tt>mul</tt> can perform mixed-type arithmetic, 
but it always returns floating point numbers. 
Any floating point calculation with 
<tt>NaN</tt> also returns <tt>NaN</tt>.
</p>

<!-- example -->


<pre>
(mul 1 2 3 4 5 1.1)  <span class='arw'>&rarr;</span> 132
(mul 0.5 0.5)        <span class='arw'>&rarr;</span> 0.25
</pre>

<br/><br/>

<a name="multiply"></a>
<h2><span class="function">multiply</span></h2>
<h4>syntax: (multiply <em>matrix-A</em> <em>matrix-B</em>)</h4>

<p>
Returns the matrix multiplication of matrices 
in <em>matrix-A</em> and <em>matrix-B</em>. 
If <em>matrix-A</em> has the dimensions <em>n</em> by <em>m</em> 
and <em>matrix-B</em> the dimensions <em>k</em> by <em>l</em> 
(<em>m</em> and <em>k</em> must be equal), 
the result is an <em>n</em> by <em>l</em> matrix. 
<tt> multiply</tt> can perform mixed-type arithmetic, 
but the results are always double precision floating points, 
even if all input values are integers.
</p>

<p>
The dimensions of a matrix are determined 
by the number of rows and the number 
of elements in the first row. 
For missing elements 
in non-rectangular matrices, 
<tt>0.0</tt> is assumed. 
A matrix can either be a nested list 
or <a href="#array">array</a>.
</p>

<!-- example -->

<pre>
(set 'A '((1 2 3) (4 5 6)))
(set 'B '((1 2) (1 2) (1 2)))
(multiply A B)  <span class='arw'>&rarr;</span> ((6 12) (15 30))

(set 'v '(10 20 30))
(multiply A (transpose (list v))) <span class='arw'>&rarr;</span> ((140) (320))
</pre>

<p>When multiplying a matrix with a vector of <tt>n</tt> elements, the vector
must be transformed into <tt>n</tt> rows by <tt>1</tt> column matrix using
 <a href="#transpose">transpose</a>.</p>

<p>
All operations shown here on lists 
can be performed on arrays, as well.
</p>

<p>
See also the matrix operations <a href="#det">det</a>,
<a href="#invert">invert</a>, <a href="#mat">mat</a> 
and <a href="#transpose">transpose</a>.
</p>

<br/><br/>

<a name="name"></a>
<h2><span class="function">name</span></h2>
<p>This function is deprecated, use <a href="#term">term</a> instead.</p>

<br/><br/>

<a name="NaNp"></a>
<h2><span class="function">NaN?</span></h2>
<h4>syntax: (NaN? <em>float</em>)</h4>

<p>
Tests if the result of a floating point math operation is a <tt>NaN</tt>.  
Certain floating point operations return a special IEEE 754 number format 
called a <tt>NaN</tt> for 'Not a Number'.</p>

<!-- example -->

<pre>
; floating point operation on NaN yield NaN
(set 'x (sqrt -1))  <span class='arw'>&rarr;</span> NaN
(NaN? x)            <span class='arw'>&rarr;</span> true
(add x 123)         <span class='arw'>&rarr;</span> NaN
(mul x 123)         <span class='arw'>&rarr;</span> NaN

; integer operations treat NaN as zero
(+ x 123)  <span class='arw'>&rarr;</span> 123
(* x 123)  <span class='arw'>&rarr;</span> 0

; comparisons with NaN values yield nil
(&gt; x 0)   <span class='arw'>&rarr;</span> nil
(&lt;= x 0)  <span class='arw'>&rarr;</span> nil
(= x x)   <span class='arw'>&rarr;</span> nil

(set 'infinity (mul 1.0e200 1.0e200)) <span class='arw'>&rarr;</span> inf
(NaN? (sub infinity infinity)) <span class='arw'>&rarr;</span> true
</pre>


<p>
Note that all floating point arithmetic operations 
with a <tt>NaN</tt> yield a <tt>NaN</tt>. 
All comparisons with <tt>NaN</tt> return <tt>nil</tt>, 
but <tt>true</tt> when comparing to itself. 
Comparison with itself, however, 
would result in <em>not</em> <tt>true</tt> when using ANSI C.  Integer operations 
treat <tt>NaN</tt> as <tt>0</tt> (zero) values.</p>

<p>See also <a href="#infp">inf?</a> for testing a floating point value for infinity.</p>

<br/><br/>

<a name="net-accept"></a>
<h2><span class="function">net-accept</span></h2>
<h4>syntax: (net-accept <em>int-socket</em>)</h4>

<p>
Accepts a connection on a socket 
previously put into listening mode. 
Returns a newly created socket handle 
for receiving and sending data 
on this connection.
</p>

<!-- example -->

<pre>
(set 'socket (net-listen 1234))
(net-accept socket)
</pre>


<p>
Note that for ports less than 1024, 
newLISP must be started in superuser mode
on Unix-like operating systems.
</p>

<p> See also the files <tt>server</tt> and <tt>client</tt> examples
in the <tt>examples/</tt> directory of the source distribution.</p>

<br/><br/>

<a name="net-close"></a>
<h2><span class="function">net-close</span></h2>
<h4>syntax: (net-close <em>int-socket</em> [<em>true</em>])</h4>

<p>
Closes a network socket in <em>int-socket</em> that 
was previously created by a 
<a href="#net-connect">net-connect</a> 
or <a href="#net-accept">net-accept</a> function. 
Returns <tt>true</tt> on success and 
<tt>nil</tt> on failure.
</p>

<!-- example -->

<pre>
(net-close aSock)
</pre>


<p>The optional <em>true</em> flag suppresses immediate shutdown
of sockets by waiting for pending data transmissions to finish.</p>

<br/><br/>

<a name="net-connect"></a>
<h2><span class="function">net-connect</span></h2>
<h4>syntax: (net-connect <em>str-remote-host</em> <em>int-port</em> [<em>int-timeout-ms</em>])<br/>
syntax: (net-connect <em>str-remote-host</em> <em>int-port</em> [<em>str-mode</em> [<em>int-ttl</em>]])<br/>
syntax: (net-connect <em>str-file-path</em>)</h4>

<p>In the first syntax, connects to a remote host computer specified in 
<em>str-remote-host</em> and a port specified in <em>int-port</em>. 
Returns a socket handle after having connected successfully; 
otherwise, returns <tt>nil</tt>.</p>

<!-- example -->

<pre>
(set 'socket (net-connect "example.com" 80))
(net-send socket "GET /\r\n\r\n")
(net-receive socket buffer 10000)
(println buffer)
(exit)
</pre>

<p>If successful, the <tt>net-connect</tt> function returns a socket
number which can be used to send and receive information from the host.
In the example a HTTP GET request is sent and subsequently a web page
received. Note that newLISP has already a built-in function 
<a href="#get-url">get-url</a> offering the same functionality.</p>

<p>Optionally a timeout value <em>int-timeout</em> in milliseconds
can be specified. Without a timeout value the function will wait up
to 10 seconds for an open port. With a timeout value the function can
be made to return on an unavailable port much earlier or later. The
following example shows a port scanner looking for open ports:</p>

<!-- example -->
<pre>
(set 'host (main-args 2))
(println "Scanning: " host)
(for (port 1 1024)
    (if (set 'socket (net-connect host port 500))
        (println "open port: " port " " (or (net-service port "tcp") ""))
        (print port "\r"))
)
</pre>

<p>The programs takes the host string from the shell command line as
either a domain name or an IP number in dot notation then tries to 
open each port from 1 to 1024. For each open port the port number and 
the service description string is printed. If no description is available,
an empty string "" is output. For closed ports the function outputs 
numbers in the shell window staying on the same line.</p>

<p>On Unix <tt>net-connect</tt> may return with <tt>nil</tt> before
the timeout expires, when the port is not available. On MS Windows 
<tt>net-connect</tt> will always wait for the timeout to expire before
failing with <tt>nil</tt>.</p>

<h3>UDP communications</h3>

<p>In the second syntax, a third parameter, the string <tt>"udp"</tt>
or <tt>"u"</tt> can be specified in the optional <em>str-mode</em> 
to create a socket suited for UDP (User Datagram Protocol) communications.
In UDP mode, <tt>net-connect</tt> does <em>not</em> try to connect 
to the remote host, but creates the socket and binds it to the
remote address, if an address is specified. 
A subsequent <a href="#net-send">net-send</a> will send a UDP packet 
containing that target address. 
When using <a href="#net-send-to">net-send-to</a>, only one of the
two functions <tt>net-connect</tt> or <tt>net-send-to</tt> should 
provide a target address. The other function should specify and empty
string <tt>""</tt> as the target address.</p>

<pre>
;; example server
(net-listen 4096 "226.0.0.1" "udp")  <span class='arw'>&rarr;</span> 5
(net-receive-from 5 20)

;; example client I
(net-connect "226.0.0.1" 4096 "udp") <span class='arw'>&rarr;</span> 3
(net-send 3 "hello")

;; example client II
(net-connect "" 4096 "udp") &rarr; 3
(net-send-to "226.0.0.1" 4096 "hello" 3)
</pre>

<p>The functions <a href="#net-receive">net-receive</a> and 
<a href="#net-receive-from">net-receive-from</a>
can both be used and will perform UDP communications when the <tt>"udp"</tt>
option as been used in <tt>net-listen</tt> or <tt>net-connect</tt>. 
<a href="#net-select">net-select</a> and <a href="#net-peek">net-peek</a> 
can be used to check for received data in a non-blocking fashion.</p>

<p><a href="#net-listen">net-listen</a> binds a specific 
local address and port to the socket. When <tt>net-connect</tt> is used,
the local address and port will be picked by the socket-stack 
functions of the host OS.</p>

<h3>UDP multicast communications</h3>

<p>When specifying <tt>"multi"</tt> 
or <tt>"m"</tt> as a third parameter for <em>str-mode</em>,
a socket for UDP multicast communications 
will be created. 
Optionally, the fourth parameter
<tt>int-ttl</tt> can be specified 
as a TTL (time to live) value. 
If no <em>int-ttl</em> value is specified, 
a value of 3 is assumed.
</p>

<p>
Note that specifying UDP multicast mode 
in <tt>net-connect</tt> does not actually establish 
a connection to the target multicast address 
but only puts the socket into UDP multicasting mode. 
On the receiving side, 
use <a href="#net-listen">net-listen</a> 
together with the UDP multicast option.
</p>

<!-- example -->

<pre>
;; example client I
(net-connect "" 4096 "multi")  <span class='arw'>&rarr;</span> 3
(net-send-to "226.0.0.1" 4096 "hello" 3)

;; example client II
(net-connect "226.0.0.1" 4096 "multi")  <span class='arw'>&rarr;</span> 3
(net-send 3 "hello")

;; example server
(net-listen 4096 "226.0.0.1" "multi")  <span class='arw'>&rarr;</span> 5
(net-receive-from 5 20)               
<span class='arw'>&rarr;</span> ("hello" "192.168.1.94" 32769)
</pre>


<p>
On the server side, <a href="#net-peek">net-peek</a> or <a href="#net-select">net-select</a>
can be used for non-blocking communications.  In the above example, the server would block
until a datagram is received.</p>

<p>The address <tt>226.0.0.1</tt> is just one multicast address 
in the Class D range of multicast addresses from <tt>224.0.0.0</tt> 
to <tt>239.255.255.255</tt>.</p>

<p>
The <a href="#net-send">net-send</a> and 
<a href="#net-receive">net-receive</a> functions
can also be used instead of <a href="#net-send-to">net-send-to</a> 
and <a href="#net-receive-from">net-receive-from</a>.
</p>


<h3>UDP broadcast communications</h3>

<p>
Specifying the string <tt>"broadcast"</tt> or <tt>"b"</tt> 
in the third parameter, <em>str-mode</em>, causes
UDP broadcast communications to be set up. 
In this case, the broadcast address 
ending in 255 is used.
</p>

<!-- example -->

<pre>
;; example client
(net-connect "192.168.2.255" 3000 "broadcast")  <span class='arw'>&rarr;</span> 3
(net-send 3 "hello")

;; example server
(net-listen 3000 "" "udp")  <span class='arw'>&rarr;</span> 5

(net-receive 5 buff 10)
buff  <span class='arw'>&rarr;</span> "hello"
;; or
(net-receive-from 5 10)
<span class='arw'>&rarr;</span> ("hello" "192.168.2.1" 46620)
</pre>


<p>
Note that on the receiving side, 
<a href="#net-listen">net-listen</a> should be used 
with the default address 
specified with an <tt>""</tt> (empty string). 
Broadcasts will not be received 
when specifying an address. 
As with all UDP communications, 
<a href="#net-listen">net-listen</a> does not actually put 
the receiving side in listen mode, 
but rather sets up the sockets 
for the specific UDP mode.
</p>

<p>
The <a href="#net-select">net-select</a> 
or <a href="#net-peek">net-peek</a> functions 
can be used to check for 
incoming communications 
in a non-blocking fashion.
</p>

<h3>Local domain Unix sockets</h3>

<p>In the third syntax, <tt>net-connect</tt> connects to a server on the 
local file system via a <em>local domain Unix socket</em> named using 
<em>str-file-path</em>.	Returns a socket handle after having connected 
successfully; otherwise, returns <tt>nil</tt>.
</p>

<!-- example -->

<pre>
(net-connect "/tmp/mysocket")  <span class='arw'>&rarr;</span> 3

; on OS/2 use "\\socket\\" prefix

(net-connect "\\socket\\mysocket")
</pre>


<p>A <em>local domain</em> file system socket is created and returned.
On the server side, <em>local domain</em> sockets have been created
using <a href="#net-listen">net-listen</a> and <a href="#net-accept">net-accept</a>.
After the connection has been established the functions <a href="#net-select">net-select</a>,
<a href="#net-send">net-send</a> and <a href="#net-receive">net-receive</a> can be used
as usual for TCP/IP stream communications. This type of connection can be used as a fast
bi-directional communications channel between processes on the same file system.
This type of connection is not available on MS Windows platforms.</p>

<br/><br/>

<a name="net-error"></a>
<h2><span class="function">net-error</span></h2>
<h4>syntax: (net-error)<br/>
syntax: (net-error <em>int-error</em>)</h4>

<p>Retrieves the last error that occurred when calling a any of the
following functions: <a href="#net-accept">net-accept</a>,
<a href="#net-connect">net-connect</a>,
<a href="#net-eval">net-eval</a>,
<a href="#net-listen">net-listen</a>,
<a href="#net-lookup">net-lookup</a>,
<a href="#net-receive">net-receive</a>,
<a href="#net-receive-udp">net-receive-udp</a>,
<a href="#net-select">net-select</a>,
<a href="#net-send">net-send</a>,
<a href="#net-send-udp">net-send-udp</a>,
and <a href="#net-service">net-service</a>. 
Whenever one of these functions fails, it returns <tt>nil</tt> and <tt>net-error</tt>
can be used to retrieve more information.</p>

<p>Functions that communicate using sockets close the socket automatically and 
remove it from the <a href="#net-sessions">net-sessions</a> list.</p>

<p>Each successful termination of a <a href="#socket_tcpip">net-*</a> 
function clears the error number.</p>

<p>The following messages are returned:</p>

<table summary="net-error">
<tr align="left"><th>no</th><th>description</th></tr>
<tr><td>1</td><td>Cannot open socket</td></tr>
<tr><td>2</td><td>DNS resolution failed</td></tr>
<tr><td>3</td><td>Not a valid service</td></tr>
<tr><td>4</td><td>Connection failed</td></tr>
<tr><td>5</td><td>Accept failed</td></tr>
<tr><td>6</td><td>Connection closed</td></tr>
<tr><td>7</td><td>Connection broken</td></tr>
<tr><td>8</td><td>Socket send() failed</td></tr>
<tr><td>9</td><td>Socket recv() failed</td></tr>
<tr><td>10</td><td>Cannot bind socket</td></tr>
<tr><td>11</td><td>Too many sockets in net-select</td></tr>
<tr><td>12</td><td>Listen failed</td></tr>
<tr><td>13</td><td>Badly formed IP</td></tr>
<tr><td>14</td><td>Select failed</td></tr>
<tr><td>15</td><td>Peek failed</td></tr>
<tr><td>16</td><td>Not a valid socket</td></tr>
<tr><td>17</td><td>Cannot unblock socket</td></tr>
<tr><td>18</td><td>Operation timed out</td></tr>
<tr><td>19</td><td>HTTP bad formed URL</td></tr>
<tr><td>20</td><td>HTTP file operation failed</td></tr>
<tr><td>21</td><td>HTTP transfer failed</td></tr>
<tr><td>22</td><td>HTTP invalid response from server</td></tr>
<tr><td>23</td><td>HTTP no response from server</td></tr>
<tr><td>24</td><td>HTTP no content</td></tr>
<tr><td>25</td><td>HTTP error in header</td></tr>
<tr><td>26</td><td>HTTP error in chunked format</td></tr>
</table><br/>

<br/><br/>
<!-- example -->

<pre>
(net-error) <span class='arw'>&rarr;</span> nil

(net-connect "jhghjgkjhg" 80)  <span class='arw'>&rarr;</span>  nil

(net-error)  <span class='arw'>&rarr;</span>  (2 "ERR: "DNS resolution failed") 
</pre>

<p>When <em>int-error</em> is specified the number and error text for
that error number is returned.</p>


<pre>
(net-error 10) <span class='arw'>&rarr;</span> (10 "Cannot bind socket")
</pre>


<p>See also <a href="#last-error">last-error</a> and <a href="#sys-error">sys-error</a>.</p>

<br/><br/>

<a name="net-eval"></a>
<h2><span class="function">net-eval</span></h2> 
<h4>syntax: (net-eval <em>str-host</em> <em>int-port</em> <em>exp</em> [<em>int-timeout</em> [<em>func-handler</em>]])<br/>
syntax: (net-eval '((<em>str-host</em> <em>int-port</em> <em>exp</em>) ... )  [<em>int-timeout</em> [<em>func-handler</em>]])</h4>

<p>Can be used to evaluate source remotely on one or more newLISP servers. 
This function handles all communications necessary to connect to the remote servers, 
send source for evaluation, and wait and collect responses.</p>

<p>The expression in <em>exp</em> will be evaluated remotely in the environment 
of the target node. The <em>exp</em> is either a quoted expression, or it is 
enclosed in string delimiters. For bigger expressions <tt>[text] ... [/text]</tt> 
delimiters can be used instead of double quotes <tt>" ... "</tt>.  Only one 
expression should be enclosed in the string. When more than one are specified,
all will get evaluated in the target node, but only the result of the first 
will be returned.</p>

<p>The remote TCP/IP servers are started in the following way:</p>


<pre>
newlisp -c -d 4711 &amp;

; preloading function definitions

newlisp preload.lsp -c -d 12345 &amp;

; logging connections

newlisp -l -c -d 4711 &amp;

; communicating via Unix local domain sockets

newlisp -c /tmp/mysocket
</pre>

<p>The <tt>-c</tt> option is necessary to suppress newLISP emitting
prompts.</p>

<p>The <tt>-d</tt> daemon mode allows newLISP to maintain state between 
connections.  When keeping state between connections is not desired, 
the <a href="#inetd_daemon">inetd daemon mode</a> offers more advantages. 
The Internet <tt>inetd</tt> or <tt>xinetd</tt> services daemon 
will start a new newLISP process for each client connection. 
This makes for much faster servicing of multiple connections. 
In <tt>-d</tt> daemon mode, each new client request 
would have to wait for the previous request to be finished. 
See the chapter <a href="#inetd_daemon">inetd daemon mode</a> 
on how to configure this mode correctly.</p>

<p>Instead of <tt>4711</tt>, any other port number can be used. 
Multiple nodes can be started on different hosts and with the same 
or different port numbers.  The <tt>-l</tt> or <tt>-L</tt> logging options
can be specified to log connections and remote commands.</p>


<p>In the first syntax, <tt>net-eval</tt> talks to only one 
remote newLISP server node, sending the host in <em>str-host</em>
on port <em>int-port</em> a request to evaluate the expression 
<em>exp</em>.  If <em>int-timeout</em> is not given, 
<tt>net-eval</tt> will wait up to 60 seconds for a response
after a connection is made.
Otherwise, if the timeout in milliseconds has expired, 
<tt>nil</tt> is returned; else, the evaluation result of <em>exp</em> 
is returned.</p>

<!-- example -->

<pre>
; the code to be evaluated is given in a quoted expression
(net-eval "192.168.1.94" 4711 '(+ 3 4))       <span class='arw'>&rarr;</span> 7

; expression as a string (only one expression should be in the string)
(net-eval "192.168.1.94" 4711 "(+ 3 4)")      <span class='arw'>&rarr;</span> 7

; with timeout
(net-eval "192.168.1.94" 4711 '(+ 3 4) 1)     <span class='arw'>&rarr;</span> nil  ; 1ms timeout too short
(net-error)                                   <span class='arw'>&rarr;</span> (17 "ERR: Operation timed out")

(net-eval "192.168.1.94" 4711 '(+ 3 4) 1000)  <span class='arw'>&rarr;</span> 7

; program contained in a variable
(set 'prog '(+ 3 4))
(net-eval "192.168.1.94" 4711 prog)           <span class='arw'>&rarr;</span> 7

; specify a local-domain Unix socket (not available on MS Windows)
(net-eval "/tmp/mysocket" 0 '(+ 3 4))         <span class='arw'>&rarr;</span> 7
</pre>


<p>The second syntax of <tt>net-eval</tt> returns a list of the results
after all of the responses are collected or timeout occurs. Responses that 
time out return <tt>nil</tt>.  The last example line shows how to specify
a local-domain Unix socket specifying the socket path and a port number of 
<tt>0</tt>.  Connection errors or errors that occur when sending information 
to nodes are returned as a list of error numbers and descriptive error 
strings.  See the function <a href="#net-error">net-error</a> for a list of 
potential error messages.</p>

<!-- example -->

<pre>
; two different remote nodes different IPs
(net-eval '(
    ("192.168.1.94" 4711 '(+ 3 4)) 
    ("192.168.1.95" 4711 '(+ 5 6))
    ) 5000)
<span class='arw'>&rarr;</span> (7 11)

; two persistent nodes on the same CPU different ports
(net-eval '(
    ("localhost" 8081 '(foo "abc")) 
    ("localhost" 8082 '(myfunc 123)') 
    ) 3000)

; inetd or xinetd nodes on the same server and port
; nodes are loaded on demand
(net-eval '(
    ("localhost" 2000 '(foo "abc")) 
    ("localhost" 2000 '(myfunc 123))
    ) 3000)
</pre>


<p>The first example shows two expressions evaluated on two different remote 
nodes. In the second example, both nodes run on the local computer. This may 
be useful when debugging or taking advantage of multiple CPUs on the same 
computer.  When specifying <tt>0</tt> for the port number , <tt>net-eval</tt> 
takes the host name as the file path to the local-domain Unix socket.</p>

<p>Note that definitions of <tt>foo</tt> and <tt>myfunc</tt> must both
exist in the target environment. This can be done using a <tt>net-eval</tt>
sending <tt>define</tt> statements before. It also can be done by
preloading code when starting remote nodes.</p>

<p>When nodes are inetd or xinetd-controlled, several nodes may have the 
same IP address and port number. In this case, the Unix 
daemon inetd or xinetd will start multiple newLISP servers on demand. 
This is useful when testing distributed programs on just one machine. 
The last example illustrates this case. It is also useful on multi core
CPUs, where the platform OS can distribute different processes on to different
CPU cores.</p>

<p>The source sent for evaluation can consist of entire multiline programs. 
This way, remote nodes can be loaded with programs first, then specific 
functions can be called.  For large program files, the functions 
<a href="#put-url">put-url</a> or <a href="#save">save</a> (with a URL 
file name) can be used to transfer programs. The a <tt>net-eval</tt>
statement could load these programs.</p>

<p>Optionally, a handler function can be specified. This function will be 
repeatedly called while waiting and once for every remote evaluation completion.</p>

<!-- example -->

<pre>
(define (myhandler param)
    (if param
        (println param))
)

(set 'Nodes '(
    ("192.168.1.94" 4711)
    ("192.168.1.95" 4711)
))

(set 'Progs '(
    (+ 3 4)
    (+ 5 6)
))

(net-eval (map (fn (n p) (list (n 0) (n 1) p)) Nodes Progs) 5000 myhandler)
<span class='arw'>&rarr;</span>
("192.168.1.94" 4711 7)
("192.168.1.95" 4711 11)
</pre>

<p>The example shows how the list of node specs can be assembled from a list 
of nodes and sources to evaluate. This may be useful when connecting to a 
larger number of remote nodes.</p>

<pre>
(net-eval (list 
  (list (Nodes 0 0) (Nodes 0 1) (Progs 0)) 
  (list (Nodes 1 0) (Nodes 1 1) (Progs 1)) 
 ) 3000 myhandler)
</pre>

<p>While waiting for input from remote hosts, <tt>myhandler</tt> will be called 
with <tt>nil</tt> as the argument to <tt>param</tt>.  When a remote node result 
is completely received, <tt>myhandler</tt> will be called with <tt>param</tt> 
set to a list containing the remote host name or IP number, the port, and the 
resulting expression. <tt>net-eval</tt> will return <tt>true</tt> before a 
timeout or <tt>nil</tt> if the timeout was reached or exceeded.  All remote hosts 
that exceeded the timeout limit will contain a <tt>nil</tt> in their results list.
</p>

<p>For a longer example see this program:
<a href="http://www.newlisp.org/syntax.cgi?code/mapreduce.txt">mapreduce</a>.
The example shows how a word counting task gets distributed to three remote
nodes. The three nodes count words in different texts and the master node
receives and consolidates the results.</p>

<br/><br/>

<a name="net-interface"></a>
<h2><span class="function">net-interface</span></h2>
<h4>syntax: (net-interface <em>str-ip-addr</em>)<br/>
syntax: (net-interface)</h4>

<p>Sets the default local interface address to be used for network connections.
If not set then network functions will default to an internal default address,
except when overwritten by an optional interface address given in 
<a href="#net-listen">net-listen</a>.</p>

<p>When no <em>str-ip-addr</em> is specified, the current default is returned.
If the <tt>net-interface</tt> has not been used yet to specify an IP address,
the address <tt>0.0.0.0</tt> is returned. This means that all network routines
will use the default address preconfigured by the underlying operating system.</p>

<p>This function has only usage on multihomed servers with either multiple network 
interface hardware or otherwise supplied multiple IP numbers. On all other machines 
network functions will automatically select the single network interface installed.</p>

<p>On error the function returns <tt>nil</tt> and <a href="#net-error">net-error</a>
can be used to report the error.</p>

<!-- example -->

<pre>
(net-interface "192.168.1.95")  <span class='arw'>&rarr;</span> "192.168.1.95"
(net-interface "localhost")     <span class='arw'>&rarr;</span> "127.0.0.1"
</pre>


<p>An interface address can be defined as either an IP address or a name. The
return value is the address given in <em>str-ip-addr</em></p>

<br/><br/>

<a name="net-ipv"></a>
<h2><span class="function">net-ipv</span></h2>
<h4>syntax: (net-ipv <em>int-version</em>)<br/>
syntax: (net-ipv)</h4>

<p>Switches between IPv4 and IPv6 internet protocol versions. 
<em>int-version</em> contains either a 4 for IPv4 or a 6 for IPv6. When no 
parameter is given, <tt>net-ipv</tt> returns the current setting.</p>

<!-- example -->

<pre>
(net-ipv)      <span class='arw'>&rarr;</span> 4
(net-ipv 6)    <span class='arw'>&rarr;</span> 6
</pre>

<p>By default newLISP starts up in IPv4 mode. The IPv6 protocol mode can also 
be specified from the commandline when starting newlisp:</p>

<pre>
newlisp -6
</pre>

<p>Once a socket is connected with either 
<a href="#net-connect">net-connect</a> 
or listened on with 
<a href="#net-listen">net-listen</a>, the 
<a href="#net-accept">net-accept</a>, <a href="#net-select">net-select</a>, 
<a href="#net-send">net-send</a>, <a href="#net-receive">net-receive</a> and 
<a href="#net-receive-from">net-receive-from</a> 
functions automatically adjust to the address protocol used when creating the sockets.

Different connections with different IPv4/6 settings can be open at the same time.</p>

<p>Note, that currently <a href="#net-packet">net-packet</a> does not support IPv6 and will 
work in IPv4 mode regardless of settings.</p>

<br/><br/>

<a name="net-listen"></a>
<h2><span class="function">net-listen</span></h2>
<h4>syntax: (net-listen <em>int-port</em> [<em>str-ip-addr</em> [<em>str-mode</em>]])<br/>
syntax: (net-listen <em>str-file-path</em>)</h4>

<p>Listens on a port specified in <em>int-port</em>.  A call to <tt>net-listen</tt>
returns immediately with a socket number, which is then used by 
the blocking <a href="#net-accept">net-accept</a> function 
to wait for a connection.  As soon as a connection is accepted, 
<a href="#net-accept">net-accept</a> returns a socket number 
that can be used to communicate with the connecting client.</p>


<!-- example -->

<pre>
(set 'port 1234)
(set 'listen (net-listen port))
(unless listen (begin
    (print "listening failed\n")
    (exit)))

(print "Waiting for connection on: " port "\n")

(set 'connection (net-accept listen))
(if connection
    (while (net-receive connection buff 1024 "\n")
        (print buff)
        (if (= buff "\r\n") (exit)))
    (print "Could not connect\n"))
</pre>


<p>The example waits for a connection on port 1234, then reads incoming lines 
until an empty line is received.  Note that listening on ports lower than 1024
may require superuser access on Unix systems.</p>

<p>On computers with more than one interface card, specifying an optional 
interface IP address or name in <em>str-ip-addr</em> directs <tt>net-listen</tt> 
to listen on the specified address.</p>


<pre>
;; listen on a specific address
(net-listen port "192.168.1.54") 
</pre>


<h3>Local domain Unix sockets</h3>

<p>In the second syntax, <tt>net-listen</tt> listens for a client on the 
local file system via a <em>local domain Unix socket</em> named using 
<em>str-file-path</em>.	If successful, returns a socket handle that can be 
used with <a href="#net-accept">net-accept</a> to accept a client connection; 
otherwise, returns <tt>nil</tt>.</p>

<!-- example -->

<pre>
(net-listen "/tmp/mysocket")  <span class='arw'>&rarr;</span> 5

; on OS/2 use "\\socket\\" prefix

(net-listen "\\socket\\mysocket")

(net-accept 5)
</pre>


<p>A <em>local domain</em> file system socket is created and listened on.
A client will try to connect using the same <em>str-file-path</em>.
After a connection has been accepted the functions <a href="#net-select">net-select</a>,
<a href="#net-send">net-send</a> and <a href="#net-receive">net-receive</a> can be used 
as usual for TCP/IP stream communications. This type of connection can be used as a fast
 bi-directional communications channel between processes on the same file system.
This type of connection is not available on MS Windows platforms.</p>


<h3>UDP communications</h3>

<p>
As a third parameter, 
the optional string <tt>"udp"</tt> or <tt>"u"</tt> 
can be specified in <em>str-mode</em> 
to create a socket suited for UDP 
(User Datagram Protocol) communications.
A socket created in this way 
can be used directly with 
<a href="#net-receive-from">net-receive-from</a>
to await incoming UDP data 
<em>without</em> using <tt>net-accept</tt>, 
which is only used in TCP communications. 
The <a href="#net-receive-from">net-receive-from</a> call 
will block until a UDP data packet is received. 
Alternatively, <a href="#net-select">net-select</a> 
or <a href="#net-peek">net-peek</a> can be used 
to check for ready data in a non-blocking fashion. 
To send data back to the address and port received 
with <a href="#net-receive-from">net-receive-from</a>, 
use <a href="#net-send-to">net-send-to</a>.
</p>

<p>
Note that <a href="#net-peer">net-peer</a> will not work, 
as UDP communications do not maintain 
a connected socket with address information.
</p>


<pre>
(net-listen 10002 "192.168.1.120" "udp") 

(net-listen 10002 "" "udp") 
</pre>


<p>
The first example listens on a specific network adapter, 
while the second example listens on the default adapter. 
Both calls return a socket number 
that can be used in subsequent <a href="#net-receive">net-receive</a>,
<a href="#net-receive-from">net-receive-from</a>, 
<a href="#net-send-to">net-send-to</a>,
<a href="#net-select">net-select</a>, 
or <a href="#net-peek">net-peek</a> function calls.
</p>

<p>
Both a UDP server <em>and</em> UDP client 
can be set up using <tt>net-listen</tt> 
with the <tt>"udp"</tt> option. 
In this mode, <tt>net-listen</tt> 
does not really <em>listen</em>
as in TCP/IP communications; 
it just binds the socket 
to the local interface address and port.
</p>

<p>
For a working example, see the files 
<tt>examples/client</tt> and <tt>examples/server</tt>
in the newLISP source distribution.
</p>

<p>
Instead of <tt>net-listen</tt> 
and the <tt>"udp"</tt> option,
the functions <a href="#net-receive-udp">net-receive-udp</a>  
and <a href="#net-send-udp">net-send-udp</a>
can be used for short transactions 
consisting only of one data packet.
</p>

<p>
<tt>net-listen</tt>, <a href="#net-select">net-select</a>, 
and <a href="#net-peek">net-peek</a> can be used 
to facilitate non-blocking reading. 
The listening/reading socket is not closed 
but is used again for subsequent reads. 
In contrast, when the 
<a href="#net-receive-udp">net-receive-udp</a> 
and <a href="#net-send-udp">net-send-udp</a> pair is used, 
both sides close the sockets after sending and receiving.
</p>


<h3>UDP multicast communications</h3>

<p>
If the optional string <em>str-mode</em> is specified as 
<tt>"multi"</tt> or <tt>"m"</tt>, 
<tt>net-listen</tt> returns a socket suitable for multicasting. 
In this case, <em>str-ip-addr</em> contains one 
of the multicast addresses in the range <tt>224.0.0.0</tt> 
to <tt>239.255.255.255</tt>.
<tt>net-listen</tt> will register <em>str-ip-addr</em> 
as an address on which to receive multicast transmissions. 
This address should not be confused with the IP address 
of the server host.
</p>


<!-- example -->

<pre>
;; example client

(net-connect "226.0.0.1" 4096 "multi")  <span class='arw'>&rarr;</span> 3

(net-send-to "226.0.0.1" 4096 "hello" 3)


;; example server

(net-listen 4096 "226.0.0.1" "multi")  <span class='arw'>&rarr;</span> 5

(net-receive-from 5 20)               
<span class='arw'>&rarr;</span> ("hello" "192.168.1.94" 32769)
</pre>


<p>On the server side, 
<a href="#net-peek">net-peek</a> or <a href="#net-select">net-select</a>
can be used for non-blocking communications.  In the example above, 
the server would block until a datagram is received.</p>

<p>
The <a href="#net-send">net-send</a> 
and <a href="#net-receive">net-receive</a> functions 
can be used instead of <a href="#net-send-to">net-send-to</a> 
and <a href="#net-receive-from">net-receive-from</a>.
</p>


<h3>Packet divert sockets and ports</h3>

<p>If <em>str-mode</em> is specified as <tt>"divert"</tt> or <tt>"d"</tt>, 
a divert socket can be created for a divert port in <em>int-port</em> on 
BSD like platforms.  The content of IP address in <em>str-ip-addr</em> is 
ignored and can be specified as an empty string. Only the <em>int-port</em> 
is relevant and will be bound to the raw socket returned.</p>

<p>To use the divert option in <tt>net-listen</tt>, newLISP must run in
super-user mode. This option is only available on Unix like platforms.</p>

<p>The divert socket will receive all raw packets diverted 
to the divert port. Packets may also be written back to a divert socket, 
in which case they re-enter OS kernel IP packet processing.</p>

<p>Rules for packet diversion to the divert port must be defined using 
either the <em>ipfw</em> BSD or <em>ipchains</em> Linux configuration
utilities.</p>

<p>The <a href="#net-receive-from">net-receive-from</a> and
<a href="#net-send-to">net-send-to</a> functions are used to read
and write raw packets on the divert socket created and returned by the
<tt>net-listen</tt> statement. The same address received by
<a href="#net-receive-from">net-receive-from</a> is used in the 
<a href="#net-send-to">net-send-to</a> call when re-injecting the 
packet:</p>

<pre>
; rules have been previously configured for a divert port
(set 'divertSocket (net-listen divertPort "" "divert"))

(until (net-error)
    (set 'rlist (net-receive-from divertSocket maxBytes))
    (set 'buffer (rlist 1))
    ; buffer can be processed here before reinjecting
    (net-send-to (rlist 0) divertPort buffer divertSocket)
)
</pre>

<p>For more information see the Unix man pages for <em>divert</em>
and the <em>ipfw</em> (BSDs) or <em>ipchains</em> (Linux) configuration 
utilities.</p>

<br/><br/>

<a name="net-local"></a>
<h2><span class="function">net-local</span></h2>
<h4>syntax: (net-local <em>int-socket</em>)</h4>

<p>Returns the IP number and port of the local computer 
for a connection on a specific <em>int-socket</em>.</p>

<!-- example -->

<pre>
(net-local 16)  <span class='arw'>&rarr;</span> ("204.179.131.73" 1689)
</pre>

<p>
Use the <a href="#net-peer">net-peer</a> 
function to access the remote computer's 
IP number and port.
</p>

<br/><br/>

<a name="net-lookup"></a>
<h2><span class="function">net-lookup</span></h2>

<h4>syntax: (net-lookup <em>str-ip-number</em>)<br/>
syntax: (net-lookup <em>str-hostname</em> [<em>bool</em>])</h4>


<p>
Returns either a hostname string 
from <em>str-ip-number</em> 
in IP dot format or the IP number 
in dot format from <em>str-hostname</em>:
</p>

<!-- example -->

<pre>
(net-lookup "209.24.120.224")    <span class='arw'>&rarr;</span> "www.nuevatec.com"
(net-lookup "www.nuevatec.com")  <span class='arw'>&rarr;</span> "209.24.120.224"

(net-lookup "216.16.84.66.sbl-xbl.spamhaus.org" true)
<span class='arw'>&rarr;</span> "216.16.84.66"
</pre>


<p>
Optionally,	a <em>bool</em> flag 
can be specified in the second syntax. 
If the expression in <em>bool</em> 
evaluates to anything other than <tt>nil</tt>,
host-by-name lookup will be forced, 
even if the name string starts 
with an IP number.
</p>

<br/><br/>

<a name="net-packet"></a>
<h2><span class="function">net-packet</span></h2>
<h4>syntax: (net-packet <em>str-packet</em>)</h4>

<p>The function allows custom configured network packets to be sent via
a <em>raw sockets</em> interface. The packet in <em>str-packet</em> must
start with an IP (Internet Protocol) header followed by either
a TCP, UDP or ICMP header and optional data. newLISP must be run with
super user privileges, and this function is only available on macOS,
Linux and other Unix operating systems and only for IPv4.
Currently <tt>net-packet</tt> is IPv4 only and has been tested on
macOS, Linux and OpenBSD.</p> 

<p>On success the function returns the number of bytes sent. On failure
the function returns <tt>nil</tt> and both, <a href="#net-error">net-error</a>
and <a href="#sys-error">sys-error</a>, should be inspected.</p>

<p>When custom configured packets contain zeros in the checksum fields,
<tt>net-packet</tt> will calculate and insert the correct checksums. 
Already existing checksums stay untouched.</p>

<p>The following example injects a UDP packet for IP number <tt>192.168.1.92</tt>.
The IP header consists of 20 bytes ending with the target IP number. The following
UDP header has a length of 8 bytes and is followed by the data string
<tt>Hello World</tt>. The checksum bytes in both headers are left as 
<tt>0x00 0x00</tt> and will be recalculated internally.</p>

<!-- example -->

<pre>
; packet as generated by: (net-send-udp "192.168.1.92" 12345 "Hello World")

(set 'udp-packet (pack (dup "b" 39) '(
    0x45 0x00 0x00 0x27 0x4b 0x8f 0x00 0x00 0x40 0x11 0x00 0x00 192  168  1    95
    192  168  1    92   0xf2 0xc8 0x30 0x39 0x00 0x13 0x00 0x00 0x48 0x65 0x6c 0x6c
    0x6f 0x20 0x57 0x6f 0x72 0x6c 0x64)))

(unless (net-packet udp-packet)
    (println "net-error: " (net-error))
    (println "sys-error: " (sys-error)))
</pre>

<p>The <tt>net-packet</tt> function is used when testing net security. 
Its wrong application can upset the correct functioning of network routers and 
other devices connected to a network. For this reason the function should only 
be used on well isolated, private intra-nets and only by network professionals.</p>

<p>For other examples of packet configuration, see the file 
<tt>qa-specific-tests/qa-packet</tt> in the newLISP source distribution.</p>

<br/><br/>

<a name="net-peek"></a>
<h2><span class="function">net-peek</span></h2>
<h4>syntax: (net-peek <em>int-socket</em>)</h4>

<p>
Returns the number of bytes 
ready for reading 
on the network socket <em>int-socket</em>.
If an error occurs 
or the connection is closed,
<tt>nil</tt> is returned.
</p>

<!-- example -->

<pre>
(set 'aSock (net-connect "aserver.com" 123))

(while ( = (net-peek aSock) 0) 
    (do-something-else))

(net-receive aSock buff 1024)
</pre>


<p>
After connecting, the program 
waits in a while loop 
until <tt>aSock</tt> can be read.
</p>

<p>
Use the <a href="#peek">peek</a> function
to check file descriptors and <tt>stdin</tt>.
</p>

<br/><br/>

<a name="net-peer"></a>
<h2><span class="function">net-peer</span></h2>
<h4>syntax: (net-peer <em>int-socket</em>)</h4>

<p>
Returns the IP number and port number 
of the remote computer 
for a connection on <em>int-socket</em>.
</p>

<!-- example -->

<pre>
(net-peer 16)  <span class='arw'>&rarr;</span> ("192.100.81.100" 13)
</pre>


<p>
Use the <a href="#net-local">net-local</a> function
to access the local computer's IP number and port number.
</p>

<br/><br/>

<a name="net-ping"></a>

<h2><span class="function">net-ping</span></h2>
<h4>syntax: (net-ping <em>str-address</em> [<em>int-timeout</em> [<em>int-count</em> <em>bool</em>]]])<br/>
syntax: (net-ping <em>list-addresses</em> [<em>int-timeout</em> [<em>int-count</em> <em>bool</em>]]])</h4>

<p> This function is only available on Unix-based systems 
and must be run in superuser mode, i.e. using: <tt>sudo newlisp</tt> to
start newLISP on macOS or other BSD's, or as the root user on Linux.
 Broadcast mode and specifying ranges with the <tt>-</tt> (hyphen) or
<em>*</em> (star) are not available on IPv6 address mode.</p>

<p>Superuser mode is not required on macOS.</p>

<p> In the first syntax, <tt>net-ping</tt> sends a ping 
ICMP 64-byte echo request to the address specified in <em>str-address</em>. 
If it is a broadcast address, the ICMP packet will be received 
by all addresses on the subnet.  Note that for security reasons, 
many computers do not answer ICMP broadcast ping (ICMP_ECHO) requests. 
An optional timeout parameter can be specified in <em>int-timeout</em>.
If no timeout is specified, a waiting time of 1000 milliseconds 
(one second) is assumed.</p> 

<p> <tt>net-ping</tt> returns either a list of lists of IP strings 
and round-trip time in microseconds for which a response was received 
or an empty list if no response was received.</p>

<p>
A return value of <tt>nil</tt> 
indicates a failure. 
Use the <a href="#net-error">net-error</a> function 
to retrieve the error message.  If the message reads <tt>Cannot open socket</tt>, 
it is probably because newLISP is running without root permissions. 
newLISP can be started using:
</p>

<pre>
sudo newlisp
</pre>

<p>
Alternatively, newLISP can be installed 
with the set-user-ID bit set to run 
in superuser mode.
</p>

<!-- example -->

<pre>
(net-ping "newlisp.org")     <span class='arw'>&rarr;</span> (("66.235.209.72" 634080))
(net-ping "127.0.0.1")       <span class='arw'>&rarr;</span> (("127.0.0.1" 115))
(net-ping "yahoo.com" 3000)  <span class='arw'>&rarr;</span> nil
</pre>


<p>
In the second syntax, <tt>net-ping</tt> is run in <em>batch mode</em>. 
Only one socket is opened in this mode, but multiple ICMP packets are sent out&mdash;one 
each to multiple addresses specified in a list or specified by range.
Packets are sent out as fast as possible.  In this case, multiple answers can be received.
If the same address is specified multiple times, the receiving IP address will be flooded
with ICMP packets.</p>

<p>
To limit the number of responses to be waited for in broadcast or batch mode,
an additional argument indicating the maximum number of responses to receive
can be specified in <em>int-count</em>.  Usage of this parameter can cause 
the function to return sooner than the specified timeout. 
When a given number of responses has been received, <tt>net-ping</tt> will return  
before the timeout has occurred. Not specifying <em>int-count</em> or specifying <tt>0</tt>
assumes an <em>int-count</em> equal to the number of packets sent out.</p>

<p>As third optional parameter, a <tt>true</tt> value can be specified. This setting will
return an error string instead of the response time, if the host does not answer.</p>

<!-- example -->

<pre>
(net-ping '("newlisp.org" "192.168.1.255") 2000 20)
<span class='arw'>&rarr;</span> (("66.235.209.72" 826420) ("192.168.1.1" 124) ("192.168.1.254" 210))

(net-ping "192.168.1.*" 500) ; from 1 to 254
<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))

(net-ping "192.168.1.*" 500 2) ; returns after 2 responses
<span class='arw'>&rarr;</span> (("192.168.1.3" 115) ("192.168.1.1" 145))

(net-ping "192.168.1.1-10" 1000) ; returns after 1 second
<span class='arw'>&rarr;</span> (("192.168.1.3" 196) ("192.168.1.1" 205))

(net-ping '("192.168.1.100-120" "192.168.1.124-132") 2000) ; returns after 2 seconds
<span class='arw'>&rarr;</span> ()
</pre>



<p>
Broadcast or batch mode&mdash;as well as normal addresses 
and IP numbers or hostnames&mdash; can be mixed in one <tt>net-ping</tt> statement by 
putting all of the IP specs into a list.</p> 

<p>
The second and third lines show how the batch mode of <tt>net-ping</tt> 
can be initiated by specifying the <tt>*</tt> (asterisk) 
as a wildcard character for the last subnet octet
in the IP number. The fourth and fifth lines show how an IP
range can be specified for the last subnet octet in the IP number.
<tt>net-ping</tt> will iterate through all numbers 
from either 1 to 254 for the star <tt>*</tt> or the range specified, 
sending an ICMP packet to each address. 
Note that this is different from the <em>broadcast</em> mode 
specified with an IP octet of <tt>255</tt>. 
While in broadcast mode, <tt>net-ping</tt> sends out only one packet, 
which is received by multiple addresses.  Batch mode explicitly generates 
multiple packets, one for each target address. When specifying broadcast
mode, <em>int-count</em> should be specified, too.</p>

<p>
When sending larger lists of IPs in batch mode over one socket, 
a longer timeout may be necessary to allow enough time for all of the packets 
to be sent out over one socket.  If the timeout is too short, 
the function <tt>net-ping</tt> may return an incomplete list or the empty list <tt>()</tt>.
In this case, <a href="#net-error">net-error</a> will return a timeout error.
On error, <tt>nil</tt> is returned and  <a href="#net-error">net-error</a>
can be used to retrieve an error message.</p>

<p>
On some systems only lists up to a specific length can be handled 
regardless of the timeout specified. In this case, the range should
 be broken up into sub-ranges and used with multiple <tt>net-ping</tt>
invocations. In any case, <tt>net-ping</tt> will send out packages 
as quickly as possible.
</p>

<br/><br/>

<a name="net-receive"></a>
<h2><span class="function">net-receive</span>&nbsp;<a href="#destructive">!</a></h2>
<h4>syntax: (net-receive <em>int-socket</em> <em>sym-buffer</em> <em>int-max-bytes</em> [<em>wait-string</em>])</h4>

<p>
Receives data on the socket <em>int-socket</em> into a string contained in <em>sym-buffer</em>. 
<em>sym-buffer</em> can also be a default functor specified by a context symbol 
for reference passing in and out of user-defined functions.</p>

<p> A maximum of 
<em>int-max-bytes</em> is received. <tt>net-receive</tt> returns the number of 
bytes read.  If there is a break in the connection, <tt>nil</tt> is returned. 
The space reserved in <em>sym-buffer</em> is exactly the size of bytes read.</p>

<p>
Note that <tt>net-receive</tt> is a blocking call 
and does not return until the data arrives at <em>int-socket</em>. 
Use <a href="#net-peek">net-peek</a> 
or <a href="#net-select">net-select</a> to find out 
if a socket is ready for reading.
</p>

<p>
Optionally, a <em>wait-string</em> 
can be specified 
as a fourth parameter. 
<tt>net-receive</tt> then returns after 
a character or string of characters 
matching <em>wait-string</em>
is received. 
The <em>wait-string</em> will be part 
of the data contained in <em>sym-buffer</em>.
</p>

<!-- example -->

<pre>
(define (gettime)
    (set 'socket (net-connect "netcom.com" 13))
    (net-receive socket buf 256)
    (print buf "\n")
    (net-close socket))
</pre>


<p>
When calling <tt>gettime</tt>, 
the program connects to port 13 
of the server netcom.com. 
Port 13 is a date-time service 
on most server installations. 
Upon connection, the server sends 
a string containing the date and time of day.
</p>


<pre>
(define (net-receive-line socket sBuff)
    (net-receive socket sBuff 256 "\n"))

(set 'bytesReceived (net-receive-line socket 'sm))
</pre>


<p>
The second example defines a new function 
<tt>net-receive-line</tt>, 
which returns after receiving a newline character 
(a string containing one character in this example) 
or 256 characters. 
The "\n" string is part of the contents of sBuff.
</p>

<p>
Note that when the fourth parameter is specified, 
<tt>net-receive</tt> is slower than the normal version 
because information is read character-by-character. 
In most situations, the speed difference can be neglected.
</p>

<br/><br/>

<a name="net-receive-from"></a>
<h2><span class="function">net-receive-from</span></h2>
<h4>syntax: (net-receive-from <em>int-socket</em> <em>int-max-size</em>)</h4>

<p>
<tt>net-receive-from</tt> can be used to set up 
non-blocking UDP communications. 
The socket in <em>int-socket</em> 
must previously have been opened 
by either <a href="#net-listen">net-listen</a> 
or <a href="#net-connect">net-connect</a> 
(both using the <tt>"udp"</tt> option).
<em>int-max-size</em> specifies 
the maximum number of bytes that will be received. 
On Linux/BSD, if more bytes are received, 
those will be discarded; on MS Windows, <tt>net-receive-from</tt>
returns <tt>nil</tt> and closes the socket.
</p>

<p>On success <tt>net-receive</tt> returns a list of the data string, remote 
IP number and remote port used. On failure it returns <tt>nil</tt>.</p>

<!-- example -->

<pre>
;; bind port 1001 and the default address
(net-listen 1001 "" "udp")  <span class='arw'>&rarr;</span> 1980 

;; optionally poll for arriving data with 100ms timeout
(while (not (net-select 1980 "r" 100000)) (do-something ... ))

(net-receive-from 1980 20)  <span class='arw'>&rarr;</span> ("hello" "192.168.0.5" 3240)

;; send answer back to sender
(net-send-to "192.168.0.5" 3240 "hello to you" 1980)

(net-close 1980) ; close socket
</pre>


<p>The second line in this example is optional.  Without it, the 
<tt>net-receive-from</tt> call would block until data arrives. 
A UDP server could be set up by listening and polling several ports, 
serving them as they receive data.</p>

<p>Both, the sender and the receiver have to issue 
<a href="#net-listen">net-listen</a> commands for UDP mode. Not for listening
as in TCP/IP protocol communications, but to create the socket bound to
the port and address. For a complete example see the files
<tt>udp-server.lsp</tt> and <tt>udp-client.lsp</tt> in the 
<tt>newlisp-x.x.x/examples/</tt> directory of the source distribution.</p>

<p>
Note that <tt>net-receive</tt> 
could not be used in this case 
because it does not return 
the sender's address and port information, 
which are required to talk back.
In UDP communications, 
the data packet itself 
contains the address of the sender,
<em>not</em> the socket over which 
communication takes place.
<tt>net-receive</tt> can also be used for TCP/IP communications.
</p>

<p>
See also the <a href="#net-connect">net-connect</a> function 
with the <tt>"udp"</tt> option and the 
<a href="#net-send-to">net-send-to</a> function 
for sending UDP data packets over open connections.
</p>

<p>
For blocking short UDP transactions, 
see the <a href="#net-send-udp">net-send-udp</a> 
and <a href="#net-receive-udp">net-receive-udp</a> functions.
</p>

<br/><br/>

<a name="net-receive-udp"></a>
<h2><span class="function">net-receive-udp</span></h2>
<h4>syntax: (net-receive-udp <em>int-port</em> <em>int-maxsize</em> [<em>int-microsec</em> [<em>str-addr-if</em>]])</h4>

<p>
Receives a User Datagram Protocol (UDP) packet on port <em>int-port</em>,
reading <em>int-maxsize</em> bytes. 
If more than <em>int-maxsize</em> bytes are received,
bytes over <em>int-maxsize</em> are discarded on Linux/BSD; 
on MS Windows, <tt>net-receive-udp</tt> returns <tt>nil</tt>.
<tt>net-receive-udp</tt> blocks until a datagram arrives 
or the optional timeout value in <em>int-microsec</em> expires. 
When setting up communications between datagram sender and receiver, 
the <tt>net-receive-udp</tt> statement must be set up first.
</p>


<p>
No previous setup using <tt>net-listen</tt> 
or <tt>net-connect</tt> is necessary.
</p>

<p>
<tt>net-receive-udp</tt> returns a list 
containing a string of the UDP packet 
followed by a string containing 
the sender's IP number and the port used.
</p>

<!-- example -->

<pre>
;; wait for datagram with maximum 20 bytes 
(net-receive-udp 10001 20) 

;; or
(net-receive-udp 10001 20 5000000)  ; wait for max 5 seconds
		  
;; executed on remote computer
(net-send-udp "nuevatec.com" 1001 "Hello")  <span class='arw'>&rarr;</span> 4 

;; returned from the net-receive-udp statement
<span class='arw'>&rarr;</span> ("Hello" "128.121.96.1" 3312)  

;; sending binary information
(net-send-udp "ahost.com" 2222 (pack "c c c c" 0 1 2 3))  
<span class='arw'>&rarr;</span> 4 

;; extracting the received info
(set 'buff (first (net-receive-udp 2222 10)))   

(print (unpack "c c c c" buff))  <span class='arw'>&rarr;</span> (0 1 2 3)
</pre>


<p>
See also the <a href="#net-send-udp">net-send-udp</a> 
function for sending datagrams and 
the <a href="#pack">pack</a> and <a href="#unpack">unpack</a> 
functions for packing and unpacking binary information.
</p>

<p>
To listen on a specified address 
on computers with more than one interface card, 
an interface IP address or name can be 
optionally specified in <em>str-addr-if</em>. 
When specifying <em>str-addr-if</em>, 
a timeout must also be specified
in <em>int-wait</em>.
</p>

<p>
As an alternative, UDP communication 
can be set up using <a href="#net-listen">net-listen</a>, 
or <a href="#net-connect">net-connect</a> 
together with the <tt>"udp"</tt> option 
to make non-blocking data exchange possible 
with <a href="#net-receive-from">net-receive-from</a> 
and <a href="#net-send-to">net-send-to</a>.
</p>

<br/><br/>

<a name="net-select"></a>
<h2><span class="function">net-select</span></h2>
<h4>syntax: (net-select <em>int-socket</em> <em>str-mode</em> <em>int-micro-seconds</em>)<br/>
syntax: (net-select <em>list-sockets</em> <em>str-mode</em> <em>int-micro-seconds</em>)</h4>

<p>
In the first form, 
<tt>net-select</tt> finds out about the status 
of one socket specified in  <em>int-socket</em>. 
Depending on <em>str-mode</em>, 
the socket can be checked 
if it is ready for reading or writing,
or if the socket has an error condition. 
A timeout value is specified in <em>int-micro-seconds</em>.
</p>

<p>
In the second syntax, 
<tt>net-select</tt> can check for a list of sockets 
in <em>list-sockets</em>.
</p>

<p>
The following value can be given for <em>str-mode</em>:
</p>


<tt>"read"</tt> or <tt>"r"</tt> to check if ready for reading or accepting.<br/>

<tt>"write"</tt> or <tt>"w"</tt> to check if ready for writing.<br/>
<tt>"exception"</tt> or <tt>"e"</tt> to check for an error condition.<br/>


<p>
Read, send, or accept operations 
can be handled without blocking
by using the <tt>net-select</tt> function. 
<tt>net-select</tt> waits 
for a socket to be ready 
for the value given in <em>int-micro-seconds</em>, 
then returns <tt>true</tt> or <tt>nil</tt>
depending on the readiness of the socket.
During the select loop, 
other portions of the program can run. 
On error, 
<a href="#net-error">net-error</a> is set. 
When <tt>-1</tt> is specified for <em>int-micro-seconds</em>, 
<tt>net-select</tt> will never time out.
</p>

<!-- example -->

<pre>
(set 'listen-socket (net-listen 1001))

;; wait for connection
(while (not (net-select listen-socket "read" 1000))
    (if (net-error) (print (net-error))))

(set 'connection (net-accept listen-socket))
(net-send connection "hello")

;; wait for incoming message
(while (not (net-select connection "read" 1000))
    (do-something)) 

(net-receive connection buff 1024)
</pre>


<p>
When <tt>net-select</tt> is used, 
several listen and connection sockets can be watched, 
and multiple connections can be handled. 
When used with a list of sockets, 
<tt>net-select</tt> will return a list of ready sockets. 
The following example would listen on two sockets 
and continue accepting and servicing connections:
</p>

<!-- example -->

<pre>
(set 'listen-list '(1001 1002))

; accept-connection, read-connection and write-connection
; are user defined functions

(while (not (net-error))
    (dolist (conn (net-select listen-list "r" 1000))
    (accept-connection conn))  ; build an accept-list

    (dolist (conn (net-select accept-list "r" 1000))
    (read-connection conn))    ; read on connected sockets

    (dolist (conn (net-select accept-list "w" 1000))
    (write-connection conn)))  ; write on connected sockets
</pre>


<p>
In the second syntax, 
a list  is returned 
containing all the sockets 
that passed the test;
if timeout occurred, 
an empty list is returned. 
An error causes 
<a href="#net-error">net-error</a> to be set.
</p>

<p>
Note that supplying a nonexistent socket to <tt>net-select</tt> 
will cause an error to be set in <a href="#net-error">net-error</a>.
</p>

<br/><br/>

<a name="net-send"></a>
<h2><span class="function">net-send</span></h2>
<h4>syntax: (net-send <em>int-socket</em> <em>str-buffer</em> [<em>int-num-bytes</em>])</h4>

<p>
Sends the contents of <em>str-buffer</em> on the connection specified by <em>int-socket</em>. 
If <em>int-num-bytes</em> is specified, up to <em>int-num-bytes</em> are sent. 
If <em>int-num-bytes</em> is not specified, the entire contents will be sent.
<tt>net-send</tt> returns the number of bytes sent or <tt>nil</tt> on failure.
</p>

<p>On failure, use <a href="#net-error">net-error</a> to get more error information.</p>

<!-- example -->

<pre>
(set 'buf "hello there")

(net-send sock buf)       <span class='arw'>&rarr;</span> 11
(net-send sock buf 5)     <span class='arw'>&rarr;</span> 5

(net-send sock "bye bye") <span class='arw'>&rarr;</span> 7
</pre>


<p>
The first <tt>net-send</tt> sends the string <tt>"hello there"</tt>, while
the second <tt>net-send</tt> sends only the string <tt>"hello"</tt>.
</p>

<br/><br/>

<a name="net-send-to"></a>
<h2><span class="function">net-send-to</span></h2>
<h4>syntax: (net-send-to <em>str-remotehost</em> <em>int-remoteport</em> <em>str-buffer</em> <em>int-socket</em>)</h4>

<p>Can be used for either UDP or TCP/IP communications. The socket in <em>int-socket</em> 
must have previously been opened with a <a href="#net-connect">net-connect</a> 
or <a href="#net-listen">net-listen</a> function. If the opening functions was used 
with the <tt>"udp"</tt> option, <tt>net-listen</tt> or <tt>net-connect</tt>
are not used to listen or to connect but only to create the UDP socket.
The host in <em>str-remotehost</em> can be specified either as 
a hostname or as an IP-number string.</p>

<p>When using <tt>net-connect</tt> together with <tt>net-send-to</tt>, then 
only one of the functions should specify the remote host. The other should leave 
the address as an empty string.</p>

<!-- example -->

<pre>
;;;;;;;;;;;;;;;;;; UDP server
(set 'socket (net-listen 10001 "" "udp"))
(if socket (println "server listening on port " 10001)
       (println (net-error)))
(while (not (net-error))
   (set 'msg (net-receive-from socket 255))
   (println "-&gt; " msg)
   (net-send-to (nth 1 msg) (nth 2 msg) 
                (upper-case (first msg)) socket))

;;;;;;;;;;;;;;;;;; UDP client
(set 'socket (net-listen 10002 "" "udp"))
(if (not socket) (println (net-error)))
(while (not (net-error))
   (print "&gt; ")
   (net-send-to "127.0.0.1" 10001 (read-line) socket)
   (net-receive socket buff 255)
   (println "-&gt; " buff))
</pre>


<p>In the examples both, the client and the server use <tt>net-listen</tt> to
create the UDP socket for sending and receiving. The server extracts 
the client address and port from the message received and uses it in the 
<tt>net-send-to</tt> statement.</p>

<p>See also the <a href="#net-receive-from">net-receive-from</a> function
and the <a href="#net-listen">net-listen</a> function with the 
<tt>"udp"</tt> option.</p>

<p>For blocking short UDP transactions use <a href="#net-send-udp">net-send-udp</a> 
and <a href="#net-receive-udp">net-receive-udp</a>.</p>

<br/><br/>

<a name="net-send-udp"></a>
<h2><span class="function">net-send-udp</span></h2>
<h4>syntax: (net-send-udp <em>str-remotehost</em> <em>int-remoteport</em> <em>str-buffer</em> [<em>bool</em>])</h4>

<p>
Sends a User Datagram Protocol (UDP) 
to the host specified in <em>str-remotehost</em> 
and to the port in <em>int-remoteport</em>. 
The data sent is in <em>str-buffer</em>.
</p>

<p>The theoretical maximum data size of a UDP packet on an IPv4 system
is 64K minus IP layer overhead, but much smaller on most Unix flavors.
8k seems to be a safe size on macOS, BSDs and Linux.</p>

<p>
No previous setup using <tt>net-connect</tt> 
or <tt>net-listen</tt> is necessary. 
<tt>net-send-udp</tt> returns immediately 
with the number of bytes sent 
and closes the socket used. 
If no <tt>net-receive-udp</tt> statement 
is waiting at the receiving side, 
the datagram sent is lost. 
When using datagram communications over insecure connections, 
setting up a simple protocol between sender and receiver 
is recommended for ensuring delivery. 
UDP communication by itself 
does not guarantee reliable delivery 
as TCP/IP does.
</p>

<!-- example -->

<pre>
(net-send-udp "somehost.com" 3333 "Hello")  <span class='arw'>&rarr;</span> 5
</pre>


<p>
<tt>net-send-udp</tt> is also suitable 
for sending binary information 
(e.g., the zero character or other non-visible bytes). 
For a more comprehensive example, 
see <a href="#net-receive-udp">net-receive-udp</a>.
</p>

<p>
Optionally, the sending socket 
can be put in broadcast mode 
by specifying <tt>true</tt> 
or any expression 
not evaluating to <tt>nil</tt> 
in <em>bool</em>:
</p>


<pre>
(net-send-udp "192.168.1.255" 2000 "Hello" true)  <span class='arw'>&rarr;</span> 5
</pre>


<p>
The UDP will be sent to all nodes 
on the <tt>192.168.1</tt> network. 
Note that on some operating systems, 
sending the network mask <tt>255</tt> 
without the <em>bool</em> <tt>true</tt> option 
will enable broadcast mode.
</p>

<p>
As an alternative, 
the <a href="#net-connect">net-connect</a> function 
using the <tt>"udp"</tt> option&mdash;together with 
the <a href="#net-send-to">net-send-to</a> function&mdash;can 
be used to talk to a UDP listener 
in a non-blocking fashion.
</p>

<br/><br/>

<a name="net-service"></a>
<h2><span class="function">net-service</span></h2>
<h4>syntax: (net-service <em>str-service</em> <em>str-protocol</em>)<br/>
syntax: (net-service <em>int-port</em> <em>str-protocol</em>)</h4>

<p>In the first syntax <tt>net-service</tt> makes a lookup in the 
<em>services</em> database and returns the standard port number for 
this service.</p>

<p>In the second syntax a service port is supplied in <em>int-port</em>
to look up the service name.</p>

<p>Returns <tt>nil</tt> on failure.</p>

<!-- example -->

<pre>
; get the port number from the name
(net-service "ftp" "tcp")       <span class='arw'>&rarr;</span> 21
(net-service "http" "tcp")      <span class='arw'>&rarr;</span> 80
(net-service "net-eval" "tcp")  <span class='arw'>&rarr;</span> 4711  ; if configured

; get the service name from the port number
(net-service 22 "tcp")          <span class='arw'>&rarr;</span> "ssh"
</pre>

<br/><br/>

<a name="net-sessions"></a>
<h2><span class="function">net-sessions</span></h2>
<h4>syntax: (net-sessions)</h4>

<p>
Returns a list of active listening and connection sockets.
</p>

<br/><br/>

<a name="new"></a>
<h2><span class="function">new</span></h2>
<h4>syntax: (new <em>context-source</em> <em>sym-context-target</em> [<em>bool</em>])<br/>
syntax: (new <em>context-source</em>)</h4>

<p>The context <em>context-source</em> is copied to <em>sym-context-target</em>.
If the target context does not exist, a new context with the same variable names 
and user-defined functions as in <em>context-source</em> is created.
If the target context already exists, then new symbols and definitions are added.
Existing symbols are only overwritten when the expression in <em>bool</em>
evaluates to anything other than <tt>nil</tt>; otherwise, the content of existing symbols
will remain. This makes <em>mixins</em> of context objects possible. 
<tt>new</tt> returns the target context, which cannot be MAIN.</p>

<p>In the second syntax, the existing context in <em>context-source</em> gets 
copied into the current context as the target context.</p>

<p>All references to symbols in the originating context 
will be translated to references in the target context.
This way, all functions and data structures referring to symbols
in the original context will now refer to symbols in the target context.</p>

<!-- example -->

<pre>
(new CTX 'CTX-2)  <span class='arw'>&rarr;</span> CTX-2   

;; force overwrite of existing symbols
(new CTX MyCTX true)  <span class='arw'>&rarr;</span> MyCTX   
</pre>


<p>
The first line in the example creates a new context 
called <tt>CTX-2</tt> that has the exact same structure 
as the original one. 
Note that <tt>CTX</tt> is not quoted 
because contexts evaluate to themselves, 
but CTX-2 must be quoted because it does not exist yet.
</p>

<p>
The second line merges the context <tt>CTX</tt> into <tt>MyCTX</tt>. 
Any existing symbols of the same name in <tt>MyCTX</tt> 
will be overwritten. 
Because <tt>MyCTX</tt> already exists, 
the quote before the context symbol can be omitted.
</p>

<p>
Context symbols need not be mentioned explicitly, 
but they can be contained in variables:
</p>

<!-- example -->

<pre>
(set 'foo:x 123)
(set 'bar:y 999)

(set 'ctxa foo)
(set 'ctxb bar)

(new ctxa ctxb)  ; from foo to bar

bar:x  <span class='arw'>&rarr;</span> 123  ; x has been added to bar
bar:y  <span class='arw'>&rarr;</span> 999)
</pre>


<p>
The example refers to contexts in variables 
and merges context <tt>foo</tt> into <tt>bar</tt>.
</p>


<p>
See also the function <a href="#def-new">def-new</a> 
for moving and merging single functions 
instead of entire contexts. 
See the <a href="#context">context</a> function 
for a more comprehensive example of <tt>new</tt>.
</p>

<br/><br/>

<a name="nilp"></a>
<h2><span class="function">nil?</span></h2>
<h4>syntax: (nil? <em>exp</em>)</h4>

<p>
If the expression in <em>exp</em> evaluates to <tt>nil</tt>, 
then <tt>nil?</tt> returns <tt>true</tt>; 
otherwise, it returns <tt>nil</tt>.
</p>

<!-- example -->

<pre>
(map nil? '(x nil  1 nil "hi" ()))
<span class='arw'>&rarr;</span> (nil true nil true nil nil)

(nil? nil)  <span class='arw'>&rarr;</span> true
(nil? '())  <span class='arw'>&rarr;</span> nil

; nil? means strictly nil
(nil? (not '()))  <span class='arw'>&rarr;</span> nil
</pre>


<p>
The <tt>nil?</tt> predicate 
is useful for distinguishing between 
<tt>nil</tt> and the empty list <tt>()</tt>.
</p>

<p>Note that <tt>nil?</tt> means <em>strictly</em> <tt>nil</tt>
while <tt>true?</tt> means everything not <tt>nil</tt> or the
empty list <tt>()</tt>.</p>

<br/><br/> 


<a name="normal"></a>
<h2><span class="function">normal</span></h2>
<h4>syntax: (normal <em>float-mean</em> <em>float-stdev</em> <em>int-n</em>)<br/>
syntax: (normal <em>float-mean</em> <em>float-stdev</em>)</h4>

<p>
In the first form, <tt>normal</tt> returns a list of length <em>int-n</em> 
of random, continuously distributed floating point numbers 
with a mean of <em>float-mean</em> 
and a standard deviation of <em>float-stdev</em>. 
The random generator used internally 
can be seeded using the <a href="#seed">seed</a> function.
</p>

<!-- example -->

<pre>
(normal 10 3 10)
<span class='arw'>&rarr;</span> (7 6.563476562 11.93945312 6.153320312 9.98828125
7.984375 10.17871094 6.58984375 9.42578125 12.11230469)
</pre>


<p>
In the second form, 
<tt>normal</tt> returns a single 
normal distributed floating point number:
</p>

<pre>
(normal 1 0.2) <span class='arw'>&rarr;</span> 0.646875
</pre>

<p> When no parameters are given, <tt>normal</tt> assumes a mean of <tt>0.0</tt> 
and a standard deviation of <tt>1.0</tt>.</p>


<p>
See also the <a href="#random">random</a> 
and <a href="#rand">rand</a> functions 
for evenly distributed numbers, 
<a href="#amb">amb</a> for randomizing evaluation 
in a list of expressions, 
and <a href="#seed">seed</a> for setting a different start point 
for pseudo random number generation.
</p>

<br/><br/>

<a name="not"></a>
<h2><span class="function">not</span></h2>

<h4>syntax: (not <em>exp</em>)</h4>

<p>If <em>exp</em> evaluates to <tt>nil</tt> or the empty list <tt>()</tt>, 
then <tt>true</tt> is returned; otherwise, <tt>nil</tt> is returned.</p>

<!-- example -->

<pre>
(not true)            <span class='arw'>&rarr;</span> nil
(not nil)             <span class='arw'>&rarr;</span> true
(not '())             <span class='arw'>&rarr;</span> true
(not (&lt; 1 10))        <span class='arw'>&rarr;</span> nil
(not (not (&lt; 1 10)))  <span class='arw'>&rarr;</span> true
</pre>

<br/><br/>

<a name="now"></a>
<h2><span class="function">now</span></h2>
<h4>syntax: (now [<em>int-minutes-offset</em> [<em>int-index</em>]])</h4>

<p>Returns information about the current date and time 
as a list of integers.  An optional time-zone offset 
can be specified in minutes in <em>int-minutes-offset</em>. 
This causes the time to be shifted forward or backward in time,
before being split into separate date values.</p>

<p>An optional list-index in <em>int-index</em> makes <tt>now</tt>
return a specific member in the result list.</p>

<!-- example -->

<pre>
(now)       <span class='arw'>&rarr;</span> (2002 2 27 18 21 30 140000 57 3 -300 0)
(now 0 -2)  <span class='arw'>&rarr;</span> -300 ; minutes west of GMT


(date-value (now))  <span class='arw'>&rarr;</span> 1014834090
</pre>


<p>The numbers represent the following date-time fields:</p>

<table  width="98%" summary="date formatting">
<tr align="left"><th>format</th><th>description</th></tr>

<tr><td>year</td><td>Gregorian calendar</td></tr>
<tr><td>month</td><td>               (1&ndash;12)</td></tr>
<tr><td>day</td><td>                 (1&ndash;31)</td></tr>
<tr><td>hour</td><td>                (0&ndash;23) UTC</td></tr>
<tr><td>minute</td><td>              (0&ndash;59)</td></tr>
<tr><td>second</td><td>              (0&ndash;59)</td></tr>
<tr><td>microsecond</td><td>         (0&ndash;999999) 
		OS-specific, millisecond resolution</td></tr>
		
<tr><td>day of current year</td><td>Jan 1st is 1</td></tr>
<tr><td>day of current week</td><td> (1&ndash;7) starting Monday</td></tr>
<tr><td>time zone offset in minutes</td><td> west of GMT including daylight savings bias</td></tr>
<tr><td>daylight savings time type </td><td> (0&ndash;6) on Linux/Unix
		or (0&ndash;2) on MS Windows</td></tr>
</table><br/>

<p>The second example returns the Coordinated Universal Time (UTC) 
time value of seconds after January 1, 1970.</p>

<p>Ranging from 0 to 23, hours are given in UTC and are not adjusted for 
the local time zone.  The resolution of the <tt>microseconds</tt> field 
depends on the operating system and platform.  On some platforms, 
the last three digits of the <tt>microseconds</tt> field are always 
<tt>0</tt> (zero).</p>

<p>The "day of the week" field starts with 1 on Monday conforming to the 
ISO 8601 international standard for date and time representation.</p>

<p>On some platforms, the daylight savings time flag is not active and 
returns <tt>0</tt> (zero) even during daylight savings time (dst).</p>

<p>Depending on the geographical area, the daylight savings time type
(dst) has a different value from 1 to 6:</p>

<table  width="35%" summary="date formatting">
<tr align="left"><th>UNIX type</th><th>area</th></tr>
<tr><td>0</td><td>not on daylight savings</td></tr>
<tr><td>1</td><td>USA style dst</td></tr>
<tr><td>2</td><td>Australian style daylight savings</td></tr>
<tr><td>3</td><td>Western European daylight savings</td></tr>
<tr><td>4</td><td>Middle European daylight savings</td></tr>
<tr><td>5</td><td>Eastern European daylight savings</td></tr>
<tr><td>6</td><td>Canada dst</td></tr>
</table>
<br />
<table  width="35%" summary="date formatting">
<tr align="left"><th>Windows type</th><th></th></tr>
<tr><td>0</td><td>Daylight saving time is not used</td></tr>
<tr><td>1</td><td>Standard date time range is used</td></tr>
<tr><td>2</td><td>Daylight date time range is used (daylight savings active)</td></tr> 
</table>



<p>See also the <a href="#date">date</a>, 
<a href="#date-list">date-list</a>, 
<a href="#date-parse">date-parse</a>, 
<a href="#date-value">date-value</a>, 
<a href="#time">time</a>, and <a href="#time-of-day">time-of-day</a> functions.
</p>

<br/><br/>

<a name="nper"></a>
<h2><span class="function">nper</span></h2>
<h4>syntax: (nper <em>num-interest</em> <em>num-pmt</em> <em>num-pv</em> 
[<em>num-fv</em> [<em>int-type</em>]])</h4>

<p>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>.
If payment is at the end of the period, <em>int-type</em> is <tt>0</tt> (zero) 
or <em>int-type</em> is omitted; for payment at the beginning of each period, 
<em>int-type</em> is 1.</p>

<!-- example -->

<pre>
(nper (div 0.07 12) 775.30 -100000)  <span class='arw'>&rarr;</span> 239.9992828
</pre>


<p>
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.
</p>

<p>
See also the <a href="#fv">fv</a>,
<a href="#irr">irr</a>,
<a href="#npv">npv</a>,
<a href="#pmt">pmt</a>,
and <a href="#pv">pv</a> functions.
</p>

<br/><br/>

<a name="npv"></a>
<h2><span class="function">npv</span></h2>
<h4>syntax: (npv <em>num-interest</em> <em>list-values</em>)</h4>

<p>
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>.
Payments are represented by negative values in <em>list-values</em>,
while income is represented by positive values in <em>list-values</em>.
</p>

<!-- example -->

<pre>
(npv 0.1 '(1000 1000 1000)) 
<span class='arw'>&rarr;</span> 2486.851991

(npv 0.1 '(-2486.851991 1000 1000 1000)) 
<span class='arw'>&rarr;</span> -1.434386832e-08  ; ~ 0.0 (zero)
</pre>


<p>
In the example,
an initial investment of $2,481.85 would allow for an income of $1,000 after the end of the first,
second,
and third years.
</p>

<p>
See also the <a href="#fv">fv</a>,
<a href="#irr">irr</a>,
<a href="#nper">nper</a>,
<a href="#pmt">pmt</a>,
and <a href="#pv">pv</a> functions.
</p> 

<br/><br/>

<a name="nth"></a>
<h2><span class="function">nth</span>&nbsp;<font size="-1"><a href="#utf8_capable">utf8</a></font></h2>
<h4>syntax: (nth <em>int-index</em> <em>list</em>)<br/>
syntax: (nth <em>int-index</em> <em>array</em>)<br/>
syntax: (nth <em>int-index</em> <em>str</em>)<br/><br/>

syntax: (nth <em>list-indices</em> <em>list</em>)<br/>
syntax: (nth <em>list-indices</em> <em>array</em>)</h4>

<p>
In the first syntax group <tt>nth</tt> uses <em>int-index</em> an index into the 
<em>list</em>, <em>array</em> or <em>str</em> found and returning the element found 
at that index. See also <a href="#indexing">Indexing elements of strings and lists</a>.</p>

<p>Multiple indices may be specified to recursively access elements in nested lists
or arrays. If there are more indices than nesting levels, the extra indices are ignored. 
When multiple indices are used, they must be put in a list as shown in the second
syntax group.</p>

<!-- example -->

<pre>
(set 'L '(a b c))
(nth 0 L)    <span class='arw'>&rarr;</span> a
; or simply
(L 0) <span class='arw'>&rarr;</span> a

(set 'names '(john martha robert alex)) 
<span class='arw'>&rarr;</span> (john martha robert alex)

(nth 2 names)    <span class='arw'>&rarr;</span> robert
; or simply
(names 2)        <span class='arw'>&rarr;</span> robert

(names -1)       <span class='arw'>&rarr;</span> alex


; multiple indices
(set 'persons '((john 30) (martha 120) ((john doe) 17)))

(persons 1 1)           <span class='arw'>&rarr;</span> 120

(nth '(2 0 1) persons)  <span class='arw'>&rarr;</span> doe

; or simply
(persons 2 0 1)        <span class='arw'>&rarr;</span> doe

; multiple indices in a vector
(set 'v '(2 0 1))
(persons v)       <span class='arw'>&rarr;</span> doe
(nth v persons)   <span class='arw'>&rarr;</span> doe

; negative indices
(persons -2 0)    <span class='arw'>&rarr;</span> martha

; out-of-bounds indices cause error
(persons 10)  <span class='arw'>&rarr;</span> <span class='err'>ERR: list index out of bounds</span>
(person -5)   <span class='arw'>&rarr;</span> <span class='err'>ERR: list index out of bounds</span>
</pre>


<p>The list <tt>L</tt> can be the context of the default functor <tt>L:L</tt>. 
This allows lists passed by reference:</p>

<pre>
(set 'L:L '(a b c d e f g))

(define (second ctx)
	(nth 1 ctx))

(reverse L) <span class='arw'>&rarr;</span> (g f e d c b a)
L:L <span class='arw'>&rarr;</span> (g f e d c b a)

;; passing the list in L:L by reference
(second L)   <span class='arw'>&rarr;</span> b

;; passing the list in L:L by value
(second L:L) <span class='arw'>&rarr;</span> b
</pre>

<p>Reference passing is faster and uses less memory in big lists and should
be used on lists with more than a few hundred items.</p>

<p>Note that the <i>implicit indexing</i> version of <tt>nth</tt> is not breaking newLISP
syntax rules but should be understood as a logical expansion of newLISP syntax rules to
other data types than built-in functions or lambda expressions. A list in the functor
position of an s-expression assumes self-indexing functionality using the index
arguments following.</p>

<p>
The implicit indexed syntax forms are faster but the other form with an explicit
<tt>nth</tt> may be more readable in some situations.
</p>

<p><tt>nth</tt> works on <a href="#array">arrays</a> just like it does on lists:</p>

<!-- example -->

<pre>
(set 'aArray (array 2 3 '(a b c d e f))) 
<span class='arw'>&rarr;</span> ((a b c) (d e f))
(nth 1 aArray)      <span class='arw'>&rarr;</span>  (d e f)
(aArray 1)          <span class='arw'>&rarr;</span>  (d e f)

(nth '(1 0) aArray)    <span class='arw'>&rarr;</span> d
(aArray 1 0)           <span class='arw'>&rarr;</span> d
(aArray '(1 0))        <span class='arw'>&rarr;</span> d

(set 'vec '(1 0))
(aArray vec)           <span class='arw'>&rarr;</span> d
</pre>


<p>
In the String version, <tt>nth</tt> returns the character found at the position 
<em>int-index</em> in <em>str</em> and returns it as a string.</p>

<!-- example -->

<pre>
(nth  0 "newLISP")   <span class='arw'>&rarr;</span> "n"

("newLISP" 0)        <span class='arw'>&rarr;</span> "n"

("newLISP" -1)       <span class='arw'>&rarr;</span> "P"
</pre>


<p>Note that <a href="#nth">nth</a> works on character boundaries rather than byte 
boundaries when using the UTF-8&ndash;enabled version of newLISP. To access ASCII and
binary string buffers on single byte boundaries use <a href="#slice">slice</a>.</p>

<p>See also <a href="#setf">setf</a> for modifying multidimensional lists and arrays and
<a href="#push">push</a> and <a href="#pop">pop</a> for modifying lists.</p>

<br/><br/>

<a name="nullp"></a>
<h2><span class="function">null?</span></h2>
<h4>syntax: (null? <em>exp</em>)</h4>

<p>
Checks if an expression evaluates to <tt>nil</tt>,
the empty list <tt>()</tt>,
the empty string <tt>""</tt>,
<tt>NaN</tt> (not a number),
or <tt>0</tt> (zero),
in which case it returns <tt>true</tt>.
In all other cases,
<tt>null?</tt> returns <tt>nil</tt>.
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.
</p>

<!-- example -->

<pre>
(set 'x (sqrt -1)) <span class='arw'>&rarr;</span> NaN ; or nan on UNIX
(null? x) <span class='arw'>&rarr;</span> true

(map null? '(1 0 0.0 2 "hello" "" (a b c) () true))
<span class='arw'>&rarr;</span> (nil true true nil nil true nil true nil) 

(filter null? '(1 0 2 0.0 "hello" "" (a b c) () nil true)) 
<span class='arw'>&rarr;</span> (0 0 "" () nil)

(clean null? '(1 0 2 0.0 "hello" "" (a b c) () nil true))
<span class='arw'>&rarr;</span> (1 2 "hello" (a b c) true)
</pre>

<p>
See also the predicates <a href="#emptyp">empty?</a>,
<a href="#nilp">nil?</a>
and <a href="#zerop">zero?</a>.
</p>

<br/><br/>

<a name="numberp"></a>
<h2><span class="function">number?</span>&nbsp;
<a href="#big_int"><font size="-1">bigint</font></a></h2>
<h4>syntax: (number? <em>exp</em>)</h4>

<p>
<tt>true</tt> is returned only if <em>exp</em> evaluates to a floating point number or an integer;
otherwise,
<tt>nil</tt> is returned.
</p>

<!-- example -->

<pre>
(set 'x 1.23)
(set 'y 456)
(number? x)      <span class='arw'>&rarr;</span> true
(number? y)      <span class='arw'>&rarr;</span> true
(number? "678")  <span class='arw'>&rarr;</span> nil  
</pre>


<p>
See the functions <a href="#floatp">float?</a> and <a href="#integerp">integer?</a> to test for a specific number type.
</p>

<br/><br/>

<a name="oddp"></a>
<h2><span class="function">odd?</span>&nbsp;
<a href="#big_int"><font size="-1">bigint</font></a></h2>
<h4>syntax: (odd? <em>int-number</em>)</h4>

<p>Checks the parity of an integer number. If the number is not <em>even divisible</em> by <tt>2</tt>, 
it has <em>odd</em> parity.  When a floating point number is passed for <em>int-number</em>, 
it will be converted first to an integer by cutting off its fractional part.</p>

<pre>
(odd? 123)  <span class='arw'>&rarr;</span> true
(odd? 8)    <span class='arw'>&rarr;</span> nil
(odd? 8.7)  <span class='arw'>&rarr;</span> nil
</pre>

<p>Use <a href="#evenp">even?</a> to check if an integer is even, divisible by <tt>2</tt>.</p>

<br/><br/>

<a name="open"></a>
<h2><span class="function">open</span></h2>

<h4>syntax: (open <em>str-path-file</em> <em>str-access-mode</em> [<em>str-option</em>])</h4>

<p>
The <em>str-path-file</em> is a file name,
and <em>str-access-mode</em> is a string specifying the file access mode.
<tt>open</tt> returns an integer,
which is a file handle to be used on subsequent read or write operations on the file.
On failure,
<tt>open</tt> returns <tt>nil</tt>.
The access mode <tt>"write"</tt> creates the file if it doesn't exist,
or it truncates an existing file to <tt>0</tt> (zero) bytes in length.
</p>

<p>
The following strings are legal access modes:
</p>


<tt>"read"</tt> or <tt>"r"</tt> for read only access<br/>
<tt>"write"</tt> or <tt>"w"</tt> for write only access<br/>
<tt>"update"</tt> or <tt>"u"</tt> for read/write access<br/>
<tt>"append"</tt> or <tt>"a"</tt> for append read/write access<br/>

<br/>

<!-- example -->

<pre>
(device (open "newfile.data" "write"))  <span class='arw'>&rarr;</span> 5
(print "hello world\n")  <span class='arw'>&rarr;</span> "hello world"
(close (device))         <span class='arw'>&rarr;</span> 5

(set 'aFile (open "newfile.data" "read"))
(seek aFile 6)
(set 'inChar (read-char aFile))
(print inChar "\n")
(close aFile)
</pre>


<p>
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>.
The second example reads a byte value at offset 6 in the same file (the ASCII value 
of <tt>'w'</tt> is 119). Note that using <tt>close</tt> on <a href="#device">(device)</a> 
automatically resets <a href="#device">device</a> to <tt>0</tt> (zero).
</p>

<p>
As an additional <em>str-option</em>,
<tt>"non-block"</tt> or <tt>"n"</tt> can be specified after the <tt>"read"</tt> or <tt>"write"</tt> option.
Only available on Unix systems,
non-blocking mode can be useful when opening <em>named pipes</em> but is not required to perform I/O on named pipes.
</p>

<br/><br/>

<a name="or"></a>
<h2><span class="function">or</span></h2>

<h4>syntax: (or <em>exp-1</em> [<em>exp-2</em> ... ])</h4>

<p>
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>.
The result is the return value of the <tt>or</tt> expression.
</p>

<!-- example -->

<pre>
(set 'x 10)
(or (&gt; x 100) (= x 10))          <span class='arw'>&rarr;</span> true
(or "hello" (&gt; x 100) (= x 10))  <span class='arw'>&rarr;</span> "hello"
(or '())                         <span class='arw'>&rarr;</span> ()
(or true)                        <span class='arw'>&rarr;</span> true
(or)                             <span class='arw'>&rarr;</span> nil
</pre>

<br/><br/>

<a name="ostype"></a>
<h2><span class="function">ostype</span></h2>
<h4>syntax: ostype</h4>

<p><tt>ostype</tt> is a built-in system constant 
containing the name of the operating system 
newLISP is running on.</p>

<!-- example -->

<pre>
ostype  <span class='arw'>&rarr;</span> "Windows"
</pre>


<p>One of the following strings is returned: 
<tt>"Linux", "BSD", "OSX", "Tru64Unix", "Solaris", "SunOS", "Windows", "Cygwin", or "OS/2"</tt>.
</p>


<p><tt>ostype</tt> can be used to write platform-independent code:</p>

<pre>
(if 
    (= ostype "Linux") (import "libz.so")
    (= ostype "BSD") (import "libz.so")
    (= ostype "OSX") (import "libz.dylib")
    ...
    (println "cannot import libz on this platform")
)
</pre>


<p>Use <a href="#sys-info">sys-info</a> to learn more
about the current flavor of newLISP running.</p>

<p>For a table of other built-in system variables and symbols see the
chapter <a href="#system_symbols">System Symbols and Constants</a> in the
appendix.</p>

<br/><br/>

<a name="pack"></a>
<h2><span class="function">pack</span></h2>
<h4>syntax: (pack <em>str-format</em> [<em>exp-1</em> [<em>exp-2</em> ... ]])<br/>
syntax: (pack <em>str-format</em> [<em>list</em>])<br/><br/>
syntax: (pack <em>struct</em> [<em>exp-1</em> [<em>exp-2</em> ... ]])<br/>
syntax: (pack <em>struct</em> [<em>list</em>])</h4>

<p>When the first parameter is a string, <tt>pack</tt> packs one or more expressions 
(<em>exp-1</em> to <em>exp-n</em>) into a binary format specified in the format 
string <em>str-format</em>, and returning the binary structure in a string buffer.
The symmetrical <a href="#unpack">unpack</a> function is used 
for unpacking. The expression arguments can also be given in a <em>list</em>.
<tt>pack</tt> and <tt>unpack</tt> are useful when reading and writing binary files 
(see <a href="#read">read</a> and <a href="#write">write</a>) 
or when unpacking binary structures from return values of imported C functions 
using <tt>import</tt>.</p>

<p>When the first parameter is the symbol of a <a href="#struct">struct</a>
definition, <tt>pack</tt> uses the format as specified in <em>struct</em>. 
While <tt>pack</tt> with <em>str-format</em> literally packs as specified,
<tt>pack</tt> with <em>struct</em> will insert structure aligning pad-bytes
depending on data type, order of elements and CPU architecture.
Refer to the description of the <a href="#struct">struct</a> function for more detail.</p>

<p>When no data expressions or lists are specified, formats or structures are filled
with <tt>0</tt>s (zeros).</p> 

<p>The following characters are used in <em>str-format</em>:</p>

<table  summary="format characters">
<tr align="left"><th>format</th><th>description</th></tr>

<tr>
<td WIDTH="20%"><tt>c </tt></td>

<td WIDTH="80%">a signed 8-bit number</td>
</tr>

<tr>
<td><tt>b </tt></td>
<td>an unsigned 8-bit number</td>
</tr>

<tr>
<td><tt>d </tt></td>
<td>a signed 16-bit short number</td>
</tr>

<tr>
<td><tt>u </tt></td>
<td>an unsigned 16-bit short number</td>
</tr>

<tr>
<td><tt>ld</tt></td>
<td>a signed 32-bit long number</td>
</tr>

<tr>
<td><tt>lu</tt></td>
<td>an unsigned 32-bit long number</td>
</tr>

<tr>
<td><tt>Ld</tt></td>
<td>a signed 64-bit long number</td>
</tr>

<tr>
<td><tt>Lu</tt></td>
<td>an unsigned 64-bit long number</td>
</tr>

<tr>
<td><tt>f </tt></td>
<td>a float in 32-bit representation</td>
</tr>

<tr>
<td><tt>lf</tt></td>
<td>a double float in 64-bit representation</td>
</tr>

<tr>
<td><tt>sn</tt></td>
<td>a string of <em>n</em> null padded ASCII characters</td>
</tr>

<tr>
<td><tt>nn</tt></td>
<td><em>n</em> null characters</td>
</tr>

<tr>
<td><tt>&gt;</tt></td>

<td>switch to big endian byte order</td>
</tr>

<tr>
<td><tt>&lt;</tt></td>
<td>switch to little endian byte order</td>
</tr>

</table><br/>

<p>
<tt>pack</tt> will convert all floats into integers 
when passed to <tt>b</tt>, <tt>c</tt>, <tt>d</tt>, <tt>ld</tt>,
or <tt>lu</tt> formats.
It will also convert integers into floats
when passing them to <tt>f</tt> and <tt>lf</tt> formats.
</p>

<!-- example -->

<pre>
(pack "c c c" 65 66 67)  <span class='arw'>&rarr;</span> "ABC"
(unpack "c c c" "ABC")   <span class='arw'>&rarr;</span> (65 66 67)

(pack "c c c" 0 1 2)             <span class='arw'>&rarr;</span> "\000\001\002"
(unpack "c c c" "\000\001\002")  <span class='arw'>&rarr;</span> (0 1 2)

(set 's (pack "c d u" 10 12345 56789))
(unpack "c d u" s)  <span class='arw'>&rarr;</span> (10 12345 56789)

(set 's (pack "s10 f" "result" 1.23))
(unpack "s10 f" s)
<span class='arw'>&rarr;</span> ("result\000\000\000\000" 1.230000019)

(pack "n10") <span class='arw'>&rarr;</span> "\000\000\000\000\000\000\000\000\000\000"

(set 's (pack "s3 lf" "result" 1.23))
(unpack "s3 f" s)  <span class='arw'>&rarr;</span> ("res" 1.23)

(set 's (pack "c n7 c" 11 22))
(unpack "c n7 c" s)  <span class='arw'>&rarr;</span> (11 22))

(unpack "b" (pack "b" -1.0))  <span class='arw'>&rarr;</span> (255)
(unpack "f" (pack "f" 123))   <span class='arw'>&rarr;</span> (123)
</pre>


<p>
The last two statements show 
how floating point numbers are converted 
into integers when required by the format specification.
</p>

<p>The expressions to pack can also be given in a list:</p>


<pre>
(set 'lst '("A" "B" "C"))
(set 'adr (pack "lululu" lst))
(map get-string (unpack "lululu" adr))    <span class='arw'>&rarr;</span> ("A" "B" "C")
</pre>

<p>Note that the list should be referenced directly in <tt>pack</tt>,
so the pointers passed by <tt>adr</tt> are valid. <tt>adr</tt> would be written 
as <tt>char * adr[]</tt> in the C-programming language and represents a 32-bit pointer to an
array of 32-bit string pointers or a 64-bit pointers on the 64-bit version of newLISP.
</p>

<p>
The <tt>&gt;</tt> and <tt>&lt;</tt> specifiers 
can be used to switch between <em>little endian</em> 
and <em>big endian</em> byte order 
when packing or unpacking:
</p>


<pre>
(pack "d" 1)   <span class='arw'>&rarr;</span> "\001\000"  ;; on little endian CPU
(pack "&gt;d" 1)  <span class='arw'>&rarr;</span> "\000\001"  ;; force big endian

(pack "ld" 1)   <span class='arw'>&rarr;</span> "\001\000\000\000" ;; on little endian CPU
(pack "&lt;ld" 1)  <span class='arw'>&rarr;</span> "\000\000\000\001" ;; force big endian

(pack "&gt;u &lt;u" 1 1) <span class='arw'>&rarr;</span> "\000\001\001\000" ;; switch twice
</pre>


<p>
Switching the byte order will affect all number formats with 16-,
32-, or 64-bit sizes.
</p>

<p>
The pack and unpack format need not be the same:
</p>

<pre>
(set 's (pack "s3" "ABC"))
(unpack "c c c" s)  <span class='arw'>&rarr;</span> (65 66 67)
</pre>

<p>
The examples show spaces between the format specifiers.
These are not required but can be used to improve readability.
</p> 


<p>Using <tt>pack</tt> and <tt>unpack</tt> on UTF-8 strings:</p>

<pre>
(set 'txt "我能吞下玻璃而不伤身体。") 
<span class='arw'>&rarr;</span> "我能吞下玻璃而不伤身体。"
(set 'lst (unpack (dup "b" (length txt)) txt)) 
<span class='arw'>&rarr;</span> (230 136 145 232 ... 147 227 128 130)
(pack (dup "b" (length lst)) lst) 
<span class='arw'>&rarr;</span> "我能吞下玻璃而不伤身体。"
</pre>

<p>
See also the <a href="#address">address</a>,
<a href="#get-int">get-int</a>,
<a href="#get-long">get-long</a>,
<a href="#get-char">get-char</a>,
<a href="#get-string">get-string</a>,
and <a href="#unpack">unpack</a> functions.
</p>

<br/><br/>

<a name="parse"></a>

<h2><span class="function">parse</span></h2>
<h4>syntax: (parse <em>str-data</em> [<em>str-break</em>  [<em>regex-option</em>]])</h4>

<p>
Breaks the string that results from evaluating <em>str-data</em> into string tokens,
which are then returned in a list.
When no <em>str-break</em> is given,
<tt>parse</tt> tokenizes according to newLISP's internal parsing rules.
A string may be specified in <em>str-break</em> for tokenizing only at the occurrence of a string.
If an <em>regex-option</em> number or string is specified,
a regular expression pattern may be used in <em>str-break</em>.
</p>

<p>
When <em>str-break</em> is not specified,
the maximum token size is 2048 for quoted strings and 256 for identifiers.
In this case,
newLISP uses the same faster tokenizer it uses for parsing newLISP source.
If <em>str-break</em> is specified,
there is no limitation on the length of tokens.
A different algorithm is used that splits the source string <em>str-data</em> at the string in <em>str-break</em>.
</p>

<!-- example -->

<pre>
; no break string specified
(parse "hello how are you")     <span class='arw'>&rarr;</span> ("hello" "how" "are" "you")

; strings break after spaces, parentheses, commas, colons and numbers. 
; Spaces and the colon are swollowed
(parse "weight is 10lbs")       <span class='arw'>&rarr;</span>
(parse "one:two:three" ":")     <span class='arw'>&rarr;</span> ("one" "two" "three")

;; specifying a break string
(parse "one--two--three" "--")  <span class='arw'>&rarr;</span> ("one" "two" "three")

; a regex option causes regex parsing
(parse "one-two--three---four" "-+" 0) 
<span class='arw'>&rarr;</span> ("one" "two" "three" "four")

(parse "hello regular   expression 1, 2, 3" {,\s*|\s+} 0)
<span class='arw'>&rarr;</span> ("hello" "regular" "expression" "1" "2" "3")
</pre>


<p>The last two examples show a regular expression as the break string 
with the default option <tt>0</tt> (zero).  Instead of 
<tt>{</tt> and <tt>}</tt> (left and right curly brackets), double 
quotes can be used to limit the pattern.  In this case, double 
backslashes must be used inside the pattern.  The last pattern could 
be used for parsing CSV (Comma Separated Values) files.  For the regular expression option 
numbers, see <a href="#regex">regex</a>.</p>

<p>
<tt>parse</tt> will return empty fields 
around separators 
as empty strings:
</p>


<pre>
; empty fields around separators returned as empty strings
(parse "1,2,3," ",") <span class='arw'>&rarr;</span> ("1" "2" "3" "")
(parse "1,,,4" ",")  <span class='arw'>&rarr;</span> ("1" "" "" "4")
(parse "," ",")      <span class='arw'>&rarr;</span> ("" "")

(parse "")      <span class='arw'>&rarr;</span> ()
(parse "" " ")  <span class='arw'>&rarr;</span> ()
</pre>


<p>
This behavior is needed 
when parsing records 
with empty fields.
</p>

<p>
Parsing an empty string 
will always result 
in an empty list.
</p>

<p>
Use the <a href="#regex">regex</a> function 
to break strings up 
and the <a href="#directory">directory</a>, 
<a href="#find">find</a>, 
<a href="#find-all">find-all</a>,
<a href="#regex">regex</a>, 
<a href="#replace">replace</a>, 
and <a href="#search">search</a> functions 
for using regular expressions.
</p>

<br/><br/>


<a name="peek"></a>
<h2><span class="function">peek</span></h2>
<h4>syntax: (peek <em>int-handle</em>)</h4>

<p>
Returns the number of bytes ready to be read on a file descriptor;
otherwise,
it returns <tt>nil</tt> if the file descriptor is invalid.
<tt>peek</tt> can also be used to check <tt>stdin</tt>.
This function is only available on Unix-like operating systems.
</p>

<!-- example -->

<pre>
(peek 0)  ; check # of bytes ready on stdin
</pre>


<p>
Use the <a href="#net-peek">net-peek</a> function 
to check for network sockets, 
or for the number of available bytes on them. 
On Unix systems, 
<a href="#net-peek">net-peek</a> can be used 
to check file descriptors. 
The difference is that 
<a href="#net-peek">net-peek</a> also sets 
<a href="#net-error">net-error</a>.
</p>

<br/><br/>

<a name="pipe"></a>
<h2><span class="function">pipe</span></h2>
<h4>syntax: (pipe)</h4>

<p>
Creates an inter-process communications pipe and returns the 
<tt>read</tt> and <tt>write</tt> handles to it within a list.
</p>

<!-- example -->

<pre>
(pipe)  <span class='arw'>&rarr;</span> (3 4)  ; 3 for read, 4 for writing
</pre>


<p>
The pipe handles can be passed to a child process launched via 
   <a href="#process"> process</a> or to <a href="#fork">fork</a> for inter-process communications.
</p>

<p>
Note that the pipe does not block when being written to,
but it does block reading until bytes are available.
A <a href="#read-line">read-line</a> blocks until a newline character is received.
A <a href="#read">read</a> blocks when fewer characters than 
specified are available from a pipe that has not had the writing end closed by all processes.
</p>

<p>
More than one pipe can be opened if required.
</p>

<p>
newLISP can also use <em>named pipes</em>.
See the <a href="#open">open</a> function for further information.
</p>

<br/><br/>

<a name="pmt"></a>
<h2><span class="function">pmt</span></h2>

<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>

<p>
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.
<em>num-future-value</em> is the value of the loan at the end (typically <tt>0.0</tt>).
If payment is at the end of the period, <em>int-type</em> is <tt>0</tt> (zero) 
or <em>int-type</em> is omitted; for payment at the beginning of each period, 
<em>int-type</em> is 1.</p>


<!-- example -->

<pre>
(pmt (div 0.07 12) 240 100000)  <span class='arw'>&rarr;</span> -775.2989356
</pre>


<p>
The above example calculates a payment of $775.30 for a loan of $100,000 at a yearly interest rate of 7 percent.
It is calculated monthly and paid over 20 years (20 * 12 = 240 monthly periods).
This illustrates the typical way payment is calculated for mortgages.
</p>

<p>
See also the <a href="#fv">fv</a>,
<a href="#irr">irr</a>,
<a href="#nper">nper</a>,
<a href="#npv">npv</a>,
and <a href="#pv">pv</a> functions.
</p>

<br/><br/>

<a name="pop"></a>
<h2><span class="function">pop</span>&nbsp;<a href="#destructive">!</a>&nbsp;<font size="-1"><a href="#utf8_capable">utf8</a></font></h2>
<h4>syntax: (pop <em>list</em> [<em>int-index-1</em> [<em>int-index-2</em> ... ]])<br/>
syntax: (pop <em>list</em> [<em>list-indexes</em>])<br/><br/>

syntax: (pop <em>str</em> [<em>int-index</em> [<em>int-length</em>]])</h4>

<p>Using <tt>pop</tt>, elements can be removed from lists and characters from strings.</p>

<p>
In the first syntax, <tt>pop</tt> extracts an element from the list found 
by evaluating <em>list</em>.
If a second parameter is present,
the element at <em>int-index</em> is extracted and returned.
See also <a href="#indexing">Indexing elements of strings and lists</a>.
</p>

<p>
In the second version,
indices are specified in the list <em>list-indexes</em>.
This way,
<tt>pop</tt> works easily together with <a href="#ref">ref</a>
and <a href="#ref-all">ref-all</a>,
which return lists of indices.
</p> 

<p>
<tt>pop</tt> changes the contents of the target list.
The popped element is returned.
</p>

<!-- example -->

<pre>
(set 'pList '((f g) a b c "hello" d e 10))

(pop pList)  <span class='arw'>&rarr;</span> (f g)
(pop pList)  <span class='arw'>&rarr;</span> a
pList        <span class='arw'>&rarr;</span> (b c "hello" d e 10)

(pop pList 3)    <span class='arw'>&rarr;</span> d
(pop pList -1)   <span class='arw'>&rarr;</span> 10
pList            <span class='arw'>&rarr;</span> (b c "hello" e)

(pop pList -1)  <span class='arw'>&rarr;</span> e
pList           <span class='arw'>&rarr;</span> (b c "hello")

(pop pList -2)  <span class='arw'>&rarr;</span> c
pList           <span class='arw'>&rarr;</span> (b "hello")

(set 'pList '(a 2 (x y (p q) z)))

(pop pList -1 2 0)  <span class='arw'>&rarr;</span> p

;; use indices in a list
(set 'pList '(a b (c d () e)))

(push 'x pList '(2 2 0))  
<span class='arw'>&rarr;</span> (a b (c d (x) e))

pList
<span class='arw'>&rarr;</span> (a b (c d (x) e))

(ref 'x pList)  <span class='arw'>&rarr;</span> (2 2 0)

(pop pList '(2 2 0))  <span class='arw'>&rarr;</span> x
</pre>


<p><tt>pop</tt> can also be used on strings with one index:</p>

<!-- example -->

<pre>
;; use pop on strings

(set 'str "newLISP")

(pop str -4 4)  <span class='arw'>&rarr;</span> "LISP"

str  <span class='arw'>&rarr;</span> "new"

(pop str 1)  <span class='arw'>&rarr;</span> "e"

str  <span class='arw'>&rarr;</span> "nw"

(set 'str "x")

(pop str)  <span class='arw'>&rarr;</span> "x"
(pop str)  <span class='arw'>&rarr;</span> ""
</pre>


<p>Popping an empty string will return an empty string.</p>

<p>
See also the <a href="#push">push</a> function, the inverse operation to <tt>pop</tt>.
</p>

<br/><br/>

<a name="pop-assoc"></a>
<h2><span class="function">pop-assoc</span>&nbsp;<a href="#destructive">!</a></h2>
<h4>syntax: (pop-assoc <em>exp-key</em> <em>list-assoc</em>)<br/>
syntax: (pop-assoc <em>list-keys</em> <em>list-assoc</em>)</h4>

<p>Removes an association referred to by the key in <em>exp-key</em> from the association 
list in <em>list-assoc</em> and returns the popped expression.</p>

<!-- example -->

<pre>
;; simple associations

(set 'L '((a 1) (b 2) (c 3)))
(pop-assoc 'b L) <span class='arw'>&rarr;</span> (b 2)
L <span class='arw'>&rarr;</span> ((a 1) (c 3))

;; nested associations

(set 'L '((a (b 1) (c (d 2)))))
(pop-assoc 'a L) <span class='arw'>&rarr;</span> (a (b 1) (c (d 2)))
L <span class='arw'>&rarr;</span> ()

(set 'L '((a (b 1) (c (d 2)))))
(pop-assoc '(a b) L)  <span class='arw'>&rarr;</span> (b 1)
L <span class='arw'>&rarr;</span>  ((a (c (d 2))))

(set 'L '((a (b 1) (c (d 2)))))
(pop-assoc '(a c) L)  <span class='arw'>&rarr;</span> (c (d 2))
L <span class='arw'>&rarr;</span> ((a (b 1))))
</pre>


<p>See also <a href="#assoc">assoc</a> for retrieving associations and <a href="#setf">setf</a> 
for modifying association lists.</p>

<br/><br/>

<a name="post-url"></a>
<h2><span class="function">post-url</span></h2>
<h4>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>]]])</h4>

<p>
Sends an HTTP POST request to the URL in <em>str-url</em>.
POST requests are used to post information collected from web entry forms to a web site.
Most of the time,
the function <tt>post-url</tt> mimics what a web browser would do when sending information 
collected in an HTML form to a server,
but it can also be used to upload files (see an HTTP reference).
The function returns the page returned from the server in a string.
</p>

<p>
When <tt>post-url</tt> encounters an error,
it returns a string description of the error beginning with <tt>ERR:</tt>.
</p>

<p>
The last parameter,
<em>int-timeout</em>,
is for an optional timeout value,
which is specified in milliseconds.
When no response from the host is received before the timeout has expired,
the string <tt>ERR:
timeout</tt> is returned. 
</p>
<!-- example -->

<pre>
;; specify content type
(post-url "http://somesite.com/form.pl" 
          "name=johnDoe&amp;city=New%20York" 
          "application/x-www-form-urlencoded")

;; specify content type and timeout
(post-url "http://somesite.com/form.pl" 
          "name=johnDoe&amp;city=New%20York" 
          "application/x-www-form-urlencoded" 8000)

;; assumes default content type and no timeout
(post-url "http://somesite.com/form.pl"
          "name=johnDoe&amp;city=New%20York" 
</pre>


<p>
The above example uploads a user name and city using a special format called 
<tt>application/x-www-form-urlencoded</tt>.
<tt>post-url</tt> can be used to post other content types such as files or binary data.
See an HTTP reference for other content-type specifications and data encoding formats.
When the content-type parameter is omitted,
<tt>post-url</tt> assumes <tt>application/x-www-form-urlencoded</tt> as the default content type.
</p>

<h3>Additional parameters</h3>
<p>
When <em>str-content-type</em> is specified, the optional <em>str-option</em> 
can take the same options as <a href="#get-url">get-url</a> for the returned 
content.  If the <em>int-timeout</em> option is specified, the custom header 
option <em>str-header</em> can be specified, as well. See the function 
<a href="#get-url">get-url</a> for details on all options.
</p>

<p>
See also the <a href="#get-url">get-url</a> and <a href="#put-url">put-url</a> functions.
</p>

<br/><br/>

<a name="pow"></a>
<h2><span class="function">pow</span></h2>
<h4>syntax: (pow <em>num-1</em> <em>num-2 </em> [<em>num-3</em> ... ])<br/>
syntax: (pow <em>num-1</em>)</h4>

<p>
Calculates <em>num-1</em> to the power of <em>num-2</em> and so forth.
</p>

<!-- example -->

<pre>
(pow 100 2)      <span class='arw'>&rarr;</span> 10000
(pow 100 0.5)    <span class='arw'>&rarr;</span> 10
(pow 100 0.5 3)  <span class='arw'>&rarr;</span> 1000

(pow 3)  <span class='arw'>&rarr;</span> 9
</pre>


<p>
When <em>num-1</em> is the only argument,
<tt>pow</tt> assumes 2 for the exponent.
</p>

<br/><br/>

<a name="prefix"></a>
<h2><span class="function">prefix</span></h2>
<h4>syntax: (prefix <em>sym</em>)</h4>

<p>Returns the context of a symbol in <em>sym</em>:</p>


<!-- example -->

<pre>
(setf s 'Foo:bar)      <span class='arw'>&rarr;</span> Foo:bar
(prefix s)             <span class='arw'>&rarr;</span> Foo
(context? (prefix s))  <span class='arw'>&rarr;</span> true

(term s)                         <span class='arw'>&rarr;</span> "bar"
(= s (sym (term s) (prefix s)))  <span class='arw'>&rarr;</span> true

<b>&gt;</b>(context (prefix s))   ; switches to context Foo
<b>Foo</b>
<b>Foo&gt;</b>
</pre>

<p>See also <a href="#term">term</a> to extract the term part of
a symbol.</p>

<br/><br/>

<a name="pretty-print"></a>

<h2><span class="function">pretty-print</span></h2>
<h4>syntax: (pretty-print [<em>int-length</em> [<em>str-tab</em> [<em>str-fp-format</em>]])</h4>

<p>
Reformats expressions for <a href="#print">print</a>,
<a href="#save">save</a>,
or <a href="#source">source</a> and when printing in an interactive console.
The first parameter, <em>int-length</em>, specifies the maximum line length,
and <em>str-tab</em> specifies the string used to indent lines. The third
parameter <em>str-fp-format</em> describes the default format for printing
floating point numbers.  All parameters are optional.  <tt>pretty-print</tt> 
returns the current settings or the new settings when parameters are specified.
</p>

<!-- example -->

<pre>
(pretty-print)  <span class='arw'>&rarr;</span> (80 " " "&#037;1.15g")  ; default setting

(pretty-print 90 "\t")  <span class='arw'>&rarr;</span> (90 "\t" "&#037;1.15g")

(pretty-print 100)  <span class='arw'>&rarr;</span> (100 "\t" "&#037;1.15g") 

(sin 1)    <span class='arw'>&rarr;</span> 0.841470984807897 
(pretty-print 80 " " "&#37;1.3f")
(sin 1)    <span class='arw'>&rarr;</span> 0.841

(set 'x 0.0)
x   <span class='arw'>&rarr;</span> 0.000
</pre>


<p>
The first example reports the default settings of 80 for the maximum line length and a 
<tt>space</tt> character for indenting. The second example changes the line length to 
90 and the indent to a TAB character. The third example changes the line length only.
The last example changes the default format for floating point numbers. This is useful
when printing unformatted floating point numbers without fractional parts, and these 
numbers should still be recognizable as floating point numbers. Without the custom
format, <tt>x</tt> would be printed as <tt>0</tt> indistinguishable from floating
point number. All situations where unformatted floating point numbers are printed,
are affected.</p>

<p>
Note that <tt>pretty-print</tt> cannot be used to prevent line breaks from being printed.
To completely suppress pretty printing, use the function <a href="#string">string</a> 
to convert the expression to a raw unformatted string as follows:</p>

<!-- example -->

<pre>
;; print without formatting

(print (string my-expression))	
</pre>

<br/><br/>

<a name="primitivep"></a>
<h2><span class="function">primitive?</span></h2>
<h4>syntax: (primitive? <em>exp</em>)</h4>

<p>
Evaluates and tests if <em>exp</em> is a primitive symbol and returns
<tt>true</tt> or <tt>nil</tt> depending on the result. All built-in
functions and functions created using <a href="#import">import</a>
are primitives.
</p>

<!-- example -->

<pre>
(set 'var define)
(primitive? var)  <span class='arw'>&rarr;</span> true
</pre>

<br/><br/>

<a name="print"></a>
<h2><span class="function">print</span></h2>
<h4>syntax: (print <em>exp-1</em> [<em>exp-2</em> ... ])</h4>

<p>
Evaluates and prints <em>exp-1</em>&mdash;
to the current I/O device,
which defaults to the console window.
See the built-in function <a href="#device">device</a> for details on how to specify a different I/O device.
</p>

<p>
List expressions are indented by the nesting levels of their opening parentheses.
</p>

<p>
Several special characters may be included in strings encoded with the escape character <tt>\</tt>:
</p>
 
<table  summary="escape characters in print">
<tr align="left" valign="bottom"><th>character</th><th>description</th></tr>

<tr>
<td><tt>\n</tt></td>
<td>the line-feed character (ASCII 10)</td>

</tr>

<tr>
<td><tt>\r</tt></td>
<td>the carriage-return character (ASCII 13)</td>
</tr>

<tr>
<td><tt>\t</tt></td>
<td>the tab character (ASCII 9)</td>
</tr>

<tr>

<td><tt>\nnn</tt></td>
<td>where <tt>nnn</tt> is a decimal ASCII code between 000 and 255</td>
</tr>

<tr>
<td><tt>\xnn</tt></td>
<td>where <tt>nn</tt> is a hexadecimal ASCII code between 00 and FF</td>
</tr>

</table><br/>

<br/>
<!-- example -->

<pre>
(print (set 'res (+ 1 2 3))) 
(print "the result is" res "\n")

"\065\066\067"  <span class='arw'>&rarr;</span> "ABC"
</pre>


<p>
	To finish printing with a line-feed,
	use <a href="#println">println</a>.
</p>

<br/><br/>

<a name="println"></a>
<h2><span class="function">println</span></h2>
<h4>syntax: (println <em>exp-1</em> [<em>exp-2</em> ... ])</h4>

<p>
	Evaluates and prints <em>exp-1</em>&mdash;
	to the current I/O device,
	which defaults to the console window.
	A line-feed is printed at the end.
	See the built-in function <a href="#device">device</a> for details on how to specify a different I/O device.
	<tt>println</tt> works exactly like <a href="#print">print</a> but emits a line-feed character at the end.
</p>

<p>
	See also the <a href="#write-line">write-line</a> and <a href="#print">print</a> functions.
</p>

<br/><br/>

<a name="prob-chi2"></a>
<h2><span class="function">prob-chi2</span></h2>
<h4>syntax: (prob-chi2 <em>num-chi2</em> <em>int-df</em>)</h4>

<p>Returns the probability of an observed <em>Chi&sup2;</em> statistic in <em>num-chi2</em> 
with <em>num-df</em> degrees of freedom to be equal or greater under the null hypothesis.
<tt>prob-chi2</tt> is derived from the incomplete Gamma function <a HREF="#gammai">gammai</a>.
</p>

<!-- example -->

<pre>
(prob-chi2 10 6)  <span class='arw'>&rarr;</span> 0.1246520195
</pre>


<p>
	See also the inverse function <a href="#crit-chi2">crit-chi2</a>.
</p> 

<br/><br/>

<a name="prob-f"></a>
<h2><span class="function">prob-f</span></h2>
<h4>syntax: (prob-f <em>num-f</em> <em>int-df1</em> <em>int-df2</em>)</h4>

<p>Returns the probability of an observed <em>F</em> statistic in <em>num-f</em> 
with <em>int-df1</em> and <em>int-df2</em> degrees of freedom to be equal or greater 
under the null hypothesis.</p>

<!-- example -->

<pre>
(prob-f 2.75 10 12)  <span class='arw'>&rarr;</span> 0.0501990804
</pre>


<p>
See also the inverse function <a href="#crit-f">crit-f</a>.
</p> 

<br/><br/>

<a name="prob-t"></a>
<h2><span class="function">prob-t</span></h2>
<h4>syntax: (prob-t <em>num-t</em> <em>int-df1</em>)</h4>

<p>Returns the probability of an observed <em>Student's t</em> statistic in <em>num-t</em> 
with <em>int-df</em> degrees of freedom to be equal or greater 
under the null hypothesis.</p>

<!-- example -->

<pre>
(prob-t 1.76 14)  <span class='arw'>&rarr;</span> 0.05011454551
</pre>


<p>
See also the inverse function <a href="#crit-t">crit-t</a>.
</p> 

<br/><br/>

<a name="prob-z"></a>
<h2><span class="function">prob-z</span></h2>
<h4>syntax: (prob-z <em>num-z</em>)</h4>

<p>
	Returns the probability of <em>num-z</em>,
	not to exceed the observed value where <em>num-z</em> is a normal distributed 
	value with a mean of <tt>0.0</tt> and a standard deviation of <tt>1.0</tt>.
</p>

<!-- example -->

<pre>
(prob-z 0.0)  <span class='arw'>&rarr;</span> 0.5
</pre>



<p>
	See also the inverse function <a href="#crit-z">crit-z</a>.
</p> 

<br/><br/>

<a name="process"></a>
<h2><span class="function">process</span></h2>
<h4>syntax: (process <em>str-command</em>)<br/>
syntax: (process <em>str-command</em> <em>int-pipe-in</em> <em>int-pipe-out</em> [<em>int-win-option</em>])<br/>
syntax: (process <em>str-command</em> <em>int-pipe-in</em> <em>int-pipe-out</em> [<em>int-unix-pipe-error</em>])</h4>

<p>
In the first syntax,
<tt>process</tt> launches a  process specified in <em>str-command</em> and immediately 
returns with a process ID or <tt>nil</tt> if a process could not be created. This 
process will execute the program specified or immediately die if <em>str-command</em> could not be executed.
</p>

<p>On macOS and other Unixes, the application or script must be specified with its full path-name.
The new process inherits the OS environment from the parent process.</p>

<p>Command line arguments are parsed out at spaces. Arguments containing spaces must be delimited using
single quotes on macOS and other Unixes. On MS Windows, double quotes are used. The process id returned
can be used to destroy the running process using <a href="#destroy">destroy</a>, if the process does
not exit by itself.</p>

<!-- example -->

<pre>
(process "c:/WINDOWS/system32/notepad.exe")  <span class='arw'>&rarr;</span> 1894 ; Windows
; or when in executable path
(process "notepad.exe")                      <span class='arw'>&rarr;</span> 1894 ; Windows


; find out the path of the program to start using exec, 
; if the path is not known

(process (first (exec "which xclock")))  <span class='arw'>&rarr;</span> 22607 ; on Unix
</pre>


<p>If the path of the executable is unknown, <tt>exec</tt> together with the Unix <tt>which</tt>
command can be used to start a program. The pid returned can be used to <a href="#destroy">destroy</a>
the process.</p>

<p>In the second syntax,
standard input and output of the created process can be redirected to pipe handles.
When remapping standard I/O of the launched application to a pipe,
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">write</a> and 
<a href="#read">read</a> statements:</p>

<!-- example -->

<pre>
;; Linux/Unix
;; create pipes
(map set '(myin bcout) (pipe))
(map set '(bcin myout) (pipe))   

;; launch Unix 'bc' calculator application
(process "/usr/bin/bc" bcin bcout) <span class='arw'>&rarr;</span> 7916

(write-line myout "3 + 4")  ; bc expects a line-feed

(read-line myin)  <span class='arw'>&rarr;</span> "7"


;; bc can use bignums with arbitrary precision

(write-line myout "123456789012345 * 123456789012345")

(read-line myin)  <span class='arw'>&rarr;</span> "15241578753238669120562399025"

;; destroy the process
(destroy 7916)

;; MS Windows
(map set '(myin cmdout) (pipe))
(map set '(cmdin myout) (pipe))

(process "c:/Program Files/newlisp/newlisp.exe -c" cmdin cmdout)
<span class='arw'>&rarr;</span> 1284

(write-line myout "(+ 3 4)")

(read-line myin) <span class='arw'>&rarr;</span> "7"

;; destroy the process
(destroy 1284)
</pre>


<p>On MS Windows versions of newLISP, a fourth optional parameter of <em>int-win-option</em> 
can be specified to control the display status of the application.
This option defaults to <tt>1</tt> for showing the application's window,
<tt>0</tt> for hiding it, and <tt>2</tt> for showing it minimized on the Windows 
launch bar.</p>

<p>On both MS Windows and Linux/Unix systems, standard error will be redirected to 
standard out by default. On Linux/Unix, an optional pipe handle for standard 
error output can be defined in <em>int-unix-pipe-error</em>.</p>

<p>The function <a href="#peek">peek</a> can be used to check for information 
on the pipe handles:</p>


<pre>
;; create pipes
(map set '(myin bcout) (pipe))
(map set '(bcin myout) (pipe))   
(map set '(errin errout) (pipe))   

;; launch Unix 'bc' calculator application
(process "bc" bcin bcout errout)

(write myout command)

;; wait for bc sending result or error info
(while (and (= (peek myin) 0)
            (= (peek errin) 0)) (sleep 10))

(if (&gt; (peek errin) 0)
	(println (read-line errin)))
	
(if (&gt; (peek myin) 0)
	(println (read-line myin)))
</pre>


<p>
	 Not all interactive console applications 
   can have their standard I/O channels remapped.
	Sometimes only one channel,
	<em>in</em> or <em>out</em>,
	can be remapped.
	In this case,
	specify <tt>0</tt> (zero) for the unused channel.
	The following statement uses only the launched application's output:
</p>


<pre>
(process "app" 0 appout)
</pre>


<p>
	Normally,
	two pipes are used:
	one for communications to the child process and the other one for communications from the child process.
</p>

<p>
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.
See the <a href="#fork">fork</a> and <a href="#spawn">spawn</a> functions for other ways of starting 
newLISP processes. Both are only available on macOS, Linux and other Unix like operating systems.
</p>

<br/><br/>

<a name="prompt-event"></a>
<h2><span class="function">prompt-event</span></h2>
<h4>syntax: (prompt-event <em>sym-event-handler</em> | <em>func-event-handler</em>)<br/>
syntax: (prompt-event nil)</h4>

<p>Refines the prompt as shown in the interactive newLISP shell.
The <em>sym-event-handler</em> or <em>func-event-handler</em>
is either a symbol of a user-defined function or a lambda expression:</p>

<p>To reset <tt>prompt-event</tt> to the original state, use the second syntax.</p>

<pre>
<b>></b> (prompt-event (fn (ctx) (string ctx ":" (real-path) "$ ")))
<b>$prompt-event</b>
<b>MAIN:/Users/newlisp$</b> (+ 3 4)
<b>7</b>
<b>MAIN:/Users/newlisp$</b>
</pre>

<p>The current context before calling the <tt>prompt-event</tt> code is passed as a 
parameter to the function. Computer output is shown in bold.</p>

<p>The example redefines the <tt>&gt;</tt> prompt to be the current context followed
by a colon <tt>:</tt>, followed by the directory name, followed by the dollar symbol. 
Together with the <a href="#command-event">command-event</a> function this can be 
used to create fully customized shells or custom command interpreters.</p>

<p>The function in <tt>prompt-event</tt> must return a string of 63 characters maximum. 
Not returning a string will leave the prompt unchanged.</p>

<br/><br/>

<a name="protectedp"></a>
<h2><span class="function">protected?</span></h2>

<h4>syntax: (protected? <em>sym</em>)</h4>

<p>Checks if a symbol in <em>sym</em> is protected. Protected symbols are built-in
functions, context symbols, and all symbols made constant using the <a href="#constant">constant</a>
function:</p>


<pre>
(protected? 'println)    <span class='arw'>&rarr;</span> true
(constant 'aVar 123)
(protected? 'aVar)       <span class='arw'>&rarr;</span> true
</pre>

<br/><br/>

<a name="push"></a>
<h2><span class="function">push</span>&nbsp;<a href="#destructive">!</a>&nbsp;<font size="-1"><a href="#utf8_capable">utf8</a></font></h2>
<h4>syntax: (push <em>exp</em> <em>list</em> [<em>int-index-1</em> [<em>int-index-2</em> ... ]])<br/>
syntax: (push <em>exp</em> <em>list</em> [<em>list-indexes</em>])<br/><br/>

syntax: (push <em>str-1</em> <em>str-2</em> [<em>int-index</em>])</h4>

<p>
Inserts the value of <em>exp</em> into the list <em>list</em>.
If <em>int-index</em> is present, the element is inserted at that index.
If the index is absent, the element is inserted at index <tt>0</tt> (zero),
the first element. <tt>push</tt> is a destructive operation that changes the 
contents of the target list.</p>

<p>The list changed is returned as a reference on which other built-in
functions can work. See also <a href="#indexing">Indexing elements of 
strings and lists</a>.</p>

<p>
If more than one <em>int-index</em> is present, the indices are used to 
access a nested list structure. Improper indices (those not matching list 
elements) are discarded.</p>

<p>
The second version takes a list of <em>list-indexes</em> but is otherwise 
identical to the first. In this way, <tt>push</tt> works easily together 
with <a href="#ref">ref</a> and <a href="#ref-all">ref-all</a>,
which return lists of indices.
</p>

<p>
If <em>list</em> does not contain a list, <em>list</em> must contain a 
<tt>nil</tt> and will be initialized to the empty list.
</p>

<p>
Repeatedly using <tt>push</tt> to the end of a list using <tt>-1</tt> as 
the <em>int-index</em> is optimized and as fast as pushing 
to the front of a list with no index at all. This can be used to efficiently 
grow a list.
</p>

<!-- example -->

<pre>
; inserting in front
(set 'pList '(b c))  <span class='arw'>&rarr;</span> (b c)
(push 'a pList)      <span class='arw'>&rarr;</span> (a b c)
pList                <span class='arw'>&rarr;</span> (a b c)

; insert at index
(push "hello" pList 2)  <span class='arw'>&rarr;</span> (a b "hello" c)

; optimized appending at the end
(push 'z pList -1)  <span class='arw'>&rarr;</span> (a b "hello" c z)

; inserting lists in lists
(push '(f g) pList)  <span class='arw'>&rarr;</span> ((f g) a b "hello" c z)

; inserting at negative index
(push 'x pList -3)  <span class='arw'>&rarr;</span> ((f g) a b "hello" x c z)

; using multiple indices
(push 'h pList 0 -1)  <span class='arw'>&rarr;</span> ((f g h) a b "hello" x c z)

; use indices in a list
(set 'pList '(a b (c d () e)))

(push 'x pList '(2 2 0))  <span class='arw'>&rarr;</span> (a b (c d (x) e))

(ref 'x pList)   <span class='arw'>&rarr;</span> (2 2 0)

(pop pList '(2 2 0))  <span class='arw'>&rarr;</span> x

; the target list is a place reference
(set 'lst '((a 1) (b 2) (c 3) (d)))

(push 4 (assoc 'd lst) -1) <span class='arw'>&rarr;</span> (d 4)

lst <span class='arw'>&rarr;</span> ((a 1) (b 2) (c 3) (d 4))


; push on un-initialized symbol
aVar  <span class='arw'>&rarr;</span> nil 

(push 999 aVar)  <span class='arw'>&rarr;</span> (999)

aVar  <span class='arw'>&rarr;</span> (999)
</pre>


<p><tt>push</tt> and pop can be combined to model a queue:</p>

<pre>
; pop and push a as a queue
(set 'Q '(a b c d e))

(pop (push 'f Q -1)) <span class='arw'>&rarr;</span> a
(pop (push 'g Q -1)) <span class='arw'>&rarr;</span> b

Q <span class='arw'>&rarr;</span>  (c d e f g)
</pre>


<p>Because <tt>push</tt> returns a reference to the modified list,
<tt>pop</tt> can work on it directly.</p>

<p>In the third syntax <tt>push</tt> can be used to change strings. When
<em>int-index</em> is used, it refers to character positions rather than 
byte positions. UTF-8 characters may be multi-byte characters.</p>

<pre>
;; push on strings

(set 'str "abcdefg")

(push "hijk" str -1)  <span class='arw'>&rarr;</span> "abcdefghijk"
str                   <span class='arw'>&rarr;</span> "abcdefghijk"

(push "123" str)  <span class='arw'>&rarr;</span> "123abcdefghijk"
(push "4" str 3)  <span class='arw'>&rarr;</span> "1234abcdefghijk"

(set 'str "\u03b1\u03b2\u03b3")  <span class='arw'>&rarr;</span>  "αβγ"

(push "*" str 1)  <span class='arw'>&rarr;</span>  "α*βγ"

;; push on a string reference

(set 'lst '("abc" "xyz"))

(push x (lst 0)) <span class='arw'>&rarr;</span> "xabc"

lst <span class='arw'>&rarr;</span> ("xabc" "xyz")
</pre>

<p>See also the <a href="#pop">pop</a> function, which is the inverse operation to <tt>push</tt>.
</p>

<br/><br/>

<a name="put-url"></a>
<h2><span class="function">put-url</span></h2>
<h4>syntax: (put-url <em>str-url</em> <em>str-content</em> [<em>str-option</em>] [<em>int-timeout</em> [<em>str-header</em>]])</h4>

<p>
	The HTTP PUT protocol is used to transfer information in <em>str-content</em> 
	to a file specified in <em>str-url</em>. The lesser-known HTTP PUT mode is 
	frequently used for transferring web pages from HTML editors to Web servers.
	In order to use PUT mode, the web server's software must be configured correctly.
	On the Apache web server,
	use the <tt>'Script PUT'</tt> directive in the section where directory access rights are configured.
</p>

<p>If <em>str-url</em> starts with <tt>file://</tt> then <em>str-content</em> is written
to the local file system.</p>

<p>
	Optionally,
	an <em>int-timeout</em> value can be specified in milliseconds as the last parameter.
	<tt>put-url</tt> will return <tt>ERR:
	timeout</tt> when the host gives no response and the timeout expires.
	On other error conditions,
	<tt>put-url</tt> returns a string starting with <tt>ERR:</tt> and the description of the error.
</p>

<p><tt>put-url</tt> requests are also understood by newLISP server nodes, but will
not be served when the server is started in <tt>-http-safe</tt> mode.</p>

<!-- example -->

<pre>
(put-url "http://asite.com/myFile.txt" "Hi there")
(put-url "http://asite.com/myFile.txt" "Hi there" 2000)

(put-url "http://asite.com/webpage.html" 
    (read-file "webpage.html"))

; write /home/joe/newfile.txt on the local file system
(puts-url "file:///home/joe/newfile.txt" "Hello World!")
</pre>


<p>
	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.
	In the second example,
	the local file <tt>webpage.html</tt> is transferred to <tt>asite.com</tt>.
</p>

<p>
	On an Apache web server,
	the following could be configured in <tt>httpd.conf</tt>.
</p>

<!-- example -->

<pre>
&lt;directory /www/htdocs&gt;
Options All
Script PUT /cgi-bin/put.cgi
&lt;/directory&gt;
</pre>


<p>
	 The script <tt>put.cgi</tt> would contain code to receive content from the web server via STDIN.
	The following is a working <tt>put.cgi</tt> written in newLISP for the Apache web server:
</p>

<!-- example -->
<pre>
#!/usr/home/johndoe/bin/newlisp
#
#
# get PUT method data from CGI STDIN 
# and write data to a file specified
# int the PUT request
# 
#


(print "Content-Type: text/html\n\n")

(set 'cnt 0)
(set 'result "")

(if (= "PUT" (env "REQUEST_METHOD"))
    (begin
      (set 'len (int (env "CONTENT_LENGTH")))

      (while (&lt; cnt len)
          (set 'n (read (device) buffer len))
          (if (not n) 
            (set 'cnt len) 
            (begin 
              (inc cnt n)
              (write result buffer))))
              
      (set 'path (append 
              "/usr/home/johndoe" 
              (env "PATH_TRANSLATED")))

      (write-file path result)
    )
)

(exit)
</pre>


<p>
	Note that the script appends ".txt" to the path to avoid the CGI execution of uploaded malicious scripts.
	Note also that the two lines where the file path is composed may work differently in your web server environment.
	Check environment variables passed by your web server for composition of the right file path.
</p>

<p>
	<tt>put-url</tt> returns content returned by the <tt>put.cgi</tt> script.
</p>

<h3>Additional parameters</h3>
<p>
In <em>str-option</em> can take the same options as <a href="#get-url">get-url</a>
for the returned content. If the <em>int-timeout</em> option is specified, the 
custom header option <em>str-header</em> can be specified, as well. See the 
function <a href="#get-url">get-url</a> for details on all options.
</p>

<p>
See also the functions <a href="#get-url">get-url</a> and <a href="#post-url">post-url</a>,
which can be used to upload files when formatting form data as <tt>multipart/form-data</tt>.
</p>

<br/><br/>

<a name="pv"></a>
<h2><span class="function">pv</span></h2>
<h4>syntax: (pv <em>num-int</em> <em>num-nper</em> <em>num-pmt</em> 
[<em>num-fv</em> [<em>int-type</em>]])</h4>

<p>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. The future value <em>num-fv</em> 
is assumed to be <tt>0.0</tt> if omitted. If payment is at the end of the 
period, <em>int-type</em> is <tt>0</tt> (zero) or <em>int-type</em> is omitted; 
for payment at the beginning of each period, <em>int-type</em> is 1.</p>

<!-- example -->

<pre>
(pv (div 0.07 12) 240 775.30)  <span class='arw'>&rarr;</span> -100000.1373
</pre>

<p>
	In the example,
	a loan that would be paid off (future value = <tt>0.0</tt>) in 240 payments of $775.30 at a 
	constant interest rate of 7 percent per year would start out at $100,000.14.
</p>

<p>
	See also the <a href="#fv">fv</a>,
	<a href="#irr">irr</a>,
	<a href="#nper">nper</a>,
	<a href="#npv">npv</a>,
	and <a href="#pmt">pmt</a> functions.
</p>

<br/><br/>

<a name="quote"></a>
<h2><span class="function">quote</span></h2>
<h4>syntax: (quote <em>exp</em>)</h4>

<p>Returns <em>exp</em> without evaluating it. The same effect can be obtained by 
prepending a <tt>'</tt> (single quote) to <em>exp</em>. The function <tt>quote</tt> 
is resolved during runtime, the prepended <tt>'</tt> quote is translated into a 
protective envelope (quote cell) during code translation.</p>

<!-- example -->

<pre>
(quote x)         <span class='arw'>&rarr;</span> x
(quote 123)       <span class='arw'>&rarr;</span> 123
(quote (a b c))   <span class='arw'>&rarr;</span> (a b c)
(= (quote x) 'x)  <span class='arw'>&rarr;</span> true
</pre>

<br/><br/>

<a name="quotep"></a>
<h2><span class="function">quote?</span></h2>
<h4>syntax: (quote? <em>exp</em>)</h4>

<p>
	 Evaluates and tests whether <em>exp</em> is quoted.
	Returns <tt>true</tt> or <tt>nil</tt> depending on the result.
</p>

<!-- example -->

<pre>
(set 'var ''x)  <span class='arw'>&rarr;</span> 'x
(quote? var)    <span class='arw'>&rarr;</span> true
</pre>

<p>
	 Note that in the <tt>set</tt> statement,
	<tt> ''x</tt> is quoted twice because the first quote 
  is lost during the evaluation of the <tt>set</tt> assignment.
</p>

<br/><br/>

<a name="rand"></a>
<h2><span class="function">rand</span></h2>
<h4>syntax: (rand <em>int-range</em> [<em>int-N</em>])</h4>

<p>
	Evaluates the expression in <em>int-range</em> 
	and generates a random number in the range of 
	<tt>0</tt> (zero) to (<em>int-range</em> - 1). 
	When <tt>0</tt> (zero) is passed, 
	the internal random generator 
	is initialized using 
	the current value returned by 
	the C <tt>time()</tt> function. 
	Optionally, a second parameter 
	can be specified to return 
	a list of length <em>int-N</em> 
	of random numbers.
</p>

<!-- example -->

<pre>
(dotimes (x 100) (print (rand 2))) =&gt;
11100000110100111100111101 ... 10111101011101111101001100001000

(rand 3 100)  <span class='arw'>&rarr;</span> (2 0 1 1 2 0 &hellip;)
</pre>


<p>
	The first line in the example 
	prints equally distributed <tt>0</tt>'s and <tt>1</tt>'s, 
	while the second line produces a list 
	of 100 integers with 
	<tt>0</tt>, <tt>1</tt>, and <tt>2</tt> equally distributed. 
	Use the <a href="#random">random</a> 
	and <a href="#normal">normal</a> functions
	to generate floating point
	random numbers, 
	and use <a href="#seed">seed</a> to vary 
	the initial seed 
	for random number generation.
</p>

<br/><br/>

<a name="random"></a>
<h2><span class="function">random</span></h2>
<h4>syntax: (random <em>float-offset</em> <em>float-scale</em> <em>int-n</em>)<br/>
syntax: (random <em>float-offset</em> <em>float-scale</em>)</h4>

<p>
	In the first form, 
	<tt>random</tt> returns a list of <em>int-n</em> 
	evenly distributed floating point numbers 
	scaled (multiplied) by <em>float-scale</em>, 
	with an added offset of <em>float-offset</em>. 
	The starting point of the internal random generator 
	can be seeded using <a href="#seed">seed</a>.
</p>

<!-- example -->

<pre>
(random 0 1 10)
<span class='arw'>&rarr;</span> (0.10898973 0.69823783 0.56434872 0.041507289 0.16516733
    0.81540917 0.68553784 0.76471068 0.82314585 0.95924564)
</pre>


<p>
	When used in the second form, 
	<tt>random</tt> returns a single 
	evenly distributed number:
</p>


<pre>
(random 10 5)  <span class='arw'>&rarr;</span> 11.0971
</pre>

<p> When no parameters are given, <tt>random</tt> assumes a mean of <tt>0.0</tt> 
and a standard deviation of <tt>1.0</tt>.</p>

<p>
	See also the <a href="#normal">normal</a> 
	and <a href="#rand">rand</a> functions.
</p>

<br/><br/>

<a name="randomize"></a>
<h2><span class="function">randomize</span></h2>
<h4>syntax: (randomize <em>list</em> [<em>bool</em>])</h4>

<p>
	Rearranges the order of elements in <em>list</em> 
	into a random order.
</p>

<!-- example -->

<pre>
(randomize '(a b c d e f g))  <span class='arw'>&rarr;</span> (b a c g d e f)
(randomize (sequence 1 5))    <span class='arw'>&rarr;</span> (3 5 4 1 2)
</pre>


<p>
	<tt>randomize</tt> will always return 
	a sequence different from the previous one 
	without the optional <em>bool</em> flag. 
	This may require the function to calculate 
	several sets of reordered elements, 
	which in turn may lead to different processing times 
	with different invocations of the function 
	on the same input list length. 
	To allow for the output to be equal 
	to the input, <tt>true</tt> 
	or any expression evaluating to 
	not <tt>nil</tt> 
	must be specified in <em>bool</em>.
</p>

<p>
	<tt>randomize</tt> uses 
	an internal <em>pseudo random sequence</em> generator 
	that returns the same series of results 
	each time newLISP is started. 
	Use the <a href="#seed">seed</a> function to 
	change this sequence.
</p> 

<br/><br/>

<a name="read-buffer"></a>
<a name="read"></a>
<h2><span class="function">read</span>&nbsp;<a href="#destructive">!</a></h2>

<h4>syntax: (read <em>int-file</em> <em>sym-buffer</em> <em>int-size</em> [<em>str-wait</em>])</h4>

<p>
Reads a maximum of <em>int-size</em> bytes from a file specified in <em>int-file</em> 
into a buffer in <em>sym-buffer</em>.  Any data referenced by the symbol <em>sym-buffer</em> 
prior to the reading is deleted.  The handle in <em>int-file</em> is obtained from a 
previous <a href="#open">open</a> statement. The symbol <em>sym-buffer</em> contains 
data of type string after the read operation.  <em>sym-buffer</em> can also be a default 
functor specified by a context symbol for reference passing in and out of user-defined 
functions.</p>

<p><tt>read</tt> is a shorter writing of <tt>read-buffer</tt>. The longer
form still works but is deprecated and should be avoided in new code.</p>

<p>
	Optionally, 
	a string to be waited for 
	can be specified in <em>str-wait</em>. 
	<tt>read</tt> will read 
	a maximum amount of bytes 
	specified in <em>int-size</em> 
	or return earlier 
	if <em>str-wait</em> was found 
	in the data. 
	The wait-string is part
	of the returned data and must
    not contain binary <tt>0</tt> (zero)
    characters.
</p>

<p>
	Returns the number of bytes read or <tt>nil</tt> 
	when the wait-string was not found. 
	In any case, 
	the bytes read are put into the buffer 
	pointed to by <em>sym-buffer</em>, 
	and the file pointer of the file read 
	is moved forward. 
	If no new bytes have been read, 
	<em>sym-buffer</em> will contain <tt>nil</tt>.
</p>

<!-- example -->

<pre>
(set 'handle (open "aFile.ext" "read"))
(read handle buff 200)
</pre>


<p>
	Reads 200 bytes into the symbol <tt>buff</tt> 
	from the file <tt>aFile.ext</tt>.
</p>


<pre>
(read handle buff 1000 "password:")
</pre>


<p>
	Reads 1000 bytes or until 
	the string <tt>password:</tt> is encountered. 
	The string <tt>password:</tt> 
	will be part of the data returned.
</p>

<p>
	See also the <a href="#write">write</a> function. To start reading at 
	a specific position in the file, use the <a href="#seek">seek</a> function.
</p>

<br/><br/>

<a name="read-char"></a>
<h2><span class="function">read-char</span></h2>

<h4>syntax: (read-char [<em>int-file</em>])</h4>

<p>
Reads a byte from a file specified by the file handle in <em>int-file</em> 
or from the current I/O device - e.g. <em>stdin</em> - when no file handle is specified.
The file handle is obtained from a previous <a href="#open">open</a> operation. 
Each <tt>read-char</tt> advances the file pointer by one byte. 
Once the end of the file is reached, <tt>nil</tt> is returned.
</p>

<!-- example -->

<pre>
(define (slow-file-copy from-file to-file)
    (set 'in-file (open from-file "read"))
    (set 'out-file (open to-file "write"))
    (while (set 'chr (read-char in-file))
        (write-char out-file chr))
    (close in-file)
    (close out-file)
    "finished")
</pre>


<p>
	Use <a href="#read-line">read-line</a> 
	and <a href="#device">device</a> to read 
	whole text lines at a time. 
	Note that newLISP supplies 
	a fast built-in function 
	called <a href="#copy-file">copy-file</a> 
	for copying files.
</p>

<p>
	See also the <a href="#write-char">write-char</a> function.
</p>

<br/><br/>

<a name="read-expr"></a>
<h2><span class="function">read-expr</span></h2>
<h4>syntax: (read-expr <em>str-source</em> [<em>sym-context</em> [<em>exp-error</em> [<em>int-offset</em>]]])</h4>

<p><tt>read-expr</tt> parses the first expressions it finds in <em>str-source</em> and 
returns the translated expression without evaluating it. An optional context in 
<em>sym-context</em> specifies a namespace for the translated expression.</p>

<p>After a call to <tt>read-expr</tt> the system variable <tt>$count</tt> contains the 
number of characters scanned.</p>

<p>If an error occurs when translating <em>str-source</em> the expression in
<em>exp-error</em> is evaluated and the result returned.</p>

<p><em>int-offset</em> specifies an optional offset into <em>str-source</em> where
processing should start. When calling <tt>read-expr</tt> repeatedly this number
can be updated using <tt>$count</tt>, the number of characters processed.</p>

<!-- example -->

<pre>
(set 'code "; a statement\n(define (double x) (+ x x))")

(read-expr code) <span class='arw'>&rarr;</span> (define (double x) (+ x x))

$count <span class='arw'>&rarr;</span> 41

</pre>


<p><tt>read-expr</tt> behaves similar to <a href="#eval-string">eval-string</a>
but without the evaluation step:</p>


<pre>
(read-expr "(+ 3 4)")    <span class='arw'>&rarr;</span> (+ 3 4)

(eval-string "(+ 3 4)")  <span class='arw'>&rarr;</span> 7
</pre>


<p>Using <tt>read-expr</tt> a customized code reader can be programmed
preprocessing expressions before evaluation.</p>

<p>See also <a href="#reader-event">reader-event</a> for preprocessing
expressions event-driven.</p>

<br/><br/>

<a name="read-file"></a>
<h2><span class="function">read-file</span></h2>
<h4>syntax: (read-file <em>str-file-name</em>)</h4>

<p>Reads a file in <em>str-file-name</em> in one swoop and returns a string buffer 
containing the data.</p>

<p>On failure the function returns <tt>nil</tt>. For error information, 
use <a href="#sys-error">sys-error</a> when used on files. When used
on URLs <a href="#net-error">net-error</a> gives more error
information.</p>

<!-- example -->

<pre>
(write-file "myfile.enc" 
    (encrypt (read-file "/home/lisp/myFile") "secret"))
</pre>


<p>
The file <tt>myfile</tt> is read, then encrypted using the password <tt>"secret"</tt> 
before being written back into a new file titled <tt>"myfile.enc"</tt> 
in the current directory.</p>

<p>
<tt>read-file</tt> can take an <tt>http://</tt> 
or <tt>file://</tt> URL in <em>str-file-name</em>. 
When the prefix is <tt>http://</tt>, <tt>read-file</tt> works exactly like 
<a href="#get-url">get-url</a> and can take the same additional parameters.</p>

<!-- example -->

<pre>
(read-file "http://asite.com/somefile.tgz" 10000)
</pre>


<p>
	The file <tt>somefile.tgz</tt> is retrieved from 
	the remote location <tt>http://asite.com</tt>. 
	The file transfer will time out after 10 seconds 
	if it is not finished. 
	In this mode, <tt>read-file</tt> can also be used 
	to transfer files from remote newLISP server nodes.</p>

<p>See also the <a href="#write-file">write-file</a> and 
<a href="#append-file">append-file</a> functions.
</p>

<br/><br/>

<a name="read-key"></a>
<h2><span class="function">read-key</span></h2>
<h4>syntax: (read-key [true])</h4>

<p>
Reads a key from the keyboard and returns an integer value. 
For navigation keys, more than one <tt>read-key</tt> call 
must be made depending of the platform OS. For keys representing 
ASCII characters, the return value is the same on all OSes, except 
for navigation keys and other control sequences like function keys, 
in which case the return values may vary on different OSes and 
configurations.
</p>

<p>When using the <tt>true</tt> flag the <tt>read-key</tt> is non-blocking
and a <tt>0</tt> (zero) is returned when no key has been pressed.
When not using the extra flag, the call to <tt>read-key</tt> is blocking
until a key is pressed.</p>



<!-- example -->

<pre>
(read-key)  <span class='arw'>&rarr;</span> 97  ; after hitting the A key
(read-key)  <span class='arw'>&rarr;</span> 65  ; after hitting the shifted A key
(read-key)  <span class='arw'>&rarr;</span> 10  ; after hitting [enter] on Linux
(read-key)  <span class='arw'>&rarr;</span> 13  ; after hitting [enter] on Windows

(read-key true)  <span class='arw'>&rarr;</span> 0 ; when no key has been pressed

(while (!= (set 'c (read-key)) 1) (println c))
</pre>


<p>
The last example can be used to check return sequences 
from navigation and function keys. To break out of the loop, 
press <tt>Ctrl-A</tt>.
</p>

<p>Note that <tt>read-key</tt> will only work when newLISP is running in a
Unix shell or Windows command shell. It will not work when executed by 
newLISP Unix shared library or newLISP MS Windows DLL (Dynamic Link Library).
These libraries are not listening to STD input.</p>

<br/><br/>

<a name="read-line"></a>

<h2><span class="function">read-line</span></h2>
<h4>syntax: (read-line [<em>int-file</em>])</h4>

<p>
	Reads from the current I/O device a string 
	delimited by a line-feed character (ASCII 10). 
	There is no limit 
	to the length of the string 
	that can be read. 
	The line-feed character is not part of the returned string. 
	The line always breaks on a line-feed, 
	which is then swallowed. 
	A line breaks on a carriage return (ASCII 13) 
	only if followed by a line-feed, 
	in which case both characters are discarded. 
	A carriage return alone only breaks and is swallowed 
	if it is the last character in the stream.
</p>

<p>
	By default, 
	the current <a href="#device">device</a> 
	is the keyboard (<a href="#device">device</a> <tt>0</tt>). 
	Use the built-in function <a href="#device">device</a> 
	to specify a different I/O device (e.g., a file). 
	Optionally, 
	a file handle can be specified 
	in the <em>int-file</em> obtained 
	from a previous <a href="#open">open</a> statement.
</p>

<p>
	The last buffer contents 
	from a read-line operation 
	can be retrieved using <a href="#current-line">current-line</a>.
</p>

<p>When <tt>read-line</tt> is reading from a file or from <em>stdin</em>
in a CGI program or pipe, it will return <tt>nil</tt> when input is exhausted.</p>

<p>When using <tt>read-line</tt> on <em>stdin</em>, line length is limited
to 2048 characters and performance is much faster.</p>

<!-- example -->

<pre>
(print "Enter a num:")
(set 'num (int (read-line)))

(set 'in-file (open "afile.dat" "read"))
(while (read-line in-file)
        (write-line))   
(close in-file)
</pre>


<p>
	The first example reads input from the keyboard 
	and converts it to a number. 
	In the second example, 
	a file is read line-by-line 
	and displayed on the screen. 
	The <tt>write-line</tt> statement 
	takes advantage of the fact 
	that the result from the last 
	<tt>read-line</tt> operation 
	is stored in a system internal buffer. 
	When <a href="#write-line">write-line</a> 
	is used without argument, 
	it writes the contents 
	of the last <tt>read-line</tt> buffer 
	to the screen.
</p>

<p>
	See also the <a href="#current-line">current-line</a> function
	for retrieving this buffer.
</p>

<br/><br/>

<a name="read-utf8"></a>
<h2><span class="function">read-utf8</span></h2>

<h4>syntax: (read-utf8 <em>int-file</em>)</h4>

<p>Reads an UTF-8 character from a file specified by the file handle in <em>int-file</em>. 
The file handle is obtained from a previous <a href="#open">open</a> operation. 
Each <tt>read-utf8</tt> advances the file pointer by the number of bytes contained
in the UTF-8 character.  Once the end of the file is reached, <tt>nil</tt> is returned. </p>

<p>The function returns an integer value which can be converted to a displayable UTF-8
character string using the <a href="#char">char</a> function.</p>

<!-- example -->
<pre>
(set 'fle (open "utf8text.txt" "read"))
(while (setq chr (read-utf8 fle))
	(print (char chr)))
</pre>


<p>The example reads a file containing UTF-8 encoded text and displays it to the
terminal screen.</p>

<br/><br/>


<a name="reader-event"></a>
<h2><span class="function">reader-event</span></h2>
<h4>syntax: (reader-event [<em>sym-event-handler | func-event-handler</em>])<br/>
syntax: (reader-event nil)</h4>

<p>An event handler can be specified to hook between newLISP's reader, 
translation and evaluation process. The function specified in 
<em>sym-event-handler</em> or <em>func-event-handler</em> gets called after 
newLISP translates an expression and before evaluating it. The event handler can do 
transformation on the expression before it gets evaluated.</p>

<p>Specifying <tt>nil</tt> for the event will reset it to the initial default state.</p>

<p>The following one-liner <tt>reader-event</tt> could be used to enhance
the interactive shell with a tracer:</p>

<!-- example -->
<pre>
<b>&gt;</b>(reader-event (lambda (ex) (print " =&gt; " ex)))
$reader-event
<b>&gt; (+ 1 2 3)
 =&gt; (+ 1 2 3)
6
&gt;</b>
</pre>

<p>The expression intercepted passes through unchanged, but output
is enhanced.</p>

<p>The reader event function will be called after each reading of an s-expression
by the <a href="#load">load</a> or <a href="#eval-string">eval-string</a> function.</p>

<p>In versions previous to 10.5.8 <tt>reader-event</tt> was used to define a 
<tt>macro</tt> expansion function in the module file <tt>macro.lsp</tt>. Starting 
version 10.5.8, newLISP has <a href="#macro">macro</a> as a built-in function 
behaving the same, but much faster when loading files and reading source.</p>

<br/><br/>

<a name="real-path"></a>
<h2><span class="function">real-path</span></h2>
<h4>syntax: (real-path [<em>str-path</em>])<br/>
syntax: (real-path <em>str-exec-name</em> true)
</h4>

<p>
In the first syntax <tt>real-path</tt> returns the full path from the relative 
file path given in <em>str-path</em>. If a path is not given, <tt>"."</tt> 
(the current directory) is assumed.</p>

<!-- example -->

<pre>
(real-path)  <span class='arw'>&rarr;</span> "/usr/home/fred"  ; current directory
(real-path "./somefile.txt")
<span class='arw'>&rarr;</span> "/usr/home/fred/somefile.txt"
</pre>

<p>In the second syntax <tt>real-path</tt> returns the full path for an 
executable found given in <em>str-exe-name</em>. This syntax relies on an 
environment variable PATH defined on UNIX and Windows systems.</p>

<pre>
(real-path "make" true) <span class='arw'>&rarr;</span> "/usr/bin/make"
</pre>

<p>The output length is limited by the OS's maximum allowed path length. 
If <tt>real-path</tt> fails (e.g., because of a nonexistent path), 
<tt>nil</tt> is returned.</p>

<br/><br/>

<a name="receive"></a>
<h2><span class="function">receive</span>&nbsp;<a href="#destructive">!</a></h2>
<h4>syntax: (receive <em>int-pid</em> <em>sym-message</em>)<br/>
syntax: (receive)</h4>

<p>In the first syntax, the function is used for message exchange between 
child processes launched with <a href="#spawn">spawn</a> and their parent 
process. The message received replaces the contents in <em>sym-message.</em></p>

<p>The function reads one message from the receiver queue of <em>int-pid</em>
for each invocation. When the queue is empty, <tt>nil</tt> is returned.</p>

<!-- example -->

<pre>
; sending process
(send spid "hello")  <span class='arw'>&rarr;</span> true

; receiving process
(receive pid msg)    <span class='arw'>&rarr;</span> true
msg                  <span class='arw'>&rarr;</span> "hello"
</pre>

<p>To make <tt>receive</tt> blocking and wait for arriving messages,
use the following form:</p>

<pre>
; wait until a message can be read
(until (receive pid msg))
</pre>

<p>The function will loop until a message can be read from the queue.</p>

<p>In the second syntax, the function returns a list of all child processes
with pending messages for the parent process:</p>

<!-- example -->
<pre>
; read pending messages from child processes
(dolist (pid (receive))
    (receive pid msg)
    (println "received message: " msg " from:" pid)
)
</pre>

<p>The list of child process IDs returned by <tt>(receive)</tt> only
contains PIDs of processes which have unread messages in their 
send queues. The <tt>(receive pid msg)</tt> statement now can
be issued non-blocking, because it always is guaranteed to find
a pending message in a child's message queue.</p>

<p>The <tt>receive</tt> function is not available on MS Windows.</p>

<p>For a more detailed discussion of this function and examples, see the
<a href="#send">send</a> function.</p>

<br/><br/>

<a name="ref"></a>
<h2><span class="function">ref</span></h2>
<h4>syntax: (ref <em>exp-key</em> <em>list</em> [<em>func-compare</em> [true]])</h4>

<p><tt>ref</tt> searches for the key expression <em>exp-key</em> in <em>list</em> and 
returns a list of integer indices or an empty list if <em>exp-key</em> cannot be 
found.  <tt>ref</tt> can work together with <a href="#push">push</a> and 
<a href="pop">pop</a>, both of which can also take lists of indices.</p>

<p>By default, <tt>ref</tt> checks if expressions are equal. With <em>func-compare</em>, 
more complex comparison functions can be used. The comparison function can be a 
previously defined function. Note that this function always takes two arguments,
even if only the second argument is used inside the function.</p>

<p>When the optional <tt>true</tt> parameter is present, the element found
is returned instead of the index vector.</p>

<!-- example -->

<pre>
; get index vectors for list elements

(set 'pList '(a b (c d (x) e)))

(ref 'x pList)    <span class='arw'>&rarr;</span> (2 2 0)

(ref '(x) pList)   <span class='arw'>&rarr;</span> (2 2)

; the key expression is in a variable

(set 'p '(c d (x) e))

(ref p pList)   <span class='arw'>&rarr;</span> (2)

; indexing using the vector returned from ref

(set 'v (ref '(x) pList)) <span class='arw'>&rarr;</span> (2 2)

(pList v) <span class='arw'>&rarr;</span> (x)

; if nothing is found, nil is returned

(ref 'foo plist)  <span class='arw'>&rarr;</span> nil

; not specifying a comparison functor assumes =

(set 'L '(a b (c d (e) f)))

(ref 'e L)      <span class='arw'>&rarr;</span> (2 2 0)
(ref 'e L =)    <span class='arw'>&rarr;</span> (2 2 0)

; a is the first symbol where e is greater

(ref 'e L &gt;)  <span class='arw'>&rarr;</span> (0)

; return the element instead of the index

(ref 'e L &gt; true)  <span class='arw'>&rarr;</span> a

; use an anonymous comparison function

(ref 'e L (fn (x y) (or (= x y) (= y 'd))))      <span class='arw'>&rarr;</span> (2 1)

(ref 'e L (fn (x y) (or (= x y) (= y 'd))) true) <span class='arw'>&rarr;</span> d
</pre>


<p>
The following example shows the use of 
<a href="#match">match</a> and <a href="#unify">unify</a> 
to formulate searches that are as powerful as regular expressions are 
for strings:
</p>


<pre>
(set 'L '((l 3) (a 12) (k 5) (a 10) (z 22)))

; use match as a comparison function

(ref '(a ?) L match) <span class='arw'>&rarr;</span> (1)

; use unify as a comparison function

(set 'L '( ((a b) (c d)) ((e e) (f g)) ))

(ref '(X X) L unify)      <span class='arw'>&rarr;</span> (1 0)

(ref '(X g) L unify)      <span class='arw'>&rarr;</span> (1 1)

(ref '(X g) L unify true) <span class='arw'>&rarr;</span> (f g)
</pre>


<p> The <tt>'(X X)</tt> pattern with <a href="#unify">unify</a> searches for a list pair 
where the two elements are equal.  The <tt>unify</tt> pattern <tt>'(X g)</tt>
searches for a list pair with the symbol <tt>g</tt> as the second member.
The patterns are quoted to protect them from evaluation.</p>

<p>Pass the list as a default functor:</p>

<pre>
(set 'C:C '(a b (c d) e f))

(ref 'd C)  <span class='arw'>&rarr;</span> (2 1)
</pre>

<p>This is suitable when passing lists by reference using a context. See also
the chapter <a href="#pass_big">Passing data by reference</a>.</p>

<p> See also the <a href="#ref-all">ref-all</a> function, which searches for all occurrences
of a key expression in a nested list. </p>

<br/><br/>

<a name="ref-all"></a>
<h2><span class="function">ref-all</span></h2>
<h4>syntax: (ref-all <em>exp-key</em> <em>list</em> [<em>func-compare</em> [true]])</h4>

<p> Works similarly to <a href="#ref">ref</a>, but returns a list of all index vectors found 
for <em>exp-key</em> in <em>list</em>. </p>

<p>When the optional <tt>true</tt> parameter is present, the elements found
is returned of the index vectors.</p>

<p>By default, <tt>ref-all</tt> checks if expressions are equal. 
With <em>func-compare</em>, more complex comparison functions can be used.
</p>

<p>The system variable <tt>$count</tt> counts the number of elements found.</p>

<!-- example -->

<pre>
(set 'L '(a b c (d a f (a h a)) (k a (m n a) (x))))

(ref-all 'a L) <span class='arw'>&rarr;</span> ((0) (3 1) (3 3 0) (3 3 2) (4 1) (4 2 2))
$count <span class='arw'>&rarr;</span> 6

; the index vector returned by ref-all can be used to index the list

(L '(3 1)) <span class='arw'>&rarr;</span> a

; mapped implicit indexing of L 

(map 'L (ref-all 'a L)) <span class='arw'>&rarr;</span> (a a a a a a)

; with comparison operator

(set 'L '(a b c (d f (h l a)) (k a (m n) (x))))

; not specifying a comparison functor assumes =

(ref-all 'c L)       <span class='arw'>&rarr;</span> ((2))
(ref-all 'c L =)     <span class='arw'>&rarr;</span> ((2))

; look for all elements where c is greater

(ref-all 'c L &gt;)       <span class='arw'>&rarr;</span> ((0) (1) (3 2 2) (4 1))
(ref-all 'c L &gt; true)  <span class='arw'>&rarr;</span> (a b a a)


; use an anonymous function to compare

(ref-all 'a L (fn (x y) (or (= x y) (= y 'k))))  
<span class='arw'>&rarr;</span> ((0) (3 2 2) (4 0) (4 1))

; the key is nil because the comparison function only looks at the second argument

(ref-all nil L (fn (x y) (&gt; (length y) 2)))      
<span class='arw'>&rarr;</span> ((3) (3 2) (4))

; define the comparison functions first

(define (is-long? x y) (&gt; (length y) 2)) ; the x gets occupied by 'nil

(ref-all nil L is-long?)    <span class='arw'>&rarr;</span>  ((3) (3 2) (4))

(define (is-it-or-d x y) (or (= x y) (= y 'd)))

(set 'L '(a b (c d (e) f)) )

(ref-all 'e L is-it-or-d)  <span class='arw'>&rarr;</span> ((2 1) (2 2 0))
</pre>


<p>
The comparison function can be a previously defined function. 
Note that the comparison function always takes two arguments, 
even if only the second argument is used 
inside the function (as in the example using <tt>is-long?</tt>).
</p>

<p>
Using the <a href="#match">match</a> and <a href="#unify">unify</a> functions, list 
searches can be formulated that are as powerful as regular expression searches are 
for strings.
</p>


<pre>
(set 'L '((l 3) (a 12) (k 5) (a 10) (z 22)) )

; look for all pairs staring with the symbol a

(ref-all '(a ?) L match)      <span class='arw'>&rarr;</span> ((1) (3))
(ref-all '(a ?) L match true) <span class='arw'>&rarr;</span> ((a 12) (a 10))

; look for all pairs where elements are equal

(set 'L '( ((a b) (c d)) ((e e) (f g)) ((z) (z))))

(ref-all '(X X) L unify)      <span class='arw'>&rarr;</span> ((1 0) (2))
(ref-all '(X X) L unify true) <span class='arw'>&rarr;</span> ((e e) ((z) (z)))

; look for all pairs where the second element is the symbol g

(set 'L '( ((x y z) g) ((a b) (c d)) ((e e) (f g)) ))

(ref-all '(X g) L unify)      <span class='arw'>&rarr;</span> ((0) (2 1))
(ref-all '(X g) L unify true) <span class='arw'>&rarr;</span> (((x y z) g) (f g))
</pre>

<p> See also the <a href="#ref">ref</a> function. </p>

<br/><br/>

<a name="regex"></a>

<h2><span class="function">regex</span></h2>
<h4>syntax: (regex <em>str-pattern</em> <em>str-text</em> [<em>regex-option</em> [<em>int-offset</em>]])</h4>

<p>Performs a Perl Compatible Regular Expression (PCRE) search 
on <em>str-text</em> with the pattern specified in <em>str-pattern</em>. 
The same regular expression pattern matching 
is also supported in the functions <a href="#directory">directory</a>, 
<a href="#find">find</a>, <a href="#find-all">find-all</a>, 
<a href="#parse">parse</a>, <a href="#replace">replace</a>, 
and <a href="#search">search</a> when using these functions on strings.
</p>

<p>
<tt>regex</tt> returns a list with the matched strings and substrings 
and the beginning and length of each string inside the text. 
If no match is found, it returns <tt>nil</tt>.
The offset numbers can be used for subsequent processing.
</p>

<p>Additionally a <em>regex-option</em> can be specified to control certain
regular expression options explained later. Options can be given either by
numbers or letters in a string.</p>

<p>The additional <em>int-offset</em>
parameter tells <tt>regex</tt> to start searching for a match not at the
beginning of the string but at an offset.</p>

<p>When no <em>regex-option</em> is present, the offset and length numbers in 
the <tt>regex</tt> results are given based bytes even when running the UTF-8 
enabled version of newLISP. When specifying the PCRE_UTF8 option in <em>regex-option</em>
only offset and length are reported in UTF8 characters.</p>

<p>
<tt>regex</tt> also sets the variables <tt>$0, $1,</tt> 
and <tt>$2&mdash;</tt> 
to the expression and subexpressions found. 
Just like any other symbol in newLISP, 
these variables or their equivalent expressions 
<tt>($ 0), ($ 1),</tt> and <tt>($ 2)&mdash;</tt> can be used in other 
newLISP expressions for further processing.
</p>

<p>Functions using regular expressions will not reset the <tt>$0, $1 ... $15</tt> 
variables to <tt>nil</tt> when no match is found.</p>

<!-- example -->

<pre>
(regex "b+" "aaaabbbaaaa")  <span class='arw'>&rarr;</span> ("bbb" 4 3)

; case-insensitive search option 1
(regex "b+" "AAAABBBAAAA" 1)  <span class='arw'>&rarr;</span> ("BBB" 4 3) 
; same option given as a string
(regex "b+" "AAAABBBAAAA" "i")  <span class='arw'>&rarr;</span> ("BBB" 4 3) 

(regex "[bB]+" "AAAABbBAAAA" )  <span class='arw'>&rarr;</span> ("BbB" 4 3)

(regex "http://(.*):(.*)" "http://nuevatec.com:80") 
<span class='arw'>&rarr;</span> ("http://nuevatec.com:80" 0 22 "nuevatec.com" 7 12 "80" 20 2)

$0  <span class='arw'>&rarr;</span> "http://nuevatec.com:80"
$1  <span class='arw'>&rarr;</span> "nuevatec.com"
$2  <span class='arw'>&rarr;</span> "80"

(dotimes (i 3) (println ($ i)))
<b>http://nuevatec.com:80
nuevatec.com
80</b>
<span class='arw'>&rarr;</span> "80"
</pre>


<p>
	The second example shows the usage of extra options,
	while the third example demonstrates more complex parsing of two subexpressions
	that were marked by parentheses in the search pattern.
	In the last example,
	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>.
</p>

<p>
	When <tt>""</tt> (quotes) are used 
	to delimit strings 
	that include literal backslashes, 
	the backslash must be doubled in the regular expression pattern.
	As an alternative, <tt>{ }</tt> (curly brackets) 
	or <tt>[text]</tt> and <tt>[/text]</tt> (text tags) 
	can be used to delimit text strings.
	In these cases, no extra backslashes are required.
</p>

<p>
	Characters escaped by a backslash in newLISP 
	(e.g., the quote <tt>\"</tt> or <tt>\n</tt>) 
	need not to be doubled in a regular expression pattern, 
	which itself is delimited by quotes.
</p>


<pre>
;; double backslash for parentheses and other special char in regex
(regex "\\(abc\\)" "xyz(abc)xyz")  <span class='arw'>&rarr;</span> ("(abc)" 3 5)  
;; double backslash for backslash (special char in regex)
(regex "\\d{1,3}" "qwerty567asdfg")  <span class='arw'>&rarr;</span> ("567" 6 3)

;; one backslash for quotes (special char in newLISP)
(regex "\"" "abc\"def")  <span class='arw'>&rarr;</span> ("\"" 3 1)     

;; brackets as delimiters
(regex {\(abc\)} "xyz(abc)xyz")  <span class='arw'>&rarr;</span> ("(abc)" 3 5)  

;; brackets as delimiters and quote in pattern
(regex {"} "abc\"def")  <span class='arw'>&rarr;</span> ("\"" 3 1)     

;; text tags as delimiters, good for multiline text in CGI
(regex [text]\(abc\)[/text] "xyz(abc)xyz")  <span class='arw'>&rarr;</span> ("(abc)" 3 5)  
(regex [text]"[/text] "abc\"def")           <span class='arw'>&rarr;</span> ("\"" 3 1) 
</pre>


<p>
	When curly brackets or text tags 
	are used to delimit the pattern string 
	instead of quotes, 
	a simple backslash is sufficient. 
	The pattern and string are then passed in raw form 
	to the regular expression routines.
	When curly brackets are used inside a pattern 
	itself delimited by curly brackets,
	the inner brackets must be balanced, as follows:
</p>


<pre>
;; brackets inside brackets are balanced
(regex {\d{1,3}} "qwerty567asdfg")  <span class='arw'>&rarr;</span> ("567" 6 3) 
</pre>



<p>
The following constants can be used for <em>regex-option</em>.
Several options can be combined using a binary or <tt>|</tt> (pipe) operator. 
E.g. <tt>(| 1 4)</tt> would combine options <tt>1</tt> and <tt>4</tt> or <tt>"is"</tt>
when using letters for the two options.</p>

<p>The last two options are specific for newLISP. The REPLACE_ONCE option is only 
to be used in <a href="#replace">replace</a>; it can be combined with other PCRE options.</p>

<p>Multiple options can be combined using a <tt>+</tt> (plus) or <tt>|</tt> (or) operator,
e.g.: <tt>(| PCRE_CASELESS PCRE_DOTALL)</tt> or <tt>"is"</tt> when using letters as options.
</p>

<table width="98%" summary="regex options">
<tr align="left"><th>PCRE name</th><th>no</th><th>description</th></tr>
<tr><td>PCRE_CASELESS</td><td>1 or i</td><td>treat uppercase like lowercase</td></tr>
<tr><td>PCRE_MULTILINE</td><td>2 or m</td><td>limit search at a newline like Perl's /m</td></tr>
<tr><td>PCRE_DOTALL</td><td>4 or s</td><td>. (dot) also matches newline</td></tr>
<tr><td>PCRE_EXTENDED</td><td>8 or x</td><td>ignore whitespace except inside char class</td></tr>
<tr><td>PCRE_ANCHORED</td><td>16 or A</td><td>anchor at the start</td></tr>
<tr><td>PCRE_DOLLAR_ENDONLY</td><td>32 or D</td><td>$ matches at end of string, not before newline</td></tr>
<tr><td>PCRE_EXTRA</td><td>64</td><td>additional functionality currently not used</td></tr>
<tr><td>PCRE_NOTBOL</td><td>128</td><td>first ch, not start of line; ^ shouldn't match</td></tr>
<tr><td>PCRE_NOTEOL</td><td>256</td><td>last char, not end of line; $ shouldn't match</td></tr>
<tr><td>PCRE_UNGREEDY</td><td>512i or U</td><td>invert greediness of quantifiers</td></tr>
<tr><td>PCRE_NOTEMPTY</td><td>1024</td><td>empty string considered invalid</td></tr>
<tr><td>PCRE_UTF8</td><td>2048 or u</td><td>pattern and strings as UTF-8 characters</td></tr>
<tr><td>REPLACE_ONCE</td><td>0x8000</td><td>replace only one occurrence only for use in <a href="#replace">replace</a></td></tr>
<tr><td>PRECOMPILED</td><td>0x10000 or p</td><td>pattern is pre-compiled, can only be combined with RREPLACE_ONCE 0x8000</td></tr>
</table><br/>

<p>The settings of the PCRE_CASELESS, PCRE_MULTILINE, PCRE_DOTALL, and PCRE_EXTENDED 
options can be changed from within the pattern by a sequence of option letters enclosed 
between "(?" and ")". The option letters are:</p>

<table summary="regex inline options">
<tr><td>i</td><td>for PCRE_CASELESS</td></tr>
<tr><td>m</td><td>for PCRE_MULTILINE</td></tr>
<tr><td>s</td><td>for PCRE_DOTALL</td></tr>
<tr><td>x</td><td>for PCRE_EXTENDED</td></tr>
</table><br/>

<p> Note that regular expression syntax is very complex 
and feature-rich with many special characters and forms.
Please consult a book or the PCRE manual pages for more detail.
Most PERL books or introductions to Linux or Unix 
also contain chapters about regular expressions.
See also <a href="http://www.pcre.org">http://www.pcre.org</a> 
for further references and manual pages.  </p>

<p>Regular expression patterns can be precompiled for higher speed when using 
changing repetitive patterns with <a href="#regex-comp">regex-comp</a>.</p>

<br/><br/>

<a name="regex-comp"></a>
<h2><span class="function">regex-comp</span></h2>
<h4>syntax: (regex-comp <em>str-pattern</em> [<em>int-option</em>])</h4>

<p>newLISP automatically compiles regular expression patterns and caches 
the last compilation to speed up repetitive pattern searches. If patterns
change from one to the next, but are repeated over and over again, then 
the caching of the last pattern is not sufficient. <tt>regex-comp</tt>
can be used to pre-compile repetitive patterns to speed up regular 
expression searches:</p>


<!-- example -->

<pre>
; slower without pre-compilation

(dolist (line page)
	(replace pattern-str1 line repl1 0)
	(replace pattern-str2 line repl2 512)
)

; fast with pre-compilation and option 0x10000

(set 'p1 (regex-comp pattern-str1))
(set 'p2 (regex-comp pattern-str2 512))

(dolist (line page)
	(replace p1 line repl1 0x10000)
	(replace p2 line repl2 0x10000)
)
</pre>


<p>When using pre-compiled patterns in any of the functions using regular
expressions, the option number is set to <tt>0x10000</tt> to signal
that pre-compiled patterns are used. Normal pattern options are specified
 during pre-compilation with <tt>regex-comp</tt> . The <tt>0x10000</tt> option 
can only be combined with <tt>0x8000</tt>, the option used to specify that only 
one replacement should be made when using <a href="#replace">replace</a>.</p>

<p>The function <a href="#ends-with">ends-with</a> should not be used with compiled 
patterns, as it tries to append to an un-compiled pattern internally.</p>

<br/><br/>

<a name="remove-dir"></a>
<h2><span class="function">remove-dir</span></h2>
<h4>syntax: (remove-dir <em>str-path</em>)</h4>

<p>
	Removes the directory
	whose path name is specified in <em>str-path</em>.
	The directory must be empty for <tt>remove-dir</tt> to succeed.
	Returns <tt>nil</tt> on failure.
</p>

<!-- example -->

<pre>
(remove-dir "temp")
</pre>


<p>
	Removes the directory <tt>temp</tt> 
	in the current directory.
</p>

<br/><br/>

<a name="rename-file"></a>
<h2><span class="function">rename-file</span></h2>
<h4>syntax: (rename-file <em>str-path-old</em> <em>str-path-new</em>)</h4>

<p>
Renames a file or directory entry given in the path name <em>str-path-old</em> 
to the name given in <em>str-path-new</em>. Returns <tt>nil</tt> or <tt>true</tt> 
depending on the operation's success.
</p>

<!-- example -->

<pre>
(rename-file "data.lisp" "data.backup")
</pre>

<br/><br/>

<a name="replace"></a>
<h2><span class="function">replace</span>&nbsp;<a href="#destructive">!</a></h2>
<h4>syntax: (replace <em>exp-key</em> <em>list</em> <em>exp-replacement</em> [<em>func-compare</em>])<br/>
syntax: (replace <em>exp-key</em> <em>list</em>)<br/><br/>

syntax: (replace <em>str-key</em> <em>str-data</em> <em>exp-replacement</em>)<br/>
syntax: (replace <em>str-pattern</em> <em>str-data</em> <em>exp-replacement</em> <em>regex-option</em>)</h4>

<h3>List replacement</h3>

<p>If the second argument is a list, <tt>replace</tt> replaces all elements in
the list <em>list</em> that are equal to the expression in <em>exp-key</em>. The 
element is replaced with <em>exp-replacement</em>. If <em>exp-replacement</em>
is missing, all instances of <em>exp-key</em> will be deleted from <em>list</em>.
</p>

<p>Note that <tt>replace</tt> is 
destructive. It changes the list passed to it and returns the changed list. The 
number of replacements made is contained in the system variable <tt>$count</tt> 
when the function returns. During executions of the replacement expression, the 
anaphoric system variable <tt>$it</tt> is set to the expression to be replaced.
</p>

<p>Optionally, <em>func-compare</em> can specify a comparison operator 
or user-defined function. By default, <em>func-compare</em> is the <tt>=</tt> 
(equals sign).</p>

<!-- example -->

<pre>
;; list replacement

(set 'aList '(a b c d e a b c d))

(replace 'b aList 'B)  <span class='arw'>&rarr;</span> (a B c d e a B c d)
aList  <span class='arw'>&rarr;</span> (a B c d e a B c d)
$count <span class='arw'>&rarr;</span> 2  ; number of replacements

;; list replacement with special compare functor/function

; replace all numbers where 10 &lt; number
(set 'L '(1 4 22 5 6 89 2 3 24))

(replace 10 L 10 &lt;) <span class='arw'>&rarr;</span> (1 4 10 5 6 10 2 3 10)
$count <span class='arw'>&rarr;</span> 3

; same as:

(replace 10 L 10 (fn (x y) (&lt; x y))) <span class='arw'>&rarr;</span> (1 4 10 5 6 10 2 3 10)

; change name-string to symbol, x is ignored as nil

(set 'AL '((john 5 6 4) ("mary" 3 4 7) (bob 4 2 7 9) ("jane" 3)))

(replace nil AL (cons (sym ($it 0)) (rest $it)) 
                (fn (x y) (string? (y 0)))) ; parameter x = nil not used
<span class='arw'>&rarr;</span> ((john 5 6 4) (mary 3 4 7) (bob 4 2 7 9) (jane 3))

; use $count in the replacement expression
(replace 'a '(a b a b a b) (list $count $it) =) <span class='arw'>&rarr;</span>  ((1 a) b (2 a) b (3 a) b)
</pre>


<p>
Using the <a href="#match">match</a> and <a href="#unify">unify</a> functions,
list searches can be formulated that are as powerful as regular expression string 
searches:</p>


<pre>
; calculate the sum in all associations with 'mary

(set 'AL '((john 5 6 4) (mary 3 4 7) (bob 4 2 7 9) (jane 3)))

(replace '(mary *)  AL (list 'mary (apply + (rest $it))) match)
<span class='arw'>&rarr;</span> ((john 5 6 4) (mary 14) (bob 4 2 7 9) (jane 3))
$count <span class='arw'>&rarr;</span> 1

; make sum in all expressions

(set 'AL '((john 5 6 4) (mary 3 4 7) (bob 4 2 7 9) (jane 3)))

(replace '(*) AL (list ($it 0) (apply + (rest $it))) match)
<span class='arw'>&rarr;</span> ((john 15) (mary 14) (bob 22) (jane 3))
$count <span class='arw'>&rarr;</span> 4

; using unify, replace only if elements are equal
(replace '(X X) '((3 10) (2 5) (4 4) (6 7) (8 8)) (list ($it 0) 'double ($it 1)) unify)
<span class='arw'>&rarr;</span> ((3 10) (2 5) (4 double 4) (6 7) (8 double 8))
 </pre>


<h3>List removal</h3>
<p>
The last form of <tt>replace</tt> has only two arguments: the expression <em>exp</em> 
and <em>list</em>. This form removes all <em>exp</em>s found in <em>list</em>.
</p>

<!-- example -->

<pre>
;; removing elements from a list

(set 'lst '(a b a a c d a f g))
(replace 'a lst)  <span class='arw'>&rarr;</span> (b c d f g)
lst               <span class='arw'>&rarr;</span> (b c d f g)

$count <span class='arw'>&rarr;</span> 4
</pre>


<h3>String replacement without regular expression</h3>

<p>If all arguments are strings, <tt>replace</tt> replaces all occurrences 
of <em>str-key</em> in <em>str-data</em> with the evaluated 
<em>exp-replacement</em>, returning the changed string. The expression in 
<em>exp-replacement</em> is evaluated for every replacement. The number of 
replacements made is contained in the system variable <tt>$count</tt>. This 
form of <tt>replace</tt> can also process binary <tt>0</tt>s (zeros).</p>

<!-- example -->

<pre>
;; string replacement
(set 'str "this isa sentence")
(replace "isa" str "is a")  <span class='arw'>&rarr;</span> "this is a sentence"

$count <span class='arw'>&rarr;</span> 1
</pre>


<h3>Regular expression replacement</h3>
<p>
The presence of a fourth parameter indicates that a regular expression search 
should be performed with a regular expression pattern specified in <em>str-pattern</em> 
and an option number specified in <em>regex-option</em> (e.g., <tt>1</tt> (one) or "i" for 
case-insensitive searching or <tt>0</tt> (zero) for a standard Perl Compatible Regular 
Expression (PCRE) search without options). See <a href="#regex">regex</a> above for details.
</p>

<p>
By default, <tt>replace</tt> replaces all occurrences of a search string even if a 
beginning-of-line specification is included in the search pattern. 
After each replace, a new search is started at a new position in <em>str-data</em>.
Setting the option bit to <tt>0x8000</tt> in <em>regex-option</em> will force 
<tt>replace</tt> to replace only the first occurrence. The changed string is returned.
</p>

<p>
<tt>replace</tt> with regular expressions also sets the internal variables 
<tt>$0, $1,</tt> and <tt>$2&mdash;</tt> with the contents of the expressions 
and subexpressions found. The anaphoric system variable <tt>$it</tt> is set to
the same value as <tt>$0</tt>. These can be used to perform replacements 
that depend on the content found during replacement. The symbols <tt>$it, $0, $1,</tt> 
and <tt>$2&mdash;</tt> can be used in expressions just like any other symbols.
If the replacement expression evaluates to something other than a string,
no replacement is made. As an alternative, the contents of these variables can 
also be accessed by using <tt>($ 0), ($ 1), ($ 2),</tt> and so forth.
This method allows indexed access (e.g., <tt>($ i)</tt>,
where <tt>i</tt> is an integer).
</p>

<p>After all replacements are made, the number of replacements 
is contained in the system variable <tt>$count</tt>.</p>

<!-- example -->

<pre>
;; using the option parameter to employ regular expressions

(set 'str "ZZZZZxZZZZyy")     <span class='arw'>&rarr;</span> "ZZZZZxZZZZyy"
(replace "x|y" str "PP" 0)    <span class='arw'>&rarr;</span> "ZZZZZPPZZZZPPPP"
str                           <span class='arw'>&rarr;</span> "ZZZZZPPZZZZPPPP"

;; using system variables for dynamic replacement

(set 'str "---axb---ayb---")
(replace "(a)(.)(b)" str (append $3 $2 $1) 0) 
<span class='arw'>&rarr;</span> "---bxa---bya---"

str  <span class='arw'>&rarr;</span> "---bxa---bya---"

;; using the 'replace once' option bit 0x8000

(replace "a" "aaa" "X" 0)  <span class='arw'>&rarr;</span> "XXX"

(replace "a" "aaa" "X" 0x8000)  <span class='arw'>&rarr;</span> "Xaa"

;; URL translation of hex codes with dynamic replacement

(set 'str "xxx%41xxx%42")
(replace "%([0-9A-F][0-9A-F])" str 
               (char (int (append "0x" $1))) 1)

str    <span class='arw'>&rarr;</span> "xxxAxxxB"

$count <span class='arw'>&rarr;</span> 2
</pre>


<p>
The <a href="#setf">setf</a> function together with <a href="#nth">nth</a>,
<a href="#first">first</a> or <a href="#last">last</a> can also
be used to change elements in a list.</p>

<p>
	See <a href="#directory">directory</a>,
	<a href="#find">find</a>,
	<a href="#find-all">find-all</a>,
	<a href="#parse">parse</a>,
	<a href="#regex">regex</a>, 
	and <a href="#search">search</a> 
	for other functions using regular expressions.
</p>

<br/><br/>

<a name="reset"></a>
<h2><span class="function">reset</span></h2>
<h4>syntax: (reset)<br/>
syntax: (reset true)<br/>
syntax: (reset <em>int-max-cells</em>)</h4>

<p>
In the first syntax, <tt>reset</tt> returns to the top level of evaluation,
switches the <a href="#trace">trace</a> mode off, and switches to the MAIN 
context/namespace. <tt>reset</tt> restores the top-level variable environment 
using the saved variable environments on the stack. It also throws an error 
"user reset - no error" which can be reported with user defined error handlers.
Since version 10.5.5 <tt>reset</tt> also interrupts command line parameter
processing.</p>

<p><tt>reset</tt> walks through the entire cell space, 
which may take a few seconds in a heavily loaded system.</p>

<p><tt>reset</tt> occurs automatically after an error condition.</p>

<p>In the second syntax, <tt>reset</tt> will stop the current process 
and start a new clean newLISP process with the same command-line parameters.
This mode will only work when newLISP was started using its full path-name, 
e.g. <tt>/usr/local/bin/newlisp</tt> instead of only <tt>newlisp</tt>. This mode is 
not available on MS Windows.</p>

<p>In the third syntax. <tt>reset</tt> will change the maximum cell count allowed
in the system. This number is also reported as the second number in the list 
by <a href="#sys-info">sys-info</a>. On 64-bit newLISP one lisp cell occupies
32 bytes, or 16 bytes on the 32-bit version. This does not include
string memory, which may be pointed to by cells.</p>

<p>The minimum cell count is 4095, trying to specify less will set it to 4095.
The program will exit when trying to allocate more.</p>

<pre>
(sys-info)  <span class='arw'>&rarr;</span> (437 576460752303423488 409 1 0 2048 0 60391 10602 1411)

; allocate about 1 Mbyte of cell memory on 64-bit newlisp
(reset 32768) <span class='arw'>&rarr;</span> true

(sys-info)  <span class='arw'>&rarr;</span> (437 32768 409 1 0 2048 0 60392 10602 1411)
</pre>

<p>Resetting the maximum cell count will not restart the system and can be done at any point
in a program. Cell memory is allocated in blocks of 4095 cells, which is also initial 
minimum configuration.</p>

<br/><br/>

<a name="rest"></a>
<h2><span class="function">rest</span>&nbsp;<font size="-1"><a href="#utf8_capable">utf8</a></font></h2>

<h4>syntax: (rest <em>list</em>)<br/>
syntax: (rest <em>array</em>)<br/>
syntax: (rest <em>str</em>)</h4>

<p>Returns all of the items in a list or a string, except for the first.
<tt>rest</tt> is equivalent to <em>cdr</em> or <em>tail</em> in other Lisp dialects.
</p>

<!-- example -->

<pre>
(rest '(1 2 3 4))            <span class='arw'>&rarr;</span> (2 3 4)
(rest '((a b) c d))          <span class='arw'>&rarr;</span> (c d)
(set 'aList '(a b c d e))    <span class='arw'>&rarr;</span> (a b c d e)
(rest aList)                 <span class='arw'>&rarr;</span> (b c d e)
(first (rest aList))         <span class='arw'>&rarr;</span> b
(rest (rest aList))          <span class='arw'>&rarr;</span> (d e)
(rest (first '((a b) c d)))  <span class='arw'>&rarr;</span> (b)

(set 'A (array 2 3 (sequence 1 6)))
<span class='arw'>&rarr;</span> ((1 2) (3 4) (5 6))

(rest A)  <span class='arw'>&rarr;</span> ((3 4) (5 6))

(rest '()) <span class='arw'>&rarr;</span> ()
</pre>


<p>
In the second version, <tt>rest</tt> returns all but the first character 
of the string <em>str</em> in a string.
</p>

<!-- example -->

<pre>
(rest "newLISP")          <span class='arw'>&rarr;</span> "ewLISP"
(first (rest "newLISP"))  <span class='arw'>&rarr;</span> "e"
</pre>


<p>
See also the <a href="#first">first</a> and <a href="#last">last</a> functions.
</p>

<p>
Note that an <em>implicit rest</em> is available for lists.
See the chapter <a href="#implicit_rest_slice">Implicit rest and slice</a>.
</p>

<p>Note that <a href="#rest">rest</a> works on character boundaries rather 
than byte boundaries when the UTF-8&ndash;enabled version of newLISP is used.</p>

<br/><br/>

<a name="reverse"></a>
<h2><span class="function">reverse</span>&nbsp;<a href="#destructive">!</a></h2>
<h4>syntax: (reverse <em>list</em>)<br/>
syntax: (reverse <em>array</em>)<br/>
syntax: (reverse <em>string</em>)</h4>

<p>In the first and second form, <tt>reverse</tt> reverses and returns the 
<em>list</em> or <em>array</em>. Note that <tt>reverse</tt> is destructive 
and changes the original list or array.</p>

<!-- example -->

<pre>
; reverse a list
(set 'l '(a b c d e f))

(reverse l)  <span class='arw'>&rarr;</span> (f e d c b a)
l            <span class='arw'>&rarr;</span> (f e d c b a)
i
; reverse an array
(set 'a (array 3 2 '(1 2 3 4 5 6))) <span class='arw'>&rarr;</span> ((1 2) (3 4) (5 6))

(reverse a)                         <span class='arw'>&rarr;</span> ((5 6) (3 4) (1 2))
a                                   <span class='arw'>&rarr;</span> ((5 6) (3 4) (1 2))
</pre>


<p>In the third form, <tt>reverse</tt> is used to reverse the order 
of characters in a string.</p>

<!-- example -->

<pre>
; reverse byte character string

(set 'str "newLISP")

(reverse str)  <span class='arw'>&rarr;</span> "PSILwen"
str            <span class='arw'>&rarr;</span> "PSILwen"

; reverse a multibyte character UTF-8 string, explode is UTF-8 sensitive

(join (reverse (explode "ΑΒΓΔΕΖΗΘ")))  <span class='arw'>&rarr;</span> "ΘΗΖΕΔΓΒΑ"
</pre>

<p>See also the <a href="#sort">sort</a> function.</p>

<br/><br/>

<a name="rotate"></a>
<h2><span class="function">rotate</span>&nbsp;<a href="#destructive">!</a></h2>
<h4>syntax: (rotate <em>list</em> [<em>int-count</em>])<br/>
syntax: (rotate <em>str</em> [<em>int-count</em>])</h4>

<p>Rotates and returns the <em>list</em> or string in <em>str</em>.
A count can be optionally specified in <em>int-count</em> 
to rotate more than one position.  If <em>int-count</em> is positive, 
the rotation is to the right; if <em>int-count</em> is negative, 
the rotation is to the left.  If no <em>int-count</em> is specified, 
<tt>rotate</tt> rotates 1 to the right.  <tt>rotate</tt> is a destructive function 
that changes the contents of the original list or string.</p>

<!-- example -->

<pre>
(set 'l '(1 2 3 4 5 6 7 8 9))

(rotate l)    <span class='arw'>&rarr;</span> (9 1 2 3 4 5 6 7 8)
(rotate l 2)  <span class='arw'>&rarr;</span> (7 8 9 1 2 3 4 5 6)

l  <span class='arw'>&rarr;</span> (7 8 9 1 2 3 4 5 6)

(rotate l -3)  <span class='arw'>&rarr;</span> (1 2 3 4 5 6 7 8 9)

; rotate a byte character string

(set 'str "newLISP")

(rotate str)     <span class='arw'>&rarr;</span> "PnewLIS"
(rotate str 3)   <span class='arw'>&rarr;</span> "LISPnew"
(rotate str -4)  <span class='arw'>&rarr;</span> "newLISP"

; rotate a multibyte character UTF-8 string on character boundaries

(join (rotate (explode "ΑΒΓΔΕΖΗΘ")))  <span class='arw'>&rarr;</span> "ΘΑΒΓΔΕΖΗ"
</pre>


<p>When working on a string, <tt>rotate</tt> works on byte boundaries 
rather than character boundaries.</p>

<br/><br/>

<a name="round"></a>
<h2><span class="function">round</span></h2>
<h4>syntax: (round <em>number</em> [<em>int-digits</em>])</h4>

<p>Rounds the number in <em>number</em> 
to the number of digits given in <em>int-digits</em>. 
When decimals are being rounded, <em>int-digits</em> is negative. 
It is positive when the integer part of a number is being rounded.</p>

<p>If <em>int-digits</em> is omitted, the function rounds to <tt>0</tt> decimal
digits.</p>

<!-- example -->

<pre>
(round 123.49 2)    <span class='arw'>&rarr;</span> 100
(round 123.49 1)    <span class='arw'>&rarr;</span> 120
(round 123.49 0)    <span class='arw'>&rarr;</span> 123
(round 123.49)      <span class='arw'>&rarr;</span> 123
(round 123.49 -1)   <span class='arw'>&rarr;</span> 123.5
(round 123.49 -2)   <span class='arw'>&rarr;</span> 123.49
</pre>


<p>Note that rounding for display purposes is better accomplished using 
<a href="#format">format</a>.</p>

<br/><br/>

<a name="save"></a>
<h2><span class="function">save</span></h2>
<h4>syntax: (save <em>str-file</em>)<br/>
syntax: (save <em>str-file</em> <em>sym-1</em> [<em>sym-2</em> ... ])</h4>

<p>
	In the first syntax, 
	the <tt>save</tt> function writes 
	the contents of the newLISP workspace 
	(in textual form) to the file <em>str-file</em>.
	<tt>save</tt> is the inverse function of <tt>load</tt>. 
	Using <tt>load</tt> on files 
	created with <tt>save</tt> causes 
	newLISP to return to the same state 
	as when <tt>save</tt> was originally invoked.
	System symbols starting with the <tt>$</tt> character 
	(e.g., <tt>$0</tt> from regular expressions 
	or <tt>$main-args</tt> from the command-line), symbols of built-in
	functions and symbols containing <tt>nil</tt> are not saved.
</p>

<p>
	In the second syntax, 
	symbols can be supplied as arguments.
	If <em>sym-n</em> is supplied, 
	only the definition of that symbol is saved.
	If <em>sym-n</em> evaluates to a context,
	all symbols in that context are saved.
	More than one symbol can be specified,
	and symbols and context symbols can be mixed.
	When contexts are saved,
	system variables and symbols starting with the <tt>$</tt> character 
	are not saved.
	Specifying system symbols explicitly 
	causes them to be saved.
</p>

<p>
	Each symbol is saved 
	by means of a <a href="#set">set</a> statement or&mdash;if 
	the symbol contains a lambda or lambda-macro function&mdash;by 
	means of <a href="#define">define</a> 
	or <a href="#define-macro">define-macro</a> statements.
</p>

<p>
	<tt>save</tt> returns <tt>true</tt> on completion.
</p>

<!-- example -->

<pre>
(save "save.lsp")

(save "/home/myself/myfunc.LSP" 'my-func) 
(save "file:///home/myself/myfunc.LSP" 'my-func) 

(save "http://asite.com:8080//home/myself/myfunc.LSP" 'my-func)

(save "mycontext.lsp" 'mycontext) 

;; multiple args
(save "stuff.lsp" 'aContext 'myFunc '$main-args 'Acontext)
</pre>


<p>
	Because all context symbols are part of the context <tt>MAIN</tt>,
	saving <tt>MAIN</tt> saves all contexts.
</p>

<p>
	Saving to a URL 
	will cause an HTTP PUT request to be sent to the URL.
	In this mode, 
	<tt>save</tt> can also be used 
	to push program source 
	to remote newLISP server nodes.
	Note that a double backslash is required 
	when path names are specified 
	relative to the root directory.
	<tt>save</tt> in <tt>HTTP</tt>  mode will 
	observe a 60-second timeout.</p>

<p>
	Symbols made using <a href="#sym">sym</a>
	that are incompatible with the normal syntax rules for symbols
	are serialized using a <a href="#sym">sym</a> statement 
	instead of a <a href="#set">set</a> statement.
</p>

<p>
	<tt>save</tt> serializes contexts and symbols 
	as if the current context is <tt>MAIN</tt>.
	Regardless of the current context,
	<tt>save</tt> will always generate the same output.
</p>

<p>
	See also the functions <a href="#load">load</a> 
	(the inverse operation of <tt>save</tt>) 
	and <a href="#source">source</a>,
	which saves symbols and contexts to a string 
	instead of a file.
</p>

<br/><br/>

<a name="search"></a>
<h2><span class="function">search</span></h2>
<h4>syntax: (search <em>int-file</em> <em>str-search</em> [<em>bool-flag</em> [<em>regex-option</em>]])</h4>

<p>
Searches a file specified by its handle in <em>int-file</em> for a string in <em>str-search</em>.
<em>int-file</em> can be obtained from a previous <a href="#open">open</a> file.  After the search, 
the file pointer is positioned at the beginning  or the end of the searched string or at the end 
of the file if nothing is found.</p>

<p> By default, the file pointer is positioned at the beginning
of the searched string. If <em>bool-flag</em> evaluates to <tt>true</tt>,
then the file pointer is positioned at the end of the searched string.</p>

<p> In <em>regex-option</em>,  the options flags can be specified to perform 
a PCRE regular expression search.  See the function <a href="#regex">regex</a> for details.
If <em>regex-option</em> is not specified a faster, plain string search is performed.
<tt>search</tt> returns the new file position or <tt>nil</tt> if nothing is found.
</p>

<p> When using the regular expression options flag, patterns found are stored in the system variables 
<tt>$0</tt> to <tt>$15</tt>.  </p>

<!-- example -->

<pre>
(set 'file (open "init.lsp" "read"))
(search file "define")
(print (read-line file) "\n")
(close file)

(set 'file (open "program.c" "r"))
(while (search file "#define (.*)" true 0) (println $1))
(close file)
</pre>


<p> The file <tt>init.lsp</tt> is opened and searched for the string <tt>define</tt> and the
line in which the string occurs is printed. </p>

<p>The second example looks for all lines in the file <tt>program.c</tt> which start with
the string <tt>#define</tt> and prints the rest of the line after the string "#define ".</p>

<p>
	For other functions using regular expressions, 
	see <a href="#directory">directory</a>,
	<a href="#find">find</a>,
	<a href="#find-all">find-all</a>, 
	<a href="#parse">parse</a>,
	<a href="#regex">regex</a>, 
	and <a href="#replace">replace</a>.
</p>

<br/><br/>

<a name="seed"></a>
<h2><span class="function">seed</span></h2>
<h4>syntax: (seed <em>int-seed</em>)<br/>
syntax: (seed <em>int-seed</em> <tt>true</tt> [<em>int-pre-N</em>])<br/>
syntax: (seed)</h4>

<p>Seeds the internal random generator that generates numbers for <a href="#amb">amb</a>,
<a href="#normal">normal</a>, <a href="#rand">rand</a>, and <a href="#random">random</a> 
with the number specified in <em>int-seed</em>.  Note that the first syntax uses a 
random generator based on the C-library function <em>rand()</em>.  All randomizing functions 
in newLISP are based on this function.</p>

<p>When using the second syntax, all randomizing functions are based on a random generator
independent of platforms and compilers used to built newLISP. When seeding with the second
syntax all random functions called subsequently like 
<a href="#amb">amb</a>, <a href="#normal">normal</a>, <a href="#rand">rand</a>,
<a href="#random">random</a> and <a href="#randomize">randomize</a> are based on this
platform independent random generator.</p>

<p>The optional <em>int-pre-N</em> specifies the number of random numbers to be pre-
fetched as part of the seeding and initialization procedure. When this parameter is
ommitted <tt>seed</tt> assumes <tt>50</tt>.</p>

<p>Note that the maximum value for <em>int-seed</em> is limited to 16 or 32 bits, 
depending on the operating system used.  Internally, only the 32 least significant 
bits are passed to the random seed function of the OS.</p>

<!-- example -->

<pre>
(seed 12345)

(seed (time-of-day))
</pre>


<p>After using <tt>seed</tt> with the same number, the random generator starts 
the same sequence of numbers.  This facilitates debugging 
when randomized data are involved.  Using <tt>seed</tt>, 
the same random sequences can be generated over and over again.</p>

<p>The second example is useful for guaranteeing 
a different seed any time the program starts.</p>

<p>The following example shows usage of the internal seed state in the built-in
random generator:</p>

<pre>
&gt; (seed 123 true) ; use the true parameter
123
&gt; (random)
0.2788576787704871
&gt; (random)
0.7610070955758016
&gt; (random)
0.2462553424976092
&gt; (random)
0.8135413573186572
&gt; (set 'state (seed)) ; save current state
1747066761
&gt; (random)
0.1895924546707387
&gt; (random)
0.4803856511043318
&gt; (seed state true 0) ; seed with saved state
1747066761
&gt; (random)            ; produces old sequence
0.1895924546707387       
&gt; (random)
0.4803856511043318      
&gt; 
</pre>

<p>In the last syntax <tt>seed</tt> returns the current seed state.</p>

<br/><br/>

<a name="self"></a>
<h2><span class="function">self</span></h2>
<h4>syntax: (self [<em>int-index</em> ... ])</h4>

<p>The function <tt>self</tt> accesses the target object of a FOOP method.
One or more <em>int-index</em> are used to access the object members.
<tt>self</tt> is set by the <a href="#colon">:&nbsp;colon</a> operator.</p>

<p>Objects referenced with <tt>self</tt> are mutable:</p>

<!-- example -->

<pre>
(new Class 'Circle)

(define (Circle:move dx dy)
	(inc (self 1) dx) 
	(inc (self 2) dy))

(set 'aCircle (Circle 1 2 3))
(:move aCircle 10 20)

aCircle <span class='arw'>&rarr;</span> (Circle 11 22 3)

; objects can be anonymous
(set 'circles '((Circle 1 2 3) (Circle 4 5 6)))

(:move (circles 0) 10 20)
(:move (circles 1) 10 20)

circles <span class='arw'>&rarr;</span> ((Circle 11 22 3) (Circle 14 25 6))
</pre>

<p>See also the chapter about programming with FOOP: 
<a href="#foop">Functional object-oriented programming</a></p>

<br/><br/>

<a name="seek"></a>
<h2><span class="function">seek</span></h2>
<h4>syntax: (seek <em>int-file</em> [<em>int-position</em>])</h4>

<p>
Sets the file pointer to the new position <em>int-position</em> in the file 
specified by <em>int-file</em>.The new position is expressed as an offset from 
the beginning of the file, <tt>0</tt> (zero) meaning the beginning of the file.
If no <em>int-position</em> is specified, <tt>seek</tt> returns the current 
position in the file. If <em>int-file</em> is <tt>0</tt> (zero), 
on BSD, <tt>seek</tt> will return the number of characters printed to STDOUT, 
and on Linux and MS Windows, it will return <tt>-1</tt>. On failure, <tt>seek</tt> 
returns <tt>nil</tt>. When <em>int-position</em> is set to <tt>-1</tt>, 
<tt>seek</tt> sets the file pointer to the end of the file.</p>

<p><tt>seek</tt> can set the file position past the current end of the file. Subsequent
writing to this position will extend the file and fill unused positions with zero's.
The blocks of zeros are not actually allocated on disk, so the file takes up less
space and is called a <em>sparse file</em>.</p>

<!-- example -->

<pre>
(set 'file (open "myfile" "read"))  <span class='arw'>&rarr;</span> 5 
(seek file 100)                     <span class='arw'>&rarr;</span> 100
(seek file)                         <span class='arw'>&rarr;</span> 100

(open "newlisp_manual.html" "read")
(seek file -1)  ; seek to EOF
<span class='arw'>&rarr;</span> 593816     

(set 'fle (open "large-file" "read") 
(seek file 30000000000)  <span class='arw'>&rarr;</span> 30000000000
</pre>


<p>
	newLISP supports file position numbers up to 
	9,223,372,036,854,775,807.
</p>

<br/><br/>

<a name="select"></a>
<h2><span class="function">select</span>&nbsp;<font size="-1"><a href="#utf8_capable">utf8</a></font></h2>

<h4>syntax: (select <em>list</em> <em>list-selection</em>)<br/>
syntax: (select <em>list</em> [<em>int-index_i</em> ... ])<br/><br/>

syntax: (select <em>string</em> <em>list-selection</em>)<br/>

syntax: (select <em>string</em> [<em>int-index_i</em> ... ])</h4>

<p>
	In the first two forms,
	<tt>select</tt> picks one or more elements 
	from <em>list</em> using one or more indices 
	specified in <em>list-selection</em> or the <em>int-index_i</em>.
</p>

<!-- example -->

<pre>
(set 'lst '(a b c d e f g))

(select lst '(0 3 2 5 3))  <span class='arw'>&rarr;</span> (a d c f d)

(select lst '(-2 -1 0))  <span class='arw'>&rarr;</span> (f g a)

(select lst -2 -1 0)  <span class='arw'>&rarr;</span> (f g a)
</pre>


<p>
	In the second two forms,
	<tt>select</tt> picks one or more characters 
	from <em>string</em> 
	using one or more indices specified in <em>list-selection</em> 
	or the <em>int-index_i</em>.
</p> 

<!-- example -->

<pre>
(set 'str "abcdefg") 

(select str '(0 3 2 5 3))  <span class='arw'>&rarr;</span> "adcfd"

(select str '(-2 -1 0))  <span class='arw'>&rarr;</span> "fga"

(select str -2 -1 0)  <span class='arw'>&rarr;</span> "fga"
</pre>


<p>
	Selected elements can be repeated and do not have to appear in order,
	although this speeds up processing.
	The order in <em>list-selection</em> or <em>int-index_i</em> 
	can be changed to rearrange elements.
</p>

<br/><br/>



<br/><br/>

<a name="semaphore"></a>
<h2><span class="function">semaphore</span></h2>

<h4>syntax: (semaphore)<br/>
syntax: (semaphore <em>int-id</em>)<br/>
syntax: (semaphore <em>int-id</em> <em>int-wait</em>)<br/>
syntax: (semaphore <em>int-id</em> <em>int-signal</em>)<br/>

syntax: (semaphore <em>int-id</em> <em>0</em>)</h4>

<p>A semaphore is an interprocess synchronization object 
that maintains a count between <tt>0</tt> (zero) and some maximum value.
Useful in controlling access to a shared resource, 
a semaphore is set to signaled when its count is greater than zero 
and to non-signaled when its count is zero.</p>

<p>A semaphore is created using the first syntax.  This returns 
the semaphore ID, an integer used subsequently as <em>int-id</em> 
when the <em>semaphore</em> function is called.  Initially, the 
semaphore has a value of zero, which represents the non-signaled state.
</p>

<p>
If calling <tt>semaphore</tt> with a negative value in <em>int-wait</em> 
causes it to be decremented below zero,
the function call will block until another process
signals the semaphore with a positive value in <em>int-signal</em>.
Calls to the semaphore with <em>int-wait</em> or <em>int-signal</em>
effectively try to increment or decrement the semaphore value 
by a positive or negative value specified in <em>int-signal</em> 
or <em>int-wait</em>.
Because the value of a semaphore must never fall below zero,
the function call will block when this is attempted
(i.e., a semaphore with a value of zero 
will block until another process
increases the value with a positive <em>int-signal</em>).
</p>

<p>The second syntax is used to inquire about the value of a semaphore
 by calling <tt>semaphore</tt> with the <em>int-id</em> only.
This form is not available on MS Windows.</p>

<p>Supplying <tt>0</tt> (zero) as the last argument will release system 
resources for the semaphore, which then becomes unavailable.
Any pending waits on this semaphore in other child processes 
will be released.</p>

<p>On MS Windows, only parent and child processes can share a semaphore.
On Linux/Unix, independent processes can share a semaphore.</p>

<p>On failure the <tt>semaphore</tt> function returns <tt>nil</tt>.
<a href="#sys-error">sys-error</a> can be used to retrieve the error
number and text from the underlying operating system.</p>

<p>The following code examples summarize the different syntax forms:</p>

<!-- example -->

<pre>
;; init semaphores 
(semaphore) 

;; assign a semaphore to sid 
(set 'sid (semaphore))

;; inquire the state of a semaphore (not on Windows OS)
(semaphore sid)

;; put sid semaphore in wait state (-1) 
(semaphore sid -1) 

;; run sid semaphore previously put in wait (always 1) 
(semaphore sid 1) 

;; run sid semaphore with X times a skip (backward or forward) on the function 
(semaphore sid X) 

;; release sid semaphore system-wide (always 0) 
(semaphore sid 0) 
</pre>


<p>The following example shows semaphores controlling a child process:</p> 

<!-- example -->

<pre>
;; counter process output in bold

(define (counter n)
	(println "counter started")
	(dotimes (x n)
		(semaphore sid -1)
		(println x)))

;; hit extra &lt;enter&gt; to make the prompt come back
;; after output to the console from the counter process

&gt; (set 'sid (semaphore))

&gt; (semaphore sid)
<b>0</b>

&gt; (fork (counter 100))

<b>counter started</b>
&gt; (semaphore sid 1)
<b>0</b>
&gt; (semaphore sid 3)
<b>1</b>
<b>2</b>
<b>3</b>
&gt; (semaphore sid 2)
<b>4</b>

<b>5</b>
&gt; _
</pre>


<p>
	After the semaphore is acquired in <tt>sid</tt>, 
	it has a value of <tt>0</tt>
	(the non-signaled state).
	When starting the process <tt>counter</tt>,
	the semaphore will block after the initial start message 
	and will wait in the semaphore call.
	The <tt>-1</tt> is trying to decrement the semaphore,
	which is not possible because its value is already zero.
	In the interactive, main parent process,
	the semaphore is signaled by raising its value by <tt>1</tt>.
	This unblocks the semaphore call in the <tt>counter</tt> process,
	which can now decrement the semaphore from <tt>1</tt> to <tt>0</tt> 
	and execute the <tt>print</tt> statement.
	When the semaphore call is reached again,
	it will block because the semaphore is already in the wait 
	(<tt>0</tt>) state.
</p>

<p>
	Subsequent calls to <tt>semaphore</tt> 
	with numbers greater than <tt>1</tt> 
	give the <tt>counter</tt> process an opportunity 
	to decrement the semaphore several times before blocking.
</p>

<p>
	More than one process can participate in controlling the semaphore, 
	just as more than one semaphore can be created.
	The maximum number of semaphores is controlled 
	by a system-wide kernel setting on Unix-like operating systems.
</p>

<p>Use the <a href="#fork">fork</a> function to start a new process 
and the <a href="#share">share</a> function to share information between 
processes. For a more comprehensive example of using <tt>semaphore</tt> 
to synchronize processes, see the file <tt>prodcons.lsp</tt> example 
in the <tt>examples</tt> directory in the source distribution, 
as well as the examples and modules distributed with newLISP.</p>

<br/><br/>

<a name="send"></a>
<h2><span class="function">send</span></h2>
<h4>syntax: (send <em>int-pid</em> <em>exp</em>)<br/>
syntax: (send)</h4>

<p>The <tt>send</tt> function enables communication between
parent and child processes started with <a href="#spawn">spawn</a>.
Parent processes can send and receive messages to and from
their child processes and child processes can send and receive
messages to and from their parent process. A proxy technique &ndash; shown further
down &ndash; is  employed to communicate between child process
peers. <tt>send</tt> and <a href="#receive">receive</a> do not require 
locks or semaphores. They work on dual send and receive message queues.
</p>

<p>Processes started using <a href="#fork">fork</a> or 
<a href="#process">process</a> can not use <tt>send</tt> and <tt>receive</tt>
message functions. Instead they should use either <a href="#share">share</a> 
with <a href="#semaphore">semaphore</a> or <a href="#pipe">pipe</a> to 
communicate.</p>

<p>The <tt>send</tt> function is not available on MS Windows.</p>

<p>In the first syntax <tt>send</tt> is used to send a message 
from a parent to a child process or a child to a parent process.</p>

<p>The second syntax is only used by parent processes to get a list
of all child processes ready to accept message from the parent in their 
receive queues. If a child's receive queue is full, it will not be part of
the list returned by the <tt>(send)</tt> statement.</p>

<p>The content of a message may be any newLISP expression either
atomic or list expressions: boolean constants <tt>nil</tt> and <tt>true</tt>,
integers, floating point numbers or strings, or any list expression 
in valid newLISP syntax. The size of a message is unlimited.</p>


<p>The <em>exp</em> parameter specifies the data to be sent
to the recipient in <em>int-pid</em>. The recipient can be either a
spawned child process of the current process or the parent
process. If a message queue is full, it can be read from the receiving
end, but a <tt>send</tt> issued on the other side of the queue will
fail and return <tt>nil</tt>.</p>


<pre>
; child process dispatching message to parent

(set 'ppid (sys-info -4)) ; get parent pid

(send ppid "hello") ; send message
</pre>

<p>The targeted recipient of the message is the parent process:</p>

<pre>
; parent process receiving message from child

(receive child-pid msg) <span class='arw'>&rarr;</span> true
msg                     <span class='arw'>&rarr;</span> "hello"
</pre>


<p>When the <tt>send</tt> queue is full, <tt>send</tt> will return
<tt>nil</tt> until enough message content is read on the receiving side
of the queue and the queue is ready to accept new messages from 
<tt>send</tt> statements.</p>

<p>Using the <a href="#until">until</a> looping function, the
message statements can be repeated until they return a value
not <tt>nil</tt>. This way, non-blocking <tt>send</tt> and <tt>receive</tt> 
can be made blocking until they succeed:</p>

<pre>
; blocking sender
(until (send pid msg)) ; true after message is queued up

; blocking receiver
(until (receive pid msg)) ; true after message could be read
</pre>

<p>The sender statement blocks until the message could be deposited
in the recipients queue.</p>

<p>The <tt>receive</tt> statement blocks until a new message can
be fetched from the queue.</p>

<p>As the <tt>until</tt> statements in this example lack body expressions,
the last value of the evaluated conditional expression is the return
value of the <tt>until</tt> loop.</p>

<h3>Blocking message exchange</h3>

<p>The following code shows how a recipient can listen for incoming
messages, and in turn how a sender can retry to deposit a message
into a queue. The example shows 5 child processes constantly delivering 
status data to a parent process which will display the data.
After three data sets have been read, the parent will abort all
child processes and exit:</p>

<!-- example -->

<pre>
#!/usr/local/bin/newlisp

; child process transmits random numbers
(define (child-process)
    (set 'ppid (sys-info -4)) ; get parent pid
    (while true
        (until (send ppid (rand 100))))
)

; parent starts 5  child processes, listens and displays
; the true flag is specified to enable send/receive

(dotimes (i 5) (spawn 'result (child-process) true))

(for (i 1 3)
    (dolist (cpid (sync)) ; iterate thru pending child PIDs
        (until (receive cpid msg))
        (print "pid:" cpid "-&gt;" (format "%-2d  " msg)))
    (println)
)

(abort) ; cancel child-processes
(exit)
</pre>


<p>Running above example produces the following output:</p>

<pre><b>pid:53181->47  pid:53180->61  pid:53179->75  pid:53178->39  pid:53177->3   
pid:53181->59  pid:53180->12  pid:53179->20  pid:53178->77  pid:53177->47  
pid:53181->6   pid:53180->56  pid:53179->96  pid:53178->78  pid:53177->18
</b></pre>

<p>The <tt>(sync)</tt> expression returns a list of all child PIDs,
and <tt>(until (receive cpid msg))</tt> is used to force a wait
until status messages are received for each of the child processes.</p>

<p>A timeout mechanism could be part of an <tt>until</tt> or <tt>while</tt>
loop to stop waiting after certain time has expired.</p>

<p>The examples show messages flowing from a child processes to
a parent process, in the same fashion messages could flow
into the other direction from parent to child processes. In that
case the parent process would use <tt>(send)</tt> to obtain a
list of child processes with place in their message queues.</p>

<h3>Messages containing code for evaluation</h3>

<p>The most powerful feature of the message functions is the ability
to send any newLISP expression, which then can be evaluated by the recipient. 
The recipient uses <a href="#eval">eval</a> to evaluate the received
expression. Symbols contained in the expression are evaluated in the
receivers environment.</p>

<p>The following example shows how a parent process acts like a message 
proxy. The parent receives messages from a child process A and routes them 
to a second child process with ID B. In effect this implements messages 
between child process peers. The implementation relies on the fact that 
the recipient can evaluate expressions contained in messages received.
These expressions can be any valid newLISP statements:</p>

<!-- example -->
<pre>
#!/usr/local/bin/newlisp

; sender child process of the message
(set 'A (spawn 'result 
    (begin
        (dotimes (i 3)
            (set 'ppid (sys-info -4))
            /* the statement in msg will be evaluated in the proxy */
            (set 'msg '(until (send B (string "greetings from " A))))
            (until (send ppid msg)))
        (until (send ppid '(begin 
            (sleep 100) ; make sure all else is printed
            (println "parent exiting ...\n")
            (set 'finished true))))) true)) 

; receiver child process of the message
(set 'B (spawn 'result 
    (begin
        (set 'ppid (sys-info -4))
        (while true
            (until (receive ppid msg))
            (println msg)
            (unless (= msg (string "greetings from " A))
                (println "ERROR in proxy message: " msg)))) true))

(until finished (if (receive A msg) (eval msg))) ; proxy loop

(abort)
(exit)
</pre>

<p>Child process <tt>A</tt> sends three messages to <tt>B</tt>.
As this cannot be done directly <tt>A</tt>  sends <tt>send</tt>
statements to the parent for evaluation. The statement:</p>

<pre>
(until (send pidB (string "greetings from " A)))
</pre>

<p>will be evaluated in the environment of the parent process. Even so the 
variables <tt>A</tt> and <tt>B</tt> are bound to <tt>nil</tt> in 
the sender process <tt>A</tt>, in the parent process they will be
bound to the correct process ID numbers.</p>

<p>After sending the three messages, the statement:</p>

<pre>
(set 'finished true)
</pre>

<p>is sent to the parent process. Once evaluated, it will cause the <tt>until</tt>
loop to finish.</p>

<p>For more details on <tt>send</tt> and <tt>receive</tt> and more examples 
see the <a href="http://www.newlisp.org/CodePatterns.html">Code Patterns</a>
document.</p>

<br/><br/>

<a name="sequence"></a>
<h2><span class="function">sequence</span></h2>
<h4>syntax: (sequence <em>num-start</em> <em>num-end</em> [<em>num-step</em>])</h4>

<p>
	Generates a sequence of numbers 
	from <em>num-start</em> to <em>num-end</em> 
	with an optional step size of <em>num-step</em>.
	When <em>num-step</em> is omitted,
	the value <tt>1</tt> (one) is assumed.
	The generated numbers are of type integer 
	(when no optional step size is specified) 
	or floating point 
	(when the optional step size is present).
</p>

<!-- example -->

<pre>
(sequence 10 5)     <span class='arw'>&rarr;</span> (10 9 8 7 6 5)
(sequence 0 1 0.2)  <span class='arw'>&rarr;</span> (0 0.2 0.4 0.6 0.8 1)
(sequence 2 0 0.3)  <span class='arw'>&rarr;</span> (2 1.7 1.4 1.1 0.8 0.5 0.2)
</pre>


<p>
	Note that the step size must be a positive number,
	even if sequencing from a higher to a lower number.
</p>

<p>
	Use the <a href="#series">series</a> function
	to generate geometric sequences.
</p>

<br/><br/>

<a name="series"></a>
<h2><span class="function">series</span></h2>

<h4>syntax: (series <em>num-start</em> <em>num-factor</em> <em>num-count</em>)<br/>
syntax: (series <em>exp-start</em> <em>func</em> <em>num-count</em>)</h4>

<p>In the first syntax, <tt>series</tt> creates a geometric sequence with <em>num-count</em> 
elements starting with the element in <em>num-start</em>. Each subsequent element 
is multiplied by <em>num-factor</em>. The generated numbers are always floating point 
numbers.</p>

<p>When <em>num-count</em> is less than <tt>1</tt>, then <tt>series</tt>
returns an empty list.</p>

<!-- example -->

<pre>
(series 2 2 5)     <span class='arw'>&rarr;</span> (2 4 8 16 32)
(series 1 1.2 6)   <span class='arw'>&rarr;</span> (1 1.2 1.44 1.728 2.0736 2.48832)
(series 10 0.9 4)  <span class='arw'>&rarr;</span> (10 9 8.1 7.29)
(series 0 0 10)    <span class='arw'>&rarr;</span> (0 0 0 0 0 0 0 0 0 0)
(series 99 1 5)    <span class='arw'>&rarr;</span> (99 99 99 99 99)
</pre>


<p>In the second syntax, <tt>series</tt> uses a function specified in <em>func</em>
to transform the previous expression in to the next expression:</p>


<!-- example -->

<pre>
; embed the function Phi: f(x) = 1 / (1 + x)
; see also http://en.wikipedia.org/wiki/Golden_ratio

(series 1 (fn (x) (div (add 1 x))) 20)  <span class='arw'>&rarr;</span>

(1 0.5 0.6666666 0.6 0.625 0.6153846 0.619047 0.6176470 0.6181818 
 0.6179775 0.6180555 0.6180257 0.6180371 0.6180327 0.6180344 
 0.6180338 0.6180340 0.6180339 0.6180339 0.6180339)

; pre-define the function

(define (oscillate x) 
  (if (&lt; x) 
    (+ (- x) 1) 
    (- (+ x 1)))
)

(series 1 oscillate 20)  <span class='arw'>&rarr;</span> 

(1 -2 3 -4 5 -6 7 -8 9 -10 11 -12 13 -14 15 -16 17 -18 19 -20)

; any data type is accepted as a start expression

(series "a" (fn (c) (char (inc (char c)))) 5) <span class='arw'>&rarr;</span> ("a" "b" "c" "d" "e")

; dependency of the two previous values in this fibonacci generator

(let (x 1) (series x (fn (y) (+ x (swap y x))) 10))  <span class='arw'>&rarr;</span>

(1 2 3 5 8 13 21 34 55 89)
 
</pre>


<p>The first example shows a series converging to the <em>golden ratio, &phi;</em>
(for any starting value). The second example shows how <em>func</em> can be defined
previously for better readability of the <tt>series</tt> statement.</p>

<p>The <tt>series</tt> function also updates the internal list <tt>$idx</tt>
index value, which can be used inside <em>func</em>.</p>


<p>Use the <a href="#sequence">sequence</a> function to generate arithmetic sequences.
</p>

<br/><br/>

<a name="set"></a>
<h2><span class="function">set</span>&nbsp;<a href="#destructive">!</a></h2>
<h4>syntax: (set <em>sym-1</em> <em>exp-1</em> [<em>sym-2</em> <em>exp-2</em> ... ])</h4>

<p>Evaluates both arguments and then assigns the result of <em>exp</em> 
to the symbol found in <em>sym</em>. The <tt>set</tt> expression 
returns the result of the assignment. The assignment is performed by copying 
the contents of the right side into the symbol. The old contents of the symbol 
are deleted. An error message results when trying to change the contents 
of the symbols <tt>nil</tt>, <tt>true</tt>, or a context symbol.
<tt>set</tt> can take multiple argument pairs.</p>

<!-- example -->

<pre>
(set 'x 123)     <span class='arw'>&rarr;</span> 123
(set 'x 'y)      <span class='arw'>&rarr;</span> y
(set x "hello")  <span class='arw'>&rarr;</span> "hello"

y  <span class='arw'>&rarr;</span> "hello"

(set 'alist '(1 2 3))  <span class='arw'>&rarr;</span> (1 2 3)


(set 'x 1 'y "hello")  <span class='arw'>&rarr;</span> "hello"  ; multiple arguments

x  <span class='arw'>&rarr;</span> 1
y  <span class='arw'>&rarr;</span> "hello"
</pre>


<p>The symbol for assignment could be the result from another newLISP expression.
Expressions can refer to variables in the <tt>set</tt> expression.</p>

<pre>
(set 'lst '(x y z))  <span class='arw'>&rarr;</span> (x y z)

(set (first lst) 123)  <span class='arw'>&rarr;</span> 123

x  <span class='arw'>&rarr;</span> 123

(set 'a 10 'b (+ a a))

a   <span class='arw'>&rarr;</span> 10,  b   <span class='arw'>&rarr;</span> 20
</pre>


<p>
Symbols can be set to lambda or lambda-macro expressions.
This operation is equivalent to using <a href="#define">define</a> 
or <a href="#define-macro">define-macro</a>.</p>


<pre>
(set 'double (lambda (x) (+ x x)))
<span class='arw'>&rarr;</span> (lambda (x) (+ x x))
</pre>


<p>is equivalent to:</p>


<pre>
(define (double x) (+ x x))
<span class='arw'>&rarr;</span> (lambda (x) (+ x x))
</pre>


<p>is equivalent to:</p>


<pre>
(define double (lambda (x) (+ x x)))
<span class='arw'>&rarr;</span> (lambda (x) (+ x x))
</pre>


<p>
Use the <a href="#constant">constant</a> function (which works like <tt>set</tt>)
to protect the symbol from subsequent alteration. Using the <a href="#setq">setq</a> 
or <a href="#setf">setf</a> function eliminates the need to quote the variable symbol.
</p>

<br/><br/>

<a name="set-locale"></a>
<h2><span class="function">set-locale</span></h2>
<h4>syntax: (set-locale [<em>str-locale</em> [<em>int-category</em>]])</h4>

<p>Reports or switches to a different locale on your operating system or platform.
When used without arguments, <em>set-locale</em> reports 
the current locale being used. When <em>str-locale</em> is specified, 
<em>set-locale</em> switches to the locale with all category options turned on 
(<tt>LC_ALL</tt>). Placing an empty string in <em>str-locale</em> 
switches to the default locale used on the current platform.</p>

<p><tt>set-locale</tt> returns either the current locale string and decimal 
point string in a list  or <tt>nil</tt> if the requested change could not 
be performed.</p>

<!-- example -->

<pre>
; report current locale

(set-locale)     

; set default locale of your platform and country
; return value shown when executing on German MS-Windows

(set-locale "")    <span class='arw'>&rarr;</span> ("German_Germany.1252" ",")
(add 1,234 1,234)  <span class='arw'>&rarr;</span> 2,468
</pre>

<p>By default, newLISP &ndash; if not enabled for UTF-8 &ndash; starts up with the POSIX C 
default locale. This guarantees that newLISP's behavior will be identical on any 
platform locale. On UTF-8 enabled versions of newLISP the locale of
the current platform is chosen.</p>

<pre>
; after non-UTF-8 newLISP start up

(set-locale)  <span class='arw'>&rarr;</span> ("C" ".")
</pre>

<p>In <em>int-category</em> integer numbers may be specified as <em>category options</em> 
for fine-tuning certain aspects of the locale, such as number display, date display, 
and so forth. The options valid on your platform can be found in the C include file 
<tt>locale.h</tt> and may be different on each platform. When no <em>int-category</em>
is specified, <tt>LC_ALL</tt> is used to turn on all options for that locale.</p>

<table>
<tr align="left"><th>Category</th><th>macOS, BSDs<br/>&amp; MS Windows</th></tr>
<tr><td>LC_ALL</td><td>0</td></tr>
<tr><td>LC_COLLATE</td><td>1</td></tr>
<tr><td>LC_CTYPE</td><td>2</td></tr>
<tr><td>LC_MONETARY</td><td>3</td></tr>
<tr><td>LC_NUMERIC</td><td>4</td></tr>
<tr><td>LC_TIME</td><td>5</td></tr>
</table>
<br/>

<p>The default C locale uses the decimal dot, but most others use a decimal comma.</p>

<pre>
; with the current locale "en_US.UTF-8", only change the decimal separator 
; to German locale comma on  macOS. LC_NUMERIC is 4 on most platforms 

(set-locale) <span class='arw'>&rarr;</span> ("en_US.UTF-8" ".") 
(set-locale "de_DE.UTF-8" 4) <span class='arw'>&rarr;</span> ("de_DE.UTF-8" ",") 

; mixed locale shows country setting for each category, 4 has changed
(set-locale) <span class='arw'>&rarr;</span> ("en_US.UTF-8/en_US.UTF-8/en_US.UTF-8/de_DE.UTF-8/en_US.UTF-8/en_US.UTF-8" ",")
</pre>

<p>Note that using <tt>set-locale</tt> does not change the behavior 
of regular expressions in newLISP. To localize the behavior of PCRE 
(Perl Compatible Regular Expressions), newLISP must be compiled 
with different character tables. See the file, LOCALIZATION, 
in the newLISP source distribution for details.</p>

<p>
	See also the chapter <a href="#switching">Switching the locale</a>.
</p>

<br/><br/>

<a name="set-ref"></a>
<h2><span class="function">set-ref</span>&nbsp;<a href="#destructive">!</a></h2>
<h4>syntax: (set-ref <em>exp-key</em> <em>list</em> <em>exp-replacement</em> [<em>func-compare</em>])</h4>


<p>Searches for <em>exp-key</em> in <em>list</em> and replaces the found element with 
<em>exp-replacement</em>. The <em>list</em> can be nested. The system variables 
<tt>$it</tt> contains the expression found and can be used in 
<em>exp-replacement</em>. The function returns the new modified <em>list</em>.</p>


<!-- example -->

<pre>
(set 'data '(fruits (apples 123 44) (oranges 1 5 3)))

(set-ref 'apples data 'Apples)  <span class='arw'>&rarr;</span> (fruits (Apples 123 44) (oranges 1 5 3))

data <span class='arw'>&rarr;</span> (fruits (Apples 123 44) (oranges 1 5 3)))
</pre>


<p><tt>data</tt> could be the context identifier of a default function for passing lists by reference:</p>


<pre>
(set 'db:db '(fruits (apples 123 44) (oranges 1 5 3)))

(define (update ct key value)
	(set-ref key ct value))

(update db 'apples 'Apples)    <span class='arw'>&rarr;</span> (fruits (Apples 123 44) (oranges 1 5 3))
(update db 'oranges 'Oranges)  <span class='arw'>&rarr;</span> (fruits (Apples 123 44) (Oranges 1 5 3))

db:db <span class='arw'>&rarr;</span> (fruits (Apples 123 44) (Oranges 1 5 3))
</pre>


<p>For examples on how to use <em>func-compare</em> see 
<a href="#set-ref-all">set-ref-all</a></p>

<p>For changing all occurrences of an element in a list use 
<a href="#set-ref-all">set-ref-all</a>.</p>

<br/><br/>

<a name="set-ref-all"></a>
<h2><span class="function">set-ref-all</span>&nbsp;<a href="#destructive">!</a></h2>
<h4>syntax: (set-ref-all <em>exp-key</em> <em>list</em>  <em>exp-replacement</em> [<em>func-compare</em>])</h4>

<p>Searches for <em>exp-key</em> in <em>list</em> and replaces each instance of the found element 
with <em>exp-replacement</em>. The <em>list</em> can be nested. The system variable <tt>$it</tt> 
contains the expression found and can be used in <em>exp-replacement</em>.
The system variable <tt>$count</tt> contains the number of replacements made.
The function returns the new modified <em>list</em>.</p>

<!-- example -->

<pre>
(set 'data '((monday (apples 20 30) (oranges 2 4 9)) (tuesday (apples 5) (oranges 32 1))))

(set-ref-all 'apples data "Apples")
 <span class='arw'>&rarr;</span> ((monday ("Apples" 20 30) (oranges 2 4 9)) (tuesday ("Apples" 5) (oranges 32 1)))

$count <span class='arw'>&rarr;</span> 2
</pre>


<p>Using the default functor in the <tt>(<em>list</em> <em>key</em>)</tt> pattern allows the
list to be passed by reference to a user-defined function containing a <tt>set-ref-all</tt>
statement. This would result in less memory usage and higher speeds in when doing replacements
in large lists:</p>


<pre>
(set 'db:db '((monday (apples 20 30) (oranges 2 4 9)) (tuesday (apples 5) (oranges 32 1))))

(define (foo ctx)
	(set-ref-all 'apples ctx "Apples")
)

(foo db) 
 <span class='arw'>&rarr;</span> ((monday ("Apples" 20 30) (oranges 2 4 9)) (tuesday ("Apples" 5) (oranges 32 1)))
</pre>


<p>When evaluating <tt>(foo db)</tt>, the list in <tt>db:db</tt> will be passed
by reference and <tt>set-ref-all</tt> will make the changes on the original, not on
a copy of <tt>db:db</tt>.</p>

<p>Like with <a href="#find">find</a>, <a href="#replace">replace</a>, 
<a href="#ref">ref</a> and <a href="#ref-all">ref-all</a>, 
complex searches can be expressed using 
<a href="#match">match</a> or <a href="#unify">unify</a> in <em>func-compare</em>:</p>


<pre>
(set 'data '((monday (apples 20 30) (oranges 2 4 9)) (tuesday (apples 5) (oranges 32 1))))

(set-ref-all '(oranges *) data (list (first $it) (apply + (rest $it))) match)
    <span class='arw'>&rarr;</span> ( ... (oranges 15) ... (oranges 33) ... ) 
</pre>


<p>The example sums all numbers found in records starting with 
the symbol <tt>oranges</tt>. The found items appear in <tt>$it</tt></p>

<p>See also <a href="#set-ref">set-ref</a> which replaces only the first element found.</p>

<br/><br/>

<a name="setq"></a> <a name="setf"></a>
<h2><span class="function">setq setf</span>&nbsp;<a href="#destructive">!</a></h2>
<h4>syntax: (setq <em>place-1</em> <em>exp-1</em> [<em>place-2</em> <em>exp-2</em> ... ])</h4>

<p>
<tt>setq</tt> and <tt>setf</tt> work alike in newLISP and set the contents
of a symbol, list, array or string or of a list, array or string place reference. Like 
<a href="#set">set</a>, <tt>setq</tt> and <tt>setf</tt> can take multiple argument pairs. 
Although both <tt>setq</tt> and <tt>setf</tt> point to the same built-in function internally, 
throughout this manual <tt>setq</tt> is used when setting a symbol reference and <tt>setf</tt> 
is used when setting list or array references.</p>

<!-- example -->

<pre>
(setq x 123)  <span class='arw'>&rarr;</span> 123

; multiple arguments

(setq x 1 y 2 z 3)  <span class='arw'>&rarr;</span> 3 

x  <span class='arw'>&rarr;</span> 1
y  <span class='arw'>&rarr;</span> 2
z  <span class='arw'>&rarr;</span> 3

; with nth or implicit indices
(setq L '(a b (c d) e f g))

(setf (L 1) 'B)      <span class='arw'>&rarr;</span> B
; or the same
(setf (nth 1 L) 'B)
L                    <span class='arw'>&rarr;</span> (a B (c d) e f g)

(setf (L 2 0) 'C)    <span class='arw'>&rarr;</span> C
L                    <span class='arw'>&rarr;</span> (a B (C d) e f g)

(setf (L 2) 'X)   
L                    <span class='arw'>&rarr;</span> (A B X e f g)

; with assoc
(setq L '((a 1) (b 2)))
(setf (assoc 'b L) '(b 3)) <span class='arw'>&rarr;</span> (b 3)
L                          <span class='arw'>&rarr;</span> ((a 1) (b 3))

; with lookup
(setf (lookup 'b L) 30) <span class='arw'>&rarr;</span> 30
L                       <span class='arw'>&rarr;</span> ((a 1) (b 30))

; several list accessors can be nested
(setq L '((a 1) (b 2)))

(push 'b (setf (assoc 'b l) '(b 4))) 'b) <span class='arw'>&rarr;</span> b
L                                        <span class='arw'>&rarr;</span>((a 1) (b b 4)))

; on strings
(set 's "NewISP")

(setf (s 0) "n") <span class='arw'>&rarr;</span> "n"
s <span class='arw'>&rarr;</span> "newISP"

(setf (s 3) "LI") <span class='arw'>&rarr;</span> "LI"
s <span class='arw'>&rarr;</span> "newLISP"
</pre>


<p>Often the new value set is dependent on the old value. <tt>setf</tt> can
use the anaphoric system variable <tt>$it</tt> to refer to the old
value inside the <tt>setf</tt> expression:</p>


<pre>
(setq L '((apples 4) (oranges 1))) 

(setf (L 1 1) (+ $it 1)) <span class='arw'>&rarr;</span> 2

L                        <span class='arw'>&rarr;</span> ((apples 4) (oranges 2))

(set 's "NewLISP")

(setf (s 0) (lower-case $it)) <span class='arw'>&rarr;</span> "n")

s <span class='arw'>&rarr;</span> "newLISP"
</pre>

<br/><br/>

<a name="sgn"></a>

<h2><span class="function">sgn</span></h2>
<h4>syntax: (sgn <em>num</em>)<br/>
syntax: (sgn <em>num</em> <em>exp-1</em> [<em>exp-2</em> [<em>exp-3</em>]])</h4>

<p>
In the first syntax,
the <tt>sgn</tt> function is a logical function 
that extracts the sign of a real number 
according to the following rules:
</p>
<p>
<b><em>
x &gt; <tt>0</tt> : sgn(x) = 1<br/>
x &lt; <tt>0</tt> : sgn(x) = -1<br/>
x = <tt>0</tt> : sgn(x) = <tt>0</tt>
</em></b>
</p>

<!-- example -->

<pre>
(sgn -3.5)  <span class='arw'>&rarr;</span> -1
(sgn 0)     <span class='arw'>&rarr;</span> 0
(sgn 123)   <span class='arw'>&rarr;</span> 1
</pre>

<p>In the second syntax, the result of evaluating 
one of the optional expressions 
<em>exp-1</em>, <em>exp-2</em>, or <em>exp-3</em> is returned, 
instead of <tt>-1</tt>, <tt>0</tt>, or <tt>1</tt>. 
If <em>exp-n</em> is missing for the case triggered,
then <tt>nil</tt> is returned.</p>

<!-- example -->

<pre>
(sgn x -1 0 1)         ; works like (sgn x)
(sgn x -1 1 1)         ; -1 for negative x all others 1
(sgn x nil true true)  ; nil for negative else true
(sgn x (abs x) 0)      ; (abs x) for x &lt; 0, 0 for x = 0, else nil
</pre>


<p>
Any expression or constant can be used for 
<em>exp-1</em>, <em>exp-2</em>, or <em>exp-3</em>.
</p>

<br/><br/>

<a name="share"></a>
<h2><span class="function">share</span></h2>
<h4>syntax: (share)<br/>
syntax: (share <em>int-address-or-handle</em>)<br/>
syntax: (share <em>int-address-or-handle</em> <em>exp-value</em>)<br/><br/>
syntax: (share <em>nil</em> <em>int-address</em>)</h4>

<p>
Accesses shared memory 
for communicating between 
several newLISP processes.
When called without arguments, 
 <tt>share</tt> requests a page of shared memory 
from the operating system. 
This returns a memory address on Linux/Unix 
and a handle on MS Windows, 
which can then be 
assigned to a variable 
for later reference.
This function is not available on OS/2.
</p>

<p>To set the contents of shared memory, use the third syntax of <tt>share</tt>. 
Supply a shared memory address on Linux/Unix or a handle on MS Windows in 
<em>int-address-or-handle</em>, along with an integer, float, string 
expression or any other expression (since v.10.1.0) supplied
in <em>exp-value</em>.  Using this syntax, the value supplied in <em>exp-value</em> 
is also the return value.</p>

<p>To access the contents of shared memory, 
use the second syntax of <tt>share</tt>, 
supplying only the shared memory address or handle.
The return value will be any constant or expression (since v.10.1.0)
written previously into the memory.
If the memory has not been previously set to a value, 
<tt>nil</tt> will be returned.</p>

<p>Only available on Unix-like operating systems, 
the last syntax unmaps a shared memory address.
Note that using a shared address after unmapping it 
will crash the system.</p>

<p>Memory can be shared between parent and child processes,
but not between independent processes.</p>

<p>Since 10.1.0 size of share objects can exceed the shared memory pagesize
of the operating system. For objects bigger than the pagesize, newLISP internally
uses files for sharing. This requires a <tt>/tmp</tt> directory on Unix-like
operating system. On MS Windows systems the environment variable <tt>TEMP</tt>
must be set.</p>

<!-- example -->

<pre>
(set 'mem (share))

(share mem 123)  <span class='arw'>&rarr;</span> 123
(share mem)      <span class='arw'>&rarr;</span> 123

(share mem "hello world") <span class='arw'>&rarr;</span> "hello world"
(share mem)               <span class='arw'>&rarr;</span> "hello world"

(share mem true)  <span class='arw'>&rarr;</span> true
(share mem)       <span class='arw'>&rarr;</span> true

(share mem '(+ 1 2 3 4))  <span class='arw'>&rarr;</span> (+ 1 2 3 4)
(share mem)               <span class='arw'>&rarr;</span> (+ 1 2 3 4)

; expressions received can be evaluated (since v.10.1.0)
(eval (share mem))        <span class='arw'>&rarr;</span> 10 

(share nil mem)   <span class='arw'>&rarr;</span> true  ; unmap only on Unix
</pre>


<p>Expression read from shared memory and evaluated, will be evaluated
in the recipient's process environment.</p>

<p>Note that shared memory access between different processes 
should be synchronized using a <a href="#semaphore">semaphore</a>.
Simultaneous access to shared memory can crash the running process.</p>

<p>For a more comprehensive example of using shared memory in a multi process 
Linux/Unix application, see the file <tt>example/prodcons.lsp</tt> in the
newLISP source distribution.</p>

<br/><br/>

<a name="signal"></a>
<h2><span class="function">signal</span></h2>
<h4>syntax: (signal <em>int-signal</em> <em>sym-event-handler</em> | <em>func-event-handler</em>)<br/>
syntax: (signal <em>int-signal</em> "ignore" | "default" | "reset")<br/>
syntax: (signal <em>int-signal</em>)</h4>

<p>
Sets a user-defined handler in <em>sym-event-handler</em> for a signal specified in <em>int-signal</em>
or sets to a function expression in <em>func-event-handler</em>.</p>

<p>A parameter following <em>int-signal</em> is not evaluated.</p>

<p>If no signal handler is specified any of the string constants <tt>"ignore"</tt>,
<tt>"default"</tt> or <tt>"reset"</tt> can be specified in either lower or upper case
or simply using the first letter of the option string. When signal setup with any
of these three options has been successful, <tt>true</tt> is returned.</p>

<p>Using <tt>"ignore"</tt> will make newLISP ignore the signal. Using <tt>"default"</tt>
will set the handler to the default handler of the underlying platform OS. The <tt>"reset"</tt>
option will restore the handler to newLISP startup state.</p>

<p>On startup, newLISP either specifies an empty newLISP handler or a Ctrl-C handler for 
<tt>SIGINT</tt> and a <tt>waitpipd(-1, 0, WNOHANG)</tt> C-call for <tt>SIGCHLD</tt>.
</p>

<p>Different signals are available on different OS platforms and Linux/Unix flavors.
The numbers to specify in <em>int-signal</em> also differ from platform-to-platform.
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>.</p>

<p>Some signals make newLISP exit even after a user-defined handler 
has been specified and executed (e.g., signal SIGKILL).
This behavior may also be different on different platforms.</p>

<!-- example -->

<pre>
(constant 'SIGINT 2)
(define (ctrlC-handler) (println "ctrl-C has been pressed"))

(signal SIGINT 'ctrlC-handler)

; now press ctrl-C
; the following line will appear
; this will only work in an interactive terminal window

ctrl-C has been pressed

; reset treatment of signal 2 to startup conditions

(signal SIGINT "reset")
</pre>


<p> On MS Windows, the above example would execute the handler before exiting newLISP.
On most Linux/Unix systems, newLISP would stay loaded and the prompt would appear 
after hitting the [enter] key.</p>

<p> Instead of specifying a symbol containing the signal handler,
a function can be specified directly.  The signal number is passed as a parameter:
</p>


<pre>
(signal SIGINT exit)  <span class='arw'>&rarr;</span> $signal-2

(signal SIGINT (fn (s) (println "signal " s " occurred")))
</pre>


<p> Note that the signal SIGKILL (9 on most platforms) will always terminate the 
application regardless of an existing signal handler.</p>

<p>The signal could have been sent from another shell on the same computer:</p>


<pre>
kill -s SIGINT 2035
</pre>


<p>In this example, <tt>2035</tt> is the process ID of the running newLISP.</p>

<p>The signal could also have been sent from another newLISP application using 
the function <a href="#destroy">destroy</a>:</p>


<pre>
(destroy 2035) <span class='arw'>&rarr;</span> true
</pre>


<p>If newLISP receives a signal while evaluating another function,
it will still accept the signal and the handler function will be executed:</p>


<pre>
; only on macOS, BSDs and Linux, not on Windows
(constant 'SIGINT 2)
(define (ctrlC-handler) (println "ctrl-C has been pressed"))

(signal SIGINT 'ctrlC-handler)
;; or
(signal SIGINT ctrlC-handler)


(while true (sleep 300) (println "busy"))

;; generates following output
busy
busy
busy
ctrl-C has been pressed
busy
busy
&hellip;
</pre>


<p>Specifying only a signal number will return either the name of 
the currently defined handler function or <tt>nil</tt>.
</p>

<p>The user-defined signal handler can pass the signal number as a parameter.</p>


<pre>
(define (signal-handler sig)
	(println "received signal: " sig))

;; set all signals from 1 to 8 to the same handler	
(for (s 1 8) 
	(signal s 'signal-handler))
</pre>


<p>In this example, all signals from 1 to 8 are set to the same handler.</p>

<br/><br/>

<a name="silent"></a>
<h2><span class="function">silent</span></h2>

<h4>syntax: (silent [<em>exp-1</em> [<em>exp-2</em> ... ]])</h4>

<p>
	Evaluates one or more expressions in <em>exp-1</em>&mdash;.
	<tt>silent</tt> is similar to <a href="#begin">begin</a>,
	but it suppresses console output 
	of the return value 
	and the following prompt.
	It is often used 
	when communicating from 
	a remote application with newLISP 
	(e.g., GUI front-ends 
	or other applications controlling newLISP), 
	and the return value is of no interest.
</p>

<p>
	Silent mode is reset when returning to a prompt.
	This way, 
	it can also be used without arguments 
	in a batch of expressions.
	When in interactive mode, 
	hit [enter] twice after a statement 
	using <tt>silent</tt> 
	to get the prompt back.
</p>


<!-- example -->

<pre>
(silent (my-func))  ; same as next

(silent) (my-func)  ; same effect as previous
</pre>

<br/><br/>

<a name="sin"></a>
<h2><span class="function">sin</span></h2>
<h4>syntax: (sin <em>num-radians</em>)</h4>

<p>
	Calculates the sine function 
	from <em>num-radians</em> 
	and returns the result.
</p>

<!-- example -->

<pre>
(sin 1)                     <span class='arw'>&rarr;</span> 0.8414709838
(set 'pi (mul 2 (acos 0)))  <span class='arw'>&rarr;</span> 3.141592654
(sin (div pi 2))            <span class='arw'>&rarr;</span> 1
</pre>

<br/><br/>

<a name="sinh"></a>
<h2><span class="function">sinh</span></h2>
<h4>syntax: (sinh <em>num-radians</em>)</h4>

<p>Calculates the hyperbolic sine of <em>num-radians</em>. 
The hyperbolic sine is defined mathematically as: <em>(exp (x) - exp (-x)) / 2</em>.
An overflow to <tt>inf</tt> may occur if <em>num-radians</em> is too large.</p>

<!-- example -->

<pre>
(sinh 1)     <span class='arw'>&rarr;</span> 1.175201194
(sinh 10)    <span class='arw'>&rarr;</span> 11013.23287
(sinh 1000)  <span class='arw'>&rarr;</span> inf
(sub (tanh 1) (div (sinh 1) (cosh 1))) <span class='arw'>&rarr;</span> 0
</pre>

<br/><br/>

<a name="sleep"></a>
<h2><span class="function">sleep</span></h2>

<h4>syntax: (sleep <em>num-milliseconds</em>)</h4>

<p>Gives up CPU time to other processes for the amount of 
milliseconds specified in <em>num-milli-seconds</em>.
</p>

<!-- example -->

<pre>
(sleep 1000)  ; sleeps 1 second
(sleep 0.5)   ; sleeps 500 micro seconds
</pre>


<p>On some platforms, <tt>sleep</tt> is only available with a resolution 
of one second. In this case, the parameter <em>int-milli-seconds</em> 
will be rounded to the nearest full second.</p>

<p>A <tt>sleep</tt> may be cut short by a finishing child process started
with <a href="#fork">fork</a> or <a href="#spawn">spawn</a>.</p>

<br/><br/>

<a name="slice"></a>
<h2><span class="function">slice</span></h2>

<h4>syntax: (slice <em>list</em> <em>int-index</em> [<em>int-length</em>])<br/>
syntax: (slice <em>array</em> <em>int-index</em> [<em>int-length</em>])<br/>
syntax: (slice <em>str</em> <em>int-index</em> [<em>int-length</em>])</h4>

<p>In the first form, <tt>slice</tt> copies a sublist 
from a <em>list</em>.  The original list is left unchanged.
The sublist extracted starts at index <em>int-index</em> 
and has a length of <em>int-length</em>.  If <em>int-length</em> is negative,
<tt>slice</tt> will take the parameter as offset counting from the end and copy 
up to but not including that offset.  If the parameter is omitted, 
<tt>slice</tt> copies all of the elements to the end of the list.</p>

<p>
	See also <a href="#indexing">Indexing elements of strings and lists</a>.
</p>

<!-- example -->

<pre>
(slice '(a b c d e f) 3 2)   <span class='arw'>&rarr;</span> (d e)
(slice '(a b c d e f) 2 -2)  <span class='arw'>&rarr;</span> (c d)
(slice '(a b c d e f) 2)     <span class='arw'>&rarr;</span> (c d e f)
(slice '(a b c d e f) -4 3)  <span class='arw'>&rarr;</span> (c d e)

(set 'A (array 3 2 (sequence 1 6))) <span class='arw'>&rarr;</span> ((1 2) (3 4) (5 6))
(slice A 1 2) <span class='arw'>&rarr;</span> ((3 4) (5 6))
</pre>


<p>
In the second form, a part of the string in <em>str</em> 
is extracted.  <em>int-index</em> contains the start index
and <em>int-length</em> contains the length of the substring.
If <em>int-length</em> is not specified, everything to the end of the string is extracted.
<tt>slice</tt> also works on string buffers containing binary data like <tt>0</tt>'s (zeroes). 
It operates on byte boundaries rather than character boundaries.
See also <a href="#indexing">Indexing elements of strings and lists</a>.</p>

<p>Note that <tt>slice</tt> always works on single 8-bit byte boundaries for
offset and length numbers, even when running the UTF-8 enabled version of newLISP.</p>

<!-- example -->

<pre>
(slice "Hello World" 6 2)  <span class='arw'>&rarr;</span> "Wo"
(slice "Hello World" 0 5)  <span class='arw'>&rarr;</span> "Hello"
(slice "Hello World" 6)    <span class='arw'>&rarr;</span> "World"
(slice "newLISP" -4 2)     <span class='arw'>&rarr;</span> "LI"

; UTF-8 strings are converted to a list, then joined again

(join (slice (explode "ΩΨΧΦΥΤΣΣΡΠΟΞΝΜΛΚΙΘΗΖΕΔΓΒΑ") 3 5))  <span class='arw'>&rarr;</span> "ΦΥΤΣΣ" 
</pre>


<p>
	Note that an <em>implicit slice</em> 
	is available for lists.
	See the chapter <a href="#implicit_rest_slice">Implicit rest and slice</a>.
</p>

<p>
	Be aware that <a href="#slice">slice</a> 
	always works on byte boundaries 
	rather than character boundaries 
	in the UTF-8&ndash;enabled version of newLISP.
	As a result, 
	<a href="#slice">slice</a> can be used 
	to manipulate binary content.
</p>

<br/><br/>

<a name="sort"></a>
<h2><span class="function">sort</span>&nbsp;<a href="#destructive">!</a></h2>
<h4>syntax: (sort <em>list</em> [<em>func-compare</em>])<br/>
syntax: (sort <em>array</em> [<em>func-compare</em>])</h4>

<p>All members in <em>list</em> or <em>array</em> are sorted in ascending order.
Anything may be sorted, regardless of the types.
When members are themselves lists or arrays, each element 
is recursively compared.  If two expressions 
of different types are compared, the lower type is sorted 
before the higher type in the following order:
</p>

<pre>
Atoms: nil, true, integer or float, string, symbol, primitive
Lists: quoted expression, list, lambda, lambda-macro
</pre>

<p>The <tt>sort</tt> is destructive, changing the order of the elements in the
original list or array and returning the sorted list or array. It is a stable
binary merge-sort with approximately <em>O(n log2 n)</em> performance
preserving the order of adjacent elements which are equal. When  
<em>func-compare</em> is used it must work with either <tt>&lt;=</tt> or
<tt>&gt;=</tt> operators to be stable.</p>

<p>An optional comparison operator, user-defined function, 
or anonymous function can be supplied. The functor or operator 
can be given with or without a preceding quote.</p>

<!-- example -->

<pre>
(sort '(v f r t h n m j))     <span class='arw'>&rarr;</span> (f h j m n r t v)
(sort '((3 4) (2 1) (1 10)))  <span class='arw'>&rarr;</span> ((1 10) (2 1) (3 4))
(sort '((3 4) "hi" 2.8 8 b))  <span class='arw'>&rarr;</span> (2.8 8 "hi" b (3 4))

(set 's '(k a l s))
(sort s)  <span class='arw'>&rarr;</span> (a k l s)  

(sort '(v f r t h n m j) &gt;) <span class='arw'>&rarr;</span> (v t r n m j h f)

(sort s &lt;)  <span class='arw'>&rarr;</span> (a k l s)
(sort s &gt;)  <span class='arw'>&rarr;</span> (s l k a)  
s           <span class='arw'>&rarr;</span> (s l k a)

;; define a comparison function
(define (comp x y) 
    (&gt;= (last x) (last y)))
    
(set 'db '((a 3) (g 2) (c 5)))

(sort db comp)  <span class='arw'>&rarr;</span>  ((c 5) (a 3) (g 2))

;; use an anonymous function
(sort db (fn (x y) (&gt;= (last x) (last y))))
</pre>

<br/><br/>

<a name="source"></a>
<h2><span class="function">source</span></h2>
<h4>syntax: (source)<br/>
syntax: (source <em>sym-1</em> [<em>sym-2</em> ... ])</h4>

<p>
	Works almost identically to <a href="#save">save</a>,
	except symbols and contexts get serialized to a string 
	instead of being written to a file.
	Multiple variable symbols,
	definitions, and contexts 
	can be specified.
	If no argument is given,
	<tt>source</tt> serializes the entire 
	newLISP workspace.
	When context symbols are serialized,
	any symbols contained within that context 
	will be serialized, as well.
	Symbols containing <tt>nil</tt> 
	are not serialized.
	System symbols beginning with the <tt>$</tt> (dollar sign) character 
	are only serialized when mentioned explicitly.
</p>

<p>
	Symbols not belonging to the current context
	are written out with their context prefix.
</p>

<!-- example -->

<pre>
(define (double x) (+ x x))

(source 'double)  <span class='arw'>&rarr;</span> "(define (double x)\n  (+ x x))\n\n"
</pre>


<p>
	As with <a href="#save">save</a>,
	the formatting of line breaks 
	and leading spaces or tabs 
	can be controlled using the 
	<a href="#pretty-print">pretty-print</a> function.
</p>

<br/><br/>

<a name="spawn"></a>
<h2><span class="function">spawn</span></h2>
<h4>syntax: (spawn <em>sym</em> <em>exp</em> [true])</h4>

<p>Launches the evaluation of <em>exp</em> as a child process and immediately
returns. The symbol in <em>sym</em> is quoted and receives the result of the 
evaluation when the function <a href="#sync">sync</a> is executed. <tt>spawn</tt>
is used to start parallel evaluation of expressions in concurrent processes.
If newLISP is running on a multi-core CPU, the underlying operating system 
will distribute spawned processes onto different cores, thereby evaluating 
expressions in parallel and speeding up overall processing.</p>

<p>The optional <tt>true</tt> parameter must be set if <a href="#send">send</a>
or <a href="#receive">receive</a> is used to communicated with the child
process spawned.</p>

<p>The function <tt>spawn</tt> is not available on MS Windows.</p>

<p>After successfully starting a child process,  the <tt>spawn</tt> expression
returns the process id of the forked process. The following examples shows
how the calculation of a range of prime numbers can be split up in four sub ranges to
speed up the calculation of the whole range:</p>

<!-- example -->

<pre>
; calculate primes in a range
(define (primes from to)
  (local (plist)
      (for (i from to)
          (if (= 1 (length (factor i)))
              (push i plist -1)))
      plist))

; start child processes
(set 'start (time-of-day))

(spawn 'p1 (primes 1 1000000))
(spawn 'p2 (primes 1000001 2000000))
(spawn 'p3 (primes 2000001 3000000))
(spawn 'p4 (primes 3000001 4000000))

; wait for a maximum of 60 seconds for all tasks to finish
(sync 60000) ; returns true if all finished in time
; p1, p2, p3 and p4 now each contain a lists of primes

(println "time spawn: " (- (time-of-day) start))
(println "time simple: " (time  (primes 1 4000000)))

(exit)
</pre>


<p>On a 1.83 Intel Core 2 Duo processor, the above example will finish
after about 13 seconds. Calculating all primes using <tt>(primes 1 4000000)</tt>
would take about 20 seconds.</p>

<p>The <a href="#sync">sync</a> function will wait for all child processes
to finish and receive the evaluation results in the symbols <tt>p1</tt> to
<tt>p4</tt>. When all results are collected, <tt>sync</tt>
will stop waiting and return <tt>true</tt>. When the time specified was
insufficient , <tt>sync</tt> will return <tt>nil</tt> and  another 
<tt>sync</tt> statement could be given to further wait and collect results. 
A short timeout time can be used to do other processing during waiting:</p>


<pre>
(spawn 'p1 (primes 1 1000000))
(spawn 'p2 (primes 1000001 2000000))
(spawn 'p3 (primes 2000001 3000000))
(spawn 'p4 (primes 3000001 4000000))

; print a dot after each 2 seconds of waiting
(until (sync 2000) (println "."))
</pre>


<p><tt>sync</tt> when used without any parameters, will not wait but immediately
return a list of pending child processes. For the <tt>primes</tt> example, the following
<tt>sync</tt> expression could be used to watch the progress:</p>


<pre>
(spawn 'p1 (primes 1 1000000))
(spawn 'p2 (primes 1000001 2000000))
(spawn 'p3 (primes 2000001 3000000))
(spawn 'p4 (primes 3000001 4000000))

; show a list of pending process ids after each three-tenths of a second
(until (sync 300) (println (sync)))
</pre>


<p>A parameter of <tt>-1</tt> tells <tt>sync</tt> to wait for a very long time
(~ 1193 hours). A better solution would be to wait for a maximum time, 
then <a href="#abort">abort</a>  all pending child processes:</p>


<pre>
(spawn 'p1 (primes 1 1000000))
(spawn 'p2 (primes 1000001 2000000))
(spawn 'p3 (primes 2000001 3000000))
(spawn 'p4 (primes 3000001 4000000))

; wait for one minute, then abort and
; report unfinished PIDs

(if (not (sync 60000))
    (begin
        (println "aborting unfinished: " (sync))
        (abort))
    (println "all finished successfully")
)
</pre>


<p>The three functions <tt>spawn</tt>, <tt>sync</tt> and <tt>abort</tt>
are part of the <a href="http://supertech.csail.mit.edu/cilk/">Cilk</a> API.
The original implementation also does sophisticated scheduling and allocation
of threaded tasks to multiple CPU cores. The newLISP implementation of the Cilk API
lets the operating system of the underlying platform handle process management.
Internally, the API is implemented using the Unix libc functions <tt>fork()</tt>,
<tt>waitpid()</tt> and <tt>kill()</tt>. Intercommunications between processes
and child processes is done using the <a href="#send">send</a> and 
<a href="#receive">receive</a> functions.</p>

<p><tt>spawn</tt> can be called recursively from spawned subtasks:</p>


<pre>
(define (fibo n)
  (local (f1 f2)
    (if(&lt; n 2) 1
       (begin
          (spawn 'f1 (fibo (- n 1)))
          (spawn 'f2 (fibo (- n 2)))
          (sync 10000)
          (+ f1 f2)))))

(fibo 7)  <span class='arw'>&rarr;</span> 21
</pre>


<p>With <tt>(fibo 7)</tt> 41 processes will be generated. Although the above
code shows the working of the Cilk API in a recursive application, 
it would not be practical, as the overhead required to spawn subtasks 
is much higher than the time saved through parallelization.</p>

<p>Since version 10.1 a <a href="#send">send</a> and <a href="#receive">receive</a>
message functions are available for communications between parent and child processes. 
Using these functions any data or expression of any size can be transferred. 
Additionally messaged expressions can be evaluated in the recipient's environment.</p>

<p><a href="#fork">fork</a> and <a href="#process">process</a> are other functions
to start newLISP processes.</p>

<br/><br/>

<a name="sqrt"></a>
<h2><span class="function">sqrt</span></h2>
<h4>syntax: (sqrt <em>num</em>)</h4>

<p>
	Calculates the square root from 
	the expression in <em>num</em> 
	and returns the result.
</p>

<!-- example -->

<pre>
(sqrt 10)  <span class='arw'>&rarr;</span> 3.16227766
(sqrt 25)  <span class='arw'>&rarr;</span> 5
</pre>

<br/><br/>

<a name="ssq"></a>
<h2><span class="function">ssq</span></h2>
<h4>syntax: (ssq <em>list-vector | array-vector</em>)</h4>

<p>Calculates the sum of squares of numbers in a vector in 
<em>list-vector</em> or <em>array-vector</em>.</p>

<!-- example -->

<pre>
(set 'vector (sequence 1 10))
(ssq vector) <span class='arw'>&rarr;</span> 385

(set 'vector (array 10 (sequence 1 10)))
(ssq vector) <span class='arw'>&rarr;</span> 385
</pre>

<br/><br/>

<a name="starts-with"></a>
<h2><span class="function">starts-with</span></h2>
<h4>syntax: (starts-with <em>str</em> <em> str-key</em> [<em>num-option</em>])<br/>
syntax: (starts-with <em>list</em> [<em>exp</em>])</h4>

<p>In the first version, <tt>starts-with</tt> checks if the string <em>str</em> 
starts with a key string in <em>str-key</em> and returns <tt>true</tt> or <tt>nil</tt> 
depending on the outcome.</p>

<p>If a regular expression number is specified in <em>num-option</em>,
<em>str-key</em> contains a regular expression pattern.
See <a href="#regex">regex</a> for valid <em>option</em> numbers. </p>

<!-- example -->

<pre>
(starts-with "this is useful" "this")        <span class='arw'>&rarr;</span> true
(starts-with "this is useful" "THIS")        <span class='arw'>&rarr;</span> nil

;; use regular expressions
(starts-with "this is useful" "THIS" 1)      <span class='arw'>&rarr;</span> true
(starts-with "this is useful" "this|that" 0) <span class='arw'>&rarr;</span> true
</pre>


<p>In the second version, <tt>starts-with</tt> checks to see if a list 
starts with the list element in <em>exp</em>.  <tt>true</tt> or <tt>nil</tt> 
is returned depending on outcome.</p>

<!-- example -->

<pre>
(starts-with '(1 2 3 4 5) 1)             <span class='arw'>&rarr;</span> true
(starts-with '(a b c d e) 'b)            <span class='arw'>&rarr;</span> nil
(starts-with '((+ 3 4) b c d) '(+ 3 4))  <span class='arw'>&rarr;</span> true
</pre>



<p>
	See also the <a href="#ends-with">ends-with</a> function.
</p>

<br/><br/>

<a name="stats"></a>
<h2><span class="function">stats</span></h2>
<h4>syntax: (stats <em>list-vector</em>)</h4>

<p>The functions calculates statistical values of central tendency and distribution moments
of values in <em>list-vector</em>. The following values are returned by <tt>stats</tt>
in a list:</p>

<table>
<tr align="left"><th>name</th><th>description</th></tr>
<tr><td>N</td><td>Number of values</td></tr>
<tr><td>mean</td><td>Mean of values</td></tr>
<tr><td>avdev</td><td>Average deviation from mean value</td></tr>
<tr><td>sdev</td><td>Standard deviation (population estimate)</td></tr>
<tr><td>var</td><td>Variance (population estimate)</td></tr>
<tr><td>skew</td><td>Skew of distribution</td></tr>
<tr><td>kurt</td><td>Kurtosis of distribution</td></tr>
</table>
<br/>

<!-- example -->

<p>The following example uses the list output from the <tt>stats</tt> expression as an
argument for the <a href="#format">format</a> statement:</p>

<pre>
(set 'data '(90 100 130 150 180 200 220 300 350 400))

(println (format [text]
    N        = %5d
    mean     = %8.2f
    avdev    = %8.2f
    sdev     = %8.2f
    var      = %8.2f
    skew     = %8.2f
    kurt     = %8.2f
[/text] (stats data)))

; outputs the following

    N        =    10
    mean     =   212.00
    avdev    =    84.40
    sdev     =   106.12
    var      = 11262.22
    skew     =     0.49
    kurtosis =    -1.34

</pre>


<br/><br/>

<a name="string"></a>
<h2><span class="function">string</span></h2>
<h4>syntax: (string <em>exp-1</em> [<em>exp-2</em> ... ])</h4>

<p>
	Translates into a string anything that results 
	from evaluating <em>exp-1</em>&mdash;.
	If more than one expression is specified, 
	the resulting strings are concatenated.
</p>

<!-- example -->

<pre>
(string 'hello)          <span class='arw'>&rarr;</span> "hello"
(string 1234)            <span class='arw'>&rarr;</span> "1234"
(string '(+ 3 4))        <span class='arw'>&rarr;</span> "(+ 3 4)"
(string (+ 3 4) 8)       <span class='arw'>&rarr;</span> "78"
(string 'hello " " 123)  <span class='arw'>&rarr;</span> "hello 123"
</pre>


<p>
	If a buffer passed to <tt>string</tt> 
	contains <tt>\000</tt>,
	only the string up to the first terminating zero will be copied:
</p>


<pre>
(set 'buff "ABC\000\000\000")  <span class='arw'>&rarr;</span> "ABC\000\000\000"

(length buff)  <span class='arw'>&rarr;</span> 6

(string buff)  <span class='arw'>&rarr;</span> "ABC"

(length (string buff))  <span class='arw'>&rarr;</span> 3
</pre>


<p>
	Use the <a href="#append">append</a> 
	and <a href="#join">join</a> 
	(allows the joining string 
	to be specified) functions 
	to concatenate strings containing zero bytes.
	Use the <a href="#source">source</a> function 
	to convert a lambda expression 
	into its newLISP source string representation.
</p>

<br/><br/>

<a name="stringp"></a>
<h2><span class="function">string?</span></h2>
<h4>syntax: (string? <em>exp</em>)</h4>

<p>
	Evaluates <em>exp</em> and tests 
	to see if it is a string.
	Returns <tt>true</tt> or <tt>nil</tt>
	depending on the result.
</p>

<!-- example -->

<pre>
(set 'var "hello")
(string? var)  <span class='arw'>&rarr;</span> true
</pre>

<br/><br/>

<a name="struct"></a>
<h2><span class="function">struct</span></h2>
<h4>syntax: (struct <em>symbol</em> [<em>str-data-type</em> ... ])</h4>

<p>The <tt>struct</tt> function can be used to define aggregate data types for 
usage with the extended syntax of <a href="#import">import</a>,
<a href="#pack">pack</a> and <a href="#unpack">unpack</a>, available on all
versions of newLISP compiled with <i>libffi</i>. This allows importing
functions which take C-language <em>struct</em> data types or pointers to these
aggregate data types.</p>

<p>The following example illustrates the usage of <tt>struct</tt> together with
the C data functions <tt>localtime</tt> and <tt>asctime</tt>. The <tt>localtime</tt>
functions works similar to the built-in <a href="#now">now</a> function. The
<tt>asctime</tt> function takes the numerical data output by <tt>localtime</tt>
and formats these to readable text.</p>

<pre>
/* The C function prototypes for the functions to import */

struct tm * localtime(const time_t *clock);

char * asctime(const struct tm *timeptr);

/* the tm struct aggregating different time related values */

struct tm {
    int tm_sec;      /* seconds after the minute [0-60] */
    int tm_min;      /* minutes after the hour [0-59] */
    int tm_hour;     /* hours since midnight [0-23] */
    int tm_mday;     /* day of the month [1-31] */
    int tm_mon;      /* months since January [0-11] */
    int tm_year;     /* years since 1900 */
    int tm_wday;     /* days since Sunday [0-6] */
    int tm_yday;     /* days since January 1 [0-365] */
    int tm_isdst;    /* Daylight Savings Time flag */
    long tm_gmtoff;  /* offset from CUT in seconds */   /*** not on Windows ***/
    char *tm_zone;   /* timezone abbreviation */        /*** not on Windows ***/
};
</pre>

<p>Function import and definition of the structure data type in newLISP:</p>

<pre>
;; for pointers to structs always use void*
;; as a library use msvcrt.dll on Windows or libc.so on Unix.
;; The tm struct type is configured for macOS and Linux.
;; On other OS the tm structure may be different
 
(import "libc.dylib" "asctime" "char*" "void*")
(import "libc.dylib" "localtime" "void*" "void*")

; definition of the struct
(struct 'tm "int" "int" "int" "int" "int" "int" "int" "int" "int" "long" "char*")


;; use import and struct

; todays date number (seconds after 1970 also called Unix epoch time)
(set 'today (date-value))  <span class='arw'>&rarr;</span> 1324134913

;; the time value is passed by it's address
;; localtime retirns a pointer to a tm struct

(set 'ptr (localtime (address today))) <span class='arw'>&rarr;</span> 2896219696

; unpack the tm struct  (7:15:13 on the 17th etc.)
(unpack tm ptr) <span class='arw'>&rarr;</span> (13 15 7 17 11 111 6 350 0 -28800 "PST")

; transform to readable form
(asctime ptr) <span class='arw'>&rarr;</span> "Sat Dec 17 07:15:13 2011\n"

; all in one statement does actually not use struct, pointers are passed directly
(asctime (localtime (address today))) <span class='arw'>&rarr;</span> "Sat Dec 17 07:15:13 2011"

; same as the built-in date function
(date today) <span class='arw'>&rarr;</span> "Sat Dec 17 07:15:13 2011"
</pre>

<p>Care must be taken to pass valid addresses to pointer parameters in imported functions
or when passing address pointers to <a href="#unpack">unpack</a>. Invalid address pointers
can crash newLISP or make it unstable.</p>

<p><tt>struct</tt> definitions can be nested:</p>

<pre>
; the pair aggregate type
(struct 'pair "char" "char") <span class='arw'>&rarr;</span> pair

; nested struct type
(struct 'comp "pair" "int")  <span class='arw'>&rarr;</span> comp

; pack data using the extended pack syntax
; note the insertion of structure alignment bytes after the pair
(pack comp (pack pair 1 2) 3) <span class='arw'>&rarr;</span> "\001\002\000\000\003\000\000\000"

; unpack reverses the process
(unpack comp "\001\002\000\000\003\000\000\000") <span class='arw'>&rarr;</span> ((1 2) 3)
</pre>

<p>Nested structures are unpacked recursively.</p>

<br/><br/>


<a name="sub"></a>
<h2><span class="function">sub</span></h2>
<h4>syntax: (sub <em>num-1</em> [<em>num-2</em> ... ])</h4>

<p>
	Successively subtracts
	the expressions in <em>num-1</em>,
	<em>num-2</em>&mdash;.
	<tt>sub</tt> performs mixed-type arithmetic 
	and handles integers or floating points,
	but it will always return 
	a floating point number.
	If only one argument is supplied,
	its sign is reversed.
	Any floating point calculation 
	with <tt>NaN</tt> also returns <tt>NaN</tt>.
</p>

<!-- example -->

<pre>
(sub 10 8 0.25)  <span class='arw'>&rarr;</span> 1.75
(sub 123)        <span class='arw'>&rarr;</span> -123
</pre>

<br/><br/>

<a name="swap"></a>
<h2><span class="function">swap</span>&nbsp;<a href="#destructive">!</a></h2>
<h4>syntax: (swap <em>place-1</em> <em>place-2</em>)</h4>

<p>The contents of the two places <em>place-1 and place-2</em> 
are swapped. A <em>place</em> can be the contents of an unquoted symbol or any
list or array references expressed with <a href="#nth">nth</a>, 
 <a href="#first">first</a>, <a href="#lst">last</a> or implicit
 <a href="#indexing">indexing</a> or places referenced by <a href="#assoc">assoc</a>
or <a href="#lookup">lookup</a>.</p>

<p><tt>swap</tt> is a destructive operation that changes the contents of the 
lists, arrays, or symbols involved.</p>

<!-- example -->

<pre>
(set 'lst '(a b c d e f))

(swap (first lst) (last lst)) <span class='arw'>&rarr;</span> a
lst                           <span class='arw'>&rarr;</span> (f b c d e a)

(set 'lst-b '(x y z))

(swap (lst 0) (lst-b -1)) <span class='arw'>&rarr;</span> f
lst                       <span class='arw'>&rarr;</span> (z b c d e a)
lst-b                     <span class='arw'>&rarr;</span> (x y f)

(set 'A (array 2 3 (sequence 1 6)) <span class='arw'>&rarr;</span> ((1 2 3) (4 5 6))

(swap (A 0) (A 1)) <span class='arw'>&rarr;</span> (1 2 3)
A                  <span class='arw'>&rarr;</span> ((4 5 6) (1 2 3))

(set 'x 1 'y 2)

(swap x y)  <span class='arw'>&rarr;</span> 1
x  <span class='arw'>&rarr;</span> 2
y  <span class='arw'>&rarr;</span> 1

(set 'lst '((a 1 2 3) (b 10 20 30)))
(swap (lookup 'a lst -1) (lookup 'b lst 1))
lst <span class='arw'>&rarr;</span> ((a 1 2 10) (b 3 20 30))

(swap (assoc 'a lst) (assoc 'b lst))
lst <span class='arw'>&rarr;</span>  ((b 3 20 30) (a 1 2 10))
</pre>


<p>Any two places can be swept in the same or different objects.</p>

<br/><br/>

<a name="sym"></a>
<h2><span class="function">sym</span></h2>
<h4>syntax: (sym <em>string</em> [<em>sym-context</em> [<em>nil-flag</em>]])<br/>
syntax: (sym <em>number</em> [<em>sym-context</em> [<em>nil-flag</em>]])<br/>
syntax: (sym <em>symbol</em> [<em>sym-context</em> [<em>nil-flag</em>]])</h4>

<p>
	Translates the first argument in <em>string</em>, 
	<em>number</em>, or <em>symbol</em> 
	into a symbol and returns it.
	If the optional context is not specified 
	in <em>sym-context</em>, 
	the current context is used 
	when doing symbol lookup or creation.
	Symbols will be created 
	if they do not already exist.
	When the context does not exist
	and the context is specified by a quoted symbol, 
	the symbol also gets created.
	If the context specification is unquoted, 
	the context is the specified name 
	or the context specification is a variable 
	containing the context.
</p>

<p>
	<tt>sym</tt> can create symbols within the symbol table
	that are not legal symbols in newLISP source code
	(e.g., numbers or names containing special characters
	such as parentheses, colons, etc.).
	This makes <tt>sym</tt> usable 
	as a function for associative memory access, 
	much like <em>hash table</em> access 
	in other scripting languages. 
</p>

<p>
	As a third optional argument,
	<tt>nil</tt> can be specified 
	to suppress symbol creation 
	if the symbol is not found.
	In this case,
	<tt>sym</tt> returns <tt>nil</tt> 
	if the symbol looked up does not exist.
	Using this last form,
	<tt>sym</tt> can be used 
	to check for the existence 
	of a symbol.
</p>

<!-- example -->

<pre>
(sym "some")           <span class='arw'>&rarr;</span> some
(set (sym "var") 345)  <span class='arw'>&rarr;</span> 345
var                    <span class='arw'>&rarr;</span> 345
(sym "aSym" 'MyCTX)    <span class='arw'>&rarr;</span> MyCTX:aSym
(sym "aSym" MyCTX)     <span class='arw'>&rarr;</span> MyCTX:aSym  ; unquoted context

(sym "foo" MyCTX nil)  <span class='arw'>&rarr;</span> nil  ; 'foo does not exist
(sym "foo" MyCTX)      <span class='arw'>&rarr;</span> foo  ; 'foo is created
(sym "foo" MyCTX nil)  <span class='arw'>&rarr;</span> foo  ; foo now exists
</pre>


<p>
	Because the function <tt>sym</tt> 
	returns the symbol looked up or created,
	expressions with <tt>sym</tt> can be embedded 
	directly in other expressions 
	that use symbols as arguments.
	The following example shows 
	the use of <tt>sym</tt> 
	as a hash-like function 
	for associative memory access, 
	as well as symbol configurations 
	that are not legal newLISP symbols:
</p>

<!-- example -->

<pre>
;; using sym for simulating hash tables

(set (sym "John Doe" 'MyDB) 1.234)
(set (sym "(" 'MyDB) "parenthesis open")
(set (sym 12 'MyDB) "twelve")

(eval (sym "John Doe" 'MyDB))  <span class='arw'>&rarr;</span> 1.234
(eval (sym "(" 'MyDB))         <span class='arw'>&rarr;</span> "parenthesis open"
(eval (sym 12 'MyDB))          <span class='arw'>&rarr;</span> "twelve"

;; delete a symbol from a symbol table or hash
(delete (sym "John Doe" 'MyDB))  <span class='arw'>&rarr;</span> true
</pre>


<p>
	The last statement shows 
	how a symbol can be eliminated 
	using <a href="#delete">delete</a>.
</p>

<p>
	The third syntax allows symbols to be used 
	instead of strings for the symbol name 
	in the target context.
	In this case,
	<tt>sym</tt> will extract the name from the symbol 
	and use it as the name string 
	for the symbol in the target context:
</p>

<!-- example -->

<pre>
(sym 'myVar 'FOO)  <span class='arw'>&rarr;</span> FOO:myVar

(define-macro (def-context)
  (dolist (s (rest (args)))
    (sym s (first (args)))))

(def-context foo x y z)

(symbols foo)  <span class='arw'>&rarr;</span> (foo:x foo:y foo:z)
</pre>


<p>The <tt>def-context</tt> macro shows how this could be used 
to create a macro that creates contexts and their variables 
in a dynamic fashion.</p>

<p> A syntax of the <a href="#context">context</a> function can also be used to 
create, set and evaluate symbols.
</p>

<br/><br/>

<a name="symbolp"></a>
<h2><span class="function">symbol?</span></h2>
<h4>syntax: (symbol? <em>exp</em>)</h4>

<p>
	Evaluates the <em>exp</em> expression 
	and returns <tt>true</tt> if the value is a symbol;
	otherwise, it returns <tt>nil</tt>.
</p>

<!-- example -->

<pre>
(set 'x 'y)  <span class='arw'>&rarr;</span> y

(symbol? x)  <span class='arw'>&rarr;</span> true 

(symbol? 123)  <span class='arw'>&rarr;</span> nil

(symbol? (first '(var x y z)))  <span class='arw'>&rarr;</span> true
</pre>


<p>
	The first statement sets the contents of <tt>x</tt> 
	to the symbol <tt>y</tt>.
	The second statement then checks the contents of <tt>x</tt>.
	The last example checks the first element of a list.
</p>

<br/><br/>

<a name="symbols"></a>
<h2><span class="function">symbols</span></h2>
<h4>syntax: (symbols [<em>context</em>])</h4>

<p>
	Returns a sorted list of all symbols 
	in the current context 
	when called without an argument.
	If a context symbol is specified, 
	symbols defined in that context are returned.
</p>

<!-- example -->

<pre>
(symbols)       ; list of all symbols in current context
(symbols 'CTX)  ; list of symbols in context CTX
(symbols CTX)   ; omitting the quote
(set 'ct CTX)   ; assigning context to a variable
(symbols ct)    ; list of symbols in context CTX
</pre>


<p>
	The quote can be omitted 
	because contexts evaluate to themselves.
</p>

<br/><br/>

<a name="sync"></a>
<h2><span class="function">sync</span></h2>
<h4>syntax: (sync <em>int-timeout</em> [<em>func-inlet</em>])<br/>
syntax: (sync)</h4>

<p>When <em>int-timeout</em> in milliseconds is specified, <tt>sync</tt> waits 
for child processes launched with <a href="#spawn">spawn</a> to finish. 
Whenever a child process finishes, <tt>sync</tt> assigns the evaluation result 
of the spawned subtask to the symbol specified in the spawn statement.
The <tt>sync</tt> returns <tt>true</tt> if all child processes have been processed 
or <tt>nil</tt> if the timeout value has been reached and more child processes
are pending.</p>

<p>If <tt>sync</tt> additionally is given with an optional user-defined <em>inlet</em> 
function in <em>func-inlet</em>, this function  will be called with the child process-id
as argument whenever a spawned child process returns. <em>func-inlet</em> can contain 
either a lambda expression or a symbol which defines a function.</p>

<p>Without any parameter, <tt>sync</tt> returns a list of pending child process
PIDs (process identifiers), for which results have not been processed yet.</p>

<p>The function <tt>sync</tt> is not available on MS Windows.</p>

<!-- example -->

<pre>
; wait for 10 seconds and process finished child processes
(sync 10000) 

; wait for the maximum time (~ 1193 hours)
(sync -1) 

(define (report pid)
    (println "process: " pid " has returned"))

; call the report function, when a child returns
(sync 10000 report) ; wait for 10 seconds max

; return a list of pending child processes
(sync)         <span class='arw'>&rarr;</span> (245 246 247 248)

; wait and do something else
(until (true? (sync 10 report) )
    (println (time-of-day)))

</pre>


<p>When <tt>sync</tt> is given with a timeout parameter, it will block
until timeout or until all child processes have returned, whichever
comes earlier. When no parameter is specified or a function is specified,
<tt>sync</tt> returns immediately.</p>


<p>The function <tt>sync</tt> is part of the Cilk API for synchronizing
child processes and process parallelization. See the reference for the
function <a href="#spawn">spawn</a> for a full discussion of the Cilk API.</p>

<br/><br/>


<a name="sys-error"></a>
<h2><span class="function">sys-error</span></h2>
<h4>syntax: (sys-error)<br/>
syntax: (sys-error <em>int-error</em>)<br/>
syntax: (sys-error <tt>0</tt>)</h4>

<p>Reports the last error generated by the underlying OS 
which newLISP is running on.  The error reported 
may differ on the platforms newLISP has been compiled for.
Consult the platform's C library information. The error is
reported as a list of error number and error text.</p>

<p>If no error has occurred or the system error number has
been reset, <tt>nil</tt> is returned.</p>

<p>When <em>int-error</em> is greater <tt>0</tt> (zero) a
list of the number and the error text is returned.</p>

<p>To reset the error specify <tt>0</tt> as the error number.</p>

<p>Whenever a function in newLISP within the system resources area
returns <tt>nil</tt>, <tt>sys-error</tt> can be checked 
for the underlying reason. For file operations, 
<tt>sys-error</tt> may be set for nonexistent files 
or wrong permissions when accessing the resource.
Another cause of error could be the exhaustion of certain system 
resources like file handles or semaphores.</p>

<!-- example -->

<pre>
;; trying to open a nonexistent file
(open "xyz" "r")  <span class='arw'>&rarr;</span> nil

(sys-error)       <span class='arw'>&rarr;</span> (2 "No such file or directory")

;; reset errno
(sys-error 0)     <span class='arw'>&rarr;</span> (0 "Unknown error: 0")
(sys-error)       <span class='arw'>&rarr;</span> nil
</pre>


<p>See also <a href="#last-error">last-error</a> and <a href="#net-error">net-error</a>.</p>

<br/><br/>

<a name="sys-info"></a>
<h2><span class="function">sys-info</span></h2>
<h4>syntax: (sys-info [<em>int-idx</em>])</h4>

<p>Calling <tt>sys-info</tt> without <em>int-idx</em> returns a list of internal 
resource statistics. Ten integers report the following status:</p>

<table width="98%" summary="sys-info offsets">
<tr align="left"><th>offset</th><th>description</th></tr>
<tr><td>0</td><td>Number of Lisp cells</td></tr>
<tr><td>1</td><td>Maximum number of Lisp cells constant</td></tr>
<tr><td>2</td><td>Number of symbols</td></tr>
<tr><td>3</td><td>Evaluation/recursion level</td></tr>
<tr><td>4</td><td>Environment stack level</td></tr>
<tr><td>5</td><td>Maximum call stack constant</td></tr>
<tr><td>6</td><td>Pid of the parent process or 0</td></tr>
<tr><td>7</td><td>Pid of running newLISP process</td></tr>
<tr><td>8</td><td>Version number as an integer constant</td></tr>
<tr><td>9</td><td>Operating system constant:<br/>
linux=1, bsd=2, osx=3, solaris=4,  windows=6, os/2=7, cygwin=8, tru64 unix=9, aix=10, android=11
<br/>
&nbsp;&nbsp;&nbsp;&nbsp;bit 11 will be set for ffilib (extended import/callback API) versions (add 1024)<br/>
&nbsp;&nbsp;&nbsp;&nbsp;bit 10 will be set for IPv6 versions (add 512)<br/>
&nbsp;&nbsp;&nbsp;&nbsp;bit 9 will be set for 64-bit (changeable at runtime) versions (add 256)<br/>
&nbsp;&nbsp;&nbsp;&nbsp;bit 8 will be set for UTF-8 versions (add 128)<br/>
&nbsp;&nbsp;&nbsp;&nbsp;bit 7 will be added for library versions (add 64)</td></tr>
</table><br/>

<p>The numbers from <tt>0</tt> to <tt>9</tt> indicate the optional offset 
in the returned list.</p>

<p>It is recommended to use offsets 0 to 5 to address
up and including "Maximum call stack constant" and to use
negative offsets -1 to -4 to access the last four
entries in the system info list. Future new entries will be inserted
after offset 5. This way older source code does not need to change.</p>

<p> When using <em>int-idx</em>, one element of the list will be returned.
</p>

<!-- example -->

<pre>
(sys-info)     <span class='arw'>&rarr;</span> (429 268435456 402 1 0 2048 0 19453 10406 1155)
(sys-info 3)   <span class='arw'>&rarr;</span> 1 
(sys-info -2)  <span class='arw'>&rarr;</span> 10406 ;; version 10.4.6
</pre>


<p>The number for the maximum of Lisp cells can be changed via the <tt>-m</tt> 
command-line switch. For each megabyte of Lisp cell memory, 
64k memory cells can be allocated. The maximum call stack depth 
can be changed using the <tt>-s</tt> command-line switch. </p>

<br/><br/>

<a name="t-test"></a>
<h2><span class="function">t-test</span></h2>
<h4>syntax: (t-test <em>list-vector</em> <em>number-value</em>)<br/>
syntax: (t-test <em>list-vector-A</em> <em>list-vector-B</em> [<tt>true</tt>])<br/>
syntax: (t-test <em>list-vector-A</em> <em>list-vector-B</em> <em>float-probability</em>)</h4>

<p>In the <b>first syntax</b> the function uses a one sample <em>Student's t</em> 
test to compare the mean value of <em>list-vector</em> to the value in 
<em>number-value</em>:</p>

<!-- example -->
<pre>
; one sample t-test
(t-test '(3 5 4 2 5 7 4 3) 2.5)
<span class='arw'>&rarr;</span> '(4.125 2.5 1.552 0.549 2.960 7 0.021)
</pre>

<p>The following data are returned in a list:</p>

<table>
<tr align="left"><th>name</th><th>description</th></tr>
<tr><td>mean</td><td>mean of data in vector</td></tr>
<tr><td>value</td><td>value to compare</td></tr>
<tr><td>sdev</td><td>standard deviation in data vector</td></tr>
<tr><td>mean-error</td><td>standard error of mean</td></tr>
<tr><td>t</td><td>t between mean and value</td></tr>
<tr><td>df</td><td>degrees of freedom</td></tr>
<tr><td>p</td><td>two tailed probability of t under the null hypothesis</td></tr>
</table>

<p>In above example the difference of the mean value <tt>4.125</tt> from <tt>2.5</tt> is
moderately significant. With a probability <tt>p = 0.021 (2.1%)</tt> the null hypothesis
that the mean is not significantly different, can be rejected.</p>

<p>In the <b>second syntax</b>, the function performs a t-test using the 
<em>Student's t</em> statistic for comparing the means values in <em>list-vector-A</em> 
and <em>list-vector-B</em>. If the <tt>true</tt> flag is not used, both vectors 
in A and B can be of different length and groups represented by A and B are 
not related.</p>

<p>When the optional flag is set to <tt>true</tt>, measurements were taken
from the same group twice, e.g. before and after a procedure.</p>

<p>The following results are returned in a list:</p>

<table>
<tr align="left"><th>name</th><th>description</th></tr>
<tr><td>mean-a</td><td>mean of group A</td></tr>
<tr><td>mean-b</td><td>mean of group B</td></tr>
<tr><td>sdev-a</td><td>standard deviation in group A</td></tr>
<tr><td>sdev-b</td><td>standard deviation in group B</td></tr>
<tr><td>t</td><td>t between mean values</td></tr>
<tr><td>df</td><td>degrees of freedom</td></tr>
<tr><td>p</td><td>two tailed probability of t under the null hypothesis</td></tr>
</table>

<p>The first example studies the effect of different sleep length
before a test on the SCAT (Sam's Cognitive Ability Test):</p>

<!-- example -->
<pre>
; SCAT (Sam's Cognitive Ability Test) 
; two independent sample t-test
(set 'hours-sleep-8 '(5 7 5 3 5 3 3 9))
(set 'hours-sleep-4 '(8 1 4 6 6 4 1 2))

(t-test hours-sleep-8 hours-sleep-4)
 <span class='arw'>&rarr;</span> (5 4 2.138 2.563 0.847 14 0.411)
</pre>

<p>The duration of sleeps before the SCAT does not have a significant
effect with a probability value of <tt>0.411</tt>.</p>

<p>In the second example, the same group of people get tested twice,
before and after a treatment with Prozac depression medication:</p>

<!-- example -->
<pre>
; Effect of an antidepressant on a group of depressed people
; two related samples t-test
(set 'mood-pre '(3 0 6 7 4 3 2 1 4))
(set 'mood-post '(5 1 5 7 10 9 7 11 8))

(t-test mood-pre mood-post true)
<span class='arw'>&rarr;</span> (3.333 7 2.236 3.041 -3.143 8 0.0137)
</pre>

<p>The effect of the antidepressant treatment is moderately significant with a 
<tt>p</tt> of <tt>0.0137</tt>.</p>

<p>In the <b>third syntax</b>, a form of the <em>Student's t</em> called <em>Welch's t-test</em>
is performed. This method is used when the variances observed in both
samples are significantly different. The threshold can be set using the 
<em>float-probability</em> parameter. When this parameter is used the <tt>t-test</tt>
function will perform a F-test to compare the variances in the two data samples.
If the probability of the found <em>F-ratio</em> is below the <em>float-probability</em> 
parameter, the <em>Welch's t-test</em> method will be used. Specifying this value
as <tt>1.0</tt> effectively forces a <em>Welch's t-test</em>:</p>

<!-- example -->
<pre>
; two independent sample t-test using the Welch method
(t-test '(10 4 7 1 1 6 1 8 2 4) '(4 6 9 4 6 8 9 3) 1.0)
<span class='arw'>&rarr;</span> (4.4 6.125 3.239 2.357 -1.307 15 0.211) 

; two independent sample t-test using the normal method
(t-test '(10 4 7 1 1 6 1 8 2 4) '(4 6 9 4 6 8 9 3))
<span class='arw'>&rarr;</span> (4.4 6.125 3.239 2.357 -1.260 16 0.226)
</pre>

<p>There is no significant difference between the means of the two samples.
The <em>Welch</em> method of the t-test is slightly more sensitive in this
case than using the normal t-test method.</p>

<p>Smaller values than <tt>1.0</tt> would trigger the <em>Welch's t-test</em>
method only when the significance of variance difference in the samples reaches
certain value.</p>

<br/><br/>

<a name="tan"></a>
<h2><span class="function">tan</span></h2>
<h4>syntax: (tan <em>num-radians</em>)</h4>

<p>
	Calculates the tangent function from <em>num-radians</em> 
	and returns the result.
</p>

<!-- example -->

<pre>
(tan 1)                     <span class='arw'>&rarr;</span> 1.557407725
(set 'pi (mul 2 (asin 1)))  <span class='arw'>&rarr;</span> 3.141592654
(tan (div pi 4))            <span class='arw'>&rarr;</span> 1
</pre>

<br/><br/>

<a name="tanh"></a>
<h2><span class="function">tanh</span></h2>
<h4>syntax: (tanh <em>num-radians</em>)</h4>

<p>Calculates the hyperbolic tangent of <em>num-radians</em>. 
The hyperbolic tangent is defined mathematically as: <em>sinh (x) / cosh (x)</em>.
</p>

<!-- example -->

<pre>
(tanh 1)     <span class='arw'>&rarr;</span> 0.761594156
(tanh 10)    <span class='arw'>&rarr;</span> 0.9999999959
(tanh 1000)  <span class='arw'>&rarr;</span> 1
(= (tanh 1) (div (sinh 1) (cosh 1)))  <span class='arw'>&rarr;</span> true
</pre>

<br/><br/>

<a name="term"></a>
<h2><span class="function">term</span></h2>
<h4>syntax: (term <em>symbol</em>)</h4>

<p>Returns as a string, the term part of a <em>symbol</em> without the context prefix.</p>

<!-- example -->

<pre>
(set 'ACTX:var 123)
(set 'sm 'ACTX:var)
(string sm)     <span class='arw'>&rarr;</span> "ACTX:var"
(term sm)      <span class='arw'>&rarr;</span> "var"

(set 's 'foo:bar)
(= s (sym (term s) (prefix s)))
</pre>

<p>See also <a href="#prefix">prefix</a> to extract the namespace or
context prefix from a symbol.</p>

<br/><br/>

<a name="throw"></a>
<h2><span class="function">throw</span></h2>
<h4>syntax: (throw <em>exp</em>)</h4>

<p>
	Works together with 
	the <a href="#catch">catch</a> function.
	<tt>throw</tt> forces the return of a previous <tt>catch</tt> statement 
	and puts the <em>exp</em> into the result symbol of <tt>catch</tt>.
</p>


<!-- example -->

<pre>
(define (throw-test)
    (dotimes (x 1000) 
        (if (= x 500) (throw "interrupted"))))

(catch (throw-test) 'result)  <span class='arw'>&rarr;</span> true

result  <span class='arw'>&rarr;</span> "interrupted"

(catch (throw-test))  <span class='arw'>&rarr;</span> "interrupted"
</pre>


<p>
	The last example shows a shorter form of <a href="#catch">catch</a>,
	which returns the <tt>throw</tt> result directly.
</p>

<p>
	<tt>throw</tt> is useful for breaking out of a loop 
	or for early return from user-defined functions 
	or expression blocks.
	In the following example,
	the <tt>begin</tt> block will return <tt>X</tt> 
	if <tt>(foo X)</tt> is <tt>true</tt>; 
	else <tt>Y</tt> will be returned:
</p>


<pre>
(catch (begin
    &hellip;
    (if (foo X) (throw X) Y)
    &hellip;
))
</pre>


<p>
	<tt>throw</tt> will <em>not</em> cause an error exception.
	Use <a href="#throw-error">throw-error</a>
	to throw user error exceptions.
</p> 

<br/><br/>

<a name="throw-error"></a>
<h2><span class="function">throw-error</span></h2>
<h4>syntax: (throw-error <em>exp</em>)</h4>

<p>
	Causes a user-defined error exception 
	with text provided by evaluating <em>exp</em>.
</p>

<!-- example -->

<pre>
(define (foo x y)
    (if (= x 0) (throw-error "first argument cannot be 0"))
    (+ x y))

(foo 1 2)  <span class='arw'>&rarr;</span> 3

(foo 0 2)  ; causes a user error exception
<span class='err'>ERR: user error : first argument cannot be 0
called from user-defined function foo</span>
</pre>


<p>
	The user error can be handled 
	like any other error exception 
	using user-defined error handlers 
	and the <a href="#error-event">error-event</a> function, 
	or the form of <a href="#catch">catch</a> 
	that can capture error exceptions.
</p>

<br/><br/>

<a name="time"></a>
<h2><span class="function">time</span></h2>
<h4>syntax: (time <em>exp</em> [<em>int-count</em>)</h4>

<p>Evaluates the expression in <em>exp</em> and returns the time spent 
on evaluation in floating point milliseconds. Depending on the platform
decimals of milliseconds are shown or not shown.</p>

<!-- example -->

<pre>
(time (myprog x y z))  <span class='arw'>&rarr;</span> 450.340

(time (myprog x y z) 10)  <span class='arw'>&rarr;</span> 4420.021
</pre>


<p>In first the example, 450 milliseconds elapsed 
while evaluating <tt>(myprog x y z)</tt>.  The second example 
returns the time for ten evaluations of  <tt>(myprog x y z)</tt>.
See also <a href="#date">date</a>,
<a href="#date-value">date-value</a>,
<a href="#time-of-day">time-of-day</a>, 
and <a href="#now">now</a>.</p>

<br/><br/>

<a name="time-of-day"></a>
<h2><span class="function">time-of-day</span></h2>

<h4>syntax: (time-of-day)</h4>

<p>Returns the time in milliseconds since the start of the current day. 
</p>

<p>See also the <a href="#date">date</a>,
<a href="#date-value">date-value</a>,
<a href="#time">time</a>, 
and <a href="#now">now</a> functions.</p>

<br/><br/>

<a name="timer"></a>
<h2><span class="function">timer</span></h2>
<h4>syntax: (timer <em>sym-event-handler | func-event-handler</em> <em>num-seconds</em> [<em>int-option</em>])<br/>
syntax: (timer <em>sym-event-handler | func-event-handler</em>)<br/>
syntax: (timer)</h4>

<p>Starts a one-shot timer firing off the Unix signal <tt>SIGALRM</tt>, <tt>SIGVTALRM</tt>, 
or <tt>SIGPROF</tt> after the time in seconds (specified in <em>num-seconds</em>) 
has elapsed. When the timer fires, it calls the user-defined function 
in <em>sym-</em> or <em>func-event-handler</em>.
</p>

<p>On Linux/Unix, an optional <tt>0</tt>, <tt>1</tt>, or <tt>2</tt> can 
be specified to control how the timer counts.  With default option 
<tt>0</tt>, real time is measured.  Option <tt>1</tt> measures the time 
the CPU spends processing in the process owning the timer.
Option <tt>2</tt> is a combination of both called <em>profiling time</em>.
See the Unix man page <tt>setitimer()</tt> for details.
</p>

<p>The event handler can start the timer again to achieve a 
continuous flow of events.  Starting with version 8.5.9,
seconds can be defined as floating point numbers with a fractional 
part (e.g., <tt>0.25</tt> for 250 milliseconds).</p>

<p>Defining <tt>0</tt> (zero) as time shuts the running timer down 
and prevents it from firing.</p>

<p>
When called with <em>sym-</em> or <em>func-event-handler</em>, 
<tt>timer</tt> returns the elapsed time of the timer in progress.
This can be used to program time lines or schedules.</p>

<p>
<tt>timer</tt> called without arguments returns the symbol of the current 
event handler.</p> 


<!-- example -->

<pre>
(define (ticker) 
    (println (date)) (timer 'ticker 1.0))

&gt; (ticker)
<b>Tue Apr 12 20:44:48 2005</b>	; first execution of ticker
<span class='arw'>&rarr;</span> ticker			      ; return value from ticker

&gt; <b>Tue Apr 12 20:44:49 2005</b>	; first timer event
<b>Tue Apr 12 20:44:50 2005</b>	; second timer event ...
<b>Tue Apr 12 20:44:51 2005
Tue Apr 12 20:44:52 2005</b>
</pre>


<p>
	The example shows an event handler, <tt>ticker</tt>,
	which starts the timer again after each event.
</p>

<p>
	Note that a timer cannot interrupt an 
	ongoing built-in function.
	The timer interrupt gets registered by newLISP,
	but a timer handler cannot run 
	until one expression is evaluated 
	and the next one starts.
	To interrupt an ongoing I/O operation with <tt>timer</tt>,
	use the following pattern, 
	which calls <a href="#net-select">net-select</a> 
	to test if a socket is ready for reading:
</p>

<!-- example -->

<pre>
define (interrupt)
    (set 'timeout true))
        
(set 'listen (net-listen 30001))
(set 'socket (net-accept listen))
        
(timer 'interrupt 10)
;; or specifying the function directly
(timer (fn () (set 'timeout true)) 10)
        
(until (or timeout done)
    (if (net-select socket "read" 100000)
        (begin
            (net-receive socket buffer 1024)
            (set 'done true)))
)
                                                                                
(if timeout
    (println "timeout")
    (println buffer))
                                                                              
(exit)
</pre>


<p>
	In this example,
	the <tt>until</tt> loop will run 
	until something can be read from <tt>socket</tt>, 
	or until ten seconds have passed 
	and the <tt>timeout</tt> variable is set.
</p>

<br/><br/>

<a name="title-case"></a>
<h2><span class="function">title-case</span>&nbsp;<font size="-1"><a href="#utf8_capable">utf8</a></font></h2>
<h4>syntax: (title-case <em>str</em> <em>[bool]</em>)</h4>

<p>
	Returns a copy of the string in <em>str</em> 
	with the first character converted to uppercase.
	When the optional <em>bool</em> parameter 
	evaluates to any value other than <tt>nil</tt>,
	the rest of the string is converted to lowercase.
</p>

<!-- example -->

<pre>
(title-case "hello")       <span class='arw'>&rarr;</span> "Hello"
(title-case "hELLO" true)  <span class='arw'>&rarr;</span> "Hello"
(title-case "hELLO")       <span class='arw'>&rarr;</span> "HELLO"
</pre>


<p>
	See also the <a href="#lower-case">lower-case</a> 
	and <a href="#upper-case">upper-case</a> functions.
</p>

<br/><br/>

<a name="trace"></a>
<h2><span class="function">trace</span></h2>

<h4>syntax: (trace <em>int-device</em>)<br/>
syntax: (trace <em>true</em>)<br/>
syntax: (trace <em>nil</em>)<br/>
syntax: (trace)</h4>

<p>In the first syntax the parameter is an integer of a device like an opened file.
Output is continuously written to that device. If <em>int-device</em> is 
<tt>1</tt> output is written to <i>stdout</i>. </p> 

<pre>
; write all entries and exits from expressions to trace.txt
(trace (open "trace.txt")) 

; write all entries and exits from expressions to trace.txt
(foo x y)                  
(bar x)              
      
; close the trace.txt file
(trace nil)
</pre>

<p>In the second syntax debugger mode is switched on when the 
parameter evaluates true. When in debugging mode newLISP will stop
after each entry and exit from an expression and wait for user input.
Highlighting is done by bracketing the expression between two # 
(number sign) characters.  This can be changed to a different character 
using <a href="#trace-highlight">trace-highlight</a>.:</p>

<pre>
[-&gt; 2] s|tep n|ext c|ont q|uit &gt;
</pre>

<p>
At the prompt, an <tt>s</tt>, <tt>n</tt>, <tt>c</tt>, 
or <tt>q</tt> can be entered to step into or 
merely execute the next expression.  Any expression can be entered 
at the prompt for evaluation.  Entering the name of a variable,
for example, would evaluate to its contents.
In this way, a variable's contents can be checked during debugging
or set to different values.
</p>

<!-- example -->

<pre>
;; switches newLISP into debugging mode
(trace true)  <span class='arw'>&rarr;</span> true 

;; the debugger will show each step
(my-func a b c)

;; switched newLISP out of debugging mode
(trace nil)  <span class='arw'>&rarr;</span> nil 
</pre>

<p>To set break points where newLISP should interrupt 
normal execution and go into debugging mode,
put <tt>(trace true)</tt> statements into the newLISP 
code where execution should switch on the debugger.</p>

<p>Use the <a href="#debug">debug</a> function as a shortcut 
for the above example:</p>

<pre>
(debug (my-func a b c))
</pre>


<p>In the third syntax <tt>(trace nil)</tt> closes debugger mode or 
the trace file opened.</p>

<p>In the last syntax <tt>(trace)</tt> returns the current mode.</p>

<br/><br/>

<a name="trace-highlight"></a>
<h2><span class="function">trace-highlight</span></h2>
<h4>syntax: (trace-highlight <em>str-pre</em> <em>str-post</em> [<em>str-header</em> <em>str-footer</em>])</h4>

<p>Sets the characters or string of characters used to enclose expressions 
during <a href="#trace">trace</a>.  By default, 
the # (number sign) is used to enclose the expression highlighted 
in <a href="#trace">trace</a> mode.  This can be changed to different characters 
or strings of up to seven characters.  If the console window accepts terminal 
control characters, this can be used to display the expression in a different 
color, bold, reverse, and so forth.</p>

<p>Two more strings can optionally be specified for <em>str-header and str-footer</em>,
which control the separator and prompt. A maximum of 15 characters is allowed 
for the header and 31 for the footer.</p>

<!-- example -->

<pre>
;; active expressions are enclosed in &gt;&gt; and &lt;&lt;

(trace-highlight "&gt;&gt;" "&lt;&lt;") 
             
;; 'bright' color on a VT100 or similar terminal window

(trace-highlight "\027[1m" "\027[0m")   
</pre>


<p>
The first example replaces the default <tt>#</tt> (number sign) 
with a <tt>&gt;&gt;</tt> and <tt>&lt;&lt;</tt>. The second example works 
on most Linux shells.  It may not, however, work in console windows 
under MS Windows or CYGWIN, depending on the configuration of the terminal.</p>

<br/><br/>

<a name="transpose"></a>
<h2><span class="function">transpose</span></h2>
<h4>syntax: (transpose <em>matrix</em>)</h4>

<p>Transposes a <em>matrix</em> by reversing the rows and columns.
Any kind of list-matrix can be transposed. Matrices are made rectangular 
by filling in <tt>nil</tt> for missing elements, omitting elements where 
appropriate, or expanding atoms in rows into lists.
Matrix dimensions are calculated using the number of rows in the original 
matrix for columns and the number of elements in the first row 
as number of rows for the transposed matrix.</p>

<p>The matrix to transpose can contain any data-type.</p>

<p>The dimensions of a matrix are defined by the number of rows 
and the number of elements in the first row.  A matrix can either be a 
nested list or an <a href="#array">array</a>.</p>

<!-- example -->

<pre>
(set 'A '((1 2 3) (4 5 6)))
(transpose A)                      <span class='arw'>&rarr;</span> ((1 4) (2 5) (3 6))
(transpose (list (sequence 1 5)))  <span class='arw'>&rarr;</span> ((1) (2) (3) (4) (5))

; any data type is allowed in the matrix
(transpose '((a b) (c d) (e f)))   <span class='arw'>&rarr;</span> ((a c e) (b d f))

; arrays can be transposed too
(set 'A (array 2 3 (sequence 1 6)))
(set 'M (transpose A)) 
M <span class='arw'>&rarr;</span> ((1 4) (2 5) (3 6))
</pre>


<p>The number of columns in a matrix is defined by the number of elements 
in the first row of the matrix.  If other rows have fewer elements, 
<tt>transpose</tt> will assume <tt>nil</tt> for those missing elements.
Superfluous elements in a row will be ignored.</p>


<pre>
(set 'A '((1 2 3) (4 5) (7 8 9)))

(transpose A)  <span class='arw'>&rarr;</span> ((1 4 7) (2 5 8) (3 nil 9))
</pre>


<p>If a row is any other data type besides a list,
the transposition treats it like an entire row of elements 
of that data type:</p>


<pre>
(set 'A '((1 2 3) X (7 8 9)))

(transpose A)  <span class='arw'>&rarr;</span> ((1 X 7) (2 X 8) (3 X 9))
</pre>


<p>All operations shown here on lists can also be performed on arrays.
</p>

<p>
	See also the matrix operations 
	<a href="#det">det</a>, <a href="#invert">invert</a>,
    <a href="#mat">mat</a> and <a href="#multiply">multiply</a>.
</p>

<br/><br/>

<a name="trim"></a>
<h2><span class="function">trim</span>&nbsp;<font size="-1"><a href="#utf8_capable">utf8</a></font></h2>
<h4>syntax: (trim <em>str</em>)<br/>
syntax: (trim <em>str</em> <em>str-char</em>)<br/>
syntax: (trim <em>str</em> <em>str-left-char</em> <em>str-right-char</em>)</h4>

<p>Using the first syntax, all white-space characters are trimmed from both
sides of <em>str</em>.</p>

<p>The second syntax trims the string <em>str</em> from both sides, 
stripping the leading and trailing characters as given 
in <em>str-char</em>. If <em>str-char</em> contains no character,
the space character is assumed. <tt>trim</tt> returns the new string.
</p>

<p>The third syntax can either trim different characters from both sides 
or trim only one side if an empty string is specified 
for the other.  </p>

<!-- example -->

<pre>
(trim "   hello \n ")            <span class='arw'>&rarr;</span> "hello"
(trim "   h e l l o   ")         <span class='arw'>&rarr;</span> "h e l l o")
(trim "----hello-----" "-")      <span class='arw'>&rarr;</span> "hello"
(trim "00012340" "0" "")         <span class='arw'>&rarr;</span> "12340"
(trim "1234000" "" "0")          <span class='arw'>&rarr;</span> "1234"
(trim "----hello=====" "-" "=")  <span class='arw'>&rarr;</span> "hello"
</pre>

<p>For more complex cases <a href="#replace">replace</a> can be used. When
possible, the much faster <tt>trim</tt> is preferred.</p>

<br/><br/>

<a name="truep"></a>
<h2><span class="function">true?</span></h2>
<h4>syntax: (true? <em>exp</em>)</h4>

<p>If the expression in <em>exp</em> 
evaluates to anything other than <tt>nil</tt>
or the empty list <tt>()</tt>, 
<tt>true?</tt> returns <tt>true</tt>; 
otherwise, it returns <tt>nil</tt>.</p>

<!-- example -->

<pre>
(map true? '(x 1 "hi" (a b c) nil ()))
<span class='arw'>&rarr;</span> (true true true true nil nil)
(true? nil)  <span class='arw'>&rarr;</span> nil
(true? '())  <span class='arw'>&rarr;</span> nil
</pre>


<p><tt>true?</tt> behaves like <a href="#if">if</a>
and rejects the empty list <tt>()</tt>.</p>

<br/><br/> 


<a name="unicode"></a>
<h2><span class="function">unicode</span></h2>

<h4>syntax: (unicode <em>str-utf8</em>)</h4>

<p>Converts ASCII/UTF-8 character strings in <em>str</em> 
to UCS-4&ndash;encoded Unicode of 4-byte integers per character.
The string is terminated with a 4-byte integer <tt>0</tt>.
This function is only available on UTF-8&ndash;enabled versions 
of newLISP.</p>

<!-- example -->

<pre>
(unicode "new") 
<span class='arw'>&rarr;</span> "n\000\000\000e\000\000\000w\000\000\000\000\000\000\000"

(utf8 (unicode "new"))  <span class='arw'>&rarr;</span> "new"
</pre>


<p>On <em>big endian</em> CPU architectures, the byte order will 
be reversed from high to low. The <tt>unicode</tt> and 
<a href="#utf8">utf8</a> functions are the inverse of each other.
These functions are only necessary if UCS-4 Unicode is in use.
Most systems use UTF-8 encoding only.</p>

<br/><br/>

<a name="unify"></a>
<h2><span class="function">unify</span></h2>
<h4>syntax: (unify <em>exp-1</em> <em>exp-2</em> [<em>list-env</em>])</h4>

<p>Evaluates and matches <em>exp-1</em> and <em>exp-2</em>.
Expressions match if they are equal or if one of the expressions is 
an unbound variable (which would then be bound to the other expression).
If expressions are lists, they are matched by comparing subexpressions.
Unbound variables start with an uppercase character 
to distinguish them from symbols.  <tt>unify</tt> returns <tt>nil</tt> 
when the unification process fails,
or it returns a list of variable associations on success.
When no variables were bound, but the match is still successful,
<tt>unify</tt> returns an empty list.
newLISP uses a modified <em>J. Alan Robinson</em> unification algorithm
with correctly applied <em>occurs check</em>. 
See also <em>Peter Norvig</em>'s paper about a common 
<a href="http://norvig.com/unify-bug.pdf">unification algorithm bug</a>, which 
is not present in this implementation.
</p>

<p>Since version 10.4.0 the underscore symbol <tt>_</tt> (ASCII 95) matches any atom,
list or unbound variable and never binds.</p>

<p>
    Like <a href="#match">match</a>, <tt>unify</tt> is frequently 
    employed as a parameter functor in <a href="#find">find</a>,
    <a href="#ref">ref</a>,  <a href="#ref-all">ref-all</a> and 
    <a href="#replace">replace</a>.
</p>


<!-- example -->

<pre>
(unify 'A 'A)  <span class='arw'>&rarr;</span> ()  ; tautology

(unify 'A 123)  <span class='arw'>&rarr;</span> ((A 123))  ; A bound to 123

(unify '(A B) '(x y))  <span class='arw'>&rarr;</span> ((A x) (B y))  ; A bound to x, B bound to y

(unify '(A B) '(B abc))  <span class='arw'>&rarr;</span> ((A abc) (B abc))  ; B is alias for A

(unify 'abc 'xyz)  <span class='arw'>&rarr;</span> nil  ; fails because symbols are different

(unify '(A A) '(123 456))  <span class='arw'>&rarr;</span> nil  ; fails because A cannot be bound to different values

(unify '(f A) '(f B))  <span class='arw'>&rarr;</span> ((A B))  ; A and B are aliases

(unify '(f A) '(g B))  <span class='arw'>&rarr;</span> nil  ; fails because heads of terms are different

(unify '(f A) '(f A B))  <span class='arw'>&rarr;</span> nil  ; fails because terms are of different arity

(unify '(f (g A)) '(f B))  <span class='arw'>&rarr;</span> ((B (g A)))  ; B bound to (g A)

(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

(unify '(f A) 'A)  <span class='arw'>&rarr;</span> nil  ; fails because of infinite unification (f(f(f &hellip;)))

(unify '(A xyz A) '(abc X X))  <span class='arw'>&rarr;</span>  nil ; indirect alias A to X doesn't match bound terms

(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

(unify '(q (p X Y) (p Y X)) '(q Z Z))  <span class='arw'>&rarr;</span> ((Y X) (Z (p X X)))  ; indirect alias

(unify '(A b _) '(x G z)) <span class='arw'>&rarr;</span> ((A x) (G b)) ; _ matches atom z 

(unify '(A b c _) '(x G _ z)) <span class='arw'>&rarr;</span> ((A x) (G b)) ; _ never binds, matches c and z

(unify '(A b _) '(x G (x y z))) <span class='arw'>&rarr;</span> ((A x) (G b)) ; _ matches list (x y z)

;; some examples taken from <a href="http://en.wikipedia.org/wiki/Unification_(computer_science)">http://en.wikipedia.org/wiki/Unification_(computer_science)</a>
</pre>


<p>
	<tt>unify</tt> can take an optional binding 
	or association list in <em>list-env</em>.
	This is useful when chaining <tt>unify</tt> expressions 
	and the results of previous <tt>unify</tt> bindings 
	must be included:
</p>

<!-- example -->

<pre>
(unify '(f X) '(f 123))  <span class='arw'>&rarr;</span> ((X 123))

(unify '(A B) '(X A) '((X 123)))
<span class='arw'>&rarr;</span> ((X 123) (A 123) (B 123))
</pre>


<p>
	In the previous example,
	<tt>X</tt> was bound to <tt>123</tt> earlier 
	and is included in the second statement 
	to pre-bind <tt>X</tt>.
</p> 


<h3>Use <tt>unify</tt> with <tt>expand</tt></h3>

<p>
	Note that variables are not actually bound 
	as a newLISP assignment. Rather,
	an association list is returned 
	showing the logical binding.
	A special syntax of <a href="#expand">expand</a> 
	can be used to actually replace bound variables 
	with their terms:
</p>


<pre>
(set 'bindings (unify '(f (g A) A) '(f B xyz)))
<span class='arw'>&rarr;</span> ((B (g xyz)) (A xyz))

(expand '(f (g A) A) bindings)  <span class='arw'>&rarr;</span> (f (g xyz) xyz)

; or in one statement
(expand '(f (g A) A) (unify '(f (g A) A) '(f B xyz)))
<span class='arw'>&rarr;</span> (f (g xyz) xyz)
</pre>

 
<h3>Use <tt>unify</tt> with <tt>bind</tt> for de-structuring</h3>

<p>The function <a href="#bind">bind</a> can be used to set unified
variables:</p>

<pre>
(bind (unify '(f (g A) A) '(f B xyz)))

A <span class='arw'>&rarr;</span> xyz 
B <span class='arw'>&rarr;</span> (g xyz)
</pre>

<p>This can be used for de-structuring:</p>

<pre>
(set 'structure '((one "two") 3 (four (x y z))))
(set 'pattern '((A B) C (D E)))
(bind (unify pattern structure))

A <span class='arw'>&rarr;</span> one
B <span class='arw'>&rarr;</span> "two"
C <span class='arw'>&rarr;</span> 3
D <span class='arw'>&rarr;</span> four
E <span class='arw'>&rarr;</span> (x y z)
</pre>

<p><tt>unify</tt> returns an association list and <tt>bind</tt> binds the associations.</p>

<h3>Model propositional logic with <tt>unify</tt></h3>

<p>
	The following example shows how propositional logic 
	can be modeled using <tt>unify</tt> 
	and <a href="#expand">expand</a>:
</p>


<pre>
; if somebody is human, he is mortal -&gt; (X human) :- (X mortal)
; socrates is human -&gt; (socrates human)
; is socrates mortal? -&gt; ?  (socrates mortal)

(expand '(X mortal) 
         (unify '(X human) '(socrates human))) 
<span class='arw'>&rarr;</span> (socrates mortal)
</pre>


<p>
	The following is a more complex example 
	showing a small, working PROLOG (Programming in Logic) 
	implementation.
</p>


<pre>
;; a small PROLOG implementation

(set 'facts '(
    (socrates philosopher)
    (socrates greek)
    (socrates human)
    (einstein german)
    (einstein (studied physics))
    (einstein human)
))

(set 'rules '(
    ((X mortal) &lt;- (X human))
    ((X (knows physics)) &lt;- (X physicist))
    ((X physicist) &lt;- (X (studied physics)))
))


(define (query trm)
    (or  (when (find trm facts) true) (catch (prove-rule trm))))

(define (prove-rule trm)
    (dolist (r rules)
        (when (list? (set 'e (unify trm (first r))))
            (when (query (expand (last r) e))
                (throw true))))
    nil
)

; try it

&gt; (query '(socrates human))
<b>true</b>
&gt; (query '(socrates (knows physics)))
<b>nil</b>
&gt; (query '(einstein (knows physics)))
<b>true</b>
</pre>


<p>
	The program handles a database of <tt>facts</tt> 
	and a database of simple 
	<em>A is a fact if B is a fact</em> <tt>rules</tt>.
	A fact is proven true 
	if it either can be found in the <tt>facts</tt> database 
	or if it can be proven using a rule.
	Rules can be nested:
	for example, to prove that somebody <tt>(knows physics)</tt>, 
	it must be proved true that somebody is a <tt>physicist</tt>.
	But somebody is only a physicist 
	if that person <tt>studied physics</tt>.
	The <tt>&lt;-</tt> symbol 
	separating the left and right terms of the rules 
	is not required 
	and is only added to make the rules database 
	more readable.
</p>

<p>
	This implementation does not handle multiple terms 
	in the right premise part of the rules,
	but it does handle backtracking of the <tt>rules</tt> database 
	to try out different matches.
	It does not handle backtracking 
	in multiple premises of the rule.
	For example,
	if in the following rule <tt>A if B and C and D</tt>, 
	the premises <tt>B</tt> and <tt>C</tt> succeed 
	and <tt>D</tt> fails,
	a backtracking mechanism might need to go back 
	and reunify the <tt>B</tt> or <tt>A</tt> terms 
	with different facts or rules 
	to make <tt>D</tt> succeed.
</p>

<p>
	The above algorithm could be written differently 
	by omitting <a href="#expand">expand</a> 
	from the definition of <tt>prove-rule</tt>
	and by passing the environment, <tt>e</tt>,
	as an argument to the <tt>unify</tt> and <tt>query</tt> functions.
</p>

<p>
	A <em>learning</em> of proven facts 
	can be implemented by appending them 
	to the <tt>facts</tt> database 
	once they are proven.
	This would speed up subsequent queries.
</p>

<p>
	Larger PROLOG implementations 
	also allow the evaluation of terms in rules. 
	This makes it possible to implement functions
	for doing other work 
	while processing rule terms.
	<tt>prove-rule</tt> could accomplish this testing 
	for the symbol <tt>eval</tt> in each rule term.
</p>

<br/><br/>

<a name="union"></a>
<h2><span class="function">union</span></h2>
<h4>syntax: (union <em>list-1</em> <em>list-2</em> [<em>list-3</em> ... ])</h4>

<p><tt>union</tt> returns a unique collection list of distinct elements found in two 
or more lists.</p>

<pre>
(union '(1 3 1 4 4 3) '(2 1 5 6 4))  <span class='arw'>&rarr;</span>  (1 3 4 2 5 6)
</pre>

<p>Like the other set functions <a href="#difference">difference</a>, 
<a href="#intersect">intersect</a> and <a href="#unique">unique</a>,
<tt>union</tt> maintains the order of elements as found in the original
lists.</p>

<br/><br/>

<a name="unique"></a>
<h2><span class="function">unique</span></h2>
<h4>syntax: (unique <em>list</em>)</h4>

<p>
	Returns a unique version of <em>list</em> 
	with all duplicates removed.
</p>

<!-- example -->

<pre>
(unique '(2 3 4 4 6 7 8 7))  <span class='arw'>&rarr;</span> (2 3 4 6 7 8)
</pre>


<p>
	Note that the list does not need to be sorted,
	but a sorted list makes <tt>unique</tt> perform faster.
</p>

<p>
	Other <em>set</em> functions are <a href="#difference">difference</a>,
	<a href="#intersect">intersect</a> and <a href="#union">union</a>.
</p>

<br/><br/>

<a name="unless"></a>
<h2><span class="function">unless</span></h2>
<h4>syntax: (unless <em>exp-condition</em> <em>body</em>)</h4>

<p>The statements in <em>body</em> are only evaluated if <em>exp-condition</em>
evaluates to <tt>nil</tt> or the empty list <tt>()</tt>. The result
of the last expression in <em>body</em> is returned or the return value
of <em>exp-condition</em> if <em>body</em> was not executed.</p>

<p>Because <tt>unless</tt> does not have an <em>else</em> condition as in
<a href="#if">if</a>, <!-- or <a href="#if-not">if-not</a> -->the statements in <em>body</em> need 
not to be grouped with <a href="#begin">begin</a>:</p>

<pre>
(unless (starts-with (read-line) "quit")
	(process (current-line))
	...
	(finish)
)	
</pre>

<p>See also the function <a href="#when">when</a>.</p>

<br/><br/>

<a name="unpack"></a> 

<h2><span class="function">unpack</span>&nbsp;
<a href="#shared-lib"><font size="+2">&#x26A0;</font></a></h2> 

<h4>syntax: (unpack <em>str-format</em> <em>str-addr-packed</em>)<br/>
syntax: (unpack <em>str-format</em> <em>num-addr-packed</em>)<br/><br/>
syntax: (unpack <em>struct</em> <em>num-addr-packed</em>)<br/> 
syntax: (unpack <em>struct</em> <em>str-addr-packed</em>)</h4> 

<p>When the first parameter is a string, <tt>unpack</tt> unpacks a binary structure 
in <em>str-addr-packed</em> or pointed to by <em>num-addr-packed</em> into newLISP 
variables using the format in <em>str-format</em>. <tt>unpack</tt> is the reverse 
operation of <tt>pack</tt>.  Using <em>num-addr-packed</em> facilitates the unpacking 
of structures returned from imported, shared library functions.</p>

<p>If the number specified in <em>num-addr-packed</em> is not a valid memory 
address, a system bus error or segfault can occur and crash newLISP or leave 
it in an unstable state.</p>

<p>When the first parameter is the symbol of a <a href="#struct">struct</a> definition, 
<tt>unpack</tt> uses the format as specified in <em>struct</em>. 
While <tt>unpack</tt> with <em>str-format</em> literally unpacks as specified,
<tt>unpack</tt> with <em>struct</em> will skip structure aligning pad-bytes
depending on data type, order of elements and CPU architecture.
Refer to the description of the <a href="#struct">struct</a> function for more detail.</p>

<p>When unpacking structures containing <tt>NULL</tt> pointers, an error will be
thrown when <tt>unpack</tt> tries to convert the pointer to a string. If <tt>NULL</tt>
pointers are to be expected, <tt>void*</tt> should be used in the structure definition.</p>

<p>The following characters may define a format:</p>
 
<table width="98%" summary="format chracters in pack">

<tr align="left" valign="bottom"><th>format</th><th>description</th></tr>

<tr>
<td><tt>c </tt></td>
<td>a signed 8-bit number</td>
</tr>

<tr>
<td><tt>b </tt></td>
<td>an unsigned 8-bit number</td>
</tr>

<tr>
<td><tt>d </tt></td>
<td>a signed 16-bit short number</td>
</tr>

<tr>
<td><tt>u </tt></td>
<td>an unsigned 16-bit short number</td>
</tr>

<tr>
<td><tt>ld</tt></td>
<td>a signed 32-bit long number</td>
</tr>

<tr>
<td><tt>lu</tt></td>
<td>an unsigned 32-bit long number</td>
</tr>

<tr>
<td><tt>Ld</tt></td>
<td>a signed 64-bit long number</td>
</tr>

<tr>
<td><tt>Lu</tt></td>
<td>an unsigned 64-bit long number</td>
</tr>

<tr>
<td><tt>f </tt></td>
<td>a float in 32-bit representation</td>

</tr>

<tr>
<td><tt>lf</tt></td>
<td>a double float in 64-bit representation</td>
</tr>

<tr>
<td><tt>sn</tt></td>
<td>a string of <em>n</em> null padded ASCII characters</td>
</tr>

<tr>

<td><tt>nn</tt></td>
<td><em>n</em> null characters</td>
</tr>

<tr>
<td><tt>&gt;</tt></td>
<td>switches to big endian byte order</td>
</tr>

<tr>
<td><tt>&lt;</tt></td>
<td>switches to little endian byte order</td>
</tr>

</table><br/>

<br/>
<!-- example -->

<pre>
(pack "c c c" 65 66 67)  <span class='arw'>&rarr;</span> "ABC"
(unpack "c c c" "ABC")   <span class='arw'>&rarr;</span> (65 66 67)

(set 's (pack "c d u" 10 12345 56789))
(unpack "c d u" s)  <span class='arw'>&rarr;</span> (10 12345 56789)

(set 's (pack "s10 f" "result" 1.23))
(unpack "s10 f" s)  <span class='arw'>&rarr;</span> ("result\000\000\000\000" 1.230000019)

(set 's (pack "s3 lf" "result" 1.23))
(unpack "s3 f" s)  <span class='arw'>&rarr;</span> ("res" 1.23)

(set 's (pack "c n7 c" 11 22))
(unpack "c n7 c" s)  <span class='arw'>&rarr;</span> (11 22))
</pre>


<p>
	The <tt>&gt;</tt> and <tt>&lt;</tt> specifiers 
	can be used to switch between 
	<em>little endian</em> and <em>big endian</em> byte order 
	when packing or unpacking:
</p>



<pre>
;; on a little endian system (e.g., Intel CPUs)
(set 'buff (pack "d" 1))  <span class='arw'>&rarr;</span> "\001\000" 

(unpack "d" buff)   <span class='arw'>&rarr;</span> (1)
(unpack "&gt;d" buff)  <span class='arw'>&rarr;</span> (256)
</pre>



<p>
	Switching the byte order 
	will affect all number formats 
	with 16-, 32-, or 64-bit sizes.
</p>


<p>
	The <tt>pack</tt> and <tt>unpack</tt> format 
	need not be the same,
	as in the following example:
</p>


<pre>
(set 's (pack "s3" "ABC"))
(unpack "c c c" s)  <span class='arw'>&rarr;</span> (65 66 67)
</pre>


<p>
	The examples show spaces between the format specifiers.
	Although not required, they can improve readability.
</p>

<p>
If the buffer's size at a memory address 
is smaller than the formatting string specifies, 
some formatting characters may be left unused.</p>

<p>
	See also the <a href="#address">address</a>,
	<a href="#get-int">get-int</a>,
	<a href="#get-long">get-long</a>,
	<a href="#get-char">get-char</a>,
	<a href="#get-string">get-string</a>, 
	and <a href="#pack">pack</a> functions.
</p>

<br/><br/>

<a name="until"></a>
<h2><span class="function">until</span></h2>
<h4>syntax: (until <em>exp-condition</em> [<em>body</em>])</h4>

<p> Evaluates the condition in <em>exp-condition</em>.
If the result is <tt>nil</tt> or the empty list <tt>()</tt>, 
the expressions in <em>body</em> are evaluated.
Evaluation is repeated until the exp-condition results in a value 
other than <tt>nil</tt> or the empty list.
The result of the last expression evaluated in <em>body</em>
is the return value of the <tt>until</tt> expression. If
<em>body</em> is empty, the result of last <em>exp-condition</em>
is returned. <tt>until</tt> works like 
(<a href="#while">while</a> (<a href="#not">not</a> &hellip;)).
</p>

<p><tt>until</tt> also updates the system iterator symbol <tt>$idx</tt>.</p>

<!-- example -->

<pre>
(device (open "somefile.txt" "read"))
(set 'line-count 0)
(until (not (read-line)) (inc line-count))
(close (device))
(print "the file has " line-count " lines\n")
</pre>


<p>
	Use the <a href="#do-until">do-until</a> function 
	to test the condition <em>after</em> evaluation 
	of the body expressions.
</p>

<br/><br/>

<a name="upper-case"></a>
<h2><span class="function">upper-case</span>&nbsp;<font size="-1"><a href="#utf8_capable">utf8</a></font></h2>
<h4>syntax: (upper-case <em>str</em>)</h4>

<p>Returns a copy of the string in <em>str</em> converted to uppercase.
International characters are converted correctly.</p>

<!-- example -->

<pre>
(upper-case "hello world")  <span class='arw'>&rarr;</span> "HELLO WORLD"
</pre>


<p>
	See also the <a href="#lower-case">lower-case</a> 
	and <a href="#title-case">title-case</a> functions.
</p>

<br/><br/>

<a name="utf8"></a>
<h2><span class="function">utf8</span></h2>
<h4>syntax: (utf8 <em>str-unicode</em>)</h4>

<p>Converts a UCS-4, 4-byte, Unicode-encoded string (<em>str</em>)
into UTF-8.  This function is only available on UTF-8&ndash;enabled 
versions of newLISP.</p>

<!-- example -->

<pre>
(unicode "new") 
<span class='arw'>&rarr;</span> "n\000\000\000e\000\000\000w\000\000\000\000\000\000\000"

(utf8 (unicode "new"))  <span class='arw'>&rarr;</span> "new"
</pre>


<p>The <tt>utf8</tt> function can also be used 
to test for the presence of UTF-8&ndash;enabled newLISP:</p>


<pre>
(if utf8 (do-utf8-version-of-code) (do-ascii-version-of-code))
</pre>


<p>
On <em>big endian</em> CPU architectures, the byte order will be reversed 
from highest to lowest. The <tt>utf8</tt> and <a href="#unicode">unicode</a> 
functions are the inverse of each other. These functions are only necessary 
if UCS-4 Unicode is in use. Most systems use UTF-8 Unicode encoding only.
</p>

<br/><br/>

<a name="utf8len"></a>
<h2><span class="function">utf8len</span></h2>
<h4>syntax: (utf8len <em>str</em>)</h4>

<p>Returns the number of characters in a UTF-8&ndash;encoded string. 
UTF-8 characters can be encoded in more than one 8-bit byte. 
<tt>utf8len</tt> returns the number of UTF-8 characters in a string. 
This function is only available on UTF-8&ndash;enabled versions of newLISP.</p>

<!-- example -->

<pre>
(utf8len "我能吞下玻璃而不伤身体。")    <span class='arw'>&rarr;</span> 12
(length "我能吞下玻璃而不伤身体。")      <span class='arw'>&rarr;</span> 36
</pre>


<p>See also the <a href="#unicode">unicode</a> and <a href="#utf8">utf8</a> functions.
Above Chinese text from <a href="http://www.columbia.edu/kermit/utf8.html">UTF-8 Sampler</a>.</p>

<br/><br/>

<a name="uuid"></a>
<h2><span class="function">uuid</span></h2>
<h4>syntax: (uuid [<em>str-node</em>])</h4>

<p>
	Constructs and returns
	a UUID (Universally Unique IDentifier).
	Without a node spec in <em>str-node</em>, 
	a type 4 UUID random generated byte number 
	is returned.
	When the optional <em>str-node</em> parameter is used, 
	a type 1 UUID is returned.
	The string in <em>str-node</em> 
	specifies a valid MAC (Media Access Code) 
	from a network adapter installed on the node
	or a random node ID.
	When a random node ID is specified,
	the least significant bit of the first node byte 
	should be set to 1 
	to avoid clashes with real MAC identifiers.
	UUIDs of type 1 with node ID 
	are generated from a timestamp and other data.
	See <a href="http://www.ietf.org/rfc/rfc4122.txt">RFC 4122</a> 
	for details on UUID generation.
</p>

<!-- example -->

<pre>
;; type 4 UUID for any system

(uuid)  <span class='arw'>&rarr;</span> "493AAD61-266F-48A9-B99A-33941BEE3607"

;; type 1 UUID preferred for distributed systems

;; configure node ID for ether 00:14:51:0a:e0:bc
(set 'id (pack "cccccc" 0x00 0x14 0x51 0x0a 0xe0 0xbc))

(uuid  id)  <span class='arw'>&rarr;</span> "0749161C-2EC2-11DB-BBB2-0014510AE0BC"
</pre>


<p>
	Each invocation of the <tt>uuid</tt> function 
	will yield a new unique UUID.
	The UUIDs are generated without system-wide 
	shared stable store (see RFC 4122).
	If the system generating the UUIDs 
	is distributed over several nodes, 
	then type 1 generation should be used 
	with a different node ID on each node.
	For several processes on the same node, 
	valid UUIDs are guaranteed 
	even if requested at the same time.
	This is because the process ID 
	of the generating newLISP process 
	is part of the seed 
	for the random number generator.
	When type 4 IDs are used on a distributed system, 
	two identical UUID's are still highly unlikely 
	and impossible for type 1 IDs 
	if real MAC addresses are used.
</p>

<br/><br/>

<a name="wait-pid"></a>
<h2><span class="function">wait-pid</span></h2>
<h4>syntax: (wait-pid <em>int-pid</em> [<em>int-options</em> | <tt>nil</tt>])</h4>

<p>
Waits for a child process specified in <em>int-pid</em> to end.  The child process was 
previously started with <a href="#process">process</a> or <a href="#fork">fork</a>.
When the child process specified in <em>int-pid</em> ends, a list of pid and status value is 
returned.  The status value describes the reason for termination of the child process.
The interpretation of the returned status value differs between Linux and other flavors 
of Unix.  Consult the Linux/Unix man pages for the <tt>waitpid</tt> command (without the hyphen 
used in newLISP) for further information.
</p>

<p>
When <tt>-1</tt> is specified for <em>int-pid</em>, 
pid and  status information of any child process started by the parent are returned.
When <tt>0</tt> is specified, <tt>wait-pid</tt> only watches child processes in the 
same process group as the calling process.  Any other negative value for <em>int-pid</em> 
reports child processes in the same process group as specified with a negative sign 
in <em>int-pid</em>.
</p>

<p>
An option can be specified in <em>int-option</em>.  See Linux/Unix documentation 
for details on integer values for <em>int-options</em>. As an alternative, <tt>nil</tt>
can be specified. This option causes <tt>wait-pid</tt> to be non-blocking, returning 
right away with a <tt>0</tt> in the pid of the list returned. This option used together with
 an <em>int-pid</em> parameter of <tt>-1</tt> can be used to continuously loop and act 
on returned child processes.</p>

<p>
This function is only available on macOS, Linux and other Unix-like operating systems.
</p>

<!-- example -->
<pre>
(set 'pid (fork (my-process))) <span class='arw'>&rarr;</span> 8596

(set 'ret (wait-pid pid))  <span class='arw'>&rarr;</span> (8596 0) ; child has exited

(println "process: " pid " has finished with status: " (last ret))
</pre>

<p>
	The process <tt>my-process</tt> is started, 
	then the main program blocks 
	in the <tt>wait-pid</tt> call 
	until <tt>my-process</tt> has finished.
</p>

<br/><br/>

<a name="when"></a>
<h2><span class="function">when</span></h2>
<h4>syntax: (when <em>exp-condition</em> <em>body</em>)</h4>

<p>The statements in <em>body</em> are only evaluated if <em>exp-condition</em>
evaluates to anything not <tt>nil</tt> and not the empty list <tt>()</tt>. The result
of the last expression in <em>body</em> is returned or <tt>nil</tt> or the empty
list <tt>()</tt> if <em>body</em> was not executed.</p>

<p>Because <tt>when</tt> does not have an <em>else</em> condition as in
<a href="#if">if</a>, the statements in <em>body</em> need not to be grouped with
<a href="#begin">begin</a>:</p>

<!-- example -->
<pre>
(when (read-line)
	(set 'result (analyze (current-line)))
	(report result)
	(finish)
)	
</pre>

<p>See also the function <a href="#unless">unless</a>.</p>

<br/><br/>

<a name="while"></a>
<h2><span class="function">while</span></h2>
<h4>syntax: (while <em>exp-condition</em> <em>body</em>)</h4>

<p> Evaluates the condition in <em>exp-condition</em>.
If the result is not <tt>nil</tt> or the empty list <tt>()</tt>, 
the expressions in <em>body</em> are evaluated.
Evaluation is repeated until an <em>exp-condition</em> results 
in <tt>nil</tt> or the empty list <tt>()</tt>.
The result of the body's last evaluated expression
is the return value of the <tt>while</tt> expression.
</p>

<p><tt>while</tt> also updates the system iterator symbol <tt>$idx</tt>.</p>

<!-- example -->

<pre>
(device (open "somefile.txt" "read"))
(set 'line-count 0)
(while (read-line) (inc line-count))
(close (device))
(print "the file has " line-count " lines\n")
</pre>


<p>
Use the <a href="#do-while">do-while</a> function to evaluate the condition 
<em>after</em> evaluating the body of expressions.
</p>

<br/><br/>

<a name="write"></a>
<a name="write-buffer"></a>

<h2><span class="function">write</span>&nbsp;<a href="#destructive">!</a></h2>
<h4>syntax: (write)<br/>
syntax: (write <em>int-file</em> <em>str-buffer</em> [<em>int-size</em>])<br/>
syntax: (write <em>str</em> <em>str-buffer</em> [<em>int-size</em>])</h4>


<p>In the second syntax <tt>write</tt> writes <em>int-size</em> bytes 
from a buffer in <em>str-buffer</em> to a file specified in <em>int-file</em>, 
previously obtained from a file <tt>open</tt> operation. If <em>int-size</em> 
is not specified, all data in <em>sym-buffer</em> or <em>str-buffer</em> is written.
<tt>write</tt> returns the number of bytes written or <tt>nil</tt> on failure.</p>

<p>If all parameters are omitted, <tt>write</tt> writes the contents from the
last <a href="#read-line">read-line</a> to standard out (STDOUT).</p>

<p><tt>write</tt> is a shorter writing of <tt>write-buffer</tt>. The longer
form still works but is deprecated and should be avoided in new code.</p>

<!-- example -->

<pre>
(set 'handle (open "myfile.ext" "write"))
(write handle data 100)   
(write handle "a quick message\n")
</pre>

<p>The code in the example writes 100 bytes to the file <tt>myfile.ext</tt> 
from the contents in <tt>data</tt>.</p>

<p>In the third syntax, <tt>write</tt> can be used for destructive
string appending:</p>

<pre>
(set 'str "")
(write str "hello world")

str   <span class='arw'>&rarr;</span> "hello world"
</pre>

<p>See also the <a href="#read">read</a> function.</p>

<br/><br/>

<a name="write-char"></a>
<h2><span class="function">write-char</span></h2>
<h4>syntax: (write-char <em>int-file</em> <em>int-byte1</em> [<em>int-byte2</em> ... ])</h4>

<p>
Writes a byte specified in <em>int-byte</em> to a file specified by the file 
handle in <em>int-file</em>. The file handle is obtained from a previous 
<tt>open</tt> operation. Each <tt>write-char</tt> advances the file pointer 
by one 8-bit byte.</p>

<p><tt>write-char</tt> returns the number of bytes written.</p>

<!-- example -->

<pre>
(define (slow-file-copy from-file to-file)
    (set 'in-file (open from-file "read"))
    (set 'out-file (open to-file "write"))
    (while (set 'chr (read-char in-file))
        (write-char out-file chr))
     (close in-file)
    (close out-file)
    "finished")
</pre>


<p>
Use the <a href="#print">print</a> 
and <a href="#device">device</a> functions 
to write larger portions of data at a time.
Note that newLISP already supplies a faster 
built-in function called 
<a href="#copy-file">copy-file</a>.
</p>

<p>
	See also the <a href="#read-char">read-char</a> function.
</p>

<br/><br/>

<a name="write-file"></a>
<h2><span class="function">write-file</span></h2>
<h4>syntax: (write-file <em>str-file-name</em> <em>str-buffer</em>)</h4>

<p>Writes a file in <em>str-file-name</em> with contents in <em>str-buffer</em> 
in one swoop and returns the number of bytes written.</p>

<p>On failure the function returns <tt>nil</tt>. For error information, 
use <a href="#sys-error">sys-error</a> when used on files. When used
on URLs <a href="#net-error">net-error</a> gives more error
information.</p>

<!-- example -->

<pre>
(write-file "myfile.enc"
    (encrypt (read-file "/home/lisp/myFile") "secret"))
</pre>


<p>The file <tt>myfile</tt> is read, <a href="#encrypt">encrypted</a> using the 
password <tt>secret</tt>, and written back into the new file <tt>myfile.enc</tt>
in the current directory.</p>

<p>
<tt>write-file</tt> can take an <tt>http://</tt> or <tt>file://</tt> URL 
in <em>str-file-name</em>. When the prefix <tt>http://</tt> is used, 
<tt>write-file</tt> works exactly like <a href="#put-url">put-url</a> 
and can take the same additional parameters:</p>

<!-- example -->

<pre>
(write-file "http://asite.com/message.txt" "This is a message" )
</pre>


<p>The file <tt>message.txt</tt> is created and written at a remote location, 
<tt>http://asite.com</tt>, with the contents of <em>str-buffer</em>.
In this mode, <tt>write-file</tt> can also be used to transfer files 
to remote newLISP server nodes.</p>

<p>See also the <a href="#append-file">append-file</a> 
and <a href="#read-file">read-file</a> functions.</p>

<br/><br/>

<a name="write-line"></a>
<h2><span class="function">write-line</span>&nbsp;<a href="#destructive">!</a></h2>
<h4>syntax: (write-line [<em>int-file</em> [<em>str</em>]])<br/>
syntax: (write-line <em>str-out</em> [<em>str</em>]])</h4>

<p>The string in <em>str</em> and the line termination character(s) 
are written to the device specified in <em>int-file</em>.
When the string argument is omitted <tt>write-line</tt> writes the 
contents of the last <a href="#read-line">read-line</a> to <em>int-file</em>
If the first argument is omitted too then it writes to  to standard out 
(STDOUT) or to whatever device is set by <a href="#device">device</a>.</p> 

<p>In the second syntax lines are appended to a string in <em>str-out</em>.</p>

<p><tt>write-line</tt> returns the number of bytes written.</p>

<!-- example -->

<pre>
(set 'out-file (open "myfile" "write"))
(write-line out-file "hello there")
(close out-file)

(set 'myFile (open "init.lsp" "read")
(while (read-line myFile) (write-line))

(set 'str "")
(write-line str "hello")
(write-line str "world")

str  <span class='arw'>&rarr;</span>  "hello\nworld\n"
</pre>


<p>
The first example opens/creates a file, writes a line to it, 
and closes the file. The second example shows the usage of <tt>write-line</tt> 
without arguments. The contents of <tt>init.lsp</tt> are written to the console 
screen.</p>

<p>See also the function <a href="#write">write</a> for writing
to a device without the line-terminating character.</p>

<br/><br/>

<a name="xfer-event"></a>
<h2><span class="function">xfer-event</span></h2>
<h4>syntax: (xfer-event <em>sym-event-handler</em> | <em>func-event-handler</em>)
syntax: (xfer-event nil)</h4>

<p>Registers a function in symbol <em>sym-event-handler</em> or in lambda function 
<em>func-event-handler</em>
to monitor HTTP byte transfers initiated by <a href="#get-url">get-url</a>,
<a href="#post-url">post-url</a> or <a href="#put-url">put-url</a> or initiated
by file functions which can take URLs like <a href="#load">load</a>,
<a href="#save">save</a>, <a href="#read-file">read-file</a>,
<a href="#write-file">write-file</a> and <a href="#append-file">append-file</a>.
</p>

<p>E.g. whenever a block of data requested with <a href="#get-url">get-url</a>
arrives, the function in <em>sym</em> or <em>func</em> will be called with
the number of bytes transferred. Likewise when sending data with
<a href="#post-url">post-url</a> or any of the other data sending 
functions, <em>sym</em> or <em>func</em> will be called with the number of
bytes transferred for each block of data transferred.</p>

<p>Specifying <tt>nil</tt> for the event will reset it to the initial default state.</p>

<!-- example -->

<pre>
(xfer-event (fn (n) (println "-&gt;" n)))
(length (get-url "http://newlisp.org"))
<b>
-&gt;73
-&gt;799
-&gt;1452
-&gt;351
-&gt;1093
-&gt;352
-&gt;211
-&gt;885
-&gt;564
-&gt;884
-&gt;561
-&gt;75
-&gt;812
-&gt;638
-&gt;1452
-&gt;801
-&gt;5
-&gt;927
11935
</b>
</pre>


<p>The computer output is shown in bold. Whenever a block of data is received
its byte size is printed. Instead of defining the handler
function directory with a lambda function in <em>func</em>, a symbol
containing a function definition could have been used:</p>


<pre>
(define (report n) (println "-&gt;" n))
(xfer-event 'report)
</pre>


<p> This can be used to monitor the progress of longer
lasting byte transfers in HTTP uploads or downloads.</p>

<br/><br/>

<a name="xml-error"></a>
<h2><span class="function">xml-error</span></h2>
<h4>syntax: (xml-error)</h4>

<p>
	Returns a list of error information 
	from the last <a href="#xml-parse">xml-parse</a> operation; 
	otherwise, returns <tt>nil</tt>
	if no error occurred.
	The first element contains text 
	describing the error, 
	and the second element is a number indicating 
	the last scan position in the source XML text, 
	starting at <tt>0</tt> (zero).
</p>

<!-- example -->

<pre>
(xml-parse "&lt;atag&gt;hello&lt;/atag&gt;&lt;fin")  <span class='arw'>&rarr;</span> nil

(xml-error)  <span class='arw'>&rarr;</span> ("expected closing tag: &gt;" 18)
</pre>

<br/><br/>

<a name="xml-parse"></a>
<h2><span class="function">xml-parse</span></h2>
<h4>syntax: (xml-parse <em>string-xml</em> [<em>int-options</em> [<em>sym-context</em> [<em>func-callback</em>]]])</h4>

<p>
Parses a string containing XML 1.0 compliant, <em>well-formed</em> XML.
<tt>xml-parse</tt> does not perform DTD validation. 
It skips DTDs (Document Type Declarations) and processing instructions.
Nodes of type ELEMENT, TEXT, CDATA, and COMMENT are parsed, and 
a newLISP list structure is returned.  When an element node does not have 
attributes or child nodes, it instead contains an empty list.
Attributes are returned as association lists, 
which can be accessed using <a href="#assoc">assoc</a>.
When <tt>xml-parse</tt> fails due to malformed XML, <tt>nil</tt> is returned 
and <a href="#xml-error">xml-error</a> can be used to access error information.
</p>

<!-- example -->

<pre>
(set 'xml 
  "&lt;person name='John Doe' tel='555-1212'&gt;nice guy&lt;/person&gt;")

(xml-parse xml) 
<span class='arw'>&rarr;</span> (("ELEMENT" "person" 
    (("name" "John Doe") 
     ("tel" "555-1212"))
    (("TEXT" "nice guy"))))
</pre>


<h3>Modifying the translation process.</h3>
<p>
Optionally, the <em>int-options</em> parameter can be specified 
to suppress whitespace, empty attribute lists, and comments.
It can also be used to transform tags from strings into symbols.
Another function, <a href="#xml-type-tags">xml-type-tags</a>, 
serves for translating the XML tags.
The following option numbers can be used:
</p>

<table  summary="option numbers for xml-parse">
<tr align="left" valign="bottom"><th>option</th><th>description</th></tr>
<tr><td>1</td><td>suppress whitespace text tags</td></tr>
<tr><td>2</td><td>suppress empty attribute lists</td></tr>
<tr><td>4</td><td>suppress comment tags</td></tr>
<tr><td>8</td><td>translate string tags into symbols</td></tr>

<tr><td>16</td><td>add SXML (S-expression XML) attribute tags (@ ...)</td></tr>
</table><br/>

<p>
Options can be combined by adding the numbers
(e.g., <tt>3</tt> would combine the options 
for suppressing whitespace text tags/info 
and empty attribute lists).
</p>
 
<p>
The following examples show how the different options can be used:
</p>
<br/>
<b>XML source:</b>


<pre>
&lt;?xml version="1.0" ?&gt;
&lt;DATABASE name="example.xml"&gt;
&lt;!--This is a database of fruits--&gt;
    &lt;FRUIT&gt;
        &lt;NAME&gt;apple&lt;/NAME&gt;
        &lt;COLOR&gt;red&lt;/COLOR&gt;
        &lt;PRICE&gt;0.80&lt;/PRICE&gt;
    &lt;/FRUIT&gt;

    &lt;FRUIT&gt;
        &lt;NAME&gt;orange&lt;/NAME&gt;
        &lt;COLOR&gt;orange&lt;/COLOR&gt;
        &lt;PRICE&gt;1.00&lt;/PRICE&gt;
    &lt;/FRUIT&gt;

    &lt;FRUIT&gt;
       &lt;NAME&gt;banana&lt;/NAME&gt;
       &lt;COLOR&gt;yellow&lt;/COLOR&gt;
       &lt;PRICE&gt;0.60&lt;/PRICE&gt;
    &lt;/FRUIT&gt;
&lt;/DATABASE&gt;
</pre>


<h3>Parsing without any options:</h3>


<pre>
(xml-parse (read-file "example.xml"))
<span class='arw'>&rarr;</span> (("ELEMENT" "DATABASE" (("name" "example.xml")) (("TEXT" "\r\n\t") 
    ("COMMENT" "This is a database of fruits") 
    ("TEXT" "\r\n\t") 
    ("ELEMENT" "FRUIT" () (("TEXT" "\r\n\t\t") ("ELEMENT" "NAME" () 
       (("TEXT" "apple"))) 
      ("TEXT" "\r\n\t\t") 
      ("ELEMENT" "COLOR" () (("TEXT" "red"))) 
      ("TEXT" "\r\n\t\t") 
      ("ELEMENT" "PRICE" () (("TEXT" "0.80"))) 
      ("TEXT" "\r\n\t"))) 
    ("TEXT" "\r\n\r\n\t") 
    ("ELEMENT" "FRUIT" () (("TEXT" "\r\n\t\t") ("ELEMENT" "NAME" () 
       (("TEXT" "orange"))) 
      ("TEXT" "\r\n\t\t") 
      ("ELEMENT" "COLOR" () (("TEXT" "orange"))) 
      ("TEXT" "\r\n\t\t") 
      ("ELEMENT" "PRICE" () (("TEXT" "1.00"))) 
      ("TEXT" "\r\n\t"))) 
    ("TEXT" "\r\n\r\n\t") 
    ("ELEMENT" "FRUIT" () (("TEXT" "\r\n\t\t") ("ELEMENT" "NAME" () 
       (("TEXT" "banana"))) 
      ("TEXT" "\r\n\t\t") 
      ("ELEMENT" "COLOR" () (("TEXT" "yellow"))) 
      ("TEXT" "\r\n\t\t") 
      ("ELEMENT" "PRICE" () (("TEXT" "0.60"))) 
      ("TEXT" "\r\n\t"))) 
    ("TEXT" "\r\n"))))
</pre>


<p>
The <tt>TEXT</tt> elements containing only whitespace make the output very confusing.
As the database in <tt>example.xml</tt> only contains data,
we can suppress whitespace, empty attribute lists and comments with 
option <tt>(+ 1 2 4)</tt>:</p>

<h3>Filtering whitespace TEXT, COMMENT tags, and empty attribute lists:</h3>


<pre>
(xml-parse (read-file "example.xml") (+ 1 2 4))
<span class='arw'>&rarr;</span> (("ELEMENT" "DATABASE" (("name" "example.xml")) ( 
     ("ELEMENT" "FRUIT" (
       ("ELEMENT" "NAME" (("TEXT" "apple"))) 
       ("ELEMENT" "COLOR" (("TEXT" "red"))) 
       ("ELEMENT" "PRICE" (("TEXT" "0.80"))))) 
     ("ELEMENT" "FRUIT" (
       ("ELEMENT" "NAME" (("TEXT" "orange"))) 
       ("ELEMENT" "COLOR" (("TEXT" "orange"))) 
       ("ELEMENT" "PRICE" (("TEXT" "1.00"))))) 
     ("ELEMENT" "FRUIT" (
       ("ELEMENT" "NAME" (("TEXT" "banana"))) 
       ("ELEMENT" "COLOR" (("TEXT" "yellow"))) 
       ("ELEMENT" "PRICE" (("TEXT" "0.60"))))))))
</pre>


<p>
The resulting output looks much more readable, but it can still be improved 
by using symbols instead of strings for the tags "FRUIT", "NAME", "COLOR", and "PRICE",
as well as by suppressing the XML type tags "ELEMENT" and "TEXT" completely 
using the <a href="#xml-type-tags">xml-type-tags</a> directive.
</p>

<h3>Suppressing XML type tags with <a href="#xml-type-tags">xml-type-tags</a> 
and translating string tags into symbol tags:</h3>


<pre>
;; suppress all XML type tags for TEXT and ELEMENT
;; instead of "CDATA", use cdata and instead of "COMMENT", use !--

(xml-type-tags nil 'cdata '!-- nil) 

;; turn on all options for suppressing whitespace and empty
;; attributes, translate tags to symbols

(xml-parse (read-file "example.xml") (+ 1 2 8))
<span class='arw'>&rarr;</span> ((DATABASE (("name" "example.xml")) 
     (!-- "This is a database of fruits") 
     (FRUIT (NAME "apple") (COLOR "red") (PRICE "0.80")) 
     (FRUIT (NAME "orange") (COLOR "orange") (PRICE "1.00")) 
     (FRUIT (NAME "banana") (COLOR "yellow") (PRICE "0.60"))))
</pre>


<p>
When tags are translated into symbols by using option <tt>8</tt>, 
a context can be specified in <em>sym-context</em>. 
If no context is specified, all symbols will be created inside the current context.
</p>


<pre>
(xml-type-tags nil nil nil nil)
(xml-parse "&lt;msg&gt;Hello World&lt;/msg&gt;" (+ 1 2 4 8 16) 'CTX)
<span class='arw'>&rarr;</span> ((CTX:msg "Hello World"))
</pre>


<p>
Specifying <tt>nil</tt> for the XML type tags TEXT and ELEMENT 
makes them disappear.  At the same time, 
parentheses of the child node list are removed so that 
child nodes now appear as members of the list, 
starting with the tag symbol translated from the string tags 
"FRUIT", "NAME", etcetera.
</p>

<h3>Parsing into SXML (S-expressions XML) format:</h3>
<p>
Using <a href="#xml-type-tags">xml-type-tags</a> to suppress 
all XML-type tags&mdash;along with the option numbers 
<tt>1</tt>, <tt>2</tt>, <tt>4</tt>, <tt>8</tt>, and <tt>16</tt>&mdash;SXML 
formatted output can be generated:
</p>


<pre>
(xml-type-tags nil nil nil nil)
(xml-parse (read-file "example.xml") (+ 1 2 4 8 16))
<span class='arw'>&rarr;</span> ((DATABASE (@ (name "example.xml")) 
    (FRUIT (NAME "apple") (COLOR "red") (PRICE "0.80")) 
    (FRUIT (NAME "orange") (COLOR "orange") (PRICE "1.00")) 
    (FRUIT (NAME "banana") (COLOR "yellow") (PRICE "0.60"))))
</pre>

<p>If the original XML tags contain a namespace part separated by a <tt>:</tt>,
that colon will be translated into a <tt>.</tt> dot in the resulting newLISP
symbol.</p>


<p>
Note that using option number <tt>16</tt> 
causes an <tt>@</tt> (at symbol) to be added to attribute lists.
</p>

<p>
See also the <a href="#xml-type-tags">xml-type-tags</a> function 
for further information on XML parsing.
</p>

<h3>Parsing into a specified context</h3>

<p>When parsing XML expressions, XML tags are translated into newLISP symbols,
when option 8 is specified.  The <i>sym-context</i> option specifies the target 
context for the symbol creation:</p>

<pre>
(xml-type-tags nil nil nil nil)
(xml-parse (read-file "example.xml") (+ 1 2 4 8 16) 'CTX)
<span class='arw'>&rarr;</span>((CTX:DATABASE (@ (CTX:name "example.xml")) 
    (CTX:FRUIT (CTX:NAME "apple") (CTX:COLOR "red") (CTX:PRICE "0.80")) 
    (CTX:FRUIT (CTX:NAME "orange") (CTX:COLOR "orange") (CTX:PRICE "1.00")) 
    (CTX:FRUIT (CTX:NAME "banana") (CTX:COLOR "yellow") (CTX:PRICE "0.60"))))
</pre>

<p>If the context does not exist, it will be created. If it exists, the quote can 
be omitted or the context can be referred to by a variable.</p>

<h3>Using a call back function</h3>
<p>Normally, <tt>xml-parse</tt> will not return until all parsing has finished.
Using the <em>func-callback</em> option, <tt>xml-parse</tt> will call back after
each tag closing with the generated S-expression and a start position and
length in the source XML:</p>


<pre>
;; demo callback feature
(define (xml-callback s-expr start size)
    (if (or (= (s-expr 0) 'NAME) (= (s-expr 0) 'COLOR) (= (s-expr 0) 'PRICE))
        (begin
            (print "parsed expression:" s-expr)
            (println ", source:" (start size example-xml))
        )
    )
)

(xml-type-tags nil 'cdata '!-- nil)
(xml-parse  (read-file "example.xml") (+ 1 2 8) MAIN xml-callback)
</pre>


<p>The following output will be generated by the callback function <tt>xml-callback</tt>:</p>

<pre>
parsed expression:(NAME "apple"), source:&lt;NAME&gt;apple&lt;/NAME&gt;
parsed expression:(COLOR "red"), source:&lt;COLOR&gt;red&lt;/COLOR&gt;
parsed expression:(PRICE "0.80"), source:&lt;PRICE&gt;0.80&lt;/PRICE&gt;
parsed expression:(NAME "orange"), source:&lt;NAME&gt;orange&lt;/NAME&gt;
parsed expression:(COLOR "orange"), source:&lt;COLOR&gt;orange&lt;/COLOR&gt;
parsed expression:(PRICE "1.00"), source:&lt;PRICE&gt;1.00&lt;/PRICE&gt;
parsed expression:(NAME "banana"), source:&lt;NAME&gt;banana&lt;/NAME&gt;
parsed expression:(COLOR "yellow"), source:&lt;COLOR&gt;yellow&lt;/COLOR&gt;
parsed expression:(PRICE "0.60"), source:&lt;PRICE&gt;0.60&lt;/PRICE&gt;
</pre>


<p>The example callback handler function filters the tags of interest and processes
them as they occur.</p>

<br/><br/>

<a name="xml-type-tags"></a>
<h2><span class="function">xml-type-tags</span></h2>

<h4>syntax: (xml-type-tags [<em>exp-text-tag</em> <em>exp-cdata-tag</em> <em>exp-comment-tag</em> <em>exp-element-tags</em>])</h4>

<p>
Can suppress completely or replace the XML type tags 
"TEXT", "CDATA", "COMMENT", and "ELEMENT" with something else specified 
in the parameters.
</p>

<p>
Note that <tt>xml-type-tags</tt> only suppresses or translates the tags themselves 
but does not suppress or modify the tagged information.  The latter would be done 
using option numbers in <a href="#xml-parse">xml-parse</a>.
</p>

<p>
Using <tt>xml-type-tags</tt> without arguments 
returns the current type tags:
</p>

<!-- example -->

<pre>
(xml-type-tags)  <span class='arw'>&rarr;</span> ("TEXT" "CDATA" "COMMENT" "ELEMENT")

(xml-type-tags nil 'cdata '!-- nil)
</pre>


<p>
The first example just shows the currently used type tags.
The second example specifies suppression of the "TEXT" and "ELEMENT" tags 
and shows <tt>cdata</tt> and <tt>!--</tt> instead of 
"CDATA" and "COMMENT".
</p>

<br/><br/>

<a name="zerop"></a>
<h2><span class="function">zero?</span>&nbsp;
<a href="#big_int"><font size="-1">bigint</font></a></h2>
<h4>syntax: (zero? <em>exp</em>)</h4>

<p>
Checks the evaluation of <em>exp</em> to see if it equals <tt>0</tt> (zero).
</p>

<!-- example -->

<pre>
(set 'value 1.2)
(set 'var 0)
(zero? value)  <span class='arw'>&rarr;</span> nil
(zero? var)    <span class='arw'>&rarr;</span> true

(map zero? '(0 0.0 3.4 4))  <span class='arw'>&rarr;</span> (true true nil nil)

(map zero? '(nil true 0 0.0 "" ()))  <span class='arw'>&rarr;</span> (nil nil true true nil nil)
</pre>


<p>
	<tt>zero?</tt> will return <tt>nil</tt> 
	on data types other than numbers.
</p>

<br/><br/>

<center style="font-size: 150%">
<span class="divider">(&nbsp;<font color="#7ba9d4">&part;</font>&nbsp;)</span>
</center>

<br/><br/>

<hr/>

<br/><br/>

<a name="appendix"></a>
<center><h2>newLISP APPENDIX</h2></center>

<a name="error_codes"></a>
<h2>Error codes</h2>

<table summary="Error codes">
<tr align="left"><th>description</th><th>no</th></tr>
<tr><td>not enough memory</td><td>1</td></tr>
<tr><td>environment stack overflow</td><td>2</td></tr>
<tr><td>call stack overflow</td><td>3</td></tr>
<tr><td>problem accessing file</td><td>4</td></tr>
<tr><td>not an expression</td><td>5</td></tr>
<tr><td>missing parenthesis</td><td>6</td></tr>
<tr><td>string token too long</td><td>7</td></tr>
<tr><td>missing argument</td><td>8</td></tr>
<tr><td>number or string expected</td><td>9</td></tr>
<tr><td>value expected</td><td>10</td></tr>
<tr><td>string expected</td><td>11</td></tr>
<tr><td>symbol expected</td><td>12</td></tr>
<tr><td>context expected</td><td>13</td></tr>
<tr><td>symbol or context expected</td><td>14</td></tr>
<tr><td>list expected</td><td>15</td></tr>
<tr><td>list or array expected</td><td>16</td></tr>
<tr><td>list or symbol expected</td><td>17</td></tr>
<tr><td>list or string expected</td><td>18</td></tr>
<tr><td>list or number expected</td><td>19</td></tr>
<tr><td>array expected</td><td>20</td></tr>
<tr><td>array, list or string expected</td><td>21</td></tr>
<tr><td>lambda expected</td><td>22</td></tr>
<tr><td>lambda-macro expected</td><td>23</td></tr>
<tr><td>invalid function</td><td>24</td></tr>
<tr><td>invalid lambda expression</td><td>25</td></tr>
<tr><td>invalid macro expression</td><td>26</td></tr>
<tr><td>invalid let parameter list</td><td>27</td></tr>
<tr><td>problem saving file</td><td>28</td></tr>
<tr><td>division by zero</td><td>29</td></tr>
<tr><td>matrix expected</td><td>30</td></tr>
<tr><td>wrong dimensions</td><td>31</td></tr>
<tr><td>matrix is singular</td><td>32</td></tr>
<tr><td>syntax in regular expression</td><td>33</td></tr>
<tr><td>throw without catch</td><td>34</td></tr>
<tr><td>problem loading library</td><td>35</td></tr>
<tr><td>import function not found</td><td>36</td></tr>
<tr><td>symbol is protected</td><td>37</td></tr>
<tr><td>error number too high</td><td>38</td></tr>
<tr><td>regular expression</td><td>39</td></tr>
<tr><td>missing end of text [/text]</td><td>40</td></tr>
<tr><td>mismatch in number of arguments</td><td>41</td></tr>
<tr><td>problem in format string</td><td>42</td></tr>
<tr><td>data type and format don't match</td><td>43</td></tr>
<tr><td>invalid parameter</td><td>44</td></tr>
<tr><td>invalid parameter: 0.0</td><td>45</td></tr>
<tr><td>invalid parameter: NaN</td><td>46</td></tr>
<tr><td>invalid UTF8 string</td><td>47</td></tr>
<tr><td>illegal parameter type</td><td>48</td></tr>
<tr><td>symbol not in MAIN context</td><td>49</td></tr>
<tr><td>symbol not in current context</td><td>50</td></tr>
<tr><td>target cannot be MAIN</td><td>51</td></tr>
<tr><td>list index out of bounds</td><td>52</td></tr>
<tr><td>array index out of bounds</td><td>53</td></tr>
<tr><td>string index out of bounds</td><td>54</td></tr>
<tr><td>nesting level too deep</td><td>55</td></tr>
<tr><td>list reference changed</td><td>56</td></tr>
<tr><td>invalid syntax</td><td>57</td></tr>
<tr><td>user error</td><td>58</td></tr>
<tr><td>user reset -</td><td>59</td></tr>
<tr><td>received SIGINT -</td><td>60</td></tr>
<tr><td>function is not reentrant</td><td>61</td></tr>
<tr><td>local symbol is protected</td><td>62</td></tr>
<tr><td>no reference found</td><td>63</td></tr>
<tr><td>list is empty</td><td>64</td></tr>
<tr><td>I/O error</td><td>65</td></tr>
<tr><td>working directory not found</td><td>66</td></tr>
<tr><td>invalid PID</td><td>67</td></tr>
<tr><td>cannot open socket pair</td><td>68</td></tr>
<tr><td>cannot fork process</td><td>69</td></tr>
<tr><td>no comm channel found</td><td>70</td></tr>

<tr><td>ffi preparation failed</td><td>71</td></tr>
<tr><td>invalid ffi type</td><td>72</td></tr>
<tr><td>ffi struct expected</td><td>73</td></tr>

<tr><td>bigint type not applicable</td><td>74</td></tr>
<tr><td>not a number or infinite</td><td>75</td></tr>
<tr><td>cannot convert NULL to string</td><td>76</td></tr>
</table><br/>

<br/><br/><br/>

<a name="tcpip_error_codes"></a>
<h2>TCP/IP and UDP Error Codes</h2>

<table summary="tcp/ip error codes">
<tr align="left"><th>no</th><th>description</th></tr>
<tr><td>1</td><td>Cannot open socket</td></tr>
<tr><td>2</td><td>DNS resolution failed</td></tr>
<tr><td>3</td><td>Not a valid service</td></tr>
<tr><td>4</td><td>Connection failed</td></tr>
<tr><td>5</td><td>Accept failed</td></tr>
<tr><td>6</td><td>Connection closed</td></tr>
<tr><td>7</td><td>Connection broken</td></tr>
<tr><td>8</td><td>Socket send() failed</td></tr>
<tr><td>9</td><td>Socket recv() failed</td></tr>
<tr><td>10</td><td>Cannot bind socket</td></tr>
<tr><td>11</td><td>Too many sockets in net-select</td></tr>
<tr><td>12</td><td>Listen failed</td></tr>
<tr><td>13</td><td>Badly formed IP</td></tr>
<tr><td>14</td><td>Select failed</td></tr>
<tr><td>15</td><td>Peek failed</td></tr>
<tr><td>16</td><td>Not a valid socket</td></tr>
<tr><td>17</td><td>Cannot unblock socket</td></tr>
<tr><td>18</td><td>Operation timed out</td></tr>
<tr><td>19</td><td>HTTP bad formed URL</td></tr>
<tr><td>20</td><td>HTTP file operation failed</td></tr>
<tr><td>21</td><td>HTTP transfer failed</td></tr>
<tr><td>22</td><td>HTTP invalid response from server</td></tr>
<tr><td>23</td><td>HTTP no response from server</td></tr>
<tr><td>24</td><td>HTTP document empty</td></tr>
<tr><td>25</td><td>HTTP error in header</td></tr>
<tr><td>26</td><td>HTTP error in chunked format</td></tr>
</table><br/>

<br/><br/><br/>

<a name="system_symbols"></a>
<h2>System Symbols and Constants</h2>

<h3>Variables changed by the system</h3>

<p>newLISP maintains several internal symbol variables. All of them are global
and can be used by the programmer. Some have write protection, others
are user settable. Some will change when used in a sub-expression of the
enclosing expression using it. Others are safe when using reentrant in nested 
functions or expressions.</p>

<p>All symbols starting with the <tt>$</tt> character will not be serialized
when using the <a href="#save">save</a> or <a href="#source">source</a> functions.
</p>

<table width="98%" summary="system vars">
<tr><th>&nbsp;variable&nbsp;name</th><th>purpose</th><th>&nbsp;protected&nbsp;</th><th>&nbsp;reentrant&nbsp;</th></tr>
<tr><td><tt>&nbsp;$0 - $15</tt></td><td>Used primarily in regular expressions. <tt>$0</tt>
is also used to record the last state or count of execution of some functions.</td>
<td>&nbsp;no</td><td>&nbsp;no</td></tr>

<tr><td><tt>&nbsp;$args</tt></td><td>Contains the list parameters not bound to local
variables. Normally the function <a href="#args">args</a> is used to retrieve
the contents of this variable.</td><td>&nbsp;yes</td><td>&nbsp;yes</td></tr>

<tr><td><tt>&nbsp;$count</tt></td><td>The count of elements matching when using
<a href="#find-all">find-all</a>, <a href="#replace">replace</a>,
<a href="#ref-all">ref-all</a> and <a href="#set-ref-all">set-ref-all</a> or the 
count of characters processed by <a href="#read-expr">read-expr</a>.</td>
<td>&nbsp;yes</td><td>&nbsp;no</td></tr>

<tr><td><tt>&nbsp;$idx</tt></td><td>The function <a href="#dolist">dolist</a>
maintains this as a list index or offset. The functions 
<a href="#map">map</a>, <a href="#series">series</a>,
<a href="#while">while</a>, <a href="#until">until</a>,
<a href="#do-while">do-while</a> and <a href="#do-until">do-until</a>
maintain this variable as an iteration counter starting with 0 (zero) for
the first iteration.</td>
<td>&nbsp;yes</td><td>&nbsp;yes</td></tr>

<tr><td><tt>&nbsp;$it</tt></td><td>The <em>anaphoric</em> <tt>$it</tt> refers to the
result inside an executing expression, i.e. in self referential assignments. 
<tt>$it</tt> is only available inside the function expression setting it, and
is set to <tt>nil</tt> on exit of that expression. The following functions use it:
<a href="#if">if</a>,
<a href="#hash">hashes</a>, <a href="#find-all">find-all</a>,
<a href="#replace">replace</a>, <a href="#set-ref">set-ref</a>, 
<a href="#set-ref-all">set-ref-all</a> and <a href="#setf">setf setq</a>.</td>
<td>&nbsp;yes</td><td>&nbsp;no</td></tr>

<tr><td><tt>&nbsp;$main-args</tt></td><td>Contains the list of command line arguments
passed by the OS to newLISP when it was started. Normally the function
<a href="#main-args">main-args</a> is used to retrieve the contents.</td>
<td>&nbsp;yes</td><td>&nbsp;n/a</td></tr>

</table><br/>

<h3>Predefined variables and functions.</h3>

<p>These are preset symbol constants. Two of them are used as namespace templates,
one two write platform independent code.</p> 

<table  width="98%" summary="preset vars">
<tr><th>name</th><th>purpose</th><th>&nbsp;protected&nbsp;</th><th>&nbsp;reentrant&nbsp;</th></tr>

<tr><td><tt>&nbsp;Class</tt></td><td>Is the predefined general FOOP class constructor
which can be used together with <tt>new</tt> to create new FOOP classes, e.g:
<tt>(new Class 'Rectangle)</tt> would create a class and object constructor for
a user class <tt>Rectangle</tt>. See the 
<a href="#newlisp_classes">FOOP classes and constructors</a> chapter in the users 
manual for details.</td>
<td>&nbsp;no</td><td>&nbsp;n/a</td></tr>

<tr><td><tt>&nbsp;ostype</tt></td><td>Contains a string identifying the OS-Platform
for which the running newLISP version has been compiled. See the reference section for 
<a href="#ostype">details</a></td>
<td>&nbsp;yes</td><td>&nbsp;n/a</td></tr>

<tr><td><tt>&nbsp;Tree</tt></td><td>Is a predefined namespace to serve as a hash like
dictionary. Instead of writing <tt>(define Foo:Foo)</tt> to create a <tt>Foo</tt>
dictionary, the expression <tt>(new Tree 'Foo)</tt> can be used as well. See the chapter
<a href="#hash">Hash functions and dictionaries</a> foe details.</td>
<td>&nbsp;no</td><td>&nbsp;n/a</td></tr>

<tr><td><tt>&nbsp;module</tt></td><td>Is a predefined function to load modules. 
Instead of using <tt>load</tt> together with the <tt>NEWLISPDIR</tt> environment 
variable, the <tt>module</tt> function loads automatically from 
<tt>$NEWLISPDIR/modules/</tt>.</td>
<td>&nbsp;no</td><td>&nbsp;n/a</td></tr>

</table><br/>

<p>The symbols <tt>Class</tt>, <tt>Tree</tt> and <tt>module</tt> are predefined as follows:</p>

<pre>
; built-in template for FOOP constructors
; usage: (new Class 'MyClass)
(define (Class:Class) 
    (cons (context) (args)))

; built-in template for hashes
; usage: (new Tree 'MyHash)
(context 'Tree) 
  (constant 'Tree:Tree) 
(context MAIN)"

; load modules from standard path
; usage (module "mymodule.lsp")
(define (module $x)
  (load (append (env "NEWLISPDIR") "/modules/" $x)))

(global 'module)
</pre>

<p>These symbols are not protected and can be redefined by the user.
The <tt>$x</tt> variable is built-in and protected against deletion.
This <tt>$x</tt> variable is also used in <a href="#curry">curry</a> expressions.</p>

<br/><br/>

<center style="font-size: 150%">
<span class="divider">(&nbsp;<font color="#7ba9d4">&part;</font>&nbsp;)</span>
</center>
<br/><br/>

<hr/>


<div class="license">
<a name="GNUFDL"></a>
<center>
<h2><span class="gnu">GNU Free Documentation License</span></h2>
<p>Version 1.2, November 2002</p>

<p>
Copyright (C) 2000,2001,2002  Free Software Foundation, Inc.
59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
Everyone is permitted to copy and distribute verbatim copies
of this license document, but changing it is not allowed.
</p>
</center>

<br/><br/>

<h4>0. PREAMBLE</h4>

<p>The purpose of this License is to make a manual, textbook, or other
functional and useful document "free" in the sense of freedom: to
assure everyone the effective freedom to copy and redistribute it,
with or without modifying it, either commercially or noncommercially.
Secondarily, this License preserves for the author and publisher a way
to get credit for their work, while not being considered responsible
for modifications made by others.
</p>
<p>This License is a kind of "copyleft", which means that derivative
works of the document must themselves be free in the same sense. It
complements the GNU General Public License, which is a copyleft
license designed for free software.
</p>
<p>We have designed this License in order to use it for manuals for
free
software, because free software needs free documentation: a free
program should come with manuals providing the same freedoms that the
software does. But this License is not limited to software manuals;
it can be used for any textual work, regardless of subject matter or
whether it is published as a printed book. We recommend this License
principally for works whose purpose is instruction or reference.
</p>
<h4>1. APPLICABILITY AND DEFINITIONS</h4>
<p>This License applies to any manual or other work, in any medium,
that
contains a notice placed by the copyright holder saying it can be
distributed under the terms of this License. Such a notice grants a
world-wide, royalty-free license, unlimited in duration, to use that
work under the conditions stated herein. The "Document", below,
refers to any such manual or work. Any member of the public is a
licensee, and is addressed as "you". You accept the license if you
copy, modify or distribute the work in a way requiring permission
under copyright law.
</p>
<p>A "Modified Version" of the Document means any work containing the
Document or a portion of it, either copied verbatim, or with
modifications and/or translated into another language.
</p>
<p>A "Secondary Section" is a named appendix or a front-matter section
of
the Document that deals exclusively with the relationship of the
publishers or authors of the Document to the Document's overall subject
(or to related matters) and contains nothing that could fall directly
within that overall subject. (Thus, if the Document is in part a
textbook of mathematics, a Secondary Section may not explain any
mathematics.) The relationship could be a matter of historical
connection with the subject or with related matters, or of legal,
commercial, philosophical, ethical or political position regarding
them.
</p>
<p>The "Invariant Sections" are certain Secondary Sections whose titles
are designated, as being those of Invariant Sections, in the notice
that says that the Document is released under this License. If a
section does not fit the above definition of Secondary then it is not
allowed to be designated as Invariant. The Document may contain zero
Invariant Sections. If the Document does not identify any Invariant
Sections then there are none.
</p>
<p>The "Cover Texts" are certain short passages of text that are
listed,
as Front-Cover Texts or Back-Cover Texts, in the notice that says that
the Document is released under this License. A Front-Cover Text may
be at most 5 words, and a Back-Cover Text may be at most 25 words.
</p>
<p>A "Transparent" copy of the Document means a machine-readable copy,
represented in a format whose specification is available to the
general public, that is suitable for revising the document
straightforwardly with generic text editors or (for images composed of
pixels) generic paint programs or (for drawings) some widely available
drawing editor, and that is suitable for input to text formatters or
for automatic translation to a variety of formats suitable for input
to text formatters. A copy made in an otherwise Transparent file
format whose markup, or absence of markup, has been arranged to thwart
or discourage subsequent modification by readers is not Transparent.
An image format is not Transparent if used for any substantial amount
of text. A copy that is not "Transparent" is called "Opaque".
</p>
<p>Examples of suitable formats for Transparent copies include plain
ASCII without markup, Texinfo input format, LaTeX input format, SGML
or XML using a publicly available DTD, and standard-conforming simple
HTML, PostScript or PDF designed for human modification. Examples of
transparent image formats include PNG, XCF and JPG. Opaque formats
include proprietary formats that can be read and edited only by
proprietary word processors, SGML or XML for which the DTD and/or
processing tools are not generally available, and the
machine-generated HTML, PostScript or PDF produced by some word
processors for output purposes only.
</p>
<p>The "Title Page" means, for a printed book, the title page itself,
plus such following pages as are needed to hold, legibly, the material
this License requires to appear in the title page. For works in
formats which do not have any title page as such, "Title Page" means
the text near the most prominent appearance of the work's title,
preceding the beginning of the body of the text.
</p>
<p>A section "Entitled XYZ" means a named subunit of the Document whose
title either is precisely XYZ or contains XYZ in parentheses following
text that translates XYZ in another language. (Here XYZ stands for a
specific section name mentioned below, such as "Acknowledgements",
"Dedications", "Endorsements", or "History".) To "Preserve the Title"
of such a section when you modify the Document means that it remains a
section "Entitled XYZ" according to this definition.
</p>
<p>The Document may include Warranty Disclaimers next to the notice
which
states that this License applies to the Document. These Warranty
Disclaimers are considered to be included by reference in this
License, but only as regards disclaiming warranties: any other
implication that these Warranty Disclaimers may have is void and has
no effect on the meaning of this License.
</p>
<h4>2. VERBATIM COPYING</h4>
<p>You may copy and distribute the Document in any medium, either
commercially or noncommercially, provided that this License, the
copyright notices, and the license notice saying this License applies
to the Document are reproduced in all copies, and that you add no other
conditions whatsoever to those of this License. You may not use
technical measures to obstruct or control the reading or further
copying of the copies you make or distribute. However, you may accept
compensation in exchange for copies. If you distribute a large enough
number of copies you must also follow the conditions in section 3.
</p>
<p>You may also lend copies, under the same conditions stated above,
and
you may publicly display copies.
</p>
<h4>3. COPYING IN QUANTITY</h4>
<p>If you publish printed copies (or copies in media that commonly have
printed covers) of the Document, numbering more than 100, and the
Document's license notice requires Cover Texts, you must enclose the
copies in covers that carry, clearly and legibly, all these Cover
Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on
the back cover. Both covers must also clearly and legibly identify
you as the publisher of these copies. The front cover must present
the full title with all words of the title equally prominent and
visible. You may add other material on the covers in addition.
Copying with changes limited to the covers, as long as they preserve
the title of the Document and satisfy these conditions, can be treated
as verbatim copying in other respects.
</p>
<p>If the required texts for either cover are too voluminous to fit
legibly, you should put the first ones listed (as many as fit
reasonably) on the actual cover, and continue the rest onto adjacent
pages.
</p>
<p>If you publish or distribute Opaque copies of the Document numbering
more than 100, you must either include a machine-readable Transparent
copy along with each Opaque copy, or state in or with each Opaque copy
a computer-network location from which the general network-using
public has access to download using public-standard network protocols
a complete Transparent copy of the Document, free of added material.
If you use the latter option, you must take reasonably prudent steps,
when you begin distribution of Opaque copies in quantity, to ensure
that this Transparent copy will remain thus accessible at the stated
location until at least one year after the last time you distribute an
Opaque copy (directly or through your agents or retailers) of that
edition to the public.
</p>
<p>It is requested, but not required, that you contact the authors of
the
Document well before redistributing any large number of copies, to give
them a chance to provide you with an updated version of the Document.
</p>
<h4>4. MODIFICATIONS</h4>
<p>You may copy and distribute a Modified Version of the Document under
the conditions of sections 2 and 3 above, provided that you release
the Modified Version under precisely this License, with the Modified
Version filling the role of the Document, thus licensing distribution
and modification of the Modified Version to whoever possesses a copy
of it. In addition, you must do these things in the Modified Version:
</p>
<blockquote>
  <p><b>A.</b> Use in the Title Page (and on the covers, if
any) a title distinct from that of the Document, and from those of
previous versions (which should, if there were any, be listed in the
History section of the Document). You may use the same title as a
previous version if the original publisher of that version gives
permission.</p>
  <p><b>B.</b> List on the Title Page, as authors, one or
more persons or entities responsible for authorship of the
modifications in the Modified Version, together with at least five of
the principal authors of the Document (all of its principal authors, if
it has fewer than five), unless they release you from this requirement.</p>
  <p><b>C.</b> State on the Title page the name of the
publisher of the Modified Version, as the publisher.</p>
  <p><b>D.</b> Preserve all the copyright notices of the
Document.</p>
  <p><b>E.</b> Add an appropriate copyright notice for your
modifications adjacent to the other copyright notices.</p>
  <p><b>F.</b> Include, immediately after the copyright
notices, a license notice giving the public permission to use the
Modified Version under the terms of this License, in the form shown in
the Addendum below.</p>
  <p><b>G.</b> Preserve in that license notice the full
lists of Invariant Sections and required Cover Texts given in the
Document's license notice.</p>
  <p><b>H.</b> Include an unaltered copy of this License.</p>
  <p><b>I.</b> Preserve the section Entitled "History",
Preserve its Title, and add to it an item stating at least the title,
year, new authors, and publisher of the Modified Version as given on
the Title Page. If there is no section Entitled "History" in the
Document, create one stating the title, year, authors, and publisher of
the Document as given on its Title Page, then add an item describing
the Modified Version as stated in the previous sentence.</p>
  <p><b>J.</b> Preserve the network location, if any, given
in the Document for public access to a Transparent copy of the
Document, and likewise the network locations given in the Document for
previous versions it was based on. These may be placed in the "History"
section. You may omit a network location for a work that was published
at least four years before the Document itself, or if the original
publisher of the version it refers to gives permission.</p>
  <p><b>K.</b> For any section Entitled "Acknowledgements"
or "Dedications", Preserve the Title of the section, and preserve in
the section all the substance and tone of each of the contributor
acknowledgements and/or dedications given therein.</p>
  <p><b>L.</b> Preserve all the Invariant Sections of the
Document, unaltered in their text and in their titles. Section numbers
or the equivalent are not considered part of the section titles.</p>
  <p><b>M.</b> Delete any section Entitled "Endorsements".
Such a section may not be included in the Modified Version.</p>
  <p><b>N.</b> Do not retitle any existing section to be
Entitled "Endorsements" or to conflict in title with any Invariant
Section.</p>
  <p><b>O.</b> Preserve any Warranty Disclaimers.</p>
</blockquote>
<p>
If the Modified Version includes new front-matter sections or
appendices that qualify as Secondary Sections and contain no material
copied from the Document, you may at your option designate some or all
of these sections as invariant. To do this, add their titles to the
list of Invariant Sections in the Modified Version's license notice.
These titles must be distinct from any other section titles.
</p>
<p>You may add a section Entitled "Endorsements", provided it contains
nothing but endorsements of your Modified Version by various
parties--for example, statements of peer review or that the text has
been approved by an organization as the authoritative definition of a
standard.
</p>
<p>You may add a passage of up to five words as a Front-Cover Text, and
a
passage of up to 25 words as a Back-Cover Text, to the end of the list
of Cover Texts in the Modified Version. Only one passage of
Front-Cover Text and one of Back-Cover Text may be added by (or
through arrangements made by) any one entity. If the Document already
includes a cover text for the same cover, previously added by you or
by arrangement made by the same entity you are acting on behalf of,
you may not add another; but you may replace the old one, on explicit
permission from the previous publisher that added the old one.
</p>
<p>The author(s) and publisher(s) of the Document do not by this
License
give permission to use their names for publicity for or to assert or
imply endorsement of any Modified Version.
</p>
<h4>5. COMBINING DOCUMENTS</h4>
<p>You may combine the Document with other documents released under
this
License, under the terms defined in section 4 above for modified
versions, provided that you include in the combination all of the
Invariant Sections of all of the original documents, unmodified, and
list them all as Invariant Sections of your combined work in its
license notice, and that you preserve all their Warranty Disclaimers.
</p>
<p>The combined work need only contain one copy of this License, and
multiple identical Invariant Sections may be replaced with a single
copy. If there are multiple Invariant Sections with the same name but
different contents, make the title of each such section unique by
adding at the end of it, in parentheses, the name of the original
author or publisher of that section if known, or else a unique number.
Make the same adjustment to the section titles in the list of
Invariant Sections in the license notice of the combined work.
</p>
<p>In the combination, you must combine any sections Entitled "History"
in the various original documents, forming one section Entitled
"History"; likewise combine any sections Entitled "Acknowledgements",
and any sections Entitled "Dedications". You must delete all sections
Entitled "Endorsements."
</p>
<h4>6. COLLECTIONS OF DOCUMENTS</h4>
<p>You may make a collection consisting of the Document and other
documents
released under this License, and replace the individual copies of this
License in the various documents with a single copy that is included in
the collection, provided that you follow the rules of this License for
verbatim copying of each of the documents in all other respects.
</p>
<p>You may extract a single document from such a collection, and
distribute
it individually under this License, provided you insert a copy of this
License into the extracted document, and follow this License in all
other respects regarding verbatim copying of that document.
</p>
<h4>7. AGGREGATION WITH INDEPENDENT WORKS</h4>
<p>A compilation of the Document or its derivatives with other separate
and independent documents or works, in or on a volume of a storage or
distribution medium, is called an "aggregate" if the copyright
resulting from the compilation is not used to limit the legal rights
of the compilation's users beyond what the individual works permit.
When the Document is included in an aggregate, this License does not
apply to the other works in the aggregate which are not themselves
derivative works of the Document.
</p>
<p>If the Cover Text requirement of section 3 is applicable to these
copies of the Document, then if the Document is less than one half of
the entire aggregate, the Document's Cover Texts may be placed on
covers that bracket the Document within the aggregate, or the
electronic equivalent of covers if the Document is in electronic form.
Otherwise they must appear on printed covers that bracket the whole
aggregate.
</p>
<h4>8. TRANSLATION</h4>
<p>Translation is considered a kind of modification, so you may
distribute translations of the Document under the terms of section 4.
Replacing Invariant Sections with translations requires special
permission from their copyright holders, but you may include
translations of some or all Invariant Sections in addition to the
original versions of these Invariant Sections. You may include a
translation of this License, and all the license notices in the
Document, and any Warranty Disclaimers, provided that you also include
the original English version of this License and the original versions
of those notices and disclaimers. In case of a disagreement between
the translation and the original version of this License or a notice
or disclaimer, the original version will prevail.
</p>
<p>If a section in the Document is Entitled "Acknowledgements",
"Dedications", or "History", the requirement (section 4) to Preserve
its Title (section 1) will typically require changing the actual
title.
</p>
<h4>9. TERMINATION</h4>
<p>You may not copy, modify, sublicense, or distribute the Document
except
as expressly provided for under this License. Any other attempt to
copy, modify, sublicense or distribute the Document is void, and will
automatically terminate your rights under this License. However,
parties who have received copies, or rights, from you under this
License will not have their licenses terminated so long as such
parties remain in full compliance.
</p>
<h4>10. FUTURE REVISIONS OF THIS LICENSE</h4>
<p>The Free Software Foundation may publish new, revised versions
of the GNU Free Documentation License from time to time. Such new
versions will be similar in spirit to the present version, but may
differ in detail to address new problems or concerns. See
http://www.gnu.org/copyleft/.
</p>
<p>Each version of the License is given a distinguishing version
number.
If the Document specifies that a particular numbered version of this
License "or any later version" applies to it, you have the option of
following the terms and conditions either of that specified version or
of any later version that has been published (not as a draft) by the
Free Software Foundation. If the Document does not specify a version
number of this License, you may choose any version ever published (not
as a draft) by the Free Software Foundation.
</p>
<br/><br/>

<hr/>

<br/><br/>

<br/><br/>

<a name="GNUGPL"></a>
<center>
<h2><span class="gnu">GNU GENERAL PUBLIC LICENSE</span></h2>
		      <p>Version 3, 29 June 2007</p>
</center>

<p>
 Copyright (C) 2007 Free Software Foundation, Inc. http://fsf.org/
 Everyone is permitted to copy and distribute verbatim copies
 of this license document, but changing it is not allowed.
</p>

<center><h4>Preamble</h4></center>

<p>
  The GNU General Public License is a free, copyleft license for
software and other kinds of works.
</p>
<p>
  The licenses for most software and other practical works are designed
to take away your freedom to share and change the works.  By contrast,
the GNU General Public License is intended to guarantee your freedom to
share and change all versions of a program--to make sure it remains free
software for all its users.  We, the Free Software Foundation, use the
GNU General Public License for most of our software; it applies also to
any other work released this way by its authors.  You can apply it to
your programs, too.
</p>
<p>
  When we speak of free software, we are referring to freedom, not
price.  Our General Public Licenses are designed to make sure that you
have the freedom to distribute copies of free software (and charge for
them if you wish), that you receive source code or can get it if you
want it, that you can change the software or use pieces of it in new
free programs, and that you know you can do these things.
</p>
<p>
  To protect your rights, we need to prevent others from denying you
these rights or asking you to surrender the rights.  Therefore, you have
certain responsibilities if you distribute copies of the software, or if
you modify it: responsibilities to respect the freedom of others.
</p>
<p>
  For example, if you distribute copies of such a program, whether
gratis or for a fee, you must pass on to the recipients the same
freedoms that you received.  You must make sure that they, too, receive
or can get the source code.  And you must show them these terms so they
know their rights.
</p>
<p>
  Developers that use the GNU GPL protect your rights with two steps:
</p>
<p>
(1) assert copyright on the software, and (2) offer you this License
giving you legal permission to copy, distribute and/or modify it.
</p>
<p>
  For the developers' and authors' protection, the GPL clearly explains
that there is no warranty for this free software.  For both users' and
authors' sake, the GPL requires that modified versions be marked as
changed, so that their problems will not be attributed erroneously to
authors of previous versions.
</p>
<p>
  Some devices are designed to deny users access to install or run
modified versions of the software inside them, although the manufacturer
can do so.  This is fundamentally incompatible with the aim of
protecting users' freedom to change the software.  The systematic
pattern of such abuse occurs in the area of products for individuals to
use, which is precisely where it is most unacceptable.  Therefore, we
have designed this version of the GPL to prohibit the practice for those
products.  If such problems arise substantially in other domains, we
stand ready to extend this provision to those domains in future versions
of the GPL, as needed to protect the freedom of users.
</p>
<p>
  Finally, every program is threatened constantly by software patents.
States should not allow patents to restrict development and use of
software on general-purpose computers, but in those that do, we wish to
avoid the special danger that patents applied to a free program could
make it effectively proprietary.  To prevent this, the GPL assures that
patents cannot be used to render the program non-free.
</p>
<p>
  The precise terms and conditions for copying, distribution and
modification follow.
</p>
<center><h4>TERMS AND CONDITIONS</h4></center>

<h4>0. Definitions.</h4>
<p>
  "This License" refers to version 3 of the GNU General Public License.
</p>
<p>
  "Copyright" also means copyright-like laws that apply to other kinds of
works, such as semiconductor masks.
</p>
<p>
  "The Program" refers to any copyrightable work licensed under this
License.  Each licensee is addressed as "you".  "Licensees" and
"recipients" may be individuals or organizations.
</p>
<p>
  To "modify" a work means to copy from or adapt all or part of the work
in a fashion requiring copyright permission, other than the making of an
exact copy.  The resulting work is called a "modified version" of the
earlier work or a work "based on" the earlier work.
</p>
<p>
  A "covered work" means either the unmodified Program or a work based
on the Program.
</p>
<p>
  To "propagate" a work means to do anything with it that, without
permission, would make you directly or secondarily liable for
infringement under applicable copyright law, except executing it on a
computer or modifying a private copy.  Propagation includes copying,
distribution (with or without modification), making available to the
public, and in some countries other activities as well.
</p>
<p>
  To "convey" a work means any kind of propagation that enables other
parties to make or receive copies.  Mere interaction with a user through
a computer network, with no transfer of a copy, is not conveying.
</p>
<p>
  An interactive user interface displays "Appropriate Legal Notices"
to the extent that it includes a convenient and prominently visible
feature that (1) displays an appropriate copyright notice, and (2)
tells the user that there is no warranty for the work (except to the
extent that warranties are provided), that licensees may convey the
work under this License, and how to view a copy of this License.  If
the interface presents a list of user commands or options, such as a
menu, a prominent item in the list meets this criterion.</p>

<h4>1. Source Code.</h4>

<p>
  The "source code" for a work means the preferred form of the work
for making modifications to it.  "Object code" means any non-source
form of a work.
</p>
<p>
  A "Standard Interface" means an interface that either is an official
standard defined by a recognized standards body, or, in the case of
interfaces specified for a particular programming language, one that
is widely used among developers working in that language.
</p>
<p>
  The "System Libraries" of an executable work include anything, other
than the work as a whole, that (a) is included in the normal form of
packaging a Major Component, but which is not part of that Major
Component, and (b) serves only to enable use of the work with that
Major Component, or to implement a Standard Interface for which an
implementation is available to the public in source code form.  A
"Major Component", in this context, means a major essential component
(kernel, window system, and so on) of the specific operating system
(if any) on which the executable work runs, or a compiler used to
produce the work, or an object code interpreter used to run it.
</p>
<p>
  The "Corresponding Source" for a work in object code form means all
the source code needed to generate, install, and (for an executable
work) run the object code and to modify the work, including scripts to
control those activities.  However, it does not include the work's
System Libraries, or general-purpose tools or generally available free
programs which are used unmodified in performing those activities but
which are not part of the work.  For example, Corresponding Source
includes interface definition files associated with source files for
the work, and the source code for shared libraries and dynamically
linked subprograms that the work is specifically designed to require,
such as by intimate data communication or control flow between those
subprograms and other parts of the work.
</p>
<p>
  The Corresponding Source need not include anything that users
can regenerate automatically from other parts of the Corresponding
Source.
</p>
<p>
  The Corresponding Source for a work in source code form is that
same work.
</p>
<h4>2. Basic Permissions.</h4>
<p>
  All rights granted under this License are granted for the term of
copyright on the Program, and are irrevocable provided the stated
conditions are met.  This License explicitly affirms your unlimited
permission to run the unmodified Program.  The output from running a
covered work is covered by this License only if the output, given its
content, constitutes a covered work.  This License acknowledges your
rights of fair use or other equivalent, as provided by copyright law.
</p>
<p>
  You may make, run and propagate covered works that you do not
convey, without conditions so long as your license otherwise remains
in force.  You may convey covered works to others for the sole purpose
of having them make modifications exclusively for you, or provide you
with facilities for running those works, provided that you comply with
the terms of this License in conveying all material for which you do
not control copyright.  Those thus making or running the covered works
for you must do so exclusively on your behalf, under your direction
and control, on terms that prohibit them from making any copies of
your copyrighted material outside their relationship with you.
</p>
<p>
  Conveying under any other circumstances is permitted solely under
the conditions stated below.  Sublicensing is not allowed; section 10
makes it unnecessary.
</p>
<h4>3. Protecting Users' Legal Rights From Anti-Circumvention Law.</h4>
<p>
  No covered work shall be deemed part of an effective technological
measure under any applicable law fulfilling obligations under article
11 of the WIPO copyright treaty adopted on 20 December 1996, or
similar laws prohibiting or restricting circumvention of such
measures.
</p>
<p>
  When you convey a covered work, you waive any legal power to forbid
circumvention of technological measures to the extent such circumvention
is effected by exercising rights under this License with respect to
the covered work, and you disclaim any intention to limit operation or
modification of the work as a means of enforcing, against the work's
users, your or third parties' legal rights to forbid circumvention of
technological measures.
</p>
<h4>4. Conveying Verbatim Copies.</h4>
<p>
 You may convey verbatim copies of the Program's source code as you
receive it, in any medium, provided that you conspicuously and
appropriately publish on each copy an appropriate copyright notice;
keep intact all notices stating that this License and any
non-permissive terms added in accord with section 7 apply to the code;
keep intact all notices of the absence of any warranty; and give all
recipients a copy of this License along with the Program.
</p>
<p>
  You may charge any price or no price for each copy that you convey,
and you may offer support or warranty protection for a fee.
</p>
<h4>5. Conveying Modified Source Versions.</h4>
<p>
  You may convey a work based on the Program, or the modifications to
produce it from the Program, in the form of source code under the
terms of section 4, provided that you also meet all of these conditions:
</p>
<blockquote>
    a) The work must carry prominent notices stating that you modified
    it, and giving a relevant date.
</blockquote>
<blockquote>
    b) The work must carry prominent notices stating that it is
    released under this License and any conditions added under section
    7.  This requirement modifies the requirement in section 4 to
    "keep intact all notices".
</blockquote>
<blockquote>
    c) You must license the entire work, as a whole, under this
    License to anyone who comes into possession of a copy.  This
    License will therefore apply, along with any applicable section 7
    additional terms, to the whole of the work, and all its parts,
    regardless of how they are packaged.  This License gives no
    permission to license the work in any other way, but it does not
    invalidate such permission if you have separately received it.
</blockquote>
<blockquote>
    d) If the work has interactive user interfaces, each must display
    Appropriate Legal Notices; however, if the Program has interactive
    interfaces that do not display Appropriate Legal Notices, your
    work need not make them do so.
</blockquote>
<p>
  A compilation of a covered work with other separate and independent
works, which are not by their nature extensions of the covered work,
and which are not combined with it such as to form a larger program,
in or on a volume of a storage or distribution medium, is called an
"aggregate" if the compilation and its resulting copyright are not
used to limit the access or legal rights of the compilation's users
beyond what the individual works permit.  Inclusion of a covered work
in an aggregate does not cause this License to apply to the other
parts of the aggregate.
</p>
<h4>6. Conveying Non-Source Forms.</h4>
<p>
  You may convey a covered work in object code form under the terms
of sections 4 and 5, provided that you also convey the
machine-readable Corresponding Source under the terms of this License,
in one of these ways:
</p>
<blockquote>
    a) Convey the object code in, or embodied in, a physical product
    (including a physical distribution medium), accompanied by the
    Corresponding Source fixed on a durable physical medium
    customarily used for software interchange.
</blockquote>
<blockquote>
    b) Convey the object code in, or embodied in, a physical product
    (including a physical distribution medium), accompanied by a
    written offer, valid for at least three years and valid for as
    long as you offer spare parts or customer support for that product
    model, to give anyone who possesses the object code either (1) a
    copy of the Corresponding Source for all the software in the
    product that is covered by this License, on a durable physical
    medium customarily used for software interchange, for a price no
    more than your reasonable cost of physically performing this
    conveying of source, or (2) access to copy the
    Corresponding Source from a network server at no charge.
</blockquote>
<blockquote>
    c) Convey individual copies of the object code with a copy of the
    written offer to provide the Corresponding Source.  This
    alternative is allowed only occasionally and noncommercially, and
    only if you received the object code with such an offer, in accord
    with subsection 6b.
</blockquote>
<blockquote>
    d) Convey the object code by offering access from a designated
    place (gratis or for a charge), and offer equivalent access to the
    Corresponding Source in the same way through the same place at no
    further charge.  You need not require recipients to copy the
    Corresponding Source along with the object code.  If the place to
    copy the object code is a network server, the Corresponding Source
    may be on a different server (operated by you or a third party)
    that supports equivalent copying facilities, provided you maintain
    clear directions next to the object code saying where to find the
    Corresponding Source.  Regardless of what server hosts the
    Corresponding Source, you remain obligated to ensure that it is
    available for as long as needed to satisfy these requirements.
</blockquote>
<blockquote>
    e) Convey the object code using peer-to-peer transmission, provided
    you inform other peers where the object code and Corresponding
    Source of the work are being offered to the general public at no
    charge under subsection 6d.
</blockquote>
<p>
  A separable portion of the object code, whose source code is excluded
from the Corresponding Source as a System Library, need not be
included in conveying the object code work.
</p>
<p>
  A "User Product" is either (1) a "consumer product", which means any
tangible personal property which is normally used for personal, family,
or household purposes, or (2) anything designed or sold for incorporation
into a dwelling.  In determining whether a product is a consumer product,
doubtful cases shall be resolved in favor of coverage.  For a particular
product received by a particular user, "normally used" refers to a
typical or common use of that class of product, regardless of the status
of the particular user or of the way in which the particular user
actually uses, or expects or is expected to use, the product.  A product
is a consumer product regardless of whether the product has substantial
commercial, industrial or non-consumer uses, unless such uses represent
the only significant mode of use of the product.
</p>
<p>
  "Installation Information" for a User Product means any methods,
procedures, authorization keys, or other information required to install
and execute modified versions of a covered work in that User Product from
a modified version of its Corresponding Source.  The information must
suffice to ensure that the continued functioning of the modified object
code is in no case prevented or interfered with solely because
modification has been made.
</p>
<p>
  If you convey an object code work under this section in, or with, or
specifically for use in, a User Product, and the conveying occurs as
part of a transaction in which the right of possession and use of the
User Product is transferred to the recipient in perpetuity or for a
fixed term (regardless of how the transaction is characterized), the
Corresponding Source conveyed under this section must be accompanied
by the Installation Information.  But this requirement does not apply
if neither you nor any third party retains the ability to install
modified object code on the User Product (for example, the work has
been installed in ROM).
</p>
<p>
  The requirement to provide Installation Information does not include a
requirement to continue to provide support service, warranty, or updates
for a work that has been modified or installed by the recipient, or for
the User Product in which it has been modified or installed.  Access to a
network may be denied when the modification itself materially and
adversely affects the operation of the network or violates the rules and
protocols for communication across the network.
</p>
<p>
  Corresponding Source conveyed, and Installation Information provided,
in accord with this section must be in a format that is publicly
documented (and with an implementation available to the public in
source code form), and must require no special password or key for
unpacking, reading or copying.
</p>
<h4>7. Additional Terms.</h4>
<p>
  "Additional permissions" are terms that supplement the terms of this
License by making exceptions from one or more of its conditions.
Additional permissions that are applicable to the entire Program shall
be treated as though they were included in this License, to the extent
that they are valid under applicable law.  If additional permissions
apply only to part of the Program, that part may be used separately
under those permissions, but the entire Program remains governed by
this License without regard to the additional permissions.
</p>
<p>
  When you convey a copy of a covered work, you may at your option
remove any additional permissions from that copy, or from any part of
it.  (Additional permissions may be written to require their own
removal in certain cases when you modify the work.)  You may place
additional permissions on material, added by you to a covered work,
for which you have or can give appropriate copyright permission.
</p>
<p>
  Notwithstanding any other provision of this License, for material you
add to a covered work, you may (if authorized by the copyright holders of
that material) supplement the terms of this License with terms:
</p>
<blockquote>
    a) Disclaiming warranty or limiting liability differently from the
    terms of sections 15 and 16 of this License; or
</blockquote>
<blockquote>
    b) Requiring preservation of specified reasonable legal notices or
    author attributions in that material or in the Appropriate Legal
    Notices displayed by works containing it; or
</blockquote>
<blockquote>
    c) Prohibiting misrepresentation of the origin of that material, or
    requiring that modified versions of such material be marked in
    reasonable ways as different from the original version; or
</blockquote>
<blockquote>
    d) Limiting the use for publicity purposes of names of licensors or
    authors of the material; or
</blockquote>
<blockquote>
    e) Declining to grant rights under trademark law for use of some
    trade names, trademarks, or service marks; or
</blockquote>
<blockquote>
    f) Requiring indemnification of licensors and authors of that
    material by anyone who conveys the material (or modified versions of
    it) with contractual assumptions of liability to the recipient, for
    any liability that these contractual assumptions directly impose on
    those licensors and authors.
</blockquote>
<p>
  All other non-permissive additional terms are considered "further
restrictions" within the meaning of section 10.  If the Program as you
received it, or any part of it, contains a notice stating that it is
governed by this License along with a term that is a further
restriction, you may remove that term.  If a license document contains
a further restriction but permits relicensing or conveying under this
License, you may add to a covered work material governed by the terms
of that license document, provided that the further restriction does
not survive such relicensing or conveying.
</p>
<p>
  If you add terms to a covered work in accord with this section, you
must place, in the relevant source files, a statement of the
additional terms that apply to those files, or a notice indicating
where to find the applicable terms.
</p>
<p>
  Additional terms, permissive or non-permissive, may be stated in the
form of a separately written license, or stated as exceptions;
the above requirements apply either way.
</p>
<h4>8. Termination.</h4>
<p>
  You may not propagate or modify a covered work except as expressly
provided under this License.  Any attempt otherwise to propagate or
modify it is void, and will automatically terminate your rights under
this License (including any patent licenses granted under the third
paragraph of section 11).
</p>
<p>
  However, if you cease all violation of this License, then your
license from a particular copyright holder is reinstated (a)
provisionally, unless and until the copyright holder explicitly and
finally terminates your license, and (b) permanently, if the copyright
holder fails to notify you of the violation by some reasonable means
prior to 60 days after the cessation.
</p>
<p>
  Moreover, your license from a particular copyright holder is
reinstated permanently if the copyright holder notifies you of the
violation by some reasonable means, this is the first time you have
received notice of violation of this License (for any work) from that
copyright holder, and you cure the violation prior to 30 days after
your receipt of the notice.
</p>
<p>
  Termination of your rights under this section does not terminate the
licenses of parties who have received copies or rights from you under
this License.  If your rights have been terminated and not permanently
reinstated, you do not qualify to receive new licenses for the same
material under section 10.
</p>
<h4>9. Acceptance Not Required for Having Copies.</h4>
<p>
  You are not required to accept this License in order to receive or
run a copy of the Program.  Ancillary propagation of a covered work
occurring solely as a consequence of using peer-to-peer transmission
to receive a copy likewise does not require acceptance.  However,
nothing other than this License grants you permission to propagate or
modify any covered work.  These actions infringe copyright if you do
not accept this License.  Therefore, by modifying or propagating a
covered work, you indicate your acceptance of this License to do so.
</p>
<h4>10. Automatic Licensing of Downstream Recipients.</h4>
<p>
  Each time you convey a covered work, the recipient automatically
receives a license from the original licensors, to run, modify and
propagate that work, subject to this License.  You are not responsible
for enforcing compliance by third parties with this License.
</p>
<p>
  An "entity transaction" is a transaction transferring control of an
organization, or substantially all assets of one, or subdividing an
organization, or merging organizations.  If propagation of a covered
work results from an entity transaction, each party to that
transaction who receives a copy of the work also receives whatever
licenses to the work the party's predecessor in interest had or could
give under the previous paragraph, plus a right to possession of the
Corresponding Source of the work from the predecessor in interest, if
the predecessor has it or can get it with reasonable efforts.
</p>
<p>
  You may not impose any further restrictions on the exercise of the
rights granted or affirmed under this License.  For example, you may
not impose a license fee, royalty, or other charge for exercise of
rights granted under this License, and you may not initiate litigation
(including a cross-claim or counterclaim in a lawsuit) alleging that
any patent claim is infringed by making, using, selling, offering for
sale, or importing the Program or any portion of it.
</p>
<h4>11. Patents.</h4>
<p>
  A "contributor" is a copyright holder who authorizes use under this
License of the Program or a work on which the Program is based.  The
work thus licensed is called the contributor's "contributor version".
</p>
<p>
  A contributor's "essential patent claims" are all patent claims
owned or controlled by the contributor, whether already acquired or
hereafter acquired, that would be infringed by some manner, permitted
by this License, of making, using, or selling its contributor version,
but do not include claims that would be infringed only as a
consequence of further modification of the contributor version.  For
purposes of this definition, "control" includes the right to grant
patent sublicenses in a manner consistent with the requirements of
this License.
</p>
<p>
  Each contributor grants you a non-exclusive, worldwide, royalty-free
patent license under the contributor's essential patent claims, to
make, use, sell, offer for sale, import and otherwise run, modify and
propagate the contents of its contributor version.
</p>
<p>
  In the following three paragraphs, a "patent license" is any express
agreement or commitment, however denominated, not to enforce a patent
(such as an express permission to practice a patent or covenant not to
sue for patent infringement).  To "grant" such a patent license to a
party means to make such an agreement or commitment not to enforce a
patent against the party.
</p>
<p>
  If you convey a covered work, knowingly relying on a patent license,
and the Corresponding Source of the work is not available for anyone
to copy, free of charge and under the terms of this License, through a
publicly available network server or other readily accessible means,
then you must either (1) cause the Corresponding Source to be so
available, or (2) arrange to deprive yourself of the benefit of the
patent license for this particular work, or (3) arrange, in a manner
consistent with the requirements of this License, to extend the patent
license to downstream recipients.  "Knowingly relying" means you have
actual knowledge that, but for the patent license, your conveying the
covered work in a country, or your recipient's use of the covered work
in a country, would infringe one or more identifiable patents in that
country that you have reason to believe are valid.
</p>
<p>
  If, pursuant to or in connection with a single transaction or
arrangement, you convey, or propagate by procuring conveyance of, a
covered work, and grant a patent license to some of the parties
receiving the covered work authorizing them to use, propagate, modify
or convey a specific copy of the covered work, then the patent license
you grant is automatically extended to all recipients of the covered
work and works based on it.
</p>
<p>
  A patent license is "discriminatory" if it does not include within
the scope of its coverage, prohibits the exercise of, or is
conditioned on the non-exercise of one or more of the rights that are
specifically granted under this License.  You may not convey a covered
work if you are a party to an arrangement with a third party that is
in the business of distributing software, under which you make payment
to the third party based on the extent of your activity of conveying
the work, and under which the third party grants, to any of the
parties who would receive the covered work from you, a discriminatory
patent license (a) in connection with copies of the covered work
conveyed by you (or copies made from those copies), or (b) primarily
for and in connection with specific products or compilations that
contain the covered work, unless you entered into that arrangement,
or that patent license was granted, prior to 28 March 2007.
</p>
<p>
  Nothing in this License shall be construed as excluding or limiting
any implied license or other defenses to infringement that may
otherwise be available to you under applicable patent law.
</p>
<h4>12. No Surrender of Others' Freedom.</h4>
<p>
  If conditions are imposed on you (whether by court order, agreement or
otherwise) that contradict the conditions of this License, they do not
excuse you from the conditions of this License.  If you cannot convey a
covered work so as to satisfy simultaneously your obligations under this
License and any other pertinent obligations, then as a consequence you may
not convey it at all.  For example, if you agree to terms that obligate you
to collect a royalty for further conveying from those to whom you convey
the Program, the only way you could satisfy both those terms and this
License would be to refrain entirely from conveying the Program.
</p>
<h4>13. Use with the GNU Affero General Public License.</h4>
<p>
  Notwithstanding any other provision of this License, you have
permission to link or combine any covered work with a work licensed
under version 3 of the GNU Affero General Public License into a single
combined work, and to convey the resulting work.  The terms of this
License will continue to apply to the part which is the covered work,
but the special requirements of the GNU Affero General Public License,
section 13, concerning interaction through a network will apply to the
combination as such.
</p>
<h4>14. Revised Versions of this License.</h4>
<p>
  The Free Software Foundation may publish revised and/or new versions of
the GNU General Public License from time to time.  Such new versions will
be similar in spirit to the present version, but may differ in detail to
address new problems or concerns.
</p>
<p>
  Each version is given a distinguishing version number.  If the
Program specifies that a certain numbered version of the GNU General
Public License "or any later version" applies to it, you have the
option of following the terms and conditions either of that numbered
version or of any later version published by the Free Software
Foundation.  If the Program does not specify a version number of the
GNU General Public License, you may choose any version ever published
by the Free Software Foundation.
</p>
<p>
  If the Program specifies that a proxy can decide which future
versions of the GNU General Public License can be used, that proxy's
public statement of acceptance of a version permanently authorizes you
to choose that version for the Program.
</p>
<p>
  Later license versions may give you additional or different
permissions.  However, no additional obligations are imposed on any
author or copyright holder as a result of your choosing to follow a
later version.
</p>
<h4>15. Disclaimer of Warranty.</h4>
<p>
  THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY
APPLICABLE LAW.  EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY
OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO,
THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
PURPOSE.  THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM
IS WITH YOU.  SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF
ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
</p>
<h4>16. Limitation of Liability.</h4>
<p>
  IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS
THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY
GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE
USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF
DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD
PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS),
EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF
SUCH DAMAGES.
</p>
<h4>17. Interpretation of Sections 15 and 16.</h4>
<p>
  If the disclaimer of warranty and limitation of liability provided
above cannot be given local legal effect according to their terms,
reviewing courts shall apply local law that most closely approximates
an absolute waiver of all civil liability in connection with the
Program, unless a warranty or assumption of liability accompanies a
copy of the Program in return for a fee.
</p>
<br/>
<center><h4>END OF TERMS AND CONDITIONS</h4></center>
</div>
<br/><br/>
<center style="font-size: 150%">
<span class="divider">(&nbsp;<font color="#7ba9d4">&part;</font>&nbsp;)</span>
</center>
<br/><br/>

</body>
</html>