User Manual and Reference v.10.7.5

Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.2 or any later version
published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts,
and no Back-Cover Texts. A copy of the license is included in the section entitled
GNU Free Documentation License.
The accompanying software is protected by the
GNU General Public License V.3, June 2007.
newLISP is a registered trademark of Lutz Mueller.

newLISP User Manual

1. Introduction

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

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.

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.

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 Classes in FOOP
(Functional Object Oriented Programming), (3) the definition of functions with
state and (4) the creation of Hash trees for associative key → value storage.

newLISP allocates and reclaims memory automatically, without using traditional
asynchronous garbage collection.
All objects — except for contexts, built-in primitives, and symbols —
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
data equals program paradigm and full self reflection.

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.

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

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.

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 — Perl Compatible Regular Expressions (PCRE)
and text-parsing functions — 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.

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

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.

Since version 10.5.7, newLISP also can be compiled to JavaScript and run in
a web browser.

2. Deprecated functions since version 10.3.0

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

The old writing parse-date of date-parse
is still recognized but deprecated since version 10.3.0. The old writing will
be removed in a future version.

Since version 10.4.2 if-not is deprecated and will be removed in a
future version.

Since version 10.4.6 newLISP has a built-in function
json-parse for translating JSON data into S-expressions. The module
file json.lsp is removed from the distribution.

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

( § )

3. Interactive Lisp mode

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.

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:

>
(define (foo x y)
(+ x y))
(lambda (x y) (+ x y))
> (foo 3 4)
7
>

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

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

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

The mode can also be used to call an editor or any other program:

> !vi foo.lsp

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

> (load "foo.lsp")

The program foo.lsp is now run.

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

> (pri
print println primitive?
> (pri

After entering the characters (pri 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.

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

set blink-matching-paren on

Not all systems have a version of libreadline advanced enough for
this to work.

( § )

4. Command-line options, startup and directories

Command line help summary

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

newlisp -h

in a command shell will produce the following summary of options and switches:

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 (exit) statement, else newLISP
will take command-line parameters as additional newLISP scripts to be
loaded and executed.

On Linux and other Unix systems, a newlispman page
can be found:

man newlisp

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

Specifying files as URLs

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

Stack size

The above examples show starting newLISP with different stack sizes using
the -s 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.

Maximum memory usage

newlisp -m 128

This example limits newLISP cell memory to 128 megabytes. In 32-bit newLISP,
each Lisp cell consumes 16 bytes, so the argument 128 would
represent a maximum of 8,388,608 newLISP cells. This information is returned
by sys-info 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.

Direct execution mode

Small pieces of newLISP code can be executed directly from the command-line:

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
-e and the quoted command string.

Logging I/O

In any mode, newLISP can write a log when started with the -l or -L
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 -l or -L option.
If the file does not exist, it is created when the first logging output is written.

All logging output is written to the file specified after the -l
or -L option.

Specifying the working directory

The -w option specifies the initial working directory for newLISP
after startup:

newlisp -w /usr/home/newlisp

All file requests without a directory path will now be directed to the path
specified with the -w option.

Suppressing the prompt and HTTP processing

The command-line prompt and initial copyright banner can be suppressed:

newlisp -c

Listen and connection messages are suppressed if logging is not enabled.
The -c option is useful when controlling newLISP
from other programs; it is mandatory when setting it up
as a net-eval server.

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

newlisp -c -d 8080 -w /usr/home/www

When running newLISP as a inetd or xinetd enabled
server on Unix machines, use:

newlisp -c -w /usr/home/www

In -c mode, newLISP processes command-line requests as well as
HTTP and net-eval 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
net-eval and command-line–like requests, use
the safer -http option.

Forcing prompts in pipe I/O mode

To suppress console output from return values from evaluations,
use silent.

newLISP as a TCP/IP server

newlisp some.lsp -p 9090

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 -p option. some.lsp is an optional file loaded during
startup, before listening for a connection begins.

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

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

newlisp -p 4711 &

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

telnet localhost 4711

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

When the client application closes the connection, newLISP will exit, too.

TCP/IP daemon mode

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

newlisp -d 4711 &

This works like the -p 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 exit 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 4711.

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

When running in -p or -d mode, the opening and closing tags
[cmd] and [/cmd] 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.

The following variant of the -d mode is frequently used in a
distributed computing environment, together with
net-eval on the client side:

newlisp -c -d 4711 &

The -c spec suppresses prompts, making this mode suitable
for receiving requests from the net-eval function.

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

HTTP-only server mode

newLISP can be limited to HTTP processing using the -http option.
With this mode, a secure httpd web server daemon can be configured:

newlisp -http -d 8080 -w /usr/home/www

When running newLISP as an inetd or xinetd-enabled
server on Unix machines, use:

newlisp -http -w /usr/home/www

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

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

The file httpd-conf.lsp contains a command-event
function configuring a user-defined function to analyze, filter and translate requests.
See the reference for this function for a working example.

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

file extension

media type

.avi

video/x-msvideo

.css

text/css

.gif

image/gif

.htm

text/htm

.html

text/html

.jpg

image/jpg

.js

application/javascript

.mov

video/quicktime

.mp3

audio/mpeg

.mpg

video/mpeg

.pdf

application/pdf

.png

image/png

.wav

audio/x-wav

.zip

application/zip

any other

text/plain

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

In both server modes -c and -http 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 env function.

Local domain Unix socket server

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

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.

Connection timeout

Specifies a connection timeout when running in -p or -d
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:

newlisp -c -t 3000000 -d 4711 &

The example specifies a timeout of three seconds.

inetd daemon mode

The inetd 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. inetd starts a newLISP
process for each client connection. When a client disconnects, the connection
is closed and the newLISP process exits.

inetd 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 net-eval, this mode is
preferred for efficiently handling multiple requests in a distributed computing
environment.

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

For security reasons, root should be changed to a different user
and file permissions of the www document directory adjusted accordingly.
The only_from spec can be left out to permit remote access.

See the man pages for xinetd and xinetd.conf
for other configuration options.

After configuring the daemon, inetd or
xinetd must be restarted to
allow the new or changed configuration files to be read:

kill -HUP <pid>

Replace <pid> with the process ID of the
running xinetd process.

A number or network protocol other than 4711 or TCP can be specified.

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

telnet localhost 4711

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

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

uppercase "convert me to uppercase"

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

./uppercase "convert me to uppercase"

The console should print:

CONVERT ME TO UPPERCASE

Note that neither one of the initialization files init.lsp nor
.init.lsp is loaded during startup of linked programs.

( § )

5. Startup, directories, environment

Environment variable NEWLISPDIR

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

The environment variable NEWLISPDIR is useful when loading files
installed with newLISP:

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

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

(module "mysql.lsp")

The initialization file init.lsp

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

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

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

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

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

Directories on Linux, BSD, macOS and other Unix

Directories on MS Windows

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

( § )

6. Extending newLISP with shared libraries

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.

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

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 ⚠ character linking
to this chapter.

7. newLISP as a shared library

newLISP as C library

newLISP can be compiled as a shared C library. On Linux, BSDs and other Unix
flavors the library is called newlisp.so. On Windows it is called
newlisp.dll and newlisp.dylib 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.

The main function to import is newlispEvalStr. Like
eval-string, this function takes a string containing
a newLISP expression and stores the result in a string address. The result can
be retrieved using get-string. The returned string
is formatted like output from a command-line session. It contains terminating
line-feed characters, but not the prompt string.

When calling newlispEvalStr, output normally directed to the
console (e.g. return values or print statements) is
returned in the form of an integer string pointer. The output can be accessed
by passing this pointer to the get-string function. To silence the
output from return values, use the silent function.

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

newLISP as a JavaScript library

Since version 10.5.7, newLISP can be compiled to JavaScript using the
Emscripten
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 newlisp-js-x.x.x.zip
distribution package which contains the library newlisp-js-lib.js,
documentaion and example applications. A small newLISP development
environment hosted in a browser can also be accessed here:
newlisp-js
The application contains links to another example application,
documentation and a download link for the whole package.

8. Evaluating newLISP expressions

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

Top-level expressions are evaluated when using the
load function or when entering expressions in console
mode on the command-line.

Interactive multiline expressions

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

>
(define (foo x y)
(+ x y))
(lambda (x y) (+ x y))
> (foo 3 4)
7
> _

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.

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

Integer, floating point data and operators

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.

The symbol operators
(+-*/%$~|^<<>>) return values of type integer. Functions and operators named
with a word instead of a symbol (e.g., add rather than +)
return floating point numbers. Integer operators truncate floating point
numbers to integers, discarding the fractional parts.

newLISP has two types of basic arithmetic operators: integer (+-*/) and floating point (addsubmuldiv). 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
+, -, *, and / can be redefined to
perform the floating point operators add, sub,
mul, and div:

Now the common arithmetic operators +, -, *,
and / accept both integer and floating point numbers and return
floating point results.

Care must be taken when importing from libraries
that use functions expecting integers. After redefining +, -, *,
and /, 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
int. Likewise, integers can be transformed into
floating point numbers using the float function:

Some of the modules shipping with newLISP are written assuming the
default implementations of +, -, *, and /.
This gives imported library functions maximum speed when performing address
calculations.

The newLISP preference is to leave +, -, *, and
/ defined as integer operators and use add, sub,
mul, and div 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.

Big integer, multiple precision arithmetic

The following operators, functions and predicates work on big integers:

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
Function Reference section of this manual
these are marked with a bigint
suffix.

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
bigint can be used to convert from integer, float or string
format to big integer. The predicate bigint? checks for
big integer type.

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

; because the first argument is 64-bit, no big integer arithmetic
; will be done, although the second argument is big integer
(+ 123 12345L)
→ 12468
; the second argument is recognized as a big integer
; and overflows the capacity of a 64-bit integer
(+ 123 123453456735645634565463563546)
→ERR: number overflows in function +
; now the first argument converts to big integer and the
; whole expression evaluates in big integer mode
(+ 123L 123453456735645634565463563546)
→ 123453456735645634565463563669L

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.

Evaluation rules and data types

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 load function.

A line comment begins with a ; (semicolon) or a # (number sign)
and extends to the end of the line. newLISP ignores this line during evaluation.
The # is useful when using newLISP as a scripting language in
Linux/Unix environments, where the # is commonly used as a line comment
in scripts and shells.

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

The following examples can be entered on the command-line by typing the code
to the left of the → symbol. The
result that appears on the next line should match the code to the right of the
→ symbol.

nil and true are Boolean data types that
evaluate to themselves:

nil → nil
true → true

Integers, big integers and floating point numbers evaluate to themselves:

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.

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

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

bytes = 4 * ceil(digits / 9) + 4.

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

Strings may contain null characters and can have different
delimiters. They evaluate to themselves.

In the above example, the number between the < > (angle brackets)
is the hexadecimal memory address (machine-dependent) of the
add function. It is displayed when printing a built-in primitive.

Quoted expressions lose one ' (single quote) when evaluated:

'something → something
''''any → '''any
'(a b c d) → (a b c d)

A single quote is often used to protect 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).

Lists 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 lambda expression, lambda-macro
expression, or primitive (built-in) function.

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.

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

((if (> X 10) * +) X Y)

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

Because their arguments are not evaluated, lambda-macro
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 special forms.

Shell commands: If an ! (exclamation mark)
is entered as the first character on the command-line followed by a shell
command, the command will be executed. For example, !ls on Unix or
!dir on MS Windows will display a listing of the present working directory.
No spaces are permitted between the ! and the shell command. Symbols
beginning with an ! 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.

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

Use the exec function to access shell commands from
other applications or to pass results back to newLISP.

( § )

9. Lambda expressions in newLISP

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

Note: No ' is necessary before the lambda expression because
lambda expressions evaluate to themselves in newLISP.

The second line uses the keyword fn, an alternative syntax first suggested
by Paul Graham for his Arc language project.

A lambda expression is a lambda list, a subtype of list, and its
arguments can associate from left to right or right to left. When using
append, for example, the arguments associate from left to right:

All arguments are optional when applying lambda expressions and default to nil
when not supplied by the user. This makes it possible to write functions with
multiple parameter signatures.

( § )

10. nil, true, cons, and ()

In newLISP, nil and true represent both the symbols and the
Boolean values false and true. Depending on their context,
nil and true are treated differently. The following examples use
nil, but they can be applied to true by simply reversing the logic.

Evaluation of nil yields a Boolean false and is treated as such inside
flow control expressions such as if, unless, while,
until, and not. Likewise, evaluating true yields true.

In newLISP, nil and the empty list () are not the same as in
some other Lisps. Only in conditional expressions are they treated as a Boolean
false, as in and, or, if, while,
unless, until, and cond.

Evaluation of (cons 'x '()) yields (x), but (cons 'x nil)
yields (x nil) because nil is treated as a Boolean value when
evaluated, not as an empty list. The cons of two atoms in newLISP
does not yield a dotted pair, but rather a two-element list. The predicate
atom? is true for nil, but false for the empty list. The empty
list in newLISP is only an empty list and not equal to nil.

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
dotted pair in newLISP because the cdr (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 car (head) part may contain a basic data type.
Early Lisp implementations used car and cdr for the names
head and tail.

( § )

11. Arrays

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

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

12. Indexing elements of strings, lists, and arrays

Some functions take array, list, or string elements (characters)
specified by one or more int-index (integer index). The positive
indices run 0, 1, …, N-2, N-1, where N is the
number of elements in the list. If int-index is negative, the sequence
is -N, -N+1, …, -2, -1. Adding N to the negative
index of an element yields the positive index. Unless a function does
otherwise, an index greater than N-1 or less then -N causes an
out-of-bounds error in lists and arrays.

Implicit indexing for nth

Implicit indexing can be used instead of nth to
retrieve the elements of a list or array or the characters of a string:

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.

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

Note that in the UTF-8–enabled version of newLISP, implicit indexing
of strings or using the nth function work on character rather
than single-byte boundaries.

Implicit indexing and the default functor

The default functor is a functor inside a context with the same
name as the context itself. See The context
default function chapter. A default functor can be used together with
implicit indexing to serve as a mechanism for referencing lists:

The functions rest, first
and last 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
find and regex are also in single-byte
counts and can be further processed with slice or it's
implicit form.

Modify references in lists, arrays and strings

Parts in lists, arrays and strings referenced by indices can be modified using
setf:

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 setf, 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.

( § )

13. Destructive versus nondestructive functions

Most of the primitives in newLISP are nondestructive (no side effects)
and leave existing objects untouched, although they may create new ones. There
are a few destructive functions, however, that do change the contents of a
variable, list, array, or string:

14. Early return from functions, loops, and blocks

What follows are methods of interrupting the control flow inside both
loops and the begin expression.

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

Using catch and throw

Because newLISP is a functional language, it uses no break or
return statements to exit functions or iterations. Instead, a
block or function can be exited at any point using the functions
catch and throw:

Using and and or

Using the logical functions and and
or, blocks of statements can be built
that are exited depending on the Boolean result of the enclosed functions:

(and
(func-a)
(func-b)
(func-c)
(func-d))

The and expression will return as soon as one of the
block's functions returns nil or an () (empty list).
If none of the preceding functions causes an exit from the block, the
result of the last function is returned.

The result of the or expression will be the first function
that returns a value which is notnil or ().

( § )

15. Dynamic and lexical scoping

newLISP uses dynamic scoping inside contexts. A context is a lexically
closed namespace. In this way, parts of a newLISP program can live in different
namespaces taking advantage of lexical scoping.

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.

The following example illustrates the dynamic scoping mechanism.
The text in bold is the output from newLISP:

The variable x is first set to 1. But when (g 0)
is called, x is bound to 0 and x is reported
by (f) as 0 during execution of (g 0). After
execution of (g 0), the call to (f) will report x as 1 again.

This is different from the lexical scoping 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, (f) would
always print the global bindings of the symbol x with 1.

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:

One or more user-defined functions can be placed in their own namespace called
a context. A symbol name clash cannot occur when accessing
symbols and calling functions from outside of the defining context.

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.

newLISP uses contexts for different forms of lexical scoping. See the
chapters Contexts and
default functors for more information.

( § )

16. Contexts

In newLISP, symbols can be separated into namespaces called contexts.
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.

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 lexical scoping and software object styles of programming.

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

In addition to context names, MAIN contains the symbols for built-in
functions and special symbols such as true and nil. The MAIN
context is created automatically each time newLISP is run. To see all the symbols
in MAIN, enter the following expression after starting newLISP:

(symbols)

To see all symbols in MAIN pointing to contexts:

(filter context? (map eval (symbols)))

To seel all context symbols in MAIN when MAIN is not the
current context:

(filter context? (map eval (symbols MAIN)))

Symbol creation in contexts

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

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.

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

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 MAIN for a
built-in function, context, or global symbol. If no definition
is found, the symbol is created locally inside the current context.

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 delete function.

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

A context switch only influences symbol creation during
load, sym,
or eval-string.
load 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
sym and eval-string
are used. A context switch should normally only be made on the top level of
a program, never inside a function.

Creating contexts

Contexts can be created either by using the context
function or via implicit creation. The first method is used when writing larger
portions of code belonging to the same context:

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.

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

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

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

FOO:var → 123
(FOO:func p q r)

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

The symbols function is used to show all symbols
belonging to a context:

A context is implicitly created when referring to one that does not yet exist.
Unlike the context function, the context is not switched. The following
statements are all executed inside the MAIN context:

> (set 'ACTX:var "hello")
"hello"
> ACTX:var
"hello"
> _

Note that only the symbols prefixed with their context name will be part
of the context:

(define (ACTX:foo x y)
(+ x y))

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

When loading source files on the command-line with load,
or when executing the functions eval-string or
sym, the context function tells the newLISP source
code reader in which namespace to put all of the symbols and definitions:

The draw-triangle and draw-circle functions — along
with their x, y, and z parameters — are now
part of the GRAPH context. These symbols are known only to GRAPH.
To call these functions from another context, prefix them with GRAPH:

(GRAPH:draw-triangle 1 2 3)
(GRAPH:foo) → GRAPH

The last statement shows how the runtime context has changed to
GRAPH (function foo's context).

A symbol's name and context are used when comparing symbols from different
contexts. The term function can be used to extract the term
part from a fully qualified symbol.

Without the global statement, the second aVar would have
returned nil instead of 123. If FOO had a previously
defined symbol (aVar in this example) that symbol's value
— and not the global's — would be returned instead. Note that only
symbols from the MAIN context can be made global.

Once it is made visible to contexts through the global function,
a symbol cannot be hidden from them again.

Symbol protection

By using the constant function, symbols can be both set
and protected from change at the same time:

Loading the file causes an error message for FOO, but not
for ABC. When the first context FOO is loaded, the
context ABC does not exist yet, so a local variable FOO:ABC
gets created. When ABC loads, FOO already exists as a global
protected symbol and will be correctly flagged as protected.

FOO could still be used as a local variable in the ABC
context by explicitly prefixing it, as in ABC:FOO.

Contexts as programming modules

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.

The modules, 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 newLISPdoc utility.

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:

Loading and declaring contexts

Module files are loaded using the load 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.

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.

Modules not starting with a context switch are always loaded into MAIN
except when the load statement specifies a target context
as the last parameter. The load function can take URLs
to load modules from remote locations, via HTTP.

The current context after the load statement will always be
the same as before the load.

Serializing contexts

Serialization makes a software object persistent
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 save function.
Like other symbols, contexts are saved just by using their names:

For details, see the functions save (mentioned above)
and source (for serializing to a newLISP string).

( § )

17. The context default functor

A default functor or default function
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.

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

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

Hash functions and dictionaries

There are several functions that can be used to place symbols into namespace contexts.
When using dictionaries as simple hash-like collections of variable → value pairs, use the
uninitialized default functor:

Either method can be used to make the MyHash dictionary space and default
functor. The second method is safer, as it will protect the default functor
MyHash:MyHash from change. The default functor in a namespace must
contain nil 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:

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

Most of the time, newLISP passes parameters by value copy.
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:

Any argument of a built-in function calling for either a list or a string
— but no other data type — 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.

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.

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

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

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:

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

( § )

18. Functional object-oriented programming

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

Class attributes and methods are stored in the namespace of the object class.

The namespace default functor holds the object constructor method.

An object is constructed using a list, the first element of which is the
context symbol describing the class of the object.

Polymorphism is implemented using the : (colon)
operator, which selects the appropriate class from the object.

A target object inside a class-method function is accessed via the self
function.

The following paragraphs are a short introduction to FOOP as designed by
Michael Michaels from neglook.com.

FOOP classes and constructors

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

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

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:

Creating the namespace classes using new 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.

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

In many cases the constructor as created when using new is sufficient and overwriting
it is not necessary.

Objects and associations

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 objects using any of the constructors defined previously:

Note that in none of the assoc statements Address and Street
need to carry quotes. The same is true in the set statement:
(set 'JohnDoe (Person ...)) 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.

The colon : operator and polymorphism

In newLISP, the colon character : 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 polymorphously.

The following code defines two functions called area,
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
context statements. Here, only
the symbols rectangle:area and circle:area belong
to different namespaces. The local parameters p, c,
dx, and dy are all part of MAIN,
but this is of no concern.

By prefixing the area or move symbol with the
: (colon),
we can call these functions for each class of object. Although there is no space
between the colon and the symbol following it, newLISP parses them as distinct entities.
The colon works as a function that processes parameters:

In this example, the correct qualified symbol (rectangle:area or
circle:area) 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).

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 self
is used to access and index the object.

Structuring a larger FOOP program

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
context statements to provide better isolation
of parameter variables used and to create an isolated location for potential
class variables.

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.

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 MAIN.lsp:

All sets of class functions are now lexically separated
from each other.

( § )

19. Concurrent processing and distributed computing

newLISP has high-level APIs to control multiple processes on the same
CPU or distributed onto different computer nodes on a TCP/IP network.

Cilk API

newLISP implements a Cilk-
like API to launch and control concurrent processes. The API can take advantage of
multi-core computer architectures. Only three functions, spawn,
sync and abort, 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 spawn statements and are distributed and scheduled onto
different cores in the CPU by the operating system.

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.

Since version 10.1 send and receive
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.

Only on macOS and other Unixes will the Cilk API parallelize tasks.
On MS Windows, the API is not available.

Distributed network computing

With only one function, net-eval, newLISP implements
distributed computing. Using net-eval, 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. net-eval does all the housekeeping
required to connect to remote nodes, transfer functions to execute, and
collect the results. net-eval can also use a call-back function to
further structure consolidation of incoming results from remote nodes.

The functions read-file, write-file,
append-file and delete-file 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.

( § )

20. JSON, XML, S-XML, and XML-RPC

JSON support

JSON-encoded data can be parsed into S-expressions using the
json-parse function. Error information for
failed JSON translations can be retrieved using json-error.

For a description of the JSON format (JavaScript Object Notation)
consult json.org.
Examples for correct formatted JSON text can be seen at
json.org/examples.html.

To retrieve data in nested lists resulting from JSON translation, use the
assoc, lookup and ref
functions.

See the description of json-parse for a complete example
of parsing and processing JSON data.

Use the xml-parse function
to parse XML-encoded strings.
When xml-parse encounters an error,
nil is returned.
To diagnose syntax errors caused by incorrectly formatted XML,
use the function xml-error.
The xml-type-tags 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.

To retrieve data in nested lists resulting from S-XML translation, use the
assoc, lookup and ref
functions.

See xml-parse in the reference section of the manual
for details on parsing and option numbers, as well as for a longer example.

XML-RPC

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.

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 examples/xmlrpc.cgi. This
script can be used together with a web server, like Apache.
This XML-RPC service script implements
the following methods:

method

description

system.listMethods

Returns a list of all method names

system.methodHelp

Returns help for a specific method

system.methodSignature

Returns a list of return/calling signatures for a specific method

newLISP.evalString

Evaluates a Base64 newLISP expression string

The first three methods are discovery 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 base64-enc and base64-dec functions
can be used to encode and decode Base64-encoded information.

In the modules directory of the source distribution,
the file xmlrpc-client.lsp implements a specific client interface for
all of the above methods.

Switching the locale

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
set-locale function can also be used to switch
to the default locale:

(set-locale "")

This switches to the default locale used on your platform/operating system
and ensures character handling (e.g., upper-case)
works correctly.

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:

locale -a

This command prints a list of all the locales available on your system.
Any of these may be used as arguments to set-locale:

(set-locale "es_US")

This would switch to a U.S. Spanish locale.
Accents or other characters
used in a U.S. Spanish environment
would be correctly converted.

See the manual description for more details
on the usage of set-locale.

Decimal point and decimal comma

Many countries use a comma instead of a period
as a decimal separator in numbers.
newLISP correctly parses numbers
depending on the locale set:

; switch to German locale on a Linux or OSX system
(set-locale "de_DE") → ("de_DE" ",")
; newLISP source and output use a decimal comma
(div 1,2 3) → 0,4

The default POSIX C locale, which is set when newLISP starts up,
uses a period as a decimal separator.

Unicode and UTF-8 encoding

Note that for many European languages,
the set-locale mechanism
is sufficient to display non-ASCII character sets,
as long as each character is presented as one byte internally.
UTF-8 encoding is only necessary for multi-byte character sets as described
in this chapter.

newLISP can be compiled
as a UTF-8–enabled application.
UTF-8 is a multi-byte encoding
of the international Unicode character set.
A UTF-8–enabled newLISP
running on an operating system with UTF-8 enabled
can handle any character of the installed locale.

The following steps
make UTF-8 work with newLISP
on a specific operating system and platform:

(1) Use one of the makefiles
ending in utf8
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.

The macOS binary installer contains
a UTF-8–enabled version by default.

(2) 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 locale command
or the set-locale function within newLISP.
On Linux, the locale can be changed by setting
the appropriate environment variable.
The following example uses bash
to set the U.S. locale:

export LC_CTYPE=en_US.UTF-8

(3) The UTF-8–enabled newLISP automatically switches to the locale found
on the operating system. Make sure the command shell
is UTF-8–enabled. The U.S. version of WinXP's notepad.exe
can display Unicode UTF-8–encoded characters, but the command shell cannot.
On Linux and other Unixes, the Xterm shell can be used
when started as follows:

LC_CTYPE=en_US.UTF-8 xterm

The following procedure can now be used
to check for UTF-8 support.
After starting newLISP, type:

All other string functions work on 8-bit bytes. When positions are returned,
as in find or regex,
they are single 8-bit byte positions rather than character positions which
may be multi-byte.
The get-char and slice functions
do not take multi-byte character offsets, but single-byte offsets, even
in UTF-8 enabled versions of newLISP.
The reverse 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–enabled
version of newLISP. To make slice and reverse
work with UTF-8 strings, combine them with explode and
join.

To enable UTF-8 in Perl Compatible Regular Expressions (PCRE)
— used by directory, find,
member, parse, regex,
regex-comp and replace —
set the option number accordingly (2048). Note that offset and lengths in
regex results are always in single byte counts.
See the regex documentation for details.

Use explode to obtain an array
of UTF-8 characters and to manipulate characters rather than bytes
when a UTF-8–enabled function is unavailable:

(join (reverse (explode str))) ; reverse UTF-8 characters

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–enabled version.
The size of the first 127 ASCII characters —
along with the characters in popular code pages such as ISO 8859 —
is one byte long. When working exclusively within these code pages,
UTF-8–enabled newLISP is not required.
The set-locale function alone
is sufficient for localized behavior.

Functions only available on UTF-8 enabled versions

The first two functions are rarely used in practice,
as most Unicode text files are already UTF-8–encoded
(rather than UCS-4, which uses four-byte integer characters).
Unicode can be displayed directly when using the
"%ls"format specifier.

22. Commas in parameter lists

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:

(define (my-func a b c , x y z)
(set 'x …)
(…))

When calling this function, only a, b, and c are used as parameters.
The others (the comma symbol, x, y, and z) are initialized
to nil 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.

For other ways of declaring and initializing local variables,
see let, letex and
letn.

( § )

( ∂ )

newLISP Function Reference

1. Syntax of symbol variables and numbers

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 parse without optional arguments.

Symbols for variable names

The following rules apply to the naming of symbols
used as variables or functions:

Variable symbols starting with a + or - cannot have a
number as the second character.

Any character is allowed inside a variable name, except for:" ' ( ) : , and the space character. These mark the end of a variable symbol.

A symbol name starting with [ (left square bracket) and ending with
] (right square bracket) may contain any character except the right square
bracket.

A symbol name starting with $ (dollar sign) is global. There are several of these
symbols already built into newLISP and set and changed
internally. This type of global symbol can also be created by the user.

All of the following symbols are legal variable names in newLISP:

myvar
A-name
X34-zz
[* 7 5 ()};]
*111*

Sometimes it is useful to create hash-like lookup dictionaries
with keys containing characters that are illegal in newLISP variables.
The functions sym and context
can be used to create symbols containing these characters:

The last example creates the symbol 1
containing the value 123.
Also note that creating such a symbol does not alter newLISP's normal operations,
since 1 is still parsed as the number one.

Numbers

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 inf (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.

newLISP recognizes the following number formats:

Integers are one or more digits long,
optionally preceded by a + or - 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).

123
+4567
-999

Big integers can be of unlimited precision and are processed
differently from normal 64-bi integers internally.

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.

Hexadecimals start with a 0x (or 0X),
followed by any combination of the hexadecimal digits:
0123456789abcdefABCDEF.
Any other character ends the hexadecimal number. Only up to 16 hexadecimal digits
are valid and any more digits are ignored.

0xFF → 255
0x10ab → 4267
0X10CC → 4300

Binaries start with a 0b (or 0B),
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.

0b101010 → 42

Octals start with an optional + (plus) or - (minus) sign and a 0 (zero),
followed by any combination of the octal digits: 01234567.
Any other character ends the octal number. Only up to 21 octal digits are valid
and any more digits are ignored.

012 → 10
010 → 8
077 → 63
-077 → -63

Floating point numbers can start
with an optional + (plus) or - (minus) sign,
but they cannot be followed by a 0 (zero);
this would make them octal numbers instead of floating points.
A single . (decimal point) can appear anywhere within
a floating point number, including at the beginning.

Only 16 digits are siginificant and any more digits are ignored.

1.23 → 1.23
-1.23 → -1.23
+2.3456 → 2.3456
.506 → 0.506

As described below, scientific notation
starts with a floating point number
called the significand (or mantissa),
followed by the letter e or E
and an integer exponent.

1.23e3 → 1230
-1.23E3 → -1230
+2.34e-2 → 0.0234
.506E3 → 506

( § )

2. Data types and names in the reference

To describe the types and names of a function's parameters,
the following naming convention is used throughout the reference section:

syntax: (format str-formatexp-data-1 [exp-data-i ... ])

Arguments are represented by symbols formed by the argument's type and name,
separated by a - (hyphen). Here, str-format (a string) and
exp-data-1 (an expression) are named "format" and "data-1", respectively.

Arguments enclosed in brackets [ and ] are optional. When
arguments are separated by a vertical | then one of them must be chosen.

array

body

One or more expressions for evaluation. The expressions are evaluated sequentially
if there is more than one.

1 7.8
nil
(+ 3 4)
"Hi" (+ a b)(print result)
(do-this)(do-that) 123

bool

true, nil, or an expression evaluating to one of these two.

true, nil, (<= X 10)

context

An expression evaluating to a context (namespace) or a variable symbol
holding a context.

MyContext, aCtx, TheCTX

exp

Any data type described in this chapter.

func

A symbol or an expression evaluating to
an operator symbol or lambda expression.

+, add, (first '(add sub)), (lambda (x) (+ x x))

int

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.

123, 5, (* X 5)

list

A list of elements (any type)
or an expression evaluating to a list.

(a b c "hello" (+ 3 4))

num

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.

1.234, (div 10 3), (sin 1)

matrix

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 det,
multiply, or invert,
all numbers must be floats or integers.

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,
0.0 is assumed by the functions
det, multiply,
and invert,
while transpose assumes nil.
Special rules apply for transpose
when a whole row is not a list or an array,
but some other data type.

str

Depending on the length and processing of special characters, strings are delimited
by either quotes "", braces {} or [text][/text] tags.

Strings limited by either quotes "" or braces {} must not exceed
2047 characters. Longer strings should be limited by [text][/text] tags for
unlimited text length.

"Hello", (append first-name " Miller")

Special characters can be included in quoted strings
by placing a \ (backslash) before the character or
digits to escape them:

character

description

\"

for a double quote inside a quoted string

\n

the line-feed character (ASCII 10)

\r

the carriage return character (ASCII 13)

\b

for a backspace BS character (ASCII 8)

\t

for a TAB character (ASCII 9)

\f

for a formfeed FF character (ASCII 12)

\nnn

a decimal ASCII code where nnn is between 000 and 255

\xnn

a hexadecimal code where nn is between 00 and FF

\unnnn

a unicode character encoded in the four nnnn hexadecimal
digits. When reading a quoted string, newLISP will translate
this to a UTF8 character in the UTF8 enabled versions of newLISP.

\\

the backslash character itself

Decimals start with a digit. Hexadecimals start with x:

"\065\066\067" → "ABC"
"\x41\x42\x43" → "ABC"

Instead of a " (double quote), a { (left curly bracket)
and } (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.

The tags [text] and [/text]
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 [text] tags
for strings longer than 2048 characters.

sym

A symbol or expression evaluating to a symbol.

'xyz, (first '(+ - /)), '*, '- , someSymbol,

Most of the context symbols in this manual start with an uppercase letter
to distinguish them from other symbols.

sym-context

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., bayes-train, context,
eval-string,
load, sym, and xml-parse).
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., context).
For other functions, such as context?, the distinction is critical.

4. Functions in alphabetical order

!

syntax: (! str-shell-command [int-flags])

Executes the command in str-command by shelling out to the
operating system and executing. This function returns a different value
depending on the host operating system.

(! "vi")
(! "ls -ltr")

Use the exec function to execute a shell command
and capture the standard output or to feed standard input.
The process function may be used to launch a
non-blocking child process and redirect std I/O and std error to pipes.

On Ms Windows the optional int-flags parameter takes process
creation flags as defined for the Windows CreateProcessA function
to control various parameters of process creation. The inclusion of this
parameter – which also can be 0 – forces a different
creation of the process without a command shell window. This parameter is
ignored on Unix.

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

Without the additional parameter, the ! call would create a
new command window replacing the closed one.

Note that ! (exclamation mark) can be also be used as
a command-line shell operator by omitting the parenthesis and space
after the !:

> !ls -ltr ; executed in the newLISP shell window

Used in this way,
the ! operator
is not a newLISP function at all,
but rather a special feature of
the newLISP command shell.
The ! must be entered
as the first character
on the command-line.

$

syntax: ($ int-idx)

The functions that use regular expressions (directory,
ends-with, find, find-all,
parse, regex, search,
starts-with and replace)
all bind their results to the predefined system variables $0, $1,
$2–$15 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 ($ 0), ($ 1), ($ 2),
etc. This method allows indexed access (i.e., ($ i), where i is an integer).

Floating point values in arguments to
+, -, *, /, and %
are truncated to the integer value closest to 0 (zero).

Floating point values larger or smaller than
the maximum (9,223,372,036,854,775,807)
or minimum (-9,223,372,036,854,775,808) integer values
are truncated to those values. This includes the values for
+Inf and -Inf.

Calculations resulting in values
larger than 9,223,372,036,854,775,807
or smaller than -9,223,372,036,854,775,808
wrap around from positive to negative
or negative to positive.

Floating point values that evaluate to NaN (Not a Number),
ar treated as 0 (zero).

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 true. As soon as one comparison fails,
nil is returned.

If only one argument is supplied, all comparison operators assume 0 (zero)
as a second argument. This can be used to check if a number is negative, positive, zero
or not zero.

All types of expressions can be compared:
atoms, numbers, symbols, and strings.
List expressions can also be compared
(list elements are compared recursively).

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

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.

<<, >>

The number int-1 is arithmetically shifted
to the left or right by the number of bits given as int-2,
then shifted by int-3 and so on.
For example, 64-bit integers may be shifted up to 63 positions.
When shifting right,
the most significant bit is duplicated
(arithmetic shift):

&

syntax: (& int-1int-2 [int-3 ... ])

A bitwise and operation is performed
on the number in int-1 with the number in int-2,
then successively with int-3, etc.

(& 0xAABB 0x000F) → 11 ; which is 0xB

|

syntax: (| int-1int-2 [int-3 ... ])

A bitwise or operation is performed
on the number in int-1 with the number in int-2,
then successively with int-3, etc.

(| 0x10 0x80 2 1) → 147

^

syntax: (^ int-1int-2 [int-3 ... ])

A bitwise xor operation is performed
on the number in int-1 with the number in int-2,
then successively with int-3, etc.

(^ 0xAA 0x55) → 255

~

syntax: (~ int)

A bitwise not operation is performed
on the number in int,
reversing all of the bits.

(format "%X" (~ 0xFFFFFFAA)) → "55"
(~ 0xFFFFFFFF) → 0

:

syntax: (: sym-functionlist-object [ ... ])

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 : constructs a
context symbol from the context name in the object list and the
symbol following the colon. The object list in list-object
can be followed by other parameters.

The : operator implements polymorphism 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.

Inside the FOOP methods the self function is used to access
the target object of the method.

abort

syntax: (abort int-pid)
syntax: (abort)

In the first form, abort aborts a specific child process of the
current parent process giving the process id in int-pid. The process
must have been started using spawn. For processes
started using fork, use destroy
instead.

The function abort is not available on Windows.

(abort 2245) → true

To abort all child processes spawned from the current process use abort
without any parameters:

(abort) → true ; abort all

The function abort is part of the Cilk API for synchronizing
child processes and process parallelization. See the reference for the
function spawn for a full discussion of the Cilk API.

acos

syntax: (acos num-radians)

acosh

syntax: (acosh num-radians)

Calculates the inverse hyperbolic cosine of num-radians,
the value whose hyperbolic cosine is num-radians.
If num-radians is less than 1,
acosh returns NaN.

(acosh 2) → 1.316957897
(cosh (acosh 2)) → 2
(acosh 0.5) → NaN

add

syntax: (add num-1 [num-2 ... ])

All of the numbers in num-1, num-2, and on
are summed.
add accepts float or integer operands,
but it always returns a floating point number.
Any floating point calculation with NaN
also returns NaN.

(add 2 3.25 9) → 14.25
(add 1 2 3 4 5) → 15

address

syntax: (address int)
syntax: (address float)
syntax: (address str)

Returns the memory address of the integer in int,
the double floating point number in float,
or the string in str.
This function is used for passing parameters to library functions
that have been imported using the import function.

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 address
function in that case. As the example shows, address can be used
to do pointer arithmetic on the string's address.

address should only be used on persistent addresses from
data objects referred to by a variable symbol, not from volatile intermediate
expression objects.

Internally, newLISP uses the same function as rand to pick a random number.
To generate random floating point numbers,
use random,
randomize, or normal.
To initialize the pseudo random number generating process
at a specific starting point,
use the seed function.

and

syntax: (and exp-1 [exp-2 ... ])

The expressions exp-1, exp-2, etc. are evaluated in order,
returning the result of the last expression.
If any of the expressions yield nil or the empty list (),
evaluation is terminated and nil or the empty list () is returned.

append is also suitable for processing binary strings containing zeroes.
The string function would cut off strings at zero bytes.

Linkage characters or strings can be specified using the
join function. Use the string
function to convert arguments to strings and append in one step.

Use the functions extend and push
to append to an existing list or string modifying the target.

append-file

syntax: (append-file str-filenamestr-buffer)

Works similarly to write-file, but the content
in str-buffer is appended if the file in str-filename exists.
If the file does not exist, it is created (in this case, append-file
works identically to write-file). This function
returns the number of bytes written.

On failure the function returns nil. For error information,
use sys-error when used on files. When used
on URLs net-error gives more error
information.

append-file can take a http:// or file:// URL
in str-file-name. In case of the http:// prefix ,
append-file works exactly like put-url with
"Pragma: append\r\n" in the header option and can take the same
additional parameters. The "Pragma: append\r\n" option is supplied
automatically.

(append-file "http://asite.com/message.txt" "More message text.")

The file message.txt is appended at a remote
location http://asite.com with the contents of
str-buffer. If the file does not yet exist, it
will be created. In this mode, append-file can also be used
to transfer files to remote newLISP server nodes.

The int-reduce parameter can optionally contain
the number of arguments taken by the function in func.
In this case,
func will be repeatedly applied using the previous result
as the first argument and taking the other arguments required
successively from list
(in left-associative order).
For example, if op takes two arguments, then:

The last example shows how apply's reduce functionality
can be used to convert a two-argument function into one that takes multiple arguments. Note, that a built-in gcd is available.

apply should only be used on functions and operators that evaluate all
of their arguments, not on special forms like dotimes
or case, which evaluate only some of their arguments.
Doing so will cause the function to fail.

args

syntax: (args)
syntax: (args int-idx-1 [int-idx-2 ... ])

Accesses a list of all unbound arguments passed to the currently evaluating
define, define-macro
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 args function is useful for defining functions or macros
with a variable number of parameters.

args can be used to define hygienic macros that avoid the danger of
variable capture. See define-macro.

The function foo
prints out the arguments in reverse order.
The bar function
shows args being used
with multiple indices
to access nested lists.

Remember that (args) only contains the arguments
not already bound to local variables
of the current function or macro:

(define (foo a b) (args))
(foo 1 2) → ()
(foo 1 2 3 4 5) → (3 4 5)

In the first example,
an empty list is returned because
the arguments are bound to the
two local symbols, a and b.
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 args.

(args) 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 (args) would not be evaluated
and would therefore have the wrong
contents in the new macro environment.

array

syntax: (array int-n1 [int-n2 ... ] [list-init])

Creates an array with int-n1 elements,
optionally initializing it with the contents of list-init.
Up to sixteen dimensions may be specified for multidimensional arrays.

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

The array? function
can be used to check if an expression is an array:

(array? myarray) → true
(array? (array-list myarray)) → nil

When serializing arrays using the function source
or save, the generated code includes the array
statement necessary to create them. This way, variables containing arrays are
correctly serialized when saving with save or creating
source strings using source.

assoc

In the first syntax the value of exp-key is used
to search list-alist for a member-list
whose first element matches the key value.
If found, the member-list is returned;
otherwise, the result will be nil.

For making replacements in association lists, use the
setf together with the assoc function.
The lookup function is used to perform association lookup
and element extraction in one step.

atan

syntax: (atan num-radians)

The arctangent of num-radians
is calculated and returned.

(atan 1) → 0.7853981634
(tan (atan 1)) → 1

atan2

syntax: (atan2 num-Y-radiansnum-X-radians)

The atan2 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.
atan2 is useful for converting
Cartesian coordinates
into polar coordinates.

atanh

syntax: (atanh num-radians)

Calculates the inverse hyperbolic tangent of num-radians,
the value whose hyperbolic tangent is num-radians. If the
absolute value of num-radians is greater than 1,
atanh returns NaN; if it is equal to 1, atanh returns infinity.

atom?

syntax: (atom? exp)

Returns true if the value of exp is an atom,
otherwise nil.
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.

newLISP's BASE64 handling is derived from
routines found in the Unix curl
utility and conforms to the RFC 4648 standard.

base64-enc

syntax: (base64-enc str [bool-flag])

The string in str 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–Z and a–z;
the numbers 0–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.

Without the optional bool-flag parameter the empty string "" is
encoded into "====". If bool-flag evaluates to true,
the empty string "" is translated into "". Both translations
result in "" when using base64-dec.

The encoded string is returned.

BASE64 encoding is used with many Internet protocols
to encode binary data for inclusion in text-based messages
(e.g., XML-RPC).

newLISP's BASE64 handling is derived from routines
found in the Unix curl
utility and conforms to the RFC 4648 standard.

bayes-query

syntax: (bayes-query list-Lcontext-D [bool-chain [bool-probs]])

Takes a list of tokens (list-L) and a trained dictionary (context-D)
and returns a list of the combined probabilities of the tokens in one category
(A or Mc) versus a category (B) or
against all other categories (Mi). All tokens in list-L
should occur in context-D.
When using the default R.A. Fisher inverse Chi² mode,
nonexistent tokens will skew results toward equal probability in all categories.

Non-existing tokens will not have any influence on the result when using the
true Chain Bayesian mode with bool-chain set to true.
The optional last flag, bool-probs, indicates whether frequencies or
probability values are used in the data set. The bayes-train
function is typically used to generate a data set's frequencies.

Tokens can be strings or symbols. If strings are used, they are prepended
with an underscore before being looked up in context-D. If
bayes-train was used to generate context-D's
frequencies, the underscore was automatically prepended during the learning process.

Depending on the flag specified in bool-probs,
bayes-query employs either the
R. A. Fisher inverse Chi² method of compounding probabilities
or the Chain Bayesian method.
By default, when no flag or nil is specified in bool-probs,
the inverse Chi² method of compounding probabilities is used.
When specifying true in bool-probs,
the Chain Bayesian method is used.

If the inverse Chi² 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.

For two categories A and B,
bayes-query uses the following formula:

p(A|tkn) = p(tkn|A) * p(A) / ( p(tkn|A) * p(A) + p(tkn|B) * p(B) )

For N categories, the formula can be generalized to:

p(Mc|tkn) = p(tkn|Mc) * p(Mc) / sum-i-N( p(tkn|Mi) * p(Mi) )

The probabilities (p(Mi) or p(A), along with p(B))
represent the Bayesian prior probabilities.
p(Mc|tkn) and p(A|tkn) are the
posterior Bayesian probabilities of a category or model.
This naive Bayes formula does nor take into account dependencies
between different categories.

Priors are handled differently,
depending on whether the R.A. Fisher inverse Chi²
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² method,
priors are not passed on via chaining,
but probabilities are compounded using the inverse Chi² method.

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 NaN values.

The default inverse Chi² 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 Bayesian statistics.
Imagine that five different language corpus 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.

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.

The return value of bayes-query is a list of probability values,
one for each category. Following are two examples: the first for the
default inverse Chi² mode, the second for a data set processed with the
Chain Bayesian method.

R.A. Fisher inverse Chi² method

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.

The two training sets are loaded, split into tokens,
and processed by the bayes-train function.
In the end, the DoyleDowson dictionary is saved to a file,
which will be used later with the bayes-query function.

The following code illustrates how bayes-query is used
to classify a sentence as Doyle or Dowson:

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?

Note that the Bayesian formulas used
assume statistical independence of events
for the bayes-query to work correctly.

The example shows that a person must test positive several times
before they can be confidently classified as sick.

Calculating the same example using the R.A. Fisher Chi² method
will give less-distinguished results.

Specifying probabilities instead of counts

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 bool-probs flag
allows probabilities to be entered directly
and should be used together with the Chain Bayesian mode
for maximum performance:

As expected, the results are the same for probabilities
as they are for frequencies.

bayes-train

syntax: (bayes-train list-M1 [list-M2 ... ] sym-context-D)

Takes one or more lists of tokens (M1, M2—)
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 sym-context-D, and the frequency is counted for each token
in each category Mi. If the context does not yet exist,
it must be quoted.

The M categories represent data models for which sequences of
tokens can be classified (see bayes-query).
Each token in D is a content-addressable symbol
containing a list of the frequencies for this token within each category.
String tokens are prepended with an _ (underscore)
before being converted into symbols. A symbol named total is created
containing the total of each category. The total symbol cannot be part
of the symbols passed as an Mi category.

The function returns a list of token frequencies found in the different categories
or models.

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 bayes-train function:

The last data are from a popular example used to describe the
bayes-query function in introductory papers
and books about bayesian networks.

Training can be done in different stages by using bayes-train 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.

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 bayes-train in multiple stages. Categories can also be
singularly trained by specifying an empty list for the absent corpus:

Using bayes-train inside a context other than MAIN
requires the training contexts to have been created previously within
the MAIN context via the context function.

bayes-train is not only useful with the bayes-query function,
but also as a function for counting in general.
For instance, the resulting frequencies
could be analyzed using prob-chi2
against a null hypothesis of proportional distribution
of items across categories.

begin

syntax: (begin body)

The begin function is used to group a block of expressions.
The expressions in body are evaluated in sequence, and
the value of the last expression in body is returned.

The silent function works like begin,
but suppresses console output on return.

beta

syntax: (beta cum-anum-b)

The Beta function, beta,
is derived from the log Gammagammaln function as follows:

beta = exp(gammaln(a) + gammaln(b) - gammaln(a + b))

(beta 1 2) → 0.5

betai

syntax: (betai num-xnum-anum-b)

The Incomplete Beta function, betai,
equals the cumulative probability of the Beta distribution, betai,
at x in num-x.
The cumulative binomial distribution is defined as the probability of an event, pev,
with probability p to occur k or more times in N trials:

pev = Betai(p, k, N - k + 1)

(betai 0.5 3 8) → 0.9453125

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 binomial function.

bigint

syntax: (bigint number)
syntax: (bigint string)

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.

A string argument gets parsed to a number and converted to a big integer.

binomial

syntax: (binomial int-nint-kfloat-p)

The binomial distribution function is defined as the probability for an event
to occur int-k times in int-n trials if that event has a
probability of float-p and all trials are independent of one another:

binomial = pow(p, k) * pow(1.0 - p, n - k) * n! / (k! * (n - k)!)

where x! is the factorial of x
and pow(x, y) is x raised to the power of y.

(binomial 10 3 0.5) → 0.1171875

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 betai function.

bits

syntax: (bits int [bool])

Transforms a number in int to a string of 1's and 0's or a
list, if bool evaluates to anything not nil.

In string representation bits are in high to low order. In list
presentation 1's and 0's are represented as true and nil
and in order from the lowest to the highest bit. This allows direct
indexing and program control switching on the result.

callback

In the first simple callback syntax up to sixteen (0 to 15) callback
functions for up to eight parameters can be registered with imported libraries.
The callback function returns a procedure address that invokes a
user-defined function in sym-function. The following example shows
the usage of callback functions when importing the OpenGL
graphics library:

If more than sixteen callback functions are required, slots must be
reassigned to a different callback function.

The address returned by callback is registered with the
Glut library.
The above code is a snippet from the file opengl-demo.lsp,
in the examples/ directory of the source distribution of newLISP
and can also be downloaded from
newlisp.org/downloads/OpenGL.

In the second extended callback syntax 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 sym-function
contains a newLISP defined function used as a callback function callable from a C program.

In the third syntax callback returns a previously returned C-callable
address for that symbol.

While the first simple callback syntax only handles integers and pointer
values, callback in the expanded syntax can also handle simple and double precision
floating point numbers passed in an out of the callback function.

Both the simple and extended syntax can be mixed inside the same program.

The following example shows the import of the qsort
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 qsort function:

As type specifiers the same string tags can be used as in the
import function. All pointer types are passed as numbers in and
out of the callback function. The functions get-char,
get-int, get-long and
get-string can be used to extract numbers of
different precision from parameters. Use pack and
unpack to extract data from binary buffers and structures.

case

syntax: (case exp-switch (exp-1body-1) [(exp-2body-2) ... ])

The result of evaluating exp-switch
is compared to each of the unevaluated expressions
exp-1, exp-2, —. If a match is found, the
corresponding expressions in body
are evaluated. The result of the last body expression is returned
as the result for the entire case expression.

In the second syntax,
catch evaluates the expression exp,
stores the result in symbol,
and returns true.
If an error occurs during evaluation,
catch returns nil
and stores the error message in symbol.
This form can be useful when errors are expected
as a normal potential outcome of a function
and are dealt with during program execution.

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 catch can also be used to catch errors.
The throw-error function may be used
to throw user-defined errors.

syntax: (chop str [int-chars])
syntax: (chop list [int-elements])

If the first argument evaluates to a string,
chop returns a copy of str
with the last int-char characters omitted.
If the int-char argument is absent,
one character is omitted.
chop does not alter str.

If the first argument evaluates to a list,
a copy of list is returned
with int-elements omitted
(same as for strings).

command-event

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.

command-event 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.

To only force a prompt and disable command processing, the function should return
the empty string "". To reset command-event, use the second syntax.

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.

In the definition of the command-line translation function the Unix
command cd gets a special treatment, to make sure that the directory
is changed for newLISP process too. This way when shelling out with ! and
coming back, newLISP will maintain the changed directory.

Command lines for newLISP must start either with a space or an opening
parenthesis. Unix commands must start at the beginning of the line.

When newLISP is running in server mode either using the -c or
-http option, it receives HTTP requests similar to the following:

GET /index.html

Or if a query is involved:

GET /index.cgi?userid=joe&password=secret

A function specified by command-event could filter and transform
these request lines, e.g.: discovering all queries trying to perform CGI using
a file ending in .exe. Such a request would be translated into a
request for an error page:

When starting the server mode with newlisp httpd-conf.lsp -c -d80 -w ./httpdoc
newLISP will load the definition for command-event for filtering incoming
requests, and the query:

GET /cmd.exe?dir

Would be translated into:

GET /errorpage.html

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.

httpd-conf.lsp 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.

Note, that the command line length as well as the line length in HTTP headers is limited to 512 characters for newLISP.

cond

syntax: (cond (exp-condition-1body-1) [(exp-condition-2body-2) ... ])

Like if, cond conditionally evaluates the expressions
within its body.
The exp-conditions are evaluated in turn,
until some exp-condition-i is found
that evaluates to anything other than nil
or an empty list ().
The result of evaluating body-i
is then returned as the result of the entire cond-expression.
If all conditions evaluate to nil
or an empty list,
cond returns the value of the last cond-expression.

When a body-n is missing,
the value of the last cond-expression evaluated
is returned.
If no condition evaluates to true,
the value of the last conditional expression is returned
(i.e., nil or an empty list).

(cond ((+ 3 4))) → 7

When used with multiple arguments,
the function if
behaves like cond,
except it does not need extra parentheses
to enclose the condition-body pair
of expressions.

cons

syntax: (cons exp-1exp-2)

If exp-2 evaluates to a list,
then a list is returned with the result of evaluating exp-1
inserted as the first element.
If exp-2 evaluates to anything other than a list,
the results of evaluating exp-1 and exp-2
are returned in a list.
Note that there is no dotted pair in newLISP:
consing two atoms constructs a list, not a dotted pair.

Unlike other Lisps that return (s)
as the result of the expression (cons 's nil),
newLISP's cons returns (s nil).
In newLISP, nil is a Boolean value
and is not equivalent to an empty list,
and a newLISP cell holds only one value.

cons behaves like the inverse operation of first
and rest
(or first and last if the list is a pair):

syntax: (constant sym-1exp-1 [sym-2exp-2] ...)

Identical to set in functionality,
constant further protects the symbols from subsequent modification.
A symbol set with constant can only be modified
using the constant function again.
When an attempt is made to modify the contents of a symbol protected with constant,
newLISP generates an error message.
Only symbols from the current context can be used with constant.
This prevents the overwriting of symbols
that have been protected in their home context.
The last exp-n initializer is always optional.

The first example defines a constant, aVar,
which can only be changed by using another constant statement.
The second example protects double from being changed
(except by constant).
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.

The last value to be assigned can be omitted.
constant returns the contents of
the last symbol set and protected.

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.

squareroot will behave like sqrt.
The + (plus sign) is redefined
to use the mixed type floating point mode of add.
The hexadecimal number displayed in the result
is the binary address of the built-in function
and varies on different platforms and OSes.

context

In the first syntax, context is used to switch to a different context namespace.
Subsequent loads of newLISP source or functions like
eval-string and sym will put newly created
symbols and function definitions in the new context.

If the context still needs to be created, the symbol for the new context should be specified.
When no argument is passed to context, then the symbol for the current context is returned.

Because contexts evaluate to themselves, a quote is not necessary
to switch to a different context if that context already exists.

If an identifier with the same symbol already exists,
it is redefined to be a context.

Symbols within the current context
are referred to simply by their names,
as are built-in functions and special symbols
like nil and true.
Symbols outside the current context
are referenced by prefixing the symbol name
with the context name and a : (colon).
To quote a symbol in a different context,
prefix the context name with a ' (single quote).

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:

(context 'CTX)
(define (CTX:new var)
(…))
(context 'MAIN)

CTX:new will overwrite new in MAIN.

In the second syntax, context 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
Hash functions and dictionaries.

The first three statements create a symbol and store a value of any data type inside.
The first statement also creates the context named Ctx.
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 Ctx.

Symbols can contain spaces or any other special characters
not typically allowed in newLISP symbols being used as variable names.
This second syntax of context only creates the new symbol
and returns the value contained in it. It does not switch to the new namespace.

context?

syntax: (context? exp)
syntax: (context? expstr-sym)

In the first syntax,
context? is a predicate that returns true
only if exp evaluates to a context;
otherwise, it returns nil.

The second syntax checks for the existence of a symbol in a context.
The symbol is specified by its name string in str-sym.

(context? FOO "q") → true
(context? FOO "p") → nil

Use context to change and create namespaces
and to create hash symbols in contexts.

copy

syntax: (copy exp)
syntax: (copy int-addr [bool-flag])

The first syntax makes a copy from evaluating expression in exp.
Some built-in functions are destructive, changing
the original contents of a list, array or string they are working on.
With copy their behavior can be made non-destructive.

The second example counts all occurrences
of different letters in myFile.txt.

The first list in count,
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 0 (zero).

syntax: (cpymem int-from-addressint-to-addressint-bytes)

Copies int-bytes of memory from int-from-address
to int-to-address. 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).

Note that this function should only be used when familiar with newLISP internals.
cpymem can crash the system or make it unstable if used incorrectly.

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:

Use the dump function to retrieve binary addresses
and the contents from newLISP cells.

crc32

syntax: (crc32 str-data)

Calculates a running 32-bit CRC (Circular Redundancy Check) sum
from the buffer in str-data,
starting with a CRC of 0xffffffff for the first byte.
crc32 uses an algorithm published
by www.w3.org.

(crc32 "abcdefghijklmnopqrstuvwxyz") → 1277644989

crc32 is often used to verify data integrity
in unsafe data transmissions.

crit-chi2

syntax: (crit-chi2 num-probabilityint-df)

Calculates the critical minimum Chi² for a given confidence probability
num-probability under the null hypothesis and the degrees of freedom in
int-df for testing the significance of a statistical null hypothesis.

Note that versions prior to 10.2.0 took (1.0 - p) for the probability
instead of p.

crit-f

syntax: (crit-f num-probabilityint-df1int-df2)

Calculates the critical minimum F for a given confidence probability
num-probability under the null hypothesis and the degrees of freedom
given in int-df1 and int-df2 for testing the significance of a
statistical null hypothesis using the F-test.

crit-t

syntax: (crit-t num-probabilityint-df)

Calculates the critical minimum Student's t for a given confidence probability
num-probability under the null hypothesis and the degrees of freedom in
int-df for testing the significance of a statistical null hypothesis.

This displays all comment lines starting with ;;
from a file given as a command-line argument
when invoking the script filter.

curry

syntax: (curry funcexp)

Transforms func from a function f(x, y) that takes
two arguments into a function fx(y) that takes a single argument.
curry works like a macro in that it does not evaluate its arguments.
Instead, they are evaluated during the application of func.

The first syntax returns the local time zone's
current date and time as a string representation.
If int-secs is out of range, nil is returned.

In the second syntax, date translates the number of seconds
in int-secs into its date/time string representation
for the local time zone.
The number in int-secs is usually retrieved from the system
using date-value.
Optionally, a time-zone offset (in minutes) can be specified
in int-offset, which is added
or subtracted before conversion of int-sec to a string.
If int-secs is out of range or an invalid str-format
is specified, an empty string "" is returned.

The way the date and time are presented in a string
depends on the underlying operating system.

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).
date assumes the int-secs given are in Coordinated Universal
Time (UTC; formerly Greenwich Mean Time (GMT)) and converts it according to the
local time-zone.

The third syntax makes the date string fully customizable by using a format
specified in str-format. This allows the day and month names to be
translated into results appropriate for the current locale:

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 strftime() of the individual platform's C library.

format

description

%a

abbreviated weekday name according to the current locale

%A

full weekday name according to the current locale

%b

abbreviated month name according to the current locale

%B

full month name according to the current locale

%c

preferred date and time representation for the current locale

%d

day of the month as a decimal number (range 01–31)

%H

hour as a decimal number using a 24-hour clock (range 00–23)

%I

hour as a decimal number using a 12-hour clock (range 01–12)

%j

day of the year as a decimal number (range 001–366)

%m

month as a decimal number (range 01–12)

%M

minute as a decimal number

%p

either 'am' or 'pm' according to the given time value or
the corresponding strings for the current locale

%S

second as a decimal number 0–61 (60 and 61 to account
for occasional leap seconds)

%U

week number of the current year as a decimal number,
starting with the first Sunday as the first day of the first week

%w

day of the week as a decimal, Sunday being 0

%W

week number of the current year as a decimal number,
starting with the first Monday as the first day of the first week

%x

preferred date representation for the current locale
without the time

%X

preferred time representation for the current locale
without the date

%y

year as a decimal number without a century (range 00–99)

%Y

year as a decimal number including the century

%z

time zone or name or abbreviation (same as %Z on MS Windows,
different on Unix)

%Z

time zone or name or abbreviation (same as %z on MS Windows,
different on Unix)

%%

a literal '%' character

Leading zeroes in the display of decimal day numbers can be suppressed
using "%-d" on Linux and FreeBSD and using "%e"
on OpenBSD, SunOS/Solaris and macOS. On MS Windows use "%#d".

date-list

syntax: (date-list int-seconds [int-index])
syntax: (date-list)

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.

When no parameters are given date-list generates the list from the
number of seconds for the current time, return of (date-value).

date-parse

syntax: (date-parse str-datestr-format)

Parses a date from a text string in str-date
using a format as defined in str-format, which uses
the same formatting rules found in date.
The function date-parse 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.

This function is not available on MS Windows platforms. The function was
named parse-date in previous versions. The old form is deprecated.

date-value

In the first syntax, date-value 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.

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.

In the third syntax, date-value returns the time value
in seconds for the current time.

When in debug or trace mode, error messages
will be printed. The function causing the exception will return either
0 or nil and processing will continue. This way, variables
and the current state of the program can still be inspected while debugging.

Use the -- function to decrement in integer mode.
Use the inc function to increment numbers floating point mode.

def-new

syntax: (def-new sym-source [sym-target])

This function works similarly to new,
but it only creates a copy of one symbol
and its contents from the symbol in sym-source.
When sym-target is not given,
a symbol with the same name is created
in the current context.
All symbols referenced inside sym-source
will be translated into symbol references into the current context,
which must not be MAIN.

If an argument is present in sym-target, the copy will be made
into a symbol and context as referenced by the symbol in sym-target.
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 sym-source with the same context as sym-source will
be translated into symbol references of the target context.

Defines the new function sym-name,
with optional parameters sym-param-1—.
define is equivalent to assigning
a lambda expression to sym-name.
When calling a defined function,
all arguments are evaluated and assigned
to the variables in sym-param-1—,
then the body-1— expressions are evaluated.
When a function is defined, the lambda expression
bound to sym-name is returned.

All parameters defined are optional.
When a user-defined function is called without arguments,
those parameters assume the value nil.
If those parameters have a default value
specified in exp-default,
they assume that value.

The return value of define
is the assigned lambda expression.
When calling a user-defined function,
the return value is the last expression evaluated
in the function body.

(define (area x y) (* x y)) → (lambda (x y) (* x y))
(area 2 3) → 6

As an alternative, area could be defined
as a function without using define.

(set 'area (lambda (x y) (* x y))

lambda or fn expressions may be used by themselves
as anonymous functions without being defined as a symbol:

define-macro

Functions defined using define-macro are called fexpr
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 define-macro can be combined with template
expansion using expand or letex.

Defines the new fexpr sym-name, with optional arguments sym-param-1.
define-macro is equivalent to assigning a lambda-macro expression to a symbol.
When a define-macro function is called, unevaluated arguments are assigned to
the variables in sym-param-1 .... Then the body expressions are evaluated.
When evaluating the define-macro function, the lambda-macro expression is returned.

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.

All parameters defined are optional. When a macro is called without
arguments, those parameters assume the value nil.
If those parameters have a default value specified in exp-default,
they assume that default value.

Note that in fexprs, the danger exists of passing a parameter
with the same variable name as used in the define-macro definition.
In this case, the fexpr's internal variable would end up
receiving nil instead of the intended value:

There are several methods that can be used
to avoid this problem, known as variable capture,
by writing hygienicdefine-macros:

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 default function. This is the preferred method in
newLISP to write define-macros.

The definition in the example is lexically isolated,
and no variable capture can occur.
Instead of the function being called using (my-setq:my-setq …),
it can be called with just (my-setq …)
because it is a default function.

syntax: (delete symbol [bool])
syntax: (delete sym-context [bool])

In the first syntax deletes a symbol symbol and references to
the symbol in other expressions will be changed to nil.

In the second syntax all symbols of the namespace referred to by
sym-context will be deleted and references to them in other
espressions will be changed to nil. The context symbol
sym-context will be changed to a normal symbol
containing nil.

When the expression in bool evaluates
to true, symbols are only deleted when they are not referenced.

When the expression in bool evaluates
to nil, 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
nil 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.

Protected symbols of built-in functions and special symbols
like nil and true cannot be deleted.

delete returns true if the symbol was deleted
successfully or nil if the symbol was not deleted.

When deleting a context symbol, the first delete removes the context
namespace contents and demotes the context symbol to a normal mono-variable symbol.
A second delete will remove the symbol from the symbol table.

The first example deletes the file junk 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 delete-url for details.

delete-url

syntax: (delete-url str-url)

This function deletes the file on a remote HTTP server specified in str-url.
The HTTP DELETE 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 get-url function.

If str-url starts with file:// a file on the local file system
is deleted.

This feature is also available when the delete-file
function is used and a URL is specified for the filename.

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 get-url function for details.

delete-url requests are also understood by newLISP server nodes, but will
not be served when the server is started in -http-safe mode.

destroy

syntax: (destroy int-pid)
syntax: (destroy int-pidint-signal)

Destroys a process with process id in int-pid and returns true
on success or nil on failure. The process id is normally obtained from a
previous call to fork on macOS and other Unix or
process on all platforms. On Unix, destroy works like
the system utility kill using the SIGKILL signal.

CAUTION! If int-pid is 0 the signal is sent to all processes whose
group ID is equal to the process group ID of the sender. If int-pid is -1
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.

When specifying int-signal, destroy works like a Unix kill
command sending the specified Unix signal to the process in int-pid.
This second syntax is not available on MS Windows.

det

syntax: (det matrix [float-pivot])

Returns the determinant of a square matrix. A matrix can either
be a nested list or an array.

Optionally 0.0 or a very small value can be specified
in float-pivot. This value substitutes pivot elements in
the LU-decomposition algorithm, which result in zero when
the algorithm deals with a singular matrix.

device

syntax: (device [int-io-handle])

int-io-handle is an I/O device number, which is set to 0 (zero)
for the default STD I/O pair of handles, 0 for stdin, 1
for stdout and 2 for stderr. int-io-handle may also
be a file handle previously obtained using open. 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.

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.

difference

In the first syntax, difference returns
the set difference between list-A and list-B.
The resulting list only has elements occurring in list-A,
but not in list-B.
All elements in the resulting list are unique,
but list-A and list-B need not be unique.
Elements in the lists can be any type of Lisp expression.

(difference '(2 5 6 0 3 5 0 2) '(1 2 3 3 2 1)) → (5 6 0)

In the second syntax, difference works in list mode.
bool specifies true
or an expression not evaluating to nil.
In the resulting list, all elements of list-B
are eliminated in list-A,
but duplicates of other elements in list-A are left.

directory

A list of directory entry names is returned
for the directory path given in str-path.
On failure, nil is returned.
When str-path is omitted,
the list of entries in the current directory is returned.

(directory "/bin")
(directory "c:/")

The first example returns the directory of /bin,
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 (/) can be included in path names.
When used, a backslash (\) must be
preceded by a second backslash.

In the second syntax, directory can take
a regular expression pattern in str-pattern.
Only filenames matching the pattern will be returned
in the list of directory entries.
In regex-option, special regular expression options
can be specified; see regex for details.

do-until

syntax: (do-until exp-condition [body])

The expressions in body are evaluated
before exp-condition is evaluated.
If the evaluation of exp-condition is not nil,
then the do-until expression is finished;
otherwise, the expressions in body get evaluated again.
Note that do-until evaluates the conditional expression
after evaluating the body expressions,
whereas until checks the condition
before evaluating the body.
The return value of the do-until expression
is the last evaluation of the body expression.
If body is empty, the last result of exp-condition
is returned.

do-while

syntax: (do-while exp-condition body)

The expressions in body are evaluated
before exp-condition is evaluated.
If the evaluation of exp-condition is nil,
then the do-while expression is finished;
otherwise the expressions in body get evaluated again.
Note that do-while evaluates the conditional expression
after evaluating the body expressions,
whereas while checks the condition
before evaluating the body.
The return value of the do-while expression
is the last evaluation of the body expression.

doargs

syntax: (doargs (sym [exp-break]) body)

Iterates through all members of the argument list
inside a user-defined function or macro. This function or macro can be defined using define,
define-macro, lambda, or
lambda-macro.
The variable in sym is set sequentially to all members in the argument list
until the list is exhausted or an optional break expression
(defined in exp-break) evaluates to true or a logical true value.
The doargs expression always returns the result of the last evaluation.

doargs also updates the system iterator symbol $idx.

(define (foo)
(doargs (i) (println i)))
> (foo 1 2 3 4)
1
2
3
4

The optional break expression causes doargs
to interrupt processing of the arguments:

dolist

syntax: (dolist (symlist|array [exp-break]) body)

The expressions in body are evaluated
for each element in list or array.
The variable in sym 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.

Optionally, a condition for early loop exit
may be defined in exp-break.
If the break expression evaluates to any non-nil value,
the dolist loop returns with the value of exp-break.
The break condition is tested before evaluating body.

This example prints abcdefg in the console window.
After the execution of dolist,
the value for x remains unchanged
because the x in dolist has local scope.
The return value of dolist is the result
of the last evaluated expression.

The internal system variable $idx
keeps track of the current offset
into the list passed to dolist,
and it can be accessed during its execution:

syntax: (dostring (symstring [exp-break]) body)

The expressions in body are evaluated
for each character in string.
The variable in sym 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.

Optionally, a condition for early loop exit
may be defined in exp-break.
If the break expression evaluates to any non-nil value,
the dolist loop returns with the value of exp-break.
The break condition is tested before evaluating body.

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 dostring is the result
of the last evaluated expression.

The internal system variable $idx
keeps track of the current offset
into the string passed to dostring,
and it can be accessed during its execution.

dotimes

syntax: (dotimes (sym-varint-count [exp-break]) body)

The expressions in body are evaluated int times.
The variable in sym is set from 0 (zero) to (int - 1)
each time before evaluating the body expression(s).
The variable used as the loop index is local to the dotimes
expression and behaves according the rules of dynamic scoping.
The loop index is of integer type.
dotimes returns the result of
the last expression evaluated in body.
After evaluation of the dotimes
statement sym assumes its previous
value.

Optionally, a condition for early loop exit
may be defined in exp-break.
If the break expression evaluates to any non-nil value,
the dotimes loop returns with the value of exp-break.
The break condition is tested before evaluating body.

(dotimes (x 10)
(print x)) → 9 ; return value

This prints 0123456789 to the console window.

dotree

syntax: (dotree (symsym-context [bool]) body)

The expressions in body are evaluated for all symbols in sym-context.
The symbols are accessed in a sorted order. Before each evaluation of the body expression(s),
the variable in sym is set to the next symbol from sym-context.
The variable used as the loop index is local to the dotree expression
and behaves according the rules of dynamic scoping.

When the optional bool expression evaluates to not nil, only symbols
starting with an underscore character _ are accessed. Symbol names starting with
an _ underscore are used for hash keys and symbols created by
bayes-train.

This example prints the names of all symbols inside SomeCTX to the console window.

dump

syntax: (dump [exp])

Shows the binary contents of a newLISP cell.
Without an argument, this function outputs
a listing of all Lisp cells to the console.
When exp is given,
it is evaluated and the contents
of a Lisp cell are returned in a list.

cell->contents:
string/symbol address or
high (little endian) or low (big endian) word of 64-bit integer or
high word of IEEE 754 double float

This function is valuable for changing type bits in cells
or hacking other parts of newLISP internals.
See the function cpymem
for a comprehensive example.

dup

syntax: (dup expint-n [bool])
syntax: (dup exp)

If the expression in exp evaluates to a string,
it will be replicated int-n times within a string and returned.
When specifying an expression evaluating
to anything other than nil in bool,
the string will not be concatenated
but replicated in a list like any other data type.

If exp contains any data type other than string,
the returned list will contain int-n evaluations of exp.

The first example checks a list,
while the second two examples check a string.

encrypt

syntax: (encrypt str-sourcestr-pad)

Performs a one-time pad (OTP)
encryption of str-source using the encryption pad in str-pad.
The longer str-pad 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–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:

env

syntax: (env)
syntax: (env var-str)
syntax: (env var-strvalue-str)

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.

(env)
→ (("PATH" "/bin:/usr/bin:/sbin") ("TERM" "xterm-color") ... ))

In the second syntax, the name of an environment variable
is given in var-str. env returns the value
of the variable or nil if the variable does not exist
in the environment.

(env "PATH") → "/bin:/usr/bin:/usr/local/bin"

The third syntax (variable name in var-str
and value pair in value-str) sets or creates
an environment variable. If value-str is the
empty string "", then the variable is completely
removed from the environment except when running on Solaris,
where the variable stays with an empty string.

error-event

sym-event-handler contains a user-defined function for handling errors.
Whenever an error occurs, the system performs a reset
and executes the user-defined error handler. The error handler can use the
built-in function last-error to retrieve the number
and text of the error. The event handler is specified as either a quoted
symbol or a lambda function.

In the example, the parameter 'data is quoted,
so push can work on the original list.

There is a safer method to pass arguments by reference in newLISP
by enclosing the data inside context objects.
See the chapter Passing data by reference.
Passing references into user defined
function using namespace ids avoids variable capture of
the passed symbol, in case the symbol passed is the same used as a
parameter in the function.

eval-string

The string in str-source 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.

An optional second argument can be used to specify the context to which
the string should be parsed and translated.

If an error occurs while parsing and evaluating str-source then
exp-error will be evaluated and the result returned.

int-offset specifies an optional offset into str-source,
where to start evaluation.

syntax: (eval-string-js str-JavaScript-source)

The function takes a program source in str-JavaScript-source
and returns the result in a string.

This function is only available on newLISP compiled to JavaScript.

(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")

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

See also the function display-html for displaying
an HTML page in the browser.

exec

syntax: (exec str-process)
syntax: (exec str-process [str-stdin])

In the first form, exec launches a process described in str-process
and returns all standard output as a list of strings
(one for each line in standard out (STDOUT)). exec returns nil
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.

(exec "ls *.c") → ("newlisp.c" "nl-math.c" "nl-string.c")

The example starts a process and performs the shell command ls,
capturing the output in an array of strings.

In the second form,
exec creates a process pipe,
starts the process in str-process,
and receives from str-stdin
standard input for this process.
The return value is true
if the process was successfully launched;
otherwise it is nil.

(exec "cgiProc" query)

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.

exists

syntax: (exists func-conditionlist)

Successively applies func-condition
to the elements of list
and returns the first element
that meets the condition in func-condition.
If no element meets the condition,
nil is returned.

If func-condition is nil?, the result nil is ambiguous.
In this case index or find are the better
method when looking for nil.

Use the for-all function
to check if a condition is met for all elements in a list.

exit

syntax: (exit [int])

Exits newLISP.
An optional exit code, int, may be supplied.
This code can be tested by the host operating system.
When newLISP is run in daemon server mode
using -d as a command-line option,
only the network connection is closed,
while newLISP stays resident,
listening for a new connection.

(exit 5)

exp

syntax: (exp num)

The expression in num is evaluated, and the exponential function
is calculated based on the result. exp is the inverse function of
log.

(exp 1) → 2.718281828
(exp (log 1)) → 1

expand

In the first syntax, one symbol in sym
(or more in sym-2 through sym-n)
is looked up in a simple or nested expression exp.
They are then expanded to the current binding of the symbol
and the expanded expression is returned. The original list remains unchanged.

Note that the contents of the variables
in the association list will not change.
This is different from the letex function,
where variables are set by evaluating
and assigning their association parts.

This form of expand is frequently used
in logic programming,
together with the unify function.

syntax: (expand list)

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 expand,
symbols must be preset.
Only uppercase variables and those bound
to anything other than nil
will be expanded:

In the first syntax,
explode transforms the string (str)
into a list of single-character strings.
Optionally, a chunk size can be specified in int-chunk
to break the string into multi-character chunks.
When specifying a value for bool other than nil,
the last chunk will be omitted
if it does not have the full length specified
in int-chunk.

Only on non UTF8– enabled versions, explode also works on binary content:

(explode "\000\001\002\003")
→ ("\000" "\001" "\002" "\003")

When called in UTF-8–enabled versions of newLISP,
explode will work on character boundaries rather than byte boundaries.
In UTF-8–encoded strings, characters may contain more than one byte.
Processing will stop when a zero byte character is found.

To explode binary contents on UTF-8–enabled versions of newLISP
use unpack as shown in the following example:

factor returns nil
for numbers smaller than 2.
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.

fft

syntax: (fft list-num)

Calculates the discrete Fourier transform
on the list of complex numbers in list-num
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 0.0 (zero).
When the number of elements in list-num
is not a power of 2,
fft increases the number of elements
by padding the list with zeroes.
When the imaginary part of a complex number is 0,
simple numbers can be used instead.

file-info

syntax: (file-info str-name [int-index [bool-flag]])

Returns a list of information about the file or directory in str_name.
The optional index specifies the list member to return. When no bool-flag
is specified or when bool-flag evaluates to nil information about
the link is returned if the file is a link to an original file. If bool-flag
evaluates to anything else than nil, information about the original file
referenced by the link is returned.

offset

contents

0

size

1

mode (differs with true flag)

2

device mode

3

user ID

4

group ID

5

access time

6

modification time

7

status change time

Depending on bool-flag set, the function reports on either
the link (no flag or nil flag) or on the original linked file
(true flag).

In the second example, the last status change date
for the directory /etc is retrieved.

file-info gives file statistics (size) for a linked file,
not the link, except for the mode field.

file?

syntax: (file? str-path-name [bool])

Checks for the existence of a file in str-name. Returns true
if the file exists; otherwise, it returns nil. This function will also return
true for directories. If the optional bool value is true,
the file must not be a directory and str-path-name is returned or nil
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.

filter

syntax: (filter exp-predicateexp-list)

The predicate exp-predicate is applied
to each element of the list exp-list.
A list is returned containing the elements
for which exp-predicate is true.
filter works like clean,
but with a negated predicate.

Using match and unify,
list searches can be formulated which are as powerful
as regular expression searches are for strings.

Find a string in a string

If the second argument, str-data,
evaluates to a string, then the offset position
of the string str-key (found in the first argument,
str-data) is returned. In this case, find
also works on binary str-data. The offset position
returned is always based on counting single byte characters
even when running the UTF-8 enabled version of newLISP.

The presence of a third parameter specifies a search
using the regular expression pattern specified in str-pattern,
as well as an option number specified in regex-option
(i.e., 1 (one) for case-insensitive search or 0 (zero)
for no special options). If regex-option is specified
an optional int-offset 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 find is calculated
relative to the beginning of the string.

To specify int-offset in a simple string search without regular
expressions, specify nil for regex-option.

In newLISP, regular expressions are standard
Perl Compatible Regular Expression (PCRE) searches.
Found expressions or subexpressions are returned
in the system variables $0, $1, $2, etc.,
which can be used like any other symbol.
As an alternative,
the contents of these variables
can also be accessed
by using ($ 0), ($ 1), ($ 2), etc.
This method allows indexed access
(i.e., ($ i), where i is an integer).

See regex for the meaning of the
option numbers and more information on regular expression searching.

find-all

In the first syntax, find-all finds all occurrences of str-regex-pattern
in the text str-text, returning a list containing all matching strings.
The empty list () is returned if no matches are found. In the first syntax
string searches are always done using regular expression patterns, even if no
regex-option is specified. The system variable $count is updated
with the number of matches found.

Optionally, an expression can be specified to process the found string or regular subexpressions
before placing them into the returned list. An additional option, regex-option,
specifies special regular expression options
(see regex for further details).

The first example discovers all numbers in a text.
The second example shows how an optional expression in exp
can work on subexpressions found by the regular expression pattern
in str-pattern. The last example retrieves a web page,
cleans out all HTML tags, and then collects all words
into a unique and sorted list.

Note that find-all with strings always performs a regular expression search,
even if the option in regex-option is omitted.

In the second syntax, find-all searches for all list
match patterns list-match-pattern in
list. As in find-all for strings, an expression can
be specified in exp to process further the matched sublist found in
list. The system variable $count is updated with the number
of matches found.

Any type of expression can be searched for or can be contained in the list. find-all
in this syntax works similar to filter but with the added benefit of
being able to define a processing expression for the found element.

If no func-compare is defined and exp-key is a list, then
match will be used for comparison, as in the second syntax.

float

syntax: (float exp [exp-default])

If the expression in exp
evaluates to a number or a string,
the argument is converted to a float
and returned.
If exp cannot be converted to a float
then nil or, if specified,
the evaluation of exp-default
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 + (plus sign), - (minus sign),
or . (period).
If exp is invalid,
float returns nil
as a default value.

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.

floor

syntax: (floor number)

flt

syntax: (flt number)

Converts number 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.

fn

syntax: (fn (list-parameters) exp-body)

fn or lambda are used to define anonymous functions,
which are frequently used in map, sort,
and all other expressions where functions can be used as arguments.
The fn or lambda word does not exist on its own as a symbol,
but indicates a special list type: the lambda list. Together with fn-macro
and lambda-macro 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.

Using an anonymous function eliminates the need to define a new function with
define. Instead, a function is defined on the fly:

The example defines the function fn(x), which takes an integer
(x) and doubles it. The function is mapped onto a list of
arguments using map. The second example shows strings being
sorted by length.

The lambda function (the longer, traditional form of writing)
can be used in place of fn.

for

syntax: (for (symnum-fromnum-to [num-step [exp-break]]) body)

Repeatedly evaluates the expressions in body
for a range of values specified
in num-from and num-to, inclusive.
A step size may be specified with num-step.
If no step size is specified, 1 is assumed.

Optionally, a condition for early loop exit
may be defined in exp-break.
If the break expression evaluates
to any non-nil value,
the for loop returns with
the value of exp-break.
The break condition is tested
before evaluating body. If a
break condition is defined, num-step
must be defined, too.

The symbol sym
is local in dynamic scope
to the for 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 for
statement sym assumes its previous
value.

Use the exists function
to check if at least one element in a list
meets a condition.

fork

syntax: (fork exp)

The expression in exp 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 exp finishes.

On success, fork returns with the child process ID; on failure,
nil is returned. See also the wait-pid function,
which waits for a child process to finish.

This function is only available on Linux/Unix versions of newLISP
and is based on the fork() implementation of the underlying OS.

A much simpler automated method to launch processes and collect
results is available with spawn and the Cilk API.

The example illustrates how the child process-thread inherits the symbol space
and how it is independent of the parent process. The fork statement
returns immediately with the process ID 176. The child process increments
the variable x by one each second and prints it to standard out (boldface).
In the parent process, commands can still be entered. Type x to see that
the symbol x still has the value 0 (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.

The second example illustrates how pipe can be used
to communicate between processes.

format

Constructs a formatted string from exp-data-1
using the format specified in the evaluation of str-format.
The format specified is identical to the format used for the printf()
function in the ANSI C language. Two or more exp-data arguments
can be specified for more than one format specifier in str-format.

In an alternative syntax, the data to be formatted
can be passed inside a list in list-data.

format checks for a valid format string,
matching data type, and the correct number of arguments.
Wrong formats or data types result in error messages.
int, float,
or string can be used
to ensure correct data types and to avoid error messages.

On Linux the percent sign can be followed by a single quote %'
to insert thousand's separators in number formats.

The w 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
+ (plus sign), positive numbers are displayed with a +.
When preceded by a 0 (zero), the unused space is filled with leading
zeroes. The width field is optional and serves all data types.

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

The f represents a type flag and is essential;
it cannot be omitted.

Below are the types in f:

format

description

s

text string

c

character (value 1 - 255)

d

decimal (32-bit)

u

unsigned decimal (32-bit)

x

hexadecimal lowercase

X

hexadecimal uppercase

o

octal (32-bits) (not supported on all of newLISP flavors)

f

floating point

e

scientific floating point

E

scientific floating point

g

general floating point

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
0xFFFFFFFF on 32-bit systems.

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:

format

description

ld

decimal (32/64-bit)

lu

unsigned decimal (32/64-bit)

lx

hexadecimal (32/64-bit)

lX

hexadecimal uppercase (32/64-bit)

For 64-bit numbers use the following format strings on Unix-like
operating systems and on MS Windows (not supported on TRU64):

format

description

lld

decimal (64-bit)

llu

unsigned decimal (64-bit)

llx

hexadecimal (64-bit)

llX

hexadecimal uppercase(64-bit)

On Windows platforms only the following characters apply
for 64 bit numbers:

format

description

I64d

decimal (64-bit)

I64u

unsigned decimal (64-bit)

I64x

hexadecimal (64-bit)

I64X

hexadecimal uppercase(64-bit)

Other text may occur between,
before, or after the format specs.

Note that on Tru64 Unix the format character i can be used instead
of d.

If the format string requires it,
newLISP's format will
automatically convert integers
into floating points
or floating points into integers:

(format "%f" 123) → 123.000000
(format "%d" 123.456) → 123

fv

syntax: (fv num-ratenum-npernum-pmtnum-pv [int-type])

Calculates the future value of a loan with constant payment num-pmt
and constant interest rate num-rate after num-nper period of
time and a beginning principal value of num-pv. If payment is at the
end of the period, int-type is 0 (zero) or int-type is
omitted; for payment at the beginning of each period, int-type is 1.

(fv (div 0.07 12) 240 775.30 -100000) → -0.5544645052

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.

syntax: (gcd int-1 [int-2 ... ])

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.
gcd will calculate the greatest common divisor
for the first two integers in int-i
and then further reduce the argument list
by calculating the greatest common divisor of the result
and the next argument in the parameter list.

syntax: (get-float int-address)

Gets a 64-bit double float from an address
specified in int-address.
This function is helpful when using
imported shared library functions (with import)
that return an address pointer to a double float
or a pointer to a structure containing double floats.

foo is imported and returns a pointer
to a double float when called.
Note that get-float is unsafe when used
with an incorrect address in int-address
and may result in the system crashing or becoming unstable.

syntax: (get-int int-address)

Gets a 32-bit integer from
the address specified in int-address.
This function is handy when using
imported shared library functions with import,
a function returning an address pointer
to an integer, or a pointer to a structure containing integers.

syntax: (get-long int-address)

Gets a 64-bit integer from
the address specified in int-address.
This function is handy when using import
to import shared library functions,
a function returning an address pointer to a long integer,
or a pointer to a structure containing long integers.

syntax: (get-string int-address [int-bytes [str-limit])

Copies a character string from the address specified in int-address.
This function is helpful when using imported shared library functions with
import and a C-function returns the address to a memory buffer.

Consider the above C function from a shared library,
which returns a character pointer (address to a string).

(import "mylib.so" "foo")
(print (get-string (foo))) → "ABCDEFG"

When a string is passed as an argument,
get-string will take its address as the argument.
Without the optional int-bytes argument get-string breaks off
at the first first \000 (null character) it encounters. This works for
retrieving ASCII strings from raw memory addresses:

When specifyung the number of bytes in the optional int-bytes
parameter, reading does not stpop at the first zero byte found, but
copies exactly int-bytes number of bytes from the address or string
buffer:

(set 'buff "ABC\000\000\000DEF") → "ABC\000\000\000DEF"
; without specifying the number of bytes
; buff is equivalent to (address buff)
(get-string buff) → "ABC"
; specifying the number of bytes to get
(get-string buff 9) → "ABC\000\000\000DEF"

The addtional str-limit parameter can be used to limit reading
the buffer at a certain string. If int-bytes are read before
str-limit is found, only int-bytes are read:

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 str-limit can be used to limit
the string when reading from the buffer address:

Note that get-string can crash the system
or make it unstable if the wrong address is specified.

get-url

syntax: (get-url str-url [str-option] [int-timeout [str-header]])

Reads a web page or file specified by the URL in str-url using
the HTTP GET protocol. Both http:// and file://
URLs are handled. "header" can be specified in the optional argument
str-option to retrieve only the header. The option "list"
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 "raw" option (since 10.6.4), which can be used alone or combined
with other options, suppresses header location redirection.

A "debug" option can be specified either alone or after the
"header" or "list" option separated by one character,
i.e. "header debug" or "list debug". Including "debug"
outputs all outgoing information to the console window.

The optional argument int-timeout can specify a value in milliseconds.
If no data is available from the host after the specified timeout, get-url
returns the string ERR: timeout. When other error conditions occur,
get-url returns a string starting with ERR: and the description
of the error.

get-url handles redirection if it detects a Location: spec
in the received header and automatically does a second request.
get-url also understands the Transfer-Encoding: chunked
format and will unpack data into an unchunked format.

The index page from the site specified
in str-url 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.

The second example shows usage of a file:// URL
to access /home/db/data.txt on the local file system.

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 env
function.

The int-timeout can be followed
by an optional custom header in str-header:

Custom header

The custom header may contain options
for browser cookies or other directives to the server.
When no str-header is specified,
newLISP sends certain header information by default.
After the following request:

Note that when using a custom header,
newLISP will only supply the GET request line,
as well as the Host: and Connection: header entries.
newLISP inserts all other entries supplied in the custom header
between the Host: and Connection: entries.
Each entry must end with a carriage return
line-feed pair: \r\n.

global

syntax: (global sym-1 [sym-2 ... ])

One or more symbols in sym-1 [sym-2 ... ]
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.
global returns the last symbol made global.

history

syntax: (history [bool-params])

history returns a list of the call history of the enclosing function.
Without the optional bool-params, a list of function symbols is returned.
The first symbol is the name of the enclosing function. When the optional
bool-params evaluates to true, the call arguments are included
with the symbol.

if

If the value of exp-condition is neither nil nor an empty list,
the result of evaluating exp-1 is returned; otherwise, the value of
exp-2 is returned. If exp-2 is absent, the value of
exp-condition is returned.

if also sets the anaphoric system variable $it to the value
of the conditional expression in if.

The last expression, "n/a", is optional. When this option
is omitted, the evaluation of (>= x 30) is returned, behaving
exactly like a traditional cond but without requiring
parentheses around the condition-expression pairs.

In any case, the whole if expression
always returns the last expression or condition evaluated.

ifft

syntax: (ifft list-num)

Calculates the inverse discrete Fourier transform
on a list of complex numbers in list-num
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 0.0 (zero).
When the number of elements in list-num
is not an integer power of 2,
ifft increases the number of elements
by padding the list with zeroes.
When complex numbers are 0 in the imaginary part,
simple numbers can be used.

Imports the function specified in str-function-name
from a shared library named in str-lib-name. Depending on the syntax used, string
labels for return and parameter types can be specified

If the library in str-lib-name is not in the system's library path, the
full path name should be specified.

A function can be imported only once. A repeated import of the same function
will simply return the same - already allocated - function address.

Note, that the first simple syntax is available on all versions of newLISP, even those compiled without libffi support. On libffi enabled versions - capable of the second extended syntax -
imported symbols are protected against change and can only be modified using
constant.

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.

Incorrectly using import can cause a system bus error or a segfault can occur
and crash newLISP or leave it in an unstable state.

The simple import syntax

Most library functions can be imported using the simpler first syntax.
This form is present on all compile flavors of newLISP. The API expects
all function arguments to be passed on the stack in either cdecl or stdcall
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
get-string helper function. Regardless of these
limitations, most modules included in the distribution use
this simple import API.

To pass pointers for data structures the following functions help to pack data
and calculate addresses:
address,
pack.

To transform newLISP data types into the data types needed by the
imported function, use the functions
float for 64-bit double floats,
flt for 32-bit floats,
and int 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 extended import syntax.

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.

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.

The other examples show several imports of MS Windows DLL functions and
the details of passing values by value or by reference.
Whenever strings or numbers are passed by reference, space must be
reserved beforehand.

The MS Windows and Cygwin versions of newLISP uses standard call stdcall 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 cdecl calling conventions and may need to specify the string
"cdecl" as an additional last argument when importing functions.
newLISP compiled for macOS, Linux and other Unix systems uses the
cdecl calling conventions by default and ignores any additional string.

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

The extended import syntax

The extended import API works with the second syntax. It is based on the popular
libffi library which is pre-installed on most OS platforms. The startup banner
of newLISP should show the word libffi indicating the running version
of newLISP is compiled to use the extended import API. The function
sys-info can also be used to check for libffi-support.

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

The following types can be specified for the return value in str-return-type
and for function parameters in str-param-type:

The char* type takes a string buffer only. The "void* type can take either
a string buffer or a memory address number as input. When using "void*"
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 unpack and struct for destructuring.
In the following example the return type is changed to void*:

Memory management

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 Code Patterns in newLISP
document for an example.

In case of calling foreign functions with passing by reference,
memory for variables needs to be allocated beforehand by newLISP
— see import of GetWindowsDirectoryA above —
and hence, memory needs not be deallocated manually, because it is
managed automatically by newLISP.

inf?

syntax: (inf? float)

Note that an integer division by zero e.g. (/ 1 0) will
throw an "division by zero" error and not yield infinity. See also
NaN? to check if a floating point number is valid.

int

syntax: (int exp [exp-default [int-base]])

If the expression in exp evaluates to a number or a string, the result
is converted to an integer and returned. If exp cannot be converted
to an integer, then nil or the evaluation of exp-default will
be returned. This function is mostly used when translating strings from user
input or from parsing text. If exp evaluates to a string, the string
must start with a digit; one or more spaces; or the + or - sign.
The string must begin with '0x' for hexadecimal strings or '0'
(zero) for octal strings. If exp is invalid, int returns
nil as a default value if not otherwise specified.

A second optional parameter can be used to force the number base
of conversion to a specific value.

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.

When converting from a float (as in the second form of int),
floating point values larger or smaller than the integer maximum or minimum
are also truncated. A floating point expression evaluating to NaN
is converted to 0 (zero).

Use the float function
to convert arguments to floating point numbers.

integer?

syntax: (integer? exp)

Returns true only if the value
of exp is an integer;
otherwise, it returns nil.

(set 'num 123) → 123
(integer? num) → true

intersect

syntax: (intersect list-Alist-B)
syntax: (intersect list-Alist-Bbool)

In the first syntax,
intersect returns a list
containing one copy of each element
found both in list-A and list-B.

(intersect '(3 0 1 3 2 3 4 2 1) '(1 4 2 5))
→ (2 4 1)

In the second syntax,
intersect returns a list of all elements
in list-A that are also in list-B,
without eliminating duplicates in list-A.
bool is an expression evaluating to true
or any other value not nil.

invert

syntax: (invert matrix [float-pivot])

Returns the inversion of a two-dimensional matrix in matrix.
The matrix must be square, with the same number
of rows and columns, and non-singular (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.

Optionally 0.0 or a very small value can be specified
in float-pivot. This value substitutes pivot elements in
the LU-decomposition algorithm, which result in zero when
the algorithm deals with a singular matrix.

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, 0.0 (zero) is assumed.
A matrix can either be a nested list or an array.

irr

syntax: (irr list-amounts [list-times [num-guess]])

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 0.0 (zero).
In-flowing (negative values) and out-flowing (positive values)
amounts are specified in list-amounts.
If no time periods are specified in list-times,
amounts in list-amounts correspond to
consecutive time periods increasing by 1 (1, 2, 3—).
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.
nil is returned if the algorithm
cannot converge after 50 iterations.

If an initial investment of 1,000
yields 500 after the first year,
400 after two years, and so on,
finally reaching 0.0 (zero) after five years,
then that corresponds to a yearly return
of about 20.2 percent.
The next line demonstrates the relation
between irr and npv.
Only 9.9 percent returns are necessary when making
the first withdrawal after three years.

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.

json-parse

syntax: (json-parse str-json-data)

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
false and null will be represented by the symbols false
and null 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
assoc, lookup and ref.

For JSON attribute values not recognized or wrong JSON syntax, json-parse
returns nil and json-error can be used to retrieve
the error text.

The following example shows a nested JSON object from a file person.json:

The hex-code representation of Unicoder characters in JSON is the same as can be used in
UTF-8 enabled newLISP.

Because JSON objects contain {,}," characters, quotes should not be used
to limit JSON data, or all quotes inside the JSON data would need a preceding backslash \.
{,} braces can be used as long as braces inside the JSON data are balanced.
The safest delimiter are [text], [/text] tags — they suppress all special processing
of the string when read by newLISP and are suitable to delimit large data sizes greater
2047 bytes.

join

syntax: (join list-of-strings [str-joint [bool-trail-joint]])

Concatenates the given
list of strings
in list-of-strings.
If str-joint is present,
it is inserted between each string in the join.
If bool-trail-joint is true
then a joint string is also appended to the last string.

kmeans-query

In the first usage, kmeans-query calculates the Euclidian distances
from the data vector given in list-data to the centroids given in
matrix-centroids. The data vector in list-data has m
elements. The 2-dimensional list in matrix-centroids, result from a previous
kmeans-train clustering, has k rows and m
columns for k centroids measuring m features.

The data record (1 2 3) shows the smallest distance to the 3rd
cluster centroid and would be classified as belonging to that cluster.

In the second application kmeans-query calculates Euclidian distances to a list
of other data points which are not centroids. The following example
calculates distances of the (1 2 3) data vector to all original points
from the original kmeans-train data analysis.

The data in matrix-data can be either a nested list or a 2-dimensional
array.

This vector could be sorted for a subsequent kNN (k Nearest Neighbor)
analysis:

We see that the smallest distances are shown for the data points in
the 3rd cluster at offset 2.

If the numbers of elements - features - in records of list-data
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.

kmeans-train

syntax: (kmeans-train matrix-dataint-kcontext [matrix-centroids])

The function performs Kmeans cluster analysis on matrix-data.
All n data records in matrix-data are partitioned into a number
of int-k different groups.

Both, the n * mmatrix-data and the optional k * mmatrix-centroids can be either nested lists or 2-dimensional arrays.

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.

When no optional matrix-centroids are given, kmeans-train will
assign an initial random cluster membership to each data row and calculate starting
centroids.

kmeans-train 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.

Other results of the analysis are stored as lists in variables of context.

The following example analyses 20 data records measuring m = 3 features
and tries to partition data into k = 3 clusters. Other numbers than k = 3
could be tried. The target is a result with few clusters of high density measured by the
average inner cluster distances.

The returned list of SSQs shows how in each iteration the sum of inner squared
distances decreases. The list in K:labels shows the membership fo each
data point in the same order as in the data.

The centroids in K:centroids can be used for later classification
of new data records using kmeans-query. When the
number of clusters specified in int-k is too big, kmeans-train
will produce unused centroids with nan or NaN data. When
unused cluster centroids are present, the number in int-k should be
reduced.

The average inner K:deviations 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:

See also net-error for errors generated by
networking conditions and sys-error for errors
generated by the operating system.

legal?

syntax: (legal? str)

The token in str is verified as a legal newLISP symbol.
Non-legal symbols can be created using the sym 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:

let

One or more variables sym1, sym2, ... are declared locally and
initialized with expressions in exp-init1, exp-init2, etc.
In the fully parenthesized first syntax, initializers are optional and assumed
nil if missing.

When the local variables are initialized, the initializer expressions evaluate
using symbol bindings as before the let statement. To incrementally use
symbol bindings as evaluated during the initialization of locals in let,
use letn.

One or more expressions in exp-body are evaluated using the local
definitions of sym1, sym2 etc. let 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.

letn

letn is like a nested let and works similarly to let,
but will incrementally use the new symbol bindings when evaluating the initializer expressions
as if several let were nested. In the fully parenthesized first syntax,
initializers are optional and assumed nil if missing.

While in the first example using let the variable y is
calculated using the binding of x before the let expression,
in the second example using letn the variable y is calculated using
the new local binding of x.

load

syntax: (load str-file-name-1 [str-file-name-2 ... ] [sym-context])

Loads and translates newLISP from a source file specified in one or more str-file-name
and evaluates the expressions contained in the file(s). When loading is successful,
load returns the result of the last expression in the last file evaluated. If a file
cannot be loaded, load throws an error.

An optional sym-context 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 context switches
will be loaded into the MAIN context.

The str-file-name specs can contain URLs. Both http:// and file://
URLs are supported.

In case expressions evaluated during the load are changing the
context, this will not influence the programming
module doing the load.

The current context after the load statement will always be
the same as before the load.

Normal file specs and URLs can be mixed in the same load command.

load with HTTP URLs can also be used to load code
remotely from newLISP server nodes running on a Unix-like operating system.
In this mode, load 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. load
in HTTP mode will observe a 60-second timeout.

The second to last line causes the files to be loaded into the context MyCTX.
The quote forces the context to be created if it did not exist.

The file:// URL is followed by a third / for the directory spec.

local

syntax: (local (sym-1 [sym-2 ... ]) body)

Initializes one or more symbols
in sym-1— to nil,
evaluates the expressions in body,
and returns the result of the last evaluation.

local works similarly to let,
but local variables are all initialized to nil.

local provides a simple way
to localize variables
without explicit initialization.

log

syntax: (log num)
syntax: (log numnum-base)

In the first syntax, the expression in num is evaluated and the natural
logarithmic function is calculated from the result.

(log 1) → 0
(log (exp 1)) → 1

In the second syntax, an arbitrary base can be specified in num-base.

(log 1024 2) → 10
(log (exp 1) (exp 1)) → 1

See also exp, which is the inverse function to log with
base e (2.718281828).

lookup

syntax: (lookup exp-keylist-assoc [int-index [exp-default]])

Finds in list-assoc an association, the key element of which
has the same value as exp-key, and returns the int-index element of
association (or the last element if int-index is absent).

Optionally, exp-default can be specified, which is returned if an association matching
exp-key cannot be found. If the exp-default is absent and no association
has been found, nil is returned.

macro

syntax: (macro (sym-name [sym-param-1 ... ]) [body-1 ... ])

The macro function is used to define expansion macros. The syntax
of macro is identical to the syntax of define-macro.
But while define-macro defines are fexprs functions to be evaluated
at run-time, macro defines a function to be used during the source loading
and reading process to transform certain expression call patterns into different call
patterns.

Internally all macro defined symbol call patterns are translated using
the expand expression during source reading. This can be shown using
the read-expr function:

(read-expr "(double 123)") → (+ 123 123)

All variable names to be expanded must start in upper-case. Macros can be nested containing
other macros defined earlier. But macro 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 macro definition, use the
constant function in the following way:

In both cases the incoming expression (inc a) gets evaulated twice.
This must be considered when writing both, macro or define-macro
expressions and symbols occur more than once in the body of the definition.

See also reader-event for general preprocessing
of expressions during reading of source code.

macro?

syntax: (macro? exp)

Returns true if exp evaluates to a lambda-macro expression.
If exp evaluates to a symbol and the symbol contains
a macro-expansion expression made with the macro function,
true is also returned. In all other cases nil is returned.

make-dir

syntax: (make-dir str-dir-name [int-mode])

Creates a directory as specified in str-dir-name,
with the optional access mode int-mode.
Returns true or nil
depending on the outcome.
If no access mode is specified,
most Unix systems default to drwxr-xr-x.

On Unix systems, the access mode specified
will also be masked by the OS's user-mask
set by the system administrator.
The user-mask can be retrieved
on Unix systems using the command umask
and is usually 0022 (octal),
which masks write (and creation) permission
for non-owners of the file.

;; 0 (zero) in front of 750 makes it an octal number
(make-dir "adir" 0750)

This example creates a directory named adir
in the current directory with an access mode of
0750 (octal 750 = drwxr-x---).

map

syntax: (map exp-functorlist-args-1 [list-args-2 ... ])

Successively applies the primitive function, defined function, or lambda expression
exp-functor to the arguments specified in list-args-1 list-args-2—,
returning all results in a list. Since version 10.5.5 list-args
can also be array vectors, but the returned result will always be a list.

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.

Special forms which use parentheses as syntax cannot be mapped
(i.e. case).

mat

Using the first syntax, this function performs fast floating point
scalar operations on two-dimensional matrices in matrix-A or matrix-B.
The type of operation is specified by one of the four arithmetic operators
+, -, *, or /.
This type of arithmetic operator is typically used for integer
operations in newLISP. In the case of mat, however,
all operations will be performed as floating point operations
(add, sub, mul, div).

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
multiply and invert.

match

syntax: (match list-patternlist-match [bool])

The pattern in list-pattern is matched
against the list in list-match,
and the matching expressions are returned in a list.
The three wildcard characters ?, +,
and * can be used in list-pattern.

Wildcard characters may be nested.
match returns a
list of matched expressions.
For each ? (question mark),
a matching expression element is returned.
For each + (plus sign) or
* (asterisk), a list containing
the matched elements is returned.
If the pattern cannot be matched
against the list in list-match,
match returns nil.
If no wildcard characters are present
in the pattern an empty list is returned.

Optionally, the Boolean value true (or any other expression not
evaluating to nil) can be supplied as a third argument. This
causes match to show all elements in the returned result.

max

syntax: (max num-1 [num-2 ... ])

member

syntax: (member explist)
syntax: (member str-keystr [num-option])

In the first syntax,
member searches
for the element exp
in the list list.
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,
nil is returned.
When specifying num-option,
member performs a regular expression search.

min

syntax: (min num-1 [num-2 ... ])

mod

syntax: (mod num-1num-2 [num-3 ... ])
syntax: (mod num-1)

Calculates the modular value of the
numbers in num-1 and num-2.
mod computes the remainder
from the division of the numerator num-i
by the denominator num-i + 1.
Specifically, the return value is
numerator - n * denominator,
where n 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.

In the second syntax 1 is assumed for num-2 and the
result is the fractional part of num-1.

mul

syntax: (mul num-1num-2 [num-3 ... ])

Evaluates all expressions num-1—,
calculating and returning the product.
mul can perform mixed-type arithmetic,
but it always returns floating point numbers.
Any floating point calculation with
NaN also returns NaN.

(mul 1 2 3 4 5 1.1) → 132
(mul 0.5 0.5) → 0.25

multiply

syntax: (multiply matrix-Amatrix-B)

Returns the matrix multiplication of matrices
in matrix-A and matrix-B.
If matrix-A has the dimensions n by m
and matrix-B the dimensions k by l
(m and k must be equal),
the result is an n by l matrix.
multiply can perform mixed-type arithmetic,
but the results are always double precision floating points,
even if all input values are integers.

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,
0.0 is assumed.
A matrix can either be a nested list
or array.

Note that all floating point arithmetic operations
with a NaN yield a NaN.
All comparisons with NaN return nil,
but true when comparing to itself.
Comparison with itself, however,
would result in nottrue when using ANSI C. Integer operations
treat NaN as 0 (zero) values.

net-connect

In the first syntax, connects to a remote host computer specified in
str-remote-host and a port specified in int-port.
Returns a socket handle after having connected successfully;
otherwise, returns nil.

If successful, the net-connect 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
get-url offering the same functionality.

Optionally a timeout value int-timeout 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:

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.

On Unix net-connect may return with nil before
the timeout expires, when the port is not available. On MS Windows
net-connect will always wait for the timeout to expire before
failing with nil.

UDP communications

In the second syntax, a third parameter, the string "udp"
or "u" can be specified in the optional str-mode
to create a socket suited for UDP (User Datagram Protocol) communications.
In UDP mode, net-connect does not 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 net-send will send a UDP packet
containing that target address.
When using net-send-to, only one of the
two functions net-connect or net-send-to should
provide a target address. The other function should specify and empty
string "" as the target address.

The functions net-receive and
net-receive-from
can both be used and will perform UDP communications when the "udp"
option as been used in net-listen or net-connect.
net-select and net-peek
can be used to check for received data in a non-blocking fashion.

net-listen binds a specific
local address and port to the socket. When net-connect is used,
the local address and port will be picked by the socket-stack
functions of the host OS.

UDP multicast communications

When specifying "multi"
or "m" as a third parameter for str-mode,
a socket for UDP multicast communications
will be created.
Optionally, the fourth parameter
int-ttl can be specified
as a TTL (time to live) value.
If no int-ttl value is specified,
a value of 3 is assumed.

Note that specifying UDP multicast mode
in net-connect 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 net-listen
together with the UDP multicast option.

Note that on the receiving side,
net-listen should be used
with the default address
specified with an "" (empty string).
Broadcasts will not be received
when specifying an address.
As with all UDP communications,
net-listen does not actually put
the receiving side in listen mode,
but rather sets up the sockets
for the specific UDP mode.

The net-select
or net-peek functions
can be used to check for
incoming communications
in a non-blocking fashion.

Local domain Unix sockets

In the third syntax, net-connect connects to a server on the
local file system via a local domain Unix socket named using
str-file-path. Returns a socket handle after having connected
successfully; otherwise, returns nil.

A local domain file system socket is created and returned.
On the server side, local domain sockets have been created
using net-listen and net-accept.
After the connection has been established the functions net-select,
net-send and net-receive 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.

net-eval

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.

The expression in exp will be evaluated remotely in the environment
of the target node. The exp is either a quoted expression, or it is
enclosed in string delimiters. For bigger expressions [text] ... [/text]
delimiters can be used instead of double quotes " ... ". 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.

The -d daemon mode allows newLISP to maintain state between
connections. When keeping state between connections is not desired,
the inetd daemon mode offers more advantages.
The Internet inetd or xinetd services daemon
will start a new newLISP process for each client connection.
This makes for much faster servicing of multiple connections.
In -d daemon mode, each new client request
would have to wait for the previous request to be finished.
See the chapter inetd daemon mode
on how to configure this mode correctly.

Instead of 4711, any other port number can be used.
Multiple nodes can be started on different hosts and with the same
or different port numbers. The -l or -L logging options
can be specified to log connections and remote commands.

In the first syntax, net-eval talks to only one
remote newLISP server node, sending the host in str-host
on port int-port a request to evaluate the expression
exp. If int-timeout is not given,
net-eval will wait up to 60 seconds for a response
after a connection is made.
Otherwise, if the timeout in milliseconds has expired,
nil is returned; else, the evaluation result of exp
is returned.

The second syntax of net-eval returns a list of the results
after all of the responses are collected or timeout occurs. Responses that
time out return nil. The last example line shows how to specify
a local-domain Unix socket specifying the socket path and a port number of
0. 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 net-error for a list of
potential error messages.

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 0 for the port number , net-eval
takes the host name as the file path to the local-domain Unix socket.

Note that definitions of foo and myfunc must both
exist in the target environment. This can be done using a net-eval
sending define statements before. It also can be done by
preloading code when starting remote nodes.

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.

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
put-url or save (with a URL
file name) can be used to transfer programs. The a net-eval
statement could load these programs.

Optionally, a handler function can be specified. This function will be
repeatedly called while waiting and once for every remote evaluation completion.

While waiting for input from remote hosts, myhandler will be called
with nil as the argument to param. When a remote node result
is completely received, myhandler will be called with param
set to a list containing the remote host name or IP number, the port, and the
resulting expression. net-eval will return true before a
timeout or nil if the timeout was reached or exceeded. All remote hosts
that exceeded the timeout limit will contain a nil in their results list.

For a longer example see this program:
mapreduce.
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.

net-interface

syntax: (net-interface str-ip-addr)
syntax: (net-interface)

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
net-listen.

When no str-ip-addr is specified, the current default is returned.
If the net-interface has not been used yet to specify an IP address,
the address 0.0.0.0 is returned. This means that all network routines
will use the default address preconfigured by the underlying operating system.

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.

On error the function returns nil and net-error
can be used to report the error.

net-listen

Listens on a port specified in int-port. A call to net-listen
returns immediately with a socket number, which is then used by
the blocking net-accept function
to wait for a connection. As soon as a connection is accepted,
net-accept returns a socket number
that can be used to communicate with the connecting client.

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.

On computers with more than one interface card, specifying an optional
interface IP address or name in str-ip-addr directs net-listen
to listen on the specified address.

;; listen on a specific address
(net-listen port "192.168.1.54")

Local domain Unix sockets

In the second syntax, net-listen listens for a client on the
local file system via a local domain Unix socket named using
str-file-path. If successful, returns a socket handle that can be
used with net-accept to accept a client connection;
otherwise, returns nil.

A local domain file system socket is created and listened on.
A client will try to connect using the same str-file-path.
After a connection has been accepted the functions net-select,
net-send and net-receive 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.

UDP communications

As a third parameter,
the optional string "udp" or "u"
can be specified in str-mode
to create a socket suited for UDP
(User Datagram Protocol) communications.
A socket created in this way
can be used directly with
net-receive-from
to await incoming UDP data
without using net-accept,
which is only used in TCP communications.
The net-receive-from call
will block until a UDP data packet is received.
Alternatively, net-select
or net-peek can be used
to check for ready data in a non-blocking fashion.
To send data back to the address and port received
with net-receive-from,
use net-send-to.

Note that net-peer will not work,
as UDP communications do not maintain
a connected socket with address information.

Both a UDP server and UDP client
can be set up using net-listen
with the "udp" option.
In this mode, net-listen
does not really listen
as in TCP/IP communications;
it just binds the socket
to the local interface address and port.

For a working example, see the files
examples/client and examples/server
in the newLISP source distribution.

Instead of net-listen
and the "udp" option,
the functions net-receive-udp
and net-send-udp
can be used for short transactions
consisting only of one data packet.

net-listen, net-select,
and net-peek 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
net-receive-udp
and net-send-udp pair is used,
both sides close the sockets after sending and receiving.

UDP multicast communications

If the optional string str-mode is specified as
"multi" or "m",
net-listen returns a socket suitable for multicasting.
In this case, str-ip-addr contains one
of the multicast addresses in the range 224.0.0.0
to 239.255.255.255.
net-listen will register str-ip-addr
as an address on which to receive multicast transmissions.
This address should not be confused with the IP address
of the server host.

Packet divert sockets and ports

If str-mode is specified as "divert" or "d",
a divert socket can be created for a divert port in int-port on
BSD like platforms. The content of IP address in str-ip-addr is
ignored and can be specified as an empty string. Only the int-port
is relevant and will be bound to the raw socket returned.

To use the divert option in net-listen, newLISP must run in
super-user mode. This option is only available on Unix like platforms.

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.

Rules for packet diversion to the divert port must be defined using
either the ipfw BSD or ipchains Linux configuration
utilities.

Optionally, a bool flag
can be specified in the second syntax.
If the expression in bool
evaluates to anything other than nil,
host-by-name lookup will be forced,
even if the name string starts
with an IP number.

net-packet

syntax: (net-packet str-packet)

The function allows custom configured network packets to be sent via
a raw sockets interface. The packet in str-packet 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 net-packet is IPv4 only and has been tested on
macOS, Linux and OpenBSD.

On success the function returns the number of bytes sent. On failure
the function returns nil and both, net-error
and sys-error, should be inspected.

The following example injects a UDP packet for IP number 192.168.1.92.
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
Hello World. The checksum bytes in both headers are left as
0x00 0x00 and will be recalculated internally.

The net-packet 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.

For other examples of packet configuration, see the file
qa-specific-tests/qa-packet in the newLISP source distribution.

net-peek

syntax: (net-peek int-socket)

Returns the number of bytes
ready for reading
on the network socket int-socket.
If an error occurs
or the connection is closed,
nil is returned.

net-ping

This function is only available on Unix-based systems
and must be run in superuser mode, i.e. using: sudo newlisp to
start newLISP on macOS or other BSD's, or as the root user on Linux.
Broadcast mode and specifying ranges with the - (hyphen) or
* (star) are not available on IPv6 address mode.

Superuser mode is not required on macOS.

In the first syntax, net-ping sends a ping
ICMP 64-byte echo request to the address specified in str-address.
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 int-timeout.
If no timeout is specified, a waiting time of 1000 milliseconds
(one second) is assumed.

net-ping 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.

A return value of nil
indicates a failure.
Use the net-error function
to retrieve the error message. If the message reads Cannot open socket,
it is probably because newLISP is running without root permissions.
newLISP can be started using:

sudo newlisp

Alternatively, newLISP can be installed
with the set-user-ID bit set to run
in superuser mode.

In the second syntax, net-ping is run in batch mode.
Only one socket is opened in this mode, but multiple ICMP packets are sent out—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.

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 int-count. Usage of this parameter can cause
the function to return sooner than the specified timeout.
When a given number of responses has been received, net-ping will return
before the timeout has occurred. Not specifying int-count or specifying 0
assumes an int-count equal to the number of packets sent out.

As third optional parameter, a true value can be specified. This setting will
return an error string instead of the response time, if the host does not answer.

Broadcast or batch mode—as well as normal addresses
and IP numbers or hostnames— can be mixed in one net-ping statement by
putting all of the IP specs into a list.

The second and third lines show how the batch mode of net-ping
can be initiated by specifying the * (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.
net-ping will iterate through all numbers
from either 1 to 254 for the star * or the range specified,
sending an ICMP packet to each address.
Note that this is different from the broadcast mode
specified with an IP octet of 255.
While in broadcast mode, net-ping 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, int-count should be specified, too.

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 net-ping may return an incomplete list or the empty list ().
In this case, net-error will return a timeout error.
On error, nil is returned and net-error
can be used to retrieve an error message.

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 net-ping
invocations. In any case, net-ping will send out packages
as quickly as possible.

syntax: (net-receive int-socketsym-bufferint-max-bytes [wait-string])

Receives data on the socket int-socket into a string contained in sym-buffer.
sym-buffer can also be a default functor specified by a context symbol
for reference passing in and out of user-defined functions.

A maximum of
int-max-bytes is received. net-receive returns the number of
bytes read. If there is a break in the connection, nil is returned.
The space reserved in sym-buffer is exactly the size of bytes read.

Note that net-receive is a blocking call
and does not return until the data arrives at int-socket.
Use net-peek
or net-select to find out
if a socket is ready for reading.

Optionally, a wait-string
can be specified
as a fourth parameter.
net-receive then returns after
a character or string of characters
matching wait-string
is received.
The wait-string will be part
of the data contained in sym-buffer.

When calling gettime,
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.

The second example defines a new function
net-receive-line,
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.

Note that when the fourth parameter is specified,
net-receive is slower than the normal version
because information is read character-by-character.
In most situations, the speed difference can be neglected.

net-receive-from

syntax: (net-receive-from int-socketint-max-size)

net-receive-from can be used to set up
non-blocking UDP communications.
The socket in int-socket
must previously have been opened
by either net-listen
or net-connect
(both using the "udp" option).
int-max-size 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, net-receive-from
returns nil and closes the socket.

On success net-receive returns a list of the data string, remote
IP number and remote port used. On failure it returns nil.

The second line in this example is optional. Without it, the
net-receive-from 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.

Both, the sender and the receiver have to issue
net-listen 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
udp-server.lsp and udp-client.lsp in the
newlisp-x.x.x/examples/ directory of the source distribution.

Note that net-receive
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,
not the socket over which
communication takes place.
net-receive can also be used for TCP/IP communications.

See also the net-connect function
with the "udp" option and the
net-send-to function
for sending UDP data packets over open connections.

net-receive-udp

Receives a User Datagram Protocol (UDP) packet on port int-port,
reading int-maxsize bytes.
If more than int-maxsize bytes are received,
bytes over int-maxsize are discarded on Linux/BSD;
on MS Windows, net-receive-udp returns nil.
net-receive-udp blocks until a datagram arrives
or the optional timeout value in int-microsec expires.
When setting up communications between datagram sender and receiver,
the net-receive-udp statement must be set up first.

No previous setup using net-listen
or net-connect is necessary.

net-receive-udp returns a list
containing a string of the UDP packet
followed by a string containing
the sender's IP number and the port used.

See also the net-send-udp
function for sending datagrams and
the pack and unpack
functions for packing and unpacking binary information.

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 str-addr-if.
When specifying str-addr-if,
a timeout must also be specified
in int-wait.

net-select

In the first form,
net-select finds out about the status
of one socket specified in int-socket.
Depending on str-mode,
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 int-micro-seconds.

In the second syntax,
net-select can check for a list of sockets
in list-sockets.

The following value can be given for str-mode:

"read" or "r" to check if ready for reading or accepting."write" or "w" to check if ready for writing."exception" or "e" to check for an error condition.

Read, send, or accept operations
can be handled without blocking
by using the net-select function.
net-select waits
for a socket to be ready
for the value given in int-micro-seconds,
then returns true or nil
depending on the readiness of the socket.
During the select loop,
other portions of the program can run.
On error,
net-error is set.
When -1 is specified for int-micro-seconds,
net-select will never time out.

When net-select is used,
several listen and connection sockets can be watched,
and multiple connections can be handled.
When used with a list of sockets,
net-select will return a list of ready sockets.
The following example would listen on two sockets
and continue accepting and servicing connections:

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
net-error to be set.

Note that supplying a nonexistent socket to net-select
will cause an error to be set in net-error.

net-send

syntax: (net-send int-socketstr-buffer [int-num-bytes])

Sends the contents of str-buffer on the connection specified by int-socket.
If int-num-bytes is specified, up to int-num-bytes are sent.
If int-num-bytes is not specified, the entire contents will be sent.
net-send returns the number of bytes sent or nil on failure.

net-send-to

Can be used for either UDP or TCP/IP communications. The socket in int-socket
must have previously been opened with a net-connect
or net-listen function. If the opening functions was used
with the "udp" option, net-listen or net-connect
are not used to listen or to connect but only to create the UDP socket.
The host in str-remotehost can be specified either as
a hostname or as an IP-number string.

When using net-connect together with net-send-to, then
only one of the functions should specify the remote host. The other should leave
the address as an empty string.

In the examples both, the client and the server use net-listen 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
net-send-to statement.

net-send-udp

syntax: (net-send-udp str-remotehostint-remoteportstr-buffer [bool])

Sends a User Datagram Protocol (UDP)
to the host specified in str-remotehost
and to the port in int-remoteport.
The data sent is in str-buffer.

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.

No previous setup using net-connect
or net-listen is necessary.
net-send-udp returns immediately
with the number of bytes sent
and closes the socket used.
If no net-receive-udp 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.

(net-send-udp "somehost.com" 3333 "Hello") → 5

net-send-udp is also suitable
for sending binary information
(e.g., the zero character or other non-visible bytes).
For a more comprehensive example,
see net-receive-udp.

Optionally, the sending socket
can be put in broadcast mode
by specifying true
or any expression
not evaluating to nil
in bool:

(net-send-udp "192.168.1.255" 2000 "Hello" true) → 5

The UDP will be sent to all nodes
on the 192.168.1 network.
Note that on some operating systems,
sending the network mask 255
without the booltrue option
will enable broadcast mode.

As an alternative,
the net-connect function
using the "udp" option—together with
the net-send-to function—can
be used to talk to a UDP listener
in a non-blocking fashion.

net-service

In the first syntax net-service makes a lookup in the
services database and returns the standard port number for
this service.

In the second syntax a service port is supplied in int-port
to look up the service name.

Returns nil on failure.

; get the port number from the name
(net-service "ftp" "tcp") → 21
(net-service "http" "tcp") → 80
(net-service "net-eval" "tcp") → 4711 ; if configured
; get the service name from the port number
(net-service 22 "tcp") → "ssh"

net-sessions

syntax: (net-sessions)

Returns a list of active listening and connection sockets.

new

The context context-source is copied to sym-context-target.
If the target context does not exist, a new context with the same variable names
and user-defined functions as in context-source is created.
If the target context already exists, then new symbols and definitions are added.
Existing symbols are only overwritten when the expression in bool
evaluates to anything other than nil; otherwise, the content of existing symbols
will remain. This makes mixins of context objects possible.
new returns the target context, which cannot be MAIN.

In the second syntax, the existing context in context-source gets
copied into the current context as the target context.

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.

The first line in the example creates a new context
called CTX-2 that has the exact same structure
as the original one.
Note that CTX is not quoted
because contexts evaluate to themselves,
but CTX-2 must be quoted because it does not exist yet.

The second line merges the context CTX into MyCTX.
Any existing symbols of the same name in MyCTX
will be overwritten.
Because MyCTX already exists,
the quote before the context symbol can be omitted.

Context symbols need not be mentioned explicitly,
but they can be contained in variables:

normal

In the first form, normal returns a list of length int-n
of random, continuously distributed floating point numbers
with a mean of float-mean
and a standard deviation of float-stdev.
The random generator used internally
can be seeded using the seed function.

In the second form,
normal returns a single
normal distributed floating point number:

(normal 1 0.2) → 0.646875

When no parameters are given, normal assumes a mean of 0.0
and a standard deviation of 1.0.

See also the random
and rand functions
for evenly distributed numbers,
amb for randomizing evaluation
in a list of expressions,
and seed for setting a different start point
for pseudo random number generation.

not

syntax: (not exp)

If exp evaluates to nil or the empty list (),
then true is returned; otherwise, nil is returned.

now

syntax: (now [int-minutes-offset [int-index]])

Returns information about the current date and time
as a list of integers. An optional time-zone offset
can be specified in minutes in int-minutes-offset.
This causes the time to be shifted forward or backward in time,
before being split into separate date values.

An optional list-index in int-index makes now
return a specific member in the result list.

The second example returns the Coordinated Universal Time (UTC)
time value of seconds after January 1, 1970.

Ranging from 0 to 23, hours are given in UTC and are not adjusted for
the local time zone. The resolution of the microseconds field
depends on the operating system and platform. On some platforms,
the last three digits of the microseconds field are always
0 (zero).

The "day of the week" field starts with 1 on Monday conforming to the
ISO 8601 international standard for date and time representation.

On some platforms, the daylight savings time flag is not active and
returns 0 (zero) even during daylight savings time (dst).

Depending on the geographical area, the daylight savings time type
(dst) has a different value from 1 to 6:

nper

syntax: (nper num-interestnum-pmtnum-pv
[num-fv [int-type]])

Calculates the number of payments required to pay a loan of num-pv
with a constant interest rate of num-interest and payment num-pmt.
If payment is at the end of the period, int-type is 0 (zero)
or int-type is omitted; for payment at the beginning of each period,
int-type is 1.

(nper (div 0.07 12) 775.30 -100000) → 239.9992828

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.

npv

syntax: (npv num-interestlist-values)

Calculates the net present value of an investment with a fixed interest rate
num-interest and a series of future payments and income in list-values.
Payments are represented by negative values in list-values,
while income is represented by positive values in list-values.

syntax: (nth list-indiceslist)
syntax: (nth list-indicesarray)

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.

Reference passing is faster and uses less memory in big lists and should
be used on lists with more than a few hundred items.

Note that the implicit indexing version of nth 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.

The implicit indexed syntax forms are faster but the other form with an explicit
nth may be more readable in some situations.

In the String version, nth returns the character found at the position
int-index in str and returns it as a string.

(nth 0 "newLISP") → "n"
("newLISP" 0) → "n"
("newLISP" -1) → "P"

Note that nth works on character boundaries rather than byte
boundaries when using the UTF-8–enabled version of newLISP. To access ASCII and
binary string buffers on single byte boundaries use slice.

See also setf for modifying multidimensional lists and arrays and
push and pop for modifying lists.

null?

syntax: (null? exp)

Checks if an expression evaluates to nil,
the empty list (),
the empty string "",
NaN (not a number),
or 0 (zero),
in which case it returns true.
In all other cases,
null? returns nil.
The predicate null? is useful in conjunction with the functions
filter or clean to check the outcome of other newLISP operations.

syntax: (odd? int-number)

Checks the parity of an integer number. If the number is not even divisible by 2,
it has odd parity. When a floating point number is passed for int-number,
it will be converted first to an integer by cutting off its fractional part.

open

syntax: (open str-path-filestr-access-mode [str-option])

The str-path-file is a file name,
and str-access-mode is a string specifying the file access mode.
open returns an integer,
which is a file handle to be used on subsequent read or write operations on the file.
On failure,
open returns nil.
The access mode "write" creates the file if it doesn't exist,
or it truncates an existing file to 0 (zero) bytes in length.

The following strings are legal access modes:

"read" or "r" for read only access"write" or "w" for write only access"update" or "u" for read/write access"append" or "a" for append read/write access

The first example uses open to set the device for print
and writes the word "hello world" into the file newfile.data.
The second example reads a byte value at offset 6 in the same file (the ASCII value
of 'w' is 119). Note that using close on (device)
automatically resets device to 0 (zero).

As an additional str-option,
"non-block" or "n" can be specified after the "read" or "write" option.
Only available on Unix systems,
non-blocking mode can be useful when opening named pipes but is not required to perform I/O on named pipes.

or

syntax: (or exp-1 [exp-2 ... ])

Evaluates expressions exp-x from left to right until finding a result
that does not evaluate to nil or the empty list ().
The result is the return value of the or expression.

pack

When the first parameter is a string, pack packs one or more expressions
(exp-1 to exp-n) into a binary format specified in the format
string str-format, and returning the binary structure in a string buffer.
The symmetrical unpack function is used
for unpacking. The expression arguments can also be given in a list.
pack and unpack are useful when reading and writing binary files
(see read and write)
or when unpacking binary structures from return values of imported C functions
using import.

When the first parameter is the symbol of a struct
definition, pack uses the format as specified in struct.
While pack with str-format literally packs as specified,
pack with struct will insert structure aligning pad-bytes
depending on data type, order of elements and CPU architecture.
Refer to the description of the struct function for more detail.

When no data expressions or lists are specified, formats or structures are filled
with 0s (zeros).

The following characters are used in str-format:

format

description

c

a signed 8-bit number

b

an unsigned 8-bit number

d

a signed 16-bit short number

u

an unsigned 16-bit short number

ld

a signed 32-bit long number

lu

an unsigned 32-bit long number

Ld

a signed 64-bit long number

Lu

an unsigned 64-bit long number

f

a float in 32-bit representation

lf

a double float in 64-bit representation

sn

a string of n null padded ASCII characters

nn

n null characters

>

switch to big endian byte order

<

switch to little endian byte order

pack will convert all floats into integers
when passed to b, c, d, ld,
or lu formats.
It will also convert integers into floats
when passing them to f and lf formats.

Note that the list should be referenced directly in pack,
so the pointers passed by adr are valid. adr would be written
as char * adr[] 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.

The > and < specifiers
can be used to switch between little endian
and big endian byte order
when packing or unpacking:

parse

syntax: (parse str-data [str-break [regex-option]])

Breaks the string that results from evaluating str-data into string tokens,
which are then returned in a list.
When no str-break is given,
parse tokenizes according to newLISP's internal parsing rules.
A string may be specified in str-break for tokenizing only at the occurrence of a string.
If an regex-option number or string is specified,
a regular expression pattern may be used in str-break.

When str-break 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 str-break is specified,
there is no limitation on the length of tokens.
A different algorithm is used that splits the source string str-data at the string in str-break.

The last two examples show a regular expression as the break string
with the default option 0 (zero). Instead of
{ and } (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 regex.

peek

syntax: (peek int-handle)

Returns the number of bytes ready to be read on a file descriptor;
otherwise,
it returns nil if the file descriptor is invalid.
peek can also be used to check stdin.
This function is only available on Unix-like operating systems.

(peek 0) ; check # of bytes ready on stdin

Use the net-peek function
to check for network sockets,
or for the number of available bytes on them.
On Unix systems,
net-peek can be used
to check file descriptors.
The difference is that
net-peek also sets
net-error.

pipe

syntax: (pipe)

Creates an inter-process communications pipe and returns the
read and write handles to it within a list.

(pipe) → (3 4) ; 3 for read, 4 for writing

The pipe handles can be passed to a child process launched via
process or to fork for inter-process communications.

Note that the pipe does not block when being written to,
but it does block reading until bytes are available.
A read-line blocks until a newline character is received.
A read blocks when fewer characters than
specified are available from a pipe that has not had the writing end closed by all processes.

More than one pipe can be opened if required.

newLISP can also use named pipes.
See the open function for further information.

pmt

Calculates the payment for a loan based on a constant interest of num-interest
and constant payments over num-periods of time.
num-future-value is the value of the loan at the end (typically 0.0).
If payment is at the end of the period, int-type is 0 (zero)
or int-type is omitted; for payment at the beginning of each period,
int-type is 1.

(pmt (div 0.07 12) 240 100000) → -775.2989356

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.

syntax: (pop str [int-index [int-length]])

Using pop, elements can be removed from lists and characters from strings.

In the first syntax, pop extracts an element from the list found
by evaluating list.
If a second parameter is present,
the element at int-index is extracted and returned.
See also Indexing elements of strings and lists.

In the second version,
indices are specified in the list list-indexes.
This way,
pop works easily together with ref
and ref-all,
which return lists of indices.

pop changes the contents of the target list.
The popped element is returned.

post-url

Sends an HTTP POST request to the URL in str-url.
POST requests are used to post information collected from web entry forms to a web site.
Most of the time,
the function post-url 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.

When post-url encounters an error,
it returns a string description of the error beginning with ERR:.

The last parameter,
int-timeout,
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 ERR:
timeout is returned.

The above example uploads a user name and city using a special format called
application/x-www-form-urlencoded.
post-url 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,
post-url assumes application/x-www-form-urlencoded as the default content type.

Additional parameters

When str-content-type is specified, the optional str-option
can take the same options as get-url for the returned
content. If the int-timeout option is specified, the custom header
option str-header can be specified, as well. See the function
get-url for details on all options.

pretty-print

syntax: (pretty-print [int-length [str-tab [str-fp-format]])

Reformats expressions for print,
save,
or source and when printing in an interactive console.
The first parameter, int-length, specifies the maximum line length,
and str-tab specifies the string used to indent lines. The third
parameter str-fp-format describes the default format for printing
floating point numbers. All parameters are optional. pretty-print
returns the current settings or the new settings when parameters are specified.

The first example reports the default settings of 80 for the maximum line length and a
space 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, x would be printed as 0 indistinguishable from floating
point number. All situations where unformatted floating point numbers are printed,
are affected.

Note that pretty-print cannot be used to prevent line breaks from being printed.
To completely suppress pretty printing, use the function string
to convert the expression to a raw unformatted string as follows:

;; print without formatting
(print (string my-expression))

primitive?

syntax: (primitive? exp)

Evaluates and tests if exp is a primitive symbol and returns
true or nil depending on the result. All built-in
functions and functions created using import
are primitives.

(set 'var define)
(primitive? var) → true

print

syntax: (print exp-1 [exp-2 ... ])

Evaluates and prints exp-1—
to the current I/O device,
which defaults to the console window.
See the built-in function device for details on how to specify a different I/O device.

List expressions are indented by the nesting levels of their opening parentheses.

Several special characters may be included in strings encoded with the escape character \:

println

syntax: (println exp-1 [exp-2 ... ])

Evaluates and prints exp-1—
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 device for details on how to specify a different I/O device.
println works exactly like print but emits a line-feed character at the end.

prob-chi2

syntax: (prob-chi2 num-chi2int-df)

Returns the probability of an observed Chi² statistic in num-chi2
with num-df degrees of freedom to be equal or greater under the null hypothesis.
prob-chi2 is derived from the incomplete Gamma function gammai.

process

In the first syntax,
process launches a process specified in str-command and immediately
returns with a process ID or nil if a process could not be created. This
process will execute the program specified or immediately die if str-command could not be executed.

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.

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 destroy, if the process does
not exit by itself.

(process "c:/WINDOWS/system32/notepad.exe") → 1894 ; Windows
; or when in executable path
(process "notepad.exe") → 1894 ; Windows
; find out the path of the program to start using exec,
; if the path is not known
(process (first (exec "which xclock"))) → 22607 ; on Unix

If the path of the executable is unknown, exec together with the Unix which
command can be used to start a program. The pid returned can be used to destroy
the process.

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 write-line
and read-line or write and
read statements:

On MS Windows versions of newLISP, a fourth optional parameter of int-win-option
can be specified to control the display status of the application.
This option defaults to 1 for showing the application's window,
0 for hiding it, and 2 for showing it minimized on the Windows
launch bar.

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 int-unix-pipe-error.

The function peek can be used to check for information
on the pipe handles:

Not all interactive console applications
can have their standard I/O channels remapped.
Sometimes only one channel,
in or out,
can be remapped.
In this case,
specify 0 (zero) for the unused channel.
The following statement uses only the launched application's output:

(process "app" 0 appout)

Normally,
two pipes are used:
one for communications to the child process and the other one for communications from the child process.

See also the pipe and share functions for inter-process
communications and the semaphore function for synchronization of several processes.
See the fork and spawn functions for other ways of starting
newLISP processes. Both are only available on macOS, Linux and other Unix like operating systems.

The current context before calling the prompt-event code is passed as a
parameter to the function. Computer output is shown in bold.

The example redefines the > prompt to be the current context followed
by a colon :, followed by the directory name, followed by the dollar symbol.
Together with the command-event function this can be
used to create fully customized shells or custom command interpreters.

The function in prompt-event must return a string of 63 characters maximum.
Not returning a string will leave the prompt unchanged.

protected?

syntax: (protected? sym)

Checks if a symbol in sym is protected. Protected symbols are built-in
functions, context symbols, and all symbols made constant using the constant
function:

syntax: (push str-1str-2 [int-index])

Inserts the value of exp into the list list.
If int-index is present, the element is inserted at that index.
If the index is absent, the element is inserted at index 0 (zero),
the first element. push is a destructive operation that changes the
contents of the target list.

put-url

The HTTP PUT protocol is used to transfer information in str-content
to a file specified in str-url. 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 'Script PUT' directive in the section where directory access rights are configured.

If str-url starts with file:// then str-content is written
to the local file system.

Optionally,
an int-timeout value can be specified in milliseconds as the last parameter.
put-url will return ERR:
timeout when the host gives no response and the timeout expires.
On other error conditions,
put-url returns a string starting with ERR: and the description of the error.

put-url requests are also understood by newLISP server nodes, but will
not be served when the server is started in -http-safe mode.

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.

put-url returns content returned by the put.cgi script.

Additional parameters

In str-option can take the same options as get-url
for the returned content. If the int-timeout option is specified, the
custom header option str-header can be specified, as well. See the
function get-url for details on all options.

See also the functions get-url and post-url,
which can be used to upload files when formatting form data as multipart/form-data.

pv

syntax: (pv num-intnum-npernum-pmt
[num-fv [int-type]])

Calculates the present value of a loan with the constant interest rate
num-interest and the constant payment num-pmt after
num-nper number of payments. The future value num-fv
is assumed to be 0.0 if omitted. If payment is at the end of the
period, int-type is 0 (zero) or int-type is omitted;
for payment at the beginning of each period, int-type is 1.

(pv (div 0.07 12) 240 775.30) → -100000.1373

In the example,
a loan that would be paid off (future value = 0.0) in 240 payments of $775.30 at a
constant interest rate of 7 percent per year would start out at $100,000.14.

quote

syntax: (quote exp)

Returns exp without evaluating it. The same effect can be obtained by
prepending a ' (single quote) to exp. The function quote
is resolved during runtime, the prepended ' quote is translated into a
protective envelope (quote cell) during code translation.

quote?

syntax: (quote? exp)

Evaluates and tests whether exp is quoted.
Returns true or nil depending on the result.

(set 'var ''x) → 'x
(quote? var) → true

Note that in the set statement,
''x is quoted twice because the first quote
is lost during the evaluation of the set assignment.

rand

syntax: (rand int-range [int-N])

Evaluates the expression in int-range
and generates a random number in the range of
0 (zero) to (int-range - 1).
When 0 (zero) is passed,
the internal random generator
is initialized using
the current value returned by
the C time() function.
Optionally, a second parameter
can be specified to return
a list of length int-N
of random numbers.

The first line in the example
prints equally distributed 0's and 1's,
while the second line produces a list
of 100 integers with
0, 1, and 2 equally distributed.
Use the random
and normal functions
to generate floating point
random numbers,
and use seed to vary
the initial seed
for random number generation.

random

In the first form,
random returns a list of int-n
evenly distributed floating point numbers
scaled (multiplied) by float-scale,
with an added offset of float-offset.
The starting point of the internal random generator
can be seeded using seed.

randomize

syntax: (randomize list [bool])

randomize will always return
a sequence different from the previous one
without the optional bool 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, true
or any expression evaluating to
not nil
must be specified in bool.

randomize uses
an internal pseudo random sequence generator
that returns the same series of results
each time newLISP is started.
Use the seed function to
change this sequence.

syntax: (read int-filesym-bufferint-size [str-wait])

Reads a maximum of int-size bytes from a file specified in int-file
into a buffer in sym-buffer. Any data referenced by the symbol sym-buffer
prior to the reading is deleted. The handle in int-file is obtained from a
previous open statement. The symbol sym-buffer contains
data of type string after the read operation. sym-buffer can also be a default
functor specified by a context symbol for reference passing in and out of user-defined
functions.

read is a shorter writing of read-buffer. The longer
form still works but is deprecated and should be avoided in new code.

Optionally,
a string to be waited for
can be specified in str-wait.
read will read
a maximum amount of bytes
specified in int-size
or return earlier
if str-wait was found
in the data.
The wait-string is part
of the returned data and must
not contain binary 0 (zero)
characters.

Returns the number of bytes read or nil
when the wait-string was not found.
In any case,
the bytes read are put into the buffer
pointed to by sym-buffer,
and the file pointer of the file read
is moved forward.
If no new bytes have been read,
sym-buffer will contain nil.

(set 'handle (open "aFile.ext" "read"))
(read handle buff 200)

Reads 200 bytes into the symbol buff
from the file aFile.ext.

(read handle buff 1000 "password:")

Reads 1000 bytes or until
the string password: is encountered.
The string password:
will be part of the data returned.

See also the write function. To start reading at
a specific position in the file, use the seek function.

read-char

syntax: (read-char [int-file])

Reads a byte from a file specified by the file handle in int-file
or from the current I/O device - e.g. stdin - when no file handle is specified.
The file handle is obtained from a previous open operation.
Each read-char advances the file pointer by one byte.
Once the end of the file is reached, nil is returned.

read-expr

syntax: (read-expr str-source [sym-context [exp-error [int-offset]]])

read-expr parses the first expressions it finds in str-source and
returns the translated expression without evaluating it. An optional context in
sym-context specifies a namespace for the translated expression.

After a call to read-expr the system variable $count contains the
number of characters scanned.

If an error occurs when translating str-source the expression in
exp-error is evaluated and the result returned.

int-offset specifies an optional offset into str-source where
processing should start. When calling read-expr repeatedly this number
can be updated using $count, the number of characters processed.

The file myfile is read, then encrypted using the password "secret"
before being written back into a new file titled "myfile.enc"
in the current directory.

read-file can take an http://
or file:// URL in str-file-name.
When the prefix is http://, read-file works exactly like
get-url and can take the same additional parameters.

(read-file "http://asite.com/somefile.tgz" 10000)

The file somefile.tgz is retrieved from
the remote location http://asite.com.
The file transfer will time out after 10 seconds
if it is not finished.
In this mode, read-file can also be used
to transfer files from remote newLISP server nodes.

read-key

syntax: (read-key [true])

Reads a key from the keyboard and returns an integer value.
For navigation keys, more than one read-key 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.

When using the true flag the read-key is non-blocking
and a 0 (zero) is returned when no key has been pressed.
When not using the extra flag, the call to read-key is blocking
until a key is pressed.

The last example can be used to check return sequences
from navigation and function keys. To break out of the loop,
press Ctrl-A.

Note that read-key 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.

read-line

syntax: (read-line [int-file])

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.

By default,
the current device
is the keyboard (device0).
Use the built-in function device
to specify a different I/O device (e.g., a file).
Optionally,
a file handle can be specified
in the int-file obtained
from a previous open statement.

The last buffer contents
from a read-line operation
can be retrieved using current-line.

When read-line is reading from a file or from stdin
in a CGI program or pipe, it will return nil when input is exhausted.

When using read-line on stdin, line length is limited
to 2048 characters and performance is much faster.

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 write-line statement
takes advantage of the fact
that the result from the last
read-line operation
is stored in a system internal buffer.
When write-line
is used without argument,
it writes the contents
of the last read-line buffer
to the screen.

read-utf8

syntax: (read-utf8 int-file)

Reads an UTF-8 character from a file specified by the file handle in int-file.
The file handle is obtained from a previous open operation.
Each read-utf8 advances the file pointer by the number of bytes contained
in the UTF-8 character. Once the end of the file is reached, nil is returned.

The function returns an integer value which can be converted to a displayable UTF-8
character string using the char function.

reader-event

An event handler can be specified to hook between newLISP's reader,
translation and evaluation process. The function specified in
sym-event-handler or func-event-handler gets called after
newLISP translates an expression and before evaluating it. The event handler can do
transformation on the expression before it gets evaluated.

Specifying nil for the event will reset it to the initial default state.

The following one-liner reader-event could be used to enhance
the interactive shell with a tracer:

The expression intercepted passes through unchanged, but output
is enhanced.

The reader event function will be called after each reading of an s-expression
by the load or eval-string function.

In versions previous to 10.5.8 reader-event was used to define a
macro expansion function in the module file macro.lsp. Starting
version 10.5.8, newLISP has macro as a built-in function
behaving the same, but much faster when loading files and reading source.

real-path

syntax: (real-path [str-path])
syntax: (real-path str-exec-name true)

In the first syntax real-path returns the full path from the relative
file path given in str-path. If a path is not given, "."
(the current directory) is assumed.

The list of child process IDs returned by (receive) only
contains PIDs of processes which have unread messages in their
send queues. The (receive pid msg) statement now can
be issued non-blocking, because it always is guaranteed to find
a pending message in a child's message queue.

The receive function is not available on MS Windows.

For a more detailed discussion of this function and examples, see the
send function.

ref

syntax: (ref exp-keylist [func-compare [true]])

ref searches for the key expression exp-key in list and
returns a list of integer indices or an empty list if exp-key cannot be
found. ref can work together with push and
pop, both of which can also take lists of indices.

By default, ref checks if expressions are equal. With func-compare,
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.

When the optional true parameter is present, the element found
is returned instead of the index vector.

The '(X X) pattern with unify searches for a list pair
where the two elements are equal. The unify pattern '(X g)
searches for a list pair with the symbol g as the second member.
The patterns are quoted to protect them from evaluation.

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 is-long?).

Using the match and unify functions, list
searches can be formulated that are as powerful as regular expression searches are
for strings.

regex

syntax: (regex str-patternstr-text [regex-option [int-offset]])

Performs a Perl Compatible Regular Expression (PCRE) search
on str-text with the pattern specified in str-pattern.
The same regular expression pattern matching
is also supported in the functions directory,
find, find-all,
parse, replace,
and search when using these functions on strings.

regex 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 nil.
The offset numbers can be used for subsequent processing.

Additionally a regex-option can be specified to control certain
regular expression options explained later. Options can be given either by
numbers or letters in a string.

The additional int-offset
parameter tells regex to start searching for a match not at the
beginning of the string but at an offset.

When no regex-option is present, the offset and length numbers in
the regex results are given based bytes even when running the UTF-8
enabled version of newLISP. When specifying the PCRE_UTF8 option in regex-option
only offset and length are reported in UTF8 characters.

regex also sets the variables $0, $1,
and $2—
to the expression and subexpressions found.
Just like any other symbol in newLISP,
these variables or their equivalent expressions
($ 0), ($ 1), and ($ 2)— can be used in other
newLISP expressions for further processing.

Functions using regular expressions will not reset the $0, $1 ... $15
variables to nil when no match is found.

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
$0 to $2 or their equivalent expression ($ 0) to ($ 2).

When "" (quotes) are used
to delimit strings
that include literal backslashes,
the backslash must be doubled in the regular expression pattern.
As an alternative, { } (curly brackets)
or [text] and [/text] (text tags)
can be used to delimit text strings.
In these cases, no extra backslashes are required.

Characters escaped by a backslash in newLISP
(e.g., the quote \" or \n)
need not to be doubled in a regular expression pattern,
which itself is delimited by quotes.

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:

The following constants can be used for regex-option.
Several options can be combined using a binary or | (pipe) operator.
E.g. (| 1 4) would combine options 1 and 4 or "is"
when using letters for the two options.

The last two options are specific for newLISP. The REPLACE_ONCE option is only
to be used in replace; it can be combined with other PCRE options.

Multiple options can be combined using a + (plus) or | (or) operator,
e.g.: (| PCRE_CASELESS PCRE_DOTALL) or "is" when using letters as options.

pattern is pre-compiled, can only be combined with RREPLACE_ONCE 0x8000

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:

i

for PCRE_CASELESS

m

for PCRE_MULTILINE

s

for PCRE_DOTALL

x

for PCRE_EXTENDED

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 http://www.pcre.org
for further references and manual pages.

Regular expression patterns can be precompiled for higher speed when using
changing repetitive patterns with regex-comp.

regex-comp

syntax: (regex-comp str-pattern [int-option])

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. regex-comp
can be used to pre-compile repetitive patterns to speed up regular
expression searches:

When using pre-compiled patterns in any of the functions using regular
expressions, the option number is set to 0x10000 to signal
that pre-compiled patterns are used. Normal pattern options are specified
during pre-compilation with regex-comp . The 0x10000 option
can only be combined with 0x8000, the option used to specify that only
one replacement should be made when using replace.

The function ends-with should not be used with compiled
patterns, as it tries to append to an un-compiled pattern internally.

remove-dir

syntax: (remove-dir str-path)

Removes the directory
whose path name is specified in str-path.
The directory must be empty for remove-dir to succeed.
Returns nil on failure.

(remove-dir "temp")

Removes the directory temp
in the current directory.

rename-file

syntax: (rename-file str-path-oldstr-path-new)

Renames a file or directory entry given in the path name str-path-old
to the name given in str-path-new. Returns nil or true
depending on the operation's success.

List replacement

If the second argument is a list, replace replaces all elements in
the list list that are equal to the expression in exp-key. The
element is replaced with exp-replacement. If exp-replacement
is missing, all instances of exp-key will be deleted from list.

Note that replace 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 $count
when the function returns. During executions of the replacement expression, the
anaphoric system variable $it is set to the expression to be replaced.

Optionally, func-compare can specify a comparison operator
or user-defined function. By default, func-compare is the =
(equals sign).

String replacement without regular expression

If all arguments are strings, replace replaces all occurrences
of str-key in str-data with the evaluated
exp-replacement, returning the changed string. The expression in
exp-replacement is evaluated for every replacement. The number of
replacements made is contained in the system variable $count. This
form of replace can also process binary 0s (zeros).

Regular expression replacement

The presence of a fourth parameter indicates that a regular expression search
should be performed with a regular expression pattern specified in str-pattern
and an option number specified in regex-option (e.g., 1 (one) or "i" for
case-insensitive searching or 0 (zero) for a standard Perl Compatible Regular
Expression (PCRE) search without options). See regex above for details.

By default, replace 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 str-data.
Setting the option bit to 0x8000 in regex-option will force
replace to replace only the first occurrence. The changed string is returned.

replace with regular expressions also sets the internal variables
$0, $1, and $2— with the contents of the expressions
and subexpressions found. The anaphoric system variable $it is set to
the same value as $0. These can be used to perform replacements
that depend on the content found during replacement. The symbols $it, $0, $1,
and $2— 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 ($ 0), ($ 1), ($ 2), and so forth.
This method allows indexed access (e.g., ($ i),
where i is an integer).

After all replacements are made, the number of replacements
is contained in the system variable $count.

reset

syntax: (reset)
syntax: (reset true)
syntax: (reset int-max-cells)

In the first syntax, reset returns to the top level of evaluation,
switches the trace mode off, and switches to the MAIN
context/namespace. reset 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 reset also interrupts command line parameter
processing.

reset walks through the entire cell space,
which may take a few seconds in a heavily loaded system.

reset occurs automatically after an error condition.

In the second syntax, reset 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. /usr/local/bin/newlisp instead of only newlisp. This mode is
not available on MS Windows.

In the third syntax. reset will change the maximum cell count allowed
in the system. This number is also reported as the second number in the list
by sys-info. 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.

The minimum cell count is 4095, trying to specify less will set it to 4095.
The program will exit when trying to allocate more.

syntax: (rotate list [int-count])
syntax: (rotate str [int-count])

Rotates and returns the list or string in str.
A count can be optionally specified in int-count
to rotate more than one position. If int-count is positive,
the rotation is to the right; if int-count is negative,
the rotation is to the left. If no int-count is specified,
rotate rotates 1 to the right. rotate is a destructive function
that changes the contents of the original list or string.

Note that rounding for display purposes is better accomplished using
format.

save

syntax: (save str-file)
syntax: (save str-filesym-1 [sym-2 ... ])

In the first syntax,
the save function writes
the contents of the newLISP workspace
(in textual form) to the file str-file.
save is the inverse function of load.
Using load on files
created with save causes
newLISP to return to the same state
as when save was originally invoked.
System symbols starting with the $ character
(e.g., $0 from regular expressions
or $main-args from the command-line), symbols of built-in
functions and symbols containing nil are not saved.

In the second syntax,
symbols can be supplied as arguments.
If sym-n is supplied,
only the definition of that symbol is saved.
If sym-n 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 $ character
are not saved.
Specifying system symbols explicitly
causes them to be saved.

Each symbol is saved
by means of a set statement or—if
the symbol contains a lambda or lambda-macro function—by
means of define
or define-macro statements.

Because all context symbols are part of the context MAIN,
saving MAIN saves all contexts.

Saving to a URL
will cause an HTTP PUT request to be sent to the URL.
In this mode,
save 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.
save in HTTP mode will
observe a 60-second timeout.

Symbols made using sym
that are incompatible with the normal syntax rules for symbols
are serialized using a sym statement
instead of a set statement.

save serializes contexts and symbols
as if the current context is MAIN.
Regardless of the current context,
save will always generate the same output.

See also the functions load
(the inverse operation of save)
and source,
which saves symbols and contexts to a string
instead of a file.

search

syntax: (search int-filestr-search [bool-flag [regex-option]])

Searches a file specified by its handle in int-file for a string in str-search.
int-file can be obtained from a previous open 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.

By default, the file pointer is positioned at the beginning
of the searched string. If bool-flag evaluates to true,
then the file pointer is positioned at the end of the searched string.

In regex-option, the options flags can be specified to perform
a PCRE regular expression search. See the function regex for details.
If regex-option is not specified a faster, plain string search is performed.
search returns the new file position or nil if nothing is found.

When using the regular expression options flag, patterns found are stored in the system variables
$0 to $15.

seed

Seeds the internal random generator that generates numbers for amb,
normal, rand, and random
with the number specified in int-seed. Note that the first syntax uses a
random generator based on the C-library function rand(). All randomizing functions
in newLISP are based on this function.

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
amb, normal, rand,
random and randomize are based on this
platform independent random generator.

The optional int-pre-N specifies the number of random numbers to be pre-
fetched as part of the seeding and initialization procedure. When this parameter is
ommitted seed assumes 50.

Note that the maximum value for int-seed 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.

(seed 12345)
(seed (time-of-day))

After using seed with the same number, the random generator starts
the same sequence of numbers. This facilitates debugging
when randomized data are involved. Using seed,
the same random sequences can be generated over and over again.

The second example is useful for guaranteeing
a different seed any time the program starts.

The following example shows usage of the internal seed state in the built-in
random generator:

seek

syntax: (seek int-file [int-position])

Sets the file pointer to the new position int-position in the file
specified by int-file.The new position is expressed as an offset from
the beginning of the file, 0 (zero) meaning the beginning of the file.
If no int-position is specified, seek returns the current
position in the file. If int-file is 0 (zero),
on BSD, seek will return the number of characters printed to STDOUT,
and on Linux and MS Windows, it will return -1. On failure, seek
returns nil. When int-position is set to -1,
seek sets the file pointer to the end of the file.

seek 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 sparse file.

semaphore

A semaphore is an interprocess synchronization object
that maintains a count between 0 (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.

A semaphore is created using the first syntax. This returns
the semaphore ID, an integer used subsequently as int-id
when the semaphore function is called. Initially, the
semaphore has a value of zero, which represents the non-signaled state.

If calling semaphore with a negative value in int-wait
causes it to be decremented below zero,
the function call will block until another process
signals the semaphore with a positive value in int-signal.
Calls to the semaphore with int-wait or int-signal
effectively try to increment or decrement the semaphore value
by a positive or negative value specified in int-signal
or int-wait.
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 int-signal).

The second syntax is used to inquire about the value of a semaphore
by calling semaphore with the int-id only.
This form is not available on MS Windows.

Supplying 0 (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.

On MS Windows, only parent and child processes can share a semaphore.
On Linux/Unix, independent processes can share a semaphore.

On failure the semaphore function returns nil.
sys-error can be used to retrieve the error
number and text from the underlying operating system.

After the semaphore is acquired in sid,
it has a value of 0
(the non-signaled state).
When starting the process counter,
the semaphore will block after the initial start message
and will wait in the semaphore call.
The -1 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 1.
This unblocks the semaphore call in the counter process,
which can now decrement the semaphore from 1 to 0
and execute the print statement.
When the semaphore call is reached again,
it will block because the semaphore is already in the wait
(0) state.

Subsequent calls to semaphore
with numbers greater than 1
give the counter process an opportunity
to decrement the semaphore several times before blocking.

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.

Use the fork function to start a new process
and the share function to share information between
processes. For a more comprehensive example of using semaphore
to synchronize processes, see the file prodcons.lsp example
in the examples directory in the source distribution,
as well as the examples and modules distributed with newLISP.

send

syntax: (send int-pidexp)
syntax: (send)

The send function enables communication between
parent and child processes started with spawn.
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 – shown further
down – is employed to communicate between child process
peers. send and receive do not require
locks or semaphores. They work on dual send and receive message queues.

Processes started using fork or
process can not use send and receive
message functions. Instead they should use either share
with semaphore or pipe to
communicate.

The send function is not available on MS Windows.

In the first syntax send is used to send a message
from a parent to a child process or a child to a parent process.

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 (send) statement.

The content of a message may be any newLISP expression either
atomic or list expressions: boolean constants nil and true,
integers, floating point numbers or strings, or any list expression
in valid newLISP syntax. The size of a message is unlimited.

The exp parameter specifies the data to be sent
to the recipient in int-pid. 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 send issued on the other side of the queue will
fail and return nil.

The sender statement blocks until the message could be deposited
in the recipients queue.

The receive statement blocks until a new message can
be fetched from the queue.

As the until statements in this example lack body expressions,
the last value of the evaluated conditional expression is the return
value of the until loop.

Blocking message exchange

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:

The (sync) expression returns a list of all child PIDs,
and (until (receive cpid msg)) is used to force a wait
until status messages are received for each of the child processes.

A timeout mechanism could be part of an until or while
loop to stop waiting after certain time has expired.

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 (send) to obtain a
list of child processes with place in their message queues.

Messages containing code for evaluation

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 eval to evaluate the received
expression. Symbols contained in the expression are evaluated in the
receivers environment.

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:

Child process A sends three messages to B.
As this cannot be done directly A sends send
statements to the parent for evaluation. The statement:

(until (send pidB (string "greetings from " A)))

will be evaluated in the environment of the parent process. Even so the
variables A and B are bound to nil in
the sender process A, in the parent process they will be
bound to the correct process ID numbers.

After sending the three messages, the statement:

(set 'finished true)

is sent to the parent process. Once evaluated, it will cause the until
loop to finish.

For more details on send and receive and more examples
see the Code Patterns
document.

sequence

syntax: (sequence num-startnum-end [num-step])

Generates a sequence of numbers
from num-start to num-end
with an optional step size of num-step.
When num-step is omitted,
the value 1 (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).

series

In the first syntax, series creates a geometric sequence with num-count
elements starting with the element in num-start. Each subsequent element
is multiplied by num-factor. The generated numbers are always floating point
numbers.

syntax: (set sym-1exp-1 [sym-2exp-2 ... ])

Evaluates both arguments and then assigns the result of exp
to the symbol found in sym. The set 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 nil, true, or a context symbol.
set can take multiple argument pairs.

Symbols can be set to lambda or lambda-macro expressions.
This operation is equivalent to using define
or define-macro.

(set 'double (lambda (x) (+ x x)))
→ (lambda (x) (+ x x))

is equivalent to:

(define (double x) (+ x x))
→ (lambda (x) (+ x x))

is equivalent to:

(define double (lambda (x) (+ x x)))
→ (lambda (x) (+ x x))

Use the constant function (which works like set)
to protect the symbol from subsequent alteration. Using the setq
or setf function eliminates the need to quote the variable symbol.

set-locale

syntax: (set-locale [str-locale [int-category]])

Reports or switches to a different locale on your operating system or platform.
When used without arguments, set-locale reports
the current locale being used. When str-locale is specified,
set-locale switches to the locale with all category options turned on
(LC_ALL). Placing an empty string in str-locale
switches to the default locale used on the current platform.

set-locale returns either the current locale string and decimal
point string in a list or nil if the requested change could not
be performed.

By default, newLISP – if not enabled for UTF-8 – 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.

; after non-UTF-8 newLISP start up
(set-locale) → ("C" ".")

In int-category integer numbers may be specified as category options
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
locale.h and may be different on each platform. When no int-category
is specified, LC_ALL is used to turn on all options for that locale.

Category

macOS, BSDs& MS Windows

LC_ALL

0

LC_COLLATE

1

LC_CTYPE

2

LC_MONETARY

3

LC_NUMERIC

4

LC_TIME

5

The default C locale uses the decimal dot, but most others use a decimal comma.

; 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) → ("en_US.UTF-8" ".")
(set-locale "de_DE.UTF-8" 4) → ("de_DE.UTF-8" ",")
; mixed locale shows country setting for each category, 4 has changed
(set-locale) → ("en_US.UTF-8/en_US.UTF-8/en_US.UTF-8/de_DE.UTF-8/en_US.UTF-8/en_US.UTF-8" ",")

Note that using set-locale 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.

syntax: (set-ref exp-keylistexp-replacement [func-compare])

Searches for exp-key in list and replaces the found element with
exp-replacement. The list can be nested. The system variables
$it contains the expression found and can be used in
exp-replacement. The function returns the new modified list.

syntax: (set-ref-all exp-keylistexp-replacement [func-compare])

Searches for exp-key in list and replaces each instance of the found element
with exp-replacement. The list can be nested. The system variable $it
contains the expression found and can be used in exp-replacement.
The system variable $count contains the number of replacements made.
The function returns the new modified list.

Using the default functor in the (listkey) pattern allows the
list to be passed by reference to a user-defined function containing a set-ref-all
statement. This would result in less memory usage and higher speeds in when doing replacements
in large lists:

syntax: (setq place-1exp-1 [place-2exp-2 ... ])

setq and setf 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
set, setq and setf can take multiple argument pairs.
Although both setq and setf point to the same built-in function internally,
throughout this manual setq is used when setting a symbol reference and setf
is used when setting list or array references.

sgn

syntax: (sgn num)
syntax: (sgn numexp-1 [exp-2 [exp-3]])

In the first syntax,
the sgn function is a logical function
that extracts the sign of a real number
according to the following rules:

x > 0 : sgn(x) = 1
x < 0 : sgn(x) = -1
x = 0 : sgn(x) = 0

(sgn -3.5) → -1
(sgn 0) → 0
(sgn 123) → 1

In the second syntax, the result of evaluating
one of the optional expressions
exp-1, exp-2, or exp-3 is returned,
instead of -1, 0, or 1.
If exp-n is missing for the case triggered,
then nil is returned.

share

syntax: (share nilint-address)

Accesses shared memory
for communicating between
several newLISP processes.
When called without arguments,
share 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.

To set the contents of shared memory, use the third syntax of share.
Supply a shared memory address on Linux/Unix or a handle on MS Windows in
int-address-or-handle, along with an integer, float, string
expression or any other expression (since v.10.1.0) supplied
in exp-value. Using this syntax, the value supplied in exp-value
is also the return value.

To access the contents of shared memory,
use the second syntax of share,
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,
nil will be returned.

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.

Memory can be shared between parent and child processes,
but not between independent processes.

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 /tmp directory on Unix-like
operating system. On MS Windows systems the environment variable TEMP
must be set.

signal

Sets a user-defined handler in sym-event-handler for a signal specified in int-signal
or sets to a function expression in func-event-handler.

A parameter following int-signal is not evaluated.

If no signal handler is specified any of the string constants "ignore",
"default" or "reset" 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, true is returned.

Using "ignore" will make newLISP ignore the signal. Using "default"
will set the handler to the default handler of the underlying platform OS. The "reset"
option will restore the handler to newLISP startup state.

On startup, newLISP either specifies an empty newLISP handler or a Ctrl-C handler for
SIGINT and a waitpipd(-1, 0, WNOHANG) C-call for SIGCHLD.

Different signals are available on different OS platforms and Linux/Unix flavors.
The numbers to specify in int-signal also differ from platform-to-platform.
Valid values can normally be extracted from a file found in /usr/include/sys/signal.h
or /usr/include/signal.h.

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.

(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")

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.

Instead of specifying a symbol containing the signal handler,
a function can be specified directly. The signal number is passed as a parameter:

silent

syntax: (silent [exp-1 [exp-2 ... ]])

Evaluates one or more expressions in exp-1—.
silent is similar to begin,
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.

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 silent
to get the prompt back.

(silent (my-func)) ; same as next
(silent) (my-func) ; same effect as previous

slice

In the first form, slice copies a sublist
from a list. The original list is left unchanged.
The sublist extracted starts at index int-index
and has a length of int-length. If int-length is negative,
slice will take the parameter as offset counting from the end and copy
up to but not including that offset. If the parameter is omitted,
slice copies all of the elements to the end of the list.

In the second form, a part of the string in str
is extracted. int-index contains the start index
and int-length contains the length of the substring.
If int-length is not specified, everything to the end of the string is extracted.
slice also works on string buffers containing binary data like 0's (zeroes).
It operates on byte boundaries rather than character boundaries.
See also Indexing elements of strings and lists.

Note that slice always works on single 8-bit byte boundaries for
offset and length numbers, even when running the UTF-8 enabled version of newLISP.

All members in list or array 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:

The sort 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 O(n log2 n) performance
preserving the order of adjacent elements which are equal. When
func-compare is used it must work with either <= or
>= operators to be stable.

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.

source

syntax: (source)
syntax: (source sym-1 [sym-2 ... ])

Works almost identically to save,
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,
source serializes the entire
newLISP workspace.
When context symbols are serialized,
any symbols contained within that context
will be serialized, as well.
Symbols containing nil
are not serialized.
System symbols beginning with the $ (dollar sign) character
are only serialized when mentioned explicitly.

Symbols not belonging to the current context
are written out with their context prefix.

As with save,
the formatting of line breaks
and leading spaces or tabs
can be controlled using the
pretty-print function.

spawn

syntax: (spawn symexp [true])

Launches the evaluation of exp as a child process and immediately
returns. The symbol in sym is quoted and receives the result of the
evaluation when the function sync is executed. spawn
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.

The optional true parameter must be set if send
or receive is used to communicated with the child
process spawned.

The function spawn is not available on MS Windows.

After successfully starting a child process, the spawn 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:

On a 1.83 Intel Core 2 Duo processor, the above example will finish
after about 13 seconds. Calculating all primes using (primes 1 4000000)
would take about 20 seconds.

The sync function will wait for all child processes
to finish and receive the evaluation results in the symbols p1 to
p4. When all results are collected, sync
will stop waiting and return true. When the time specified was
insufficient , sync will return nil and another
sync statement could be given to further wait and collect results.
A short timeout time can be used to do other processing during waiting:

sync when used without any parameters, will not wait but immediately
return a list of pending child processes. For the primes example, the following
sync expression could be used to watch the progress:

The three functions spawn, sync and abort
are part of the Cilk 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 fork(),
waitpid() and kill(). Intercommunications between processes
and child processes is done using the send and
receive functions.

With (fibo 7) 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.

Since version 10.1 a send and receive
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.

Use the append
and join
(allows the joining string
to be specified) functions
to concatenate strings containing zero bytes.
Use the source function
to convert a lambda expression
into its newLISP source string representation.

string?

syntax: (string? exp)

Evaluates exp and tests
to see if it is a string.
Returns true or nil
depending on the result.

(set 'var "hello")
(string? var) → true

struct

syntax: (struct symbol [str-data-type ... ])

The struct function can be used to define aggregate data types for
usage with the extended syntax of import,
pack and unpack, available on all
versions of newLISP compiled with libffi. This allows importing
functions which take C-language struct data types or pointers to these
aggregate data types.

The following example illustrates the usage of struct together with
the C data functions localtime and asctime. The localtime
functions works similar to the built-in now function. The
asctime function takes the numerical data output by localtime
and formats these to readable text.

sub

syntax: (sub num-1 [num-2 ... ])

Successively subtracts
the expressions in num-1,
num-2—.
sub 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 NaN also returns NaN.

syntax: (swap place-1place-2)

The contents of the two places place-1 and place-2
are swapped. A place can be the contents of an unquoted symbol or any
list or array references expressed with nth,
first, last or implicit
indexing or places referenced by assoc
or lookup.

swap is a destructive operation that changes the contents of the
lists, arrays, or symbols involved.

sym

Translates the first argument in string,
number, or symbol
into a symbol and returns it.
If the optional context is not specified
in sym-context,
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.

sym 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 sym usable
as a function for associative memory access,
much like hash table access
in other scripting languages.

As a third optional argument,
nil can be specified
to suppress symbol creation
if the symbol is not found.
In this case,
sym returns nil
if the symbol looked up does not exist.
Using this last form,
sym can be used
to check for the existence
of a symbol.

Because the function sym
returns the symbol looked up or created,
expressions with sym can be embedded
directly in other expressions
that use symbols as arguments.
The following example shows
the use of sym
as a hash-like function
for associative memory access,
as well as symbol configurations
that are not legal newLISP symbols:

The third syntax allows symbols to be used
instead of strings for the symbol name
in the target context.
In this case,
sym will extract the name from the symbol
and use it as the name string
for the symbol in the target context:

sync

syntax: (sync int-timeout [func-inlet])
syntax: (sync)

When int-timeout in milliseconds is specified, sync waits
for child processes launched with spawn to finish.
Whenever a child process finishes, sync assigns the evaluation result
of the spawned subtask to the symbol specified in the spawn statement.
The sync returns true if all child processes have been processed
or nil if the timeout value has been reached and more child processes
are pending.

If sync additionally is given with an optional user-defined inlet
function in func-inlet, this function will be called with the child process-id
as argument whenever a spawned child process returns. func-inlet can contain
either a lambda expression or a symbol which defines a function.

Without any parameter, sync returns a list of pending child process
PIDs (process identifiers), for which results have not been processed yet.

When sync 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,
sync returns immediately.

The function sync is part of the Cilk API for synchronizing
child processes and process parallelization. See the reference for the
function spawn for a full discussion of the Cilk API.

sys-error

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.

If no error has occurred or the system error number has
been reset, nil is returned.

When int-error is greater 0 (zero) a
list of the number and the error text is returned.

To reset the error specify 0 as the error number.

Whenever a function in newLISP within the system resources area
returns nil, sys-error can be checked
for the underlying reason. For file operations,
sys-error 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.

Operating system constant:
linux=1, bsd=2, osx=3, solaris=4, windows=6, os/2=7, cygwin=8, tru64 unix=9, aix=10, android=11
bit 11 will be set for ffilib (extended import/callback API) versions (add 1024)
bit 10 will be set for IPv6 versions (add 512)
bit 9 will be set for 64-bit (changeable at runtime) versions (add 256)
bit 8 will be set for UTF-8 versions (add 128)
bit 7 will be added for library versions (add 64)

The numbers from 0 to 9 indicate the optional offset
in the returned list.

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.

The number for the maximum of Lisp cells can be changed via the -m
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 -s command-line switch.

In above example the difference of the mean value 4.125 from 2.5 is
moderately significant. With a probability p = 0.021 (2.1%) the null hypothesis
that the mean is not significantly different, can be rejected.

In the second syntax, the function performs a t-test using the
Student's t statistic for comparing the means values in list-vector-A
and list-vector-B. If the true 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.

When the optional flag is set to true, measurements were taken
from the same group twice, e.g. before and after a procedure.

The following results are returned in a list:

name

description

mean-a

mean of group A

mean-b

mean of group B

sdev-a

standard deviation in group A

sdev-b

standard deviation in group B

t

t between mean values

df

degrees of freedom

p

two tailed probability of t under the null hypothesis

The first example studies the effect of different sleep length
before a test on the SCAT (Sam's Cognitive Ability Test):

The effect of the antidepressant treatment is moderately significant with a
p of 0.0137.

In the third syntax, a form of the Student's t called Welch's t-test
is performed. This method is used when the variances observed in both
samples are significantly different. The threshold can be set using the
float-probability parameter. When this parameter is used the t-test
function will perform a F-test to compare the variances in the two data samples.
If the probability of the found F-ratio is below the float-probability
parameter, the Welch's t-test method will be used. Specifying this value
as 1.0 effectively forces a Welch's t-test:

The last example shows a shorter form of catch,
which returns the throw result directly.

throw is useful for breaking out of a loop
or for early return from user-defined functions
or expression blocks.
In the following example,
the begin block will return X
if (foo X) is true;
else Y will be returned:

(catch (begin
…
(if (foo X) (throw X) Y)
…
))

throw will not cause an error exception.
Use throw-error
to throw user error exceptions.

The user error can be handled
like any other error exception
using user-defined error handlers
and the error-event function,
or the form of catch
that can capture error exceptions.

time

syntax: (time exp [int-count)

Evaluates the expression in exp and returns the time spent
on evaluation in floating point milliseconds. Depending on the platform
decimals of milliseconds are shown or not shown.

(time (myprog x y z)) → 450.340
(time (myprog x y z) 10) → 4420.021

In first the example, 450 milliseconds elapsed
while evaluating (myprog x y z). The second example
returns the time for ten evaluations of (myprog x y z).
See also date,
date-value,
time-of-day,
and now.

timer

Starts a one-shot timer firing off the Unix signal SIGALRM, SIGVTALRM,
or SIGPROF after the time in seconds (specified in num-seconds)
has elapsed. When the timer fires, it calls the user-defined function
in sym- or func-event-handler.

On Linux/Unix, an optional 0, 1, or 2 can
be specified to control how the timer counts. With default option
0, real time is measured. Option 1 measures the time
the CPU spends processing in the process owning the timer.
Option 2 is a combination of both called profiling time.
See the Unix man page setitimer() for details.

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., 0.25 for 250 milliseconds).

Defining 0 (zero) as time shuts the running timer down
and prevents it from firing.

When called with sym- or func-event-handler,
timer returns the elapsed time of the timer in progress.
This can be used to program time lines or schedules.

timer called without arguments returns the symbol of the current
event handler.

The example shows an event handler, ticker,
which starts the timer again after each event.

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 timer,
use the following pattern,
which calls net-select
to test if a socket is ready for reading:

syntax: (title-case str[bool])

Returns a copy of the string in str
with the first character converted to uppercase.
When the optional bool parameter
evaluates to any value other than nil,
the rest of the string is converted to lowercase.

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 trace-highlight.:

[-> 2] s|tep n|ext c|ont q|uit >

At the prompt, an s, n, c,
or q 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.

In the third syntax (trace nil) closes debugger mode or
the trace file opened.

In the last syntax (trace) returns the current mode.

trace-highlight

syntax: (trace-highlight str-prestr-post [str-headerstr-footer])

Sets the characters or string of characters used to enclose expressions
during trace. By default,
the # (number sign) is used to enclose the expression highlighted
in trace 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.

Two more strings can optionally be specified for str-header and str-footer,
which control the separator and prompt. A maximum of 15 characters is allowed
for the header and 31 for the footer.

The first example replaces the default # (number sign)
with a >> and <<. 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.

transpose

syntax: (transpose matrix)

Transposes a matrix by reversing the rows and columns.
Any kind of list-matrix can be transposed. Matrices are made rectangular
by filling in nil 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.

The matrix to transpose can contain any data-type.

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

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,
transpose will assume nil for those missing elements.
Superfluous elements in a row will be ignored.

Using the first syntax, all white-space characters are trimmed from both
sides of str.

The second syntax trims the string str from both sides,
stripping the leading and trailing characters as given
in str-char. If str-char contains no character,
the space character is assumed. trim returns the new string.

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.

unicode

syntax: (unicode str-utf8)

Converts ASCII/UTF-8 character strings in str
to UCS-4–encoded Unicode of 4-byte integers per character.
The string is terminated with a 4-byte integer 0.
This function is only available on UTF-8–enabled versions
of newLISP.

On big endian CPU architectures, the byte order will
be reversed from high to low. The unicode and
utf8 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.

unify

syntax: (unify exp-1exp-2 [list-env])

Evaluates and matches exp-1 and exp-2.
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. unify returns nil
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,
unify returns an empty list.
newLISP uses a modified J. Alan Robinson unification algorithm
with correctly applied occurs check.
See also Peter Norvig's paper about a common
unification algorithm bug, which
is not present in this implementation.

Since version 10.4.0 the underscore symbol _ (ASCII 95) matches any atom,
list or unbound variable and never binds.

In the previous example,
X was bound to 123 earlier
and is included in the second statement
to pre-bind X.

Use unify with expand

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 expand
can be used to actually replace bound variables
with their terms:

The program handles a database of facts
and a database of simple
A is a fact if B is a factrules.
A fact is proven true
if it either can be found in the facts database
or if it can be proven using a rule.
Rules can be nested:
for example, to prove that somebody (knows physics),
it must be proved true that somebody is a physicist.
But somebody is only a physicist
if that person studied physics.
The <- symbol
separating the left and right terms of the rules
is not required
and is only added to make the rules database
more readable.

This implementation does not handle multiple terms
in the right premise part of the rules,
but it does handle backtracking of the rules database
to try out different matches.
It does not handle backtracking
in multiple premises of the rule.
For example,
if in the following rule A if B and C and D,
the premises B and C succeed
and D fails,
a backtracking mechanism might need to go back
and reunify the B or A terms
with different facts or rules
to make D succeed.

The above algorithm could be written differently
by omitting expand
from the definition of prove-rule
and by passing the environment, e,
as an argument to the unify and query functions.

A learning of proven facts
can be implemented by appending them
to the facts database
once they are proven.
This would speed up subsequent queries.

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.
prove-rule could accomplish this testing
for the symbol eval in each rule term.

union

syntax: (union list-1list-2 [list-3 ... ])

union returns a unique collection list of distinct elements found in two
or more lists.

(union '(1 3 1 4 4 3) '(2 1 5 6 4)) → (1 3 4 2 5 6)

Like the other set functions difference,
intersect and unique,
union maintains the order of elements as found in the original
lists.

unique

syntax: (unique list)

Returns a unique version of list
with all duplicates removed.

(unique '(2 3 4 4 6 7 8 7)) → (2 3 4 6 7 8)

Note that the list does not need to be sorted,
but a sorted list makes unique perform faster.

unless

syntax: (unless exp-conditionbody)

The statements in body are only evaluated if exp-condition
evaluates to nil or the empty list (). The result
of the last expression in body is returned or the return value
of exp-condition if body was not executed.

Because unless does not have an else condition as in
if, the statements in body need
not to be grouped with begin:

When the first parameter is a string, unpack unpacks a binary structure
in str-addr-packed or pointed to by num-addr-packed into newLISP
variables using the format in str-format. unpack is the reverse
operation of pack. Using num-addr-packed facilitates the unpacking
of structures returned from imported, shared library functions.

If the number specified in num-addr-packed is not a valid memory
address, a system bus error or segfault can occur and crash newLISP or leave
it in an unstable state.

When the first parameter is the symbol of a struct definition,
unpack uses the format as specified in struct.
While unpack with str-format literally unpacks as specified,
unpack with struct will skip structure aligning pad-bytes
depending on data type, order of elements and CPU architecture.
Refer to the description of the struct function for more detail.

When unpacking structures containing NULL pointers, an error will be
thrown when unpack tries to convert the pointer to a string. If NULL
pointers are to be expected, void* should be used in the structure definition.

until

syntax: (until exp-condition [body])

Evaluates the condition in exp-condition.
If the result is nil or the empty list (),
the expressions in body are evaluated.
Evaluation is repeated until the exp-condition results in a value
other than nil or the empty list.
The result of the last expression evaluated in body
is the return value of the until expression. If
body is empty, the result of last exp-condition
is returned. until works like
(while (not …)).

The utf8 function can also be used
to test for the presence of UTF-8–enabled newLISP:

(if utf8 (do-utf8-version-of-code) (do-ascii-version-of-code))

On big endian CPU architectures, the byte order will be reversed
from highest to lowest. The utf8 and unicode
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.

utf8len

syntax: (utf8len str)

Returns the number of characters in a UTF-8–encoded string.
UTF-8 characters can be encoded in more than one 8-bit byte.
utf8len returns the number of UTF-8 characters in a string.
This function is only available on UTF-8–enabled versions of newLISP.

uuid

syntax: (uuid [str-node])

Constructs and returns
a UUID (Universally Unique IDentifier).
Without a node spec in str-node,
a type 4 UUID random generated byte number
is returned.
When the optional str-node parameter is used,
a type 1 UUID is returned.
The string in str-node
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 RFC 4122
for details on UUID generation.

Each invocation of the uuid 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.

wait-pid

syntax: (wait-pid int-pid [int-options | nil])

Waits for a child process specified in int-pid to end. The child process was
previously started with process or fork.
When the child process specified in int-pid 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 waitpid command (without the hyphen
used in newLISP) for further information.

When -1 is specified for int-pid,
pid and status information of any child process started by the parent are returned.
When 0 is specified, wait-pid only watches child processes in the
same process group as the calling process. Any other negative value for int-pid
reports child processes in the same process group as specified with a negative sign
in int-pid.

An option can be specified in int-option. See Linux/Unix documentation
for details on integer values for int-options. As an alternative, nil
can be specified. This option causes wait-pid to be non-blocking, returning
right away with a 0 in the pid of the list returned. This option used together with
an int-pid parameter of -1 can be used to continuously loop and act
on returned child processes.

This function is only available on macOS, Linux and other Unix-like operating systems.

The process my-process is started,
then the main program blocks
in the wait-pid call
until my-process has finished.

when

syntax: (when exp-conditionbody)

The statements in body are only evaluated if exp-condition
evaluates to anything not nil and not the empty list (). The result
of the last expression in body is returned or nil or the empty
list () if body was not executed.

Because when does not have an else condition as in
if, the statements in body need not to be grouped with
begin:

while

syntax: (while exp-conditionbody)

Evaluates the condition in exp-condition.
If the result is not nil or the empty list (),
the expressions in body are evaluated.
Evaluation is repeated until an exp-condition results
in nil or the empty list ().
The result of the body's last evaluated expression
is the return value of the while expression.

In the second syntax write writes int-size bytes
from a buffer in str-buffer to a file specified in int-file,
previously obtained from a file open operation. If int-size
is not specified, all data in sym-buffer or str-buffer is written.
write returns the number of bytes written or nil on failure.

If all parameters are omitted, write writes the contents from the
last read-line to standard out (STDOUT).

write is a shorter writing of write-buffer. The longer
form still works but is deprecated and should be avoided in new code.

write-char

syntax: (write-char int-fileint-byte1 [int-byte2 ... ])

Writes a byte specified in int-byte to a file specified by the file
handle in int-file. The file handle is obtained from a previous
open operation. Each write-char advances the file pointer
by one 8-bit byte.

The file myfile is read, encrypted using the
password secret, and written back into the new file myfile.enc
in the current directory.

write-file can take an http:// or file:// URL
in str-file-name. When the prefix http:// is used,
write-file works exactly like put-url
and can take the same additional parameters:

(write-file "http://asite.com/message.txt" "This is a message" )

The file message.txt is created and written at a remote location,
http://asite.com, with the contents of str-buffer.
In this mode, write-file can also be used to transfer files
to remote newLISP server nodes.

The string in str and the line termination character(s)
are written to the device specified in int-file.
When the string argument is omitted write-line writes the
contents of the last read-line to int-file
If the first argument is omitted too then it writes to to standard out
(STDOUT) or to whatever device is set by device.

The first example opens/creates a file, writes a line to it,
and closes the file. The second example shows the usage of write-line
without arguments. The contents of init.lsp are written to the console
screen.

See also the function write for writing
to a device without the line-terminating character.

E.g. whenever a block of data requested with get-url
arrives, the function in sym or func will be called with
the number of bytes transferred. Likewise when sending data with
post-url or any of the other data sending
functions, sym or func will be called with the number of
bytes transferred for each block of data transferred.

Specifying nil for the event will reset it to the initial default state.

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 func, a symbol
containing a function definition could have been used:

(define (report n) (println "->" n))
(xfer-event 'report)

This can be used to monitor the progress of longer
lasting byte transfers in HTTP uploads or downloads.

xml-error

syntax: (xml-error)

Returns a list of error information
from the last xml-parse operation;
otherwise, returns nil
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 0 (zero).

xml-parse

Parses a string containing XML 1.0 compliant, well-formed XML.
xml-parse 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 assoc.
When xml-parse fails due to malformed XML, nil is returned
and xml-error can be used to access error information.

Modifying the translation process.

Optionally, the int-options 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, xml-type-tags,
serves for translating the XML tags.
The following option numbers can be used:

option

description

1

suppress whitespace text tags

2

suppress empty attribute lists

4

suppress comment tags

8

translate string tags into symbols

16

add SXML (S-expression XML) attribute tags (@ ...)

Options can be combined by adding the numbers
(e.g., 3 would combine the options
for suppressing whitespace text tags/info
and empty attribute lists).

The TEXT elements containing only whitespace make the output very confusing.
As the database in example.xml only contains data,
we can suppress whitespace, empty attribute lists and comments with
option (+ 1 2 4):

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 xml-type-tags directive.

Specifying nil 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.

Parsing into SXML (S-expressions XML) format:

Using xml-type-tags to suppress
all XML-type tags—along with the option numbers
1, 2, 4, 8, and 16—SXML
formatted output can be generated:

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.

Using a call back function

Normally, xml-parse will not return until all parsing has finished.
Using the func-callback option, xml-parse will call back after
each tag closing with the generated S-expression and a start position and
length in the source XML:

System Symbols and Constants

Variables changed by the system

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.

All symbols starting with the $ character will not be serialized
when using the save or source functions.

variable name

purpose

protected

reentrant

$0 - $15

Used primarily in regular expressions. $0
is also used to record the last state or count of execution of some functions.

no

no

$args

Contains the list parameters not bound to local
variables. Normally the function args is used to retrieve
the contents of this variable.

The function dolist
maintains this as a list index or offset. The functions
map, series,
while, until,
do-while and do-until
maintain this variable as an iteration counter starting with 0 (zero) for
the first iteration.

yes

yes

$it

The anaphoric$it refers to the
result inside an executing expression, i.e. in self referential assignments.
$it is only available inside the function expression setting it, and
is set to nil on exit of that expression. The following functions use it:
if,
hashes, find-all,
replace, set-ref,
set-ref-all and setf setq.

yes

no

$main-args

Contains the list of command line arguments
passed by the OS to newLISP when it was started. Normally the function
main-args is used to retrieve the contents.

yes

n/a

Predefined variables and functions.

These are preset symbol constants. Two of them are used as namespace templates,
one two write platform independent code.

name

purpose

protected

reentrant

Class

Is the predefined general FOOP class constructor
which can be used together with new to create new FOOP classes, e.g:
(new Class 'Rectangle) would create a class and object constructor for
a user class Rectangle. See the
FOOP classes and constructors chapter in the users
manual for details.

no

n/a

ostype

Contains a string identifying the OS-Platform
for which the running newLISP version has been compiled. See the reference section for
details

yes

n/a

Tree

Is a predefined namespace to serve as a hash like
dictionary. Instead of writing (define Foo:Foo) to create a Foo
dictionary, the expression (new Tree 'Foo) can be used as well. See the chapter
Hash functions and dictionaries foe details.

no

n/a

module

Is a predefined function to load modules.
Instead of using load together with the NEWLISPDIR environment
variable, the module function loads automatically from
$NEWLISPDIR/modules/.

0. PREAMBLE

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.

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.

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.

1. APPLICABILITY AND DEFINITIONS

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.

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.

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.

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.

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.

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

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.

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.

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.

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.

2. VERBATIM COPYING

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.

You may also lend copies, under the same conditions stated above,
and
you may publicly display copies.

3. COPYING IN QUANTITY

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.

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.

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.

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.

4. MODIFICATIONS

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:

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

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.

C. State on the Title page the name of the
publisher of the Modified Version, as the publisher.

D. Preserve all the copyright notices of the
Document.

E. Add an appropriate copyright notice for your
modifications adjacent to the other copyright notices.

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

G. Preserve in that license notice the full
lists of Invariant Sections and required Cover Texts given in the
Document's license notice.

H. Include an unaltered copy of this License.

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

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

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

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

M. Delete any section Entitled "Endorsements".
Such a section may not be included in the Modified Version.

N. Do not retitle any existing section to be
Entitled "Endorsements" or to conflict in title with any Invariant
Section.

O. Preserve any Warranty Disclaimers.

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.

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.

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.

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.

5. COMBINING DOCUMENTS

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.

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.

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

6. COLLECTIONS OF DOCUMENTS

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.

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.

7. AGGREGATION WITH INDEPENDENT WORKS

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.

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.

8. TRANSLATION

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.

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.

9. TERMINATION

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.

10. FUTURE REVISIONS OF THIS LICENSE

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

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.

GNU GENERAL PUBLIC LICENSE

Version 3, 29 June 2007

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.

Preamble

The GNU General Public License is a free, copyleft license for
software and other kinds of works.

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.

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.

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.

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.

Developers that use the GNU GPL protect your rights with two steps:

(1) assert copyright on the software, and (2) offer you this License
giving you legal permission to copy, distribute and/or modify it.

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.

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.

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.

The precise terms and conditions for copying, distribution and
modification follow.

TERMS AND CONDITIONS

0. Definitions.

"This License" refers to version 3 of the GNU General Public License.

"Copyright" also means copyright-like laws that apply to other kinds of
works, such as semiconductor masks.

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

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.

A "covered work" means either the unmodified Program or a work based
on the Program.

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.

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.

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.

1. Source Code.

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.

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.

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.

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.

The Corresponding Source need not include anything that users
can regenerate automatically from other parts of the Corresponding
Source.

The Corresponding Source for a work in source code form is that
same work.

2. Basic Permissions.

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.

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.

Conveying under any other circumstances is permitted solely under
the conditions stated below. Sublicensing is not allowed; section 10
makes it unnecessary.

3. Protecting Users' Legal Rights From Anti-Circumvention Law.

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.

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.

4. Conveying Verbatim Copies.

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.

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.

5. Conveying Modified Source Versions.

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:

a) The work must carry prominent notices stating that you modified
it, and giving a relevant date.

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

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.

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.

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.

6. Conveying Non-Source Forms.

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:

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.

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.

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.

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.

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.

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.

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.

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

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

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.

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.

7. Additional Terms.

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

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.

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:

a) Disclaiming warranty or limiting liability differently from the
terms of sections 15 and 16 of this License; or

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

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

d) Limiting the use for publicity purposes of names of licensors or
authors of the material; or

e) Declining to grant rights under trademark law for use of some
trade names, trademarks, or service marks; or

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.

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.

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.

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.

8. Termination.

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

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.

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.

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.

9. Acceptance Not Required for Having Copies.

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.

10. Automatic Licensing of Downstream Recipients.

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.

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.

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.

11. Patents.

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

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.

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.

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.

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.

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.

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.

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.

12. No Surrender of Others' Freedom.

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.

13. Use with the GNU Affero General Public License.

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.

14. Revised Versions of this License.

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.

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.

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.

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.

15. Disclaimer of Warranty.

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.

16. Limitation of Liability.

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.

17. Interpretation of Sections 15 and 16.

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.