!
+-*/%
Ab
Ap
As
Ba
Ca
Cl
Co
Cu
De
Di
Do
En
Ex
Fi
Fl
Ga
Gl
In
La
Li
Ma
Mu
Net
New
Nt
Pa
Pr
Ra
Rea
Reg
Sea
Seq
Sl
St
Sy
Ti
Tr
Ut
Wr
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's efficient red-black tree implementation can handle millions of symbols in namespaces or hashes without degrading performance.
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.
newLISP has functions to modify, insert, or delete elements inside complex nested lists or multi-dimensional array structures.
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.
newLISP are licensed under version 3 of the GPL (General Public License). The newLISP documentation as well as other documentation packaged with newLISP are licensed under the GNU Free Documentation License.
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.
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:
> !ls *.html CodePatterns.html MemoryManagement.html newLISPdoc.html ExpressionEvaluation.html manual_frame.html newlisp_index.html License.html newLISP-10.3-Release.html newlisp_manual.html >
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.
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:
-h this help (no init.lsp) -n no init.lsp (must be first) -x <source> <target> link (no init.lsp) -v version -s <stacksize> -m <max-mem-MB> cell memory -e <quoted lisp expression> -l <path-file> log connections -L <path-file> log all -w <working dir> -c no prompts, HTTP -C force prompts -t <usec-server-timeout> -p <port-no> -d <port-no> demon mode -http only -http-safe safe mode -6 IPv6 mode
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 newlisp man page can be found:
man newlisp
This will display a man page in the Linux/Unix shell.
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.
newlisp aprog.lsp bprog.lsp prog.lsp newlisp http://newlisp.org/example.lsp newlisp file:///usr/home/newlisp/demo.lsp
This option suppresses loading of any present initialization file init.lsp or .init.lsp. In order to work, this must be the first option specified:
newlisp -n
More about initialization files.
newlisp -s 4000 newlisp -s 100000 aprog bprog newlisp -s 6000 myprog newlisp -s 6000 http://asite.com/example.lsp
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.
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.
Small pieces of newLISP code can be executed directly from the command-line:
newlisp -e "(+ 3 4)" → 7 ; On MS Windows and Unix newlisp -e '(append "abc" "def")' → "abcdef" ; On Unix
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.
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.
newlisp -l./logfile.txt -c newlisp -L /usr/home/www/log.txt -http -w /usr/home/www/htpdocs
The following table shows the items logged in different situations:
| logging mode | command-line and net-eval with -c | HTTP server with -http |
|---|---|---|
| newlisp -l | log only input and network connections | log only network connections |
| newlisp -L | log also newLISP output (w/o prompts) | log also HTTP requests |
All logging output is written to the file specified after the -l or -L option.
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.
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.
A capital C forces prompts when running newLISP in pipe I/O mode inside the Emacs editor:
newlisp -C
To suppress console output from return values from evaluations, use silent.
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.
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.
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 |
| 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.
Instead of a port, a local domain Unix socket path can be specified in the -d or -p server modes.
newlisp -c -d /tmp/mysocket &
Test the server using another newLISP process:
newlisp -e '(net-eval "/tmp/mysocket" 0 "(symbols)")'
A list of all built-in symbols will be printed to the terminal
This mode will work together with local domain socket modes of net-connect, net-listen, and net-eval. Local domain sockets opened with net-connect and net-listen can be served using net-accept, net-receive, and net-send. Local domain socket connections can be monitored using net-peek and net-select.
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.
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.
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.
Put one of the following lines into inetd.conf:
net-eval stream tcp nowait root /usr/local/bin/newlisp -c # as an alternative, a program can also be preloaded net-eval stream tcp nowait root /usr/local/bin/newlisp -c myprog.lsp
Instead of root, another user and optional group can be specified. For details, see the Unix man page for inetd.
The following line is put into the services file:
net-eval 4711/tcp # newLISP net-eval requests
On macOS and some Unix systems, xinetd can be used instead of inetd. Save the following to a file named net-eval in the /etc/xinetd.d/ directory:
service net-eval
{
socket_type = stream
wait = no
user = root
server = /usr/local/bin/newlisp
port = 4711
server_args = -c
only_from = localhost
}
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 server nodes answer HTTP GET and PUT requests. This can be used to retrieve and store files with get-url, put-url, read-file, write-file and append-file, or to load and save programs using load and save from and to remote server nodes.
Source code and the newLISP executable can be linked together to build a self-contained application by using the -x command line flag.
;; uppercase.lsp - Link example (println (upper-case (main-args 1))) (exit)
The program uppercase.lsp takes the first word on the command-line and converts it to uppercase.
To build this program as a self-contained executable, follow these steps:
# on OSX, Linux and other UNIX newlisp -x uppercase.lsp uppercase chmod 755 uppercase # give executable permission # on Windows the target needs .exe extension newlisp -x uppercase.lsp uppercase.exe
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.
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")
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.
The directory /usr/local/share/newlisp/modules contains modules with useful functions POP3 mail, etc. The directory /usr/local/share/doc/newlisp/ contains documentation in HTML format.
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.
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.
See also the chapter 23. Extending newLISP in the Code Patterns in newLISP document.
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.
Since v.10.3.3 callbacks can also be registered using newlispCallback. For more information read the chapter 24. newLISP compiled as a shared library in the Code Patterns in newLISP document.
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.
newLISP compiled as a JavaScript library adds new functions linked from API for newLISP in a web browser.
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.
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.
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 (add sub mul div). 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:
(constant '+ add) (constant '- sub) (constant '* mul) (constant '/ div) ;; or all 4 operators at once (constant '+ add '- sub '* mul '/ 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:
(import "mylib.dll" "foo") ; importing int foo(int x) from C (foo (int x)) ; passed argument as integer (import "mylib.dll" "bar") ; importing C int bar(double y) (bar (float y)) ; force double float
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.
The following operators, functions and predicates work on big integers:
| function | description |
|---|---|
| + - * / ++ -- % | arithmetic operators |
| < > = <= >= != | logical operators |
| abs | returns the absolute value of a number |
| gcd | calculates the greatest common divisor of a group of integers |
| even? | checks the parity of an integer number |
| odd? | checks the parity of an integer number |
| number? | checks if an expression is a float or an integer |
| zero? | checks if an expression is 0 or 0.0 |
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.
; first argument triggers big integer mode because it's big enough (+ 123456789012345678901234567890 12345) → 123456789012345678901234580235L ; first small literal put in big integer format by ; appending L to guarantee big integer mode (+ 12345L 123456789012345678901234567890) → 123456789012345678901234580235L (setq x 1234567890123456789012345) (* x x) → 1524157875323883675049533479957338669120562399025L ; conversion from bigint to float introduces rounding errors (bigint (float (* x x))) → 1524157875323883725344000000000000000000000000000L ; sequence itself does not take big integers, before using ; apply, the sequence is converted with bigint (apply * (map bigint (sequence 1 100))) ; calculate 100! → 93326215443944152681699238856266700490715968264381 62146859296389521759999322991560894146397615651828 62536979208272237582511852109168640000000000000000 00000000L ; only the first operand needs to be bigint for apply ; to work. The following gives the same result (apply * (cons 1L (sequence 2 100))) ; length on big integers returns the number of decimal digits (length (apply * (map bigint (sequence 1 100)))) → 158 ; decimal digits ; all fibonacci numbers up to 200, only the first number ; needs to be formatted as big integer, the rest follows ; automatically - when executed from the command line in ; a 120 char wide terminal, this shows a beautiful pattern (let (x 1L) (series x (fn (y) (+ x (swap y x))) 200))
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.
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:
123 → 123 ; decimal integer 0xE8 → 232 ; hexadecimal prefixed by 0x 055 → 45 ; octal prefixed by 0 (zero) 0b101010 → 42 ; binary prefixed by 0b 1.23 → 1.23 ; float 123e-3 → 0.123 ; float in scientific notation 123456789012345678901234567890 → 123456789012345678901234567890L ; parses to big integer
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.
"hello" →"hello" "\032\032\065\032" →" A " "\x20\x20\x41\x20" →" A " "\t\r\n" →"\t\r\n" "\x09\x0d\x0a" →"\t\r\n" ;; null characters are legal in strings: "\000\001\002" → "\000\001\002" {this "is" a string} → "this \"is\" a string" ;; use [text] tags for text longer than 2047 bytes: [text]this is a string, too[/text] → "this is a string, too"
Strings delimited by " (double quotes) will also process the following characters escaped with a \ (backslash):
| character | description |
|---|---|
| \" | for a double quote inside a quoted string |
| \n | for a line-feed character (ASCII 10) |
| \r | for a 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 | for a three-digit ASCII number (nnn format between 000 and 255) |
| \xnn | for a two-digit-hex ASCII number (xnn format between x00 and xff) |
| \unnnn | for a unicode character encoded in the four nnnn hexadecimal digits. newLISP will translate this to a UTF8 character in the UTF8 enabled versions of newLISP. |
| \\ | for the backslash character (ASCII 92) itself |
Quoted strings cannot exceed 2,047 characters. Longer strings should use the [text] and [/text] tag delimiters. newLISP automatically uses these tags for string output longer than 2,047 characters.
The { (left curly bracket), } (right curly bracket), and [text], [/text] delimiters do not perform escape character processing.
Lambda and lambda-macro expressions evaluate to themselves:
(lambda (x) (* x x)) → (lambda (x) (* x x)) (lambda-macro (a b) (set (eval a) b)) → (lambda-macro (a b) (set (eval a) b)) (fn (x) (* x x)) → (lambda (x) (* x x)) ; an alternative syntax
Symbols evaluate to their contents:
(set 'something 123) → 123 something → 123
Contexts evaluate to themselves:
(context 'CTX) → CTX CTX → CTX
Built-in functions also evaluate to themselves:
add → add <B845770D> (eval (eval add)) → add <B845770D> (constant '+ add) → add <B845770D> + → add <B845770D>
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.
(+ 1 2 3 4) → 10 (define (double x) (+ x x)) → (lambda (x) (+ x x))
or
(set 'double (lambda (x) (+ x x))) (double 20) → 40 ((lambda (x) (* x x)) 5) → 25
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.
Arrays evaluate to themselves:
(set 'A (array 2 2 '(1 2 3 4))) → ((1 2) (3 4)) (eval A) → ((1 2) (3 4))
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.
Lambda expressions in newLISP evaluate to themselves and can be treated just like regular lists:
(set 'double (lambda (x) (+ x x)))
(set 'double (fn (x) (+ x x))) ; alternative syntax
(last double) → (+ x x) ; treat lambda as a list
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:
(append (lambda (x)) '((+ x x))) → (lambda (x) (+ x x))
cons, on the other hand, associates the arguments from right to left:
(cons '(x) (lambda (+ x x))) → (lambda (x) (+ x x))
Note that the lambda keyword is not a symbol in a list, but a designator of a special type of list: the lambda list.
(length (lambda (x) (+ x x))) → 2 (first (lambda (x) (+ x x))) → (x)
Lambda expressions can be mapped or applied onto arguments to work as user-defined, anonymous functions:
((lambda (x) (+ x x)) 123) → 246 (apply (lambda (x) (+ x x)) '(123)) → 246 (map (lambda (x) (+ x x)) '(1 2 3)) → (2 4 6)
A lambda expression can be assigned to a symbol, which in turn can be used as a function:
(set 'double (lambda (x) (+ x x))) → (lambda (x) (+ x x)) (double 123) → 246
The define function is just a shorter way of assigning a lambda expression to a symbol:
(define (double x) (+ x x))) → (lambda (x) (+ x x)) (double 123) → 246
In the above example, the expressions inside the lambda list are still accessible within double:
(set 'double (lambda (x) (+ x x))) → (lambda (x) (+ x x)) (last double) → (+ x x)
A lambda list can be manipulated as a first-class object using any function that operates on lists:
(setf (nth 1 double) '(mul 2 x)) → (lambda (x) (mul 2 x)) double → (lambda (x) (mul 2 x)) (double 123) → 246
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.
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.
(set 'lst '(nil nil nil)) → (nil nil nil) (map symbol? lst) → (true true true)
In the above example, nil represents a symbol. In the following example, nil and true are evaluated and represent Boolean values:
(if nil "no" "yes") → "yes" (if true "yes" "no") → "yes" (map not lst) → (true true 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.
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:
| function | description |
|---|---|
| append | appends arrays |
| apply | apply a function or operator to a list of arguments. |
| array | creates and initializes an array with up to 16 dimensions |
| array-list | converts an array into a list |
| array? | checks if expression is an array |
| corr | calculates the product-moment correlation coefficient |
| det | returns the determinant of a matrix |
| dolist | evaluates once for each element in an array vector |
| first | returns the first row of an array |
| invert | returns the inversion of a matrix |
| last | returns the last row of an array |
| length | returns the number of rows in an array or elements in a vector |
| map | applies a function to vector(s) of arguments and returns results in a list. |
| mat | perform scalar operations on matrices |
| multiply | multiplies two matrices |
| nth | returns an element of and array |
| rest | returns all but the first row of an array |
| reverse | reverses the elements or rows in an array |
| setf | sets contents of an array reference |
| slice | returns a slice of an array |
| sort | sort the elements in an array |
| stats | calculates some basic statistics for a data vector |
| t-test | compares means of data samples using the Student's t statistic |
| transpose | transposes a matrix |
newLISP represents multidimensional arrays with an array of arrays (i.e., the elements of the array are themselves arrays).
When used interactively, newLISP prints and displays arrays as lists, with no way of distinguishing between them.
Use the source or save functions to serialize arrays (or the variables containing them). The array statement is included as part of the definition when serializing arrays.
Like lists, negative indices can be used to enumerate the elements of an array, starting from the last element.
An out-of-bounds index will cause an error message on an array or list.
Arrays can be non-rectangular, but they are made rectangular during serialization when using source or save. The array function always constructs arrays in rectangular form.
The matrix functions det, transpose, multiply, and invert can be used on matrices built with nested lists or arrays built with array.
For more details, see array, array?, and array-list in the reference section of this manual.
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 can be used instead of nth to retrieve the elements of a list or array or the characters of a string:
(set 'lst '(a b c (d e) (f g))) (lst 0) → a ; same as (nth 0 lst) (lst 3) → (d e) (lst 3 1) → e ; same as (nth '(3 1) lst) (lst -1) → (f g) (set 'myarray (array 3 2 (sequence 1 6))) (myarray 1) → (3 4) (myarray 1 0) → 3 (myarray 0 -1) → 2 ; indexing ASCII strings ("newLISP" 3) → "L" ; indexing strings in UTF8 enabled versions ("我能吞下玻璃而不伤身体。" 3) → "下"
Indices may also be supplied from a list. In this way, implicit indexing works together with functions that take or produce index vectors, such as push, pop, ref and ref-all.
(lst '(3 1)) → e (set 'vec (ref 'e lst)) → (3 1) (lst vec) → e ; an empty index vector yields the original list or array (lst '()) → (set 'lst '(a b c (d e) (f g)))
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.
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:
(set 'MyList:MyList '(a b c d e f g)) (MyList 0) → a (MyList 3) → d (MyList -1) → g (3 2 MyList) → (d e) (-3 MyList) → (e f g) (set 'aList MyList) (aList 3) → d
In this example, aList references MyList:MyList, not a copy of it. For more information about contexts, see Variables holding contexts.
The indexed default functor can also be used with setf as shown in the following example:
(set 'MyList:MyList '(a b c d e f g)) (setf (MyList 3) 999) → 999 (MyList 3) → 999 MyList:MyList → (a b c 999 e f g)
Implicit forms of rest and slice can be created by prepending a list with one or two numbers for offset and length. If the length is negative it counts from the end of the list or string:
(set 'lst '(a b c d e f g)) ; or as array (set 'lst (array 7 '(a b c d e f g))) (1 lst) → (b c d e f g) (2 lst) → (c d e f g) (2 3 lst) → (c d e) (-3 2 lst) → (e f) (2 -2 lst) → (c d e) ; resting and slicing is always on 8-bit char borders ; even on UTF8 enabled versions (set 'str "abcdefg") (1 str) → "bcdefg" (2 str) → "cdefg" (2 3 str) → "cde" (-3 2 str) → "ef" (2 -2 str) → "cde"
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.
Parts in lists, arrays and strings referenced by indices can be modified using setf:
; lists (set 'lst '(a b c d (e f g))) (lst 1) → b (setf (lst 1) 'z) → z lst → (a z c d (e f g)) (setf (lst -1) '(E F G)) → (E F G) lst → (a z c d (E F G)) ; arrays (set 'myarray (array 2 3 (sequence 1 6))) → ((1 2 3) (4 5 6)) (setf (myarray 1 2) 66) → 66 myarray → ((1 2 3) (4 5 66)) ; strings (set 's "NewLISP") (setf (s 0) "n") → "n" s → "newLISP"
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.
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:
| function | description |
|---|---|
| ++ | increments numbers in integer mode |
| -- | decrements numbers in integer mode |
| bind | binds variable associations in a list |
| constant | sets the contents of a variable and protects it |
| extend | extends a list or string |
| dec | decrements a number referenced by a variable, list or array |
| define | sets the contents of a variable |
| define-macro | sets the contents of a variable |
| inc | increments a number referenced by a variable, list or array |
| let | declares and initializes local variables |
| letn | initializes local variables incrementally, like nested lets |
| letex | expands local variables into an expression, then evaluates |
| net-receive | reads into a buffer variable |
| pop | pops an element from a list or string |
| pop-assoc | removes an association from an association list |
| push | pushes a new element onto a list or string |
| read | reads into a buffer variable |
| receive | receives a message from a parent or child process |
| replace | replaces elements in a list or string |
| reverse | reverses a list or string |
| rotate | rotates the elements of a list or characters of a string |
| set | sets the contents of a variable |
| setf setq | sets the contents of a variable, list, array or string |
| set-ref | searches for an element in a nested list and replaces it |
| set-ref-all | searches for an element in a nested list and replaces all instances |
| sort | sorts the elements of a list or array |
| swap | swaps two elements inside a list or string |
| write | write a string to a file or string buffer |
Some destructive functions can be made non-destructive by wrapping the target object into the copy function.
(set 'aList '(a b c d e f)) (replace 'c (copy aList)) → (a b d e f) aList → (a b c d e f)
The list in aList is left unchanged.
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.
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:
(define (foo x)
...
(if condition (throw 123))
...
456
)
;; if condition is true
(catch (foo p)) → 123
;; if condition is not true
(catch (foo p)) → 456
Breaking out of loops works in a similar way:
(catch
(dotimes (i N)
(if (= (foo i) 100) (throw i))))
→ value of i when foo(i) equals 100
The example shows how an iteration can be exited before executing N times.
Multiple points of return can be coded using throw:
(catch (begin
(foo1)
(foo2)
(if condition-A (throw 'x))
(foo3)
(if condition-B (throw 'y))
(foo4)
(foo5)))
If condition-A is true, x will be returned from the catch expression; if condition-B is true, the value returned is y. Otherwise, the result from foo5 will be used as the return value.
As an alternative to catch, the error-event function can be used to catch errors caused by faulty code or user-initiated exceptions.
The throw-error function may be used to throw user-defined errors.
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.
or can be used in a similar fashion:
(or
(func-a)
(func-b)
(func-c)
(func-d))
The result of the or expression will be the first function that returns a value which is not nil or ().
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:
> (set 'x 1) 1 > (define (f) x) (lambda () x) > (f) 1 > (define (g x) (f)) (lambda (x) (f)) > (g 0) 0 > (f) 1 > _
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:
(define (inc-symbol x y) (inc (eval x) y)) (set 'y 200) (inc-symbol 'y 123) → 246 y → 200 ; y is still 200
Because the global y shares the same symbol as the function's second parameter, inc-symbol returns 246 (123 + 123), leaving the global y unaffected. Dynamic scoping's variable capture can be a disadvantage when passing symbol references to user-defined functions. newLISP offers several methods to avoid variable capture.
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.
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)))
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.
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:
(context 'FOO)
(set 'var 123)
(define (func x y z)
... )
(context MAIN)
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:
(symbols FOO) → (FOO:func FOO:var FOO:x FOO:y FOO:z) ; or from inside the context symbols are shown without context prefix (context FOO) → (func x y z) (sumbols)
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:
(context 'ACTX)
(define (foo x y)
(+ x y)
(context MAIN
;; above same as
(define (ACTX:foo ACTX:x ACTX:y)
(+ ACTX:x ACTX:y))
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:
;;; file MY_PROG.LSP
;;
;; everything from here on goes into GRAPH
(context 'GRAPH)
(define (draw-triangle x y z)
(…))
(define (draw-circle)
(…))
;; show the runtime context, which is GRAPH
(define (foo)
(context))
;; switch back to MAIN
(context 'MAIN)
;; end of file
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.
;; same symbol name, but in different context (= 'A:val 'B:val) → nil (= (term 'A:val) (term 'B:val)) → true (= (prefix 'A:val) (prefix 'B:val)) → nil
Note: The symbols in above example are quoted with a ' (single quote) because we are interested in the symbol itself, not in the contents of the symbol.
By default, only built-in functions and symbols like nil and true are visible inside contexts other than MAIN. To make a symbol visible to every context, use the global function:
(set 'aVar 123) → 123 (global 'aVar) → aVar (context 'FOO) → FOO aVar → 123
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.
By using the constant function, symbols can be both set and protected from change at the same time:
> (constant 'aVar 123) → 123 > (set 'aVar 999) ERR: symbol is protected in function set : aVar >_
A symbol needing to be both a constant and a global can be defined simultaneously:
(constant (global 'aVar) 123)
In the current context, symbols protected by constant can be overwritten by using the constant function again. This protects the symbols from being overwritten by code in other contexts.
Global and built-in function symbols can be overwritten inside a context by prefixing them with their own context symbol:
(context 'Account)
(define (Account:new …)
(…))
(context 'MAIN)
In this example, the built-in function new is overwritten by Account:new, a different function that is private to the Account context.
Variables can be used to refer to contexts:
(set 'FOO:x 123) (set 'ctx FOO) → FOO ctx:x → 123 (set 'ctx:x 999) → 999 FOO:x → 999
Context variables are useful when writing functions, which need to refer to different contexts during runtime or use contexts which do not exist during definition:
(define (update ctx val)
(set 'ctx:sum val)
(ctx:func 999)
)
(context 'FOO)
(define (func x)
(println "=>" x))
(context MAIN)
The following shows a terminal session using above definitions. The program output is shown in bold-face:
> (update FOO 123) => 999 > FOO:sum 123 >
The same one function update can display different behavior depending on the context passed as first parameter.
The sequence in which contexts are created or loaded can lead to unexpected results. Enter the following code into a file called demo:
;; demo - file for loading contexts (context 'FOO) (set 'ABC 123) (context MAIN) (context 'ABC) (set 'FOO 456) (context 'MAIN)
Now load the file into the newlisp shell:
> (load "demo")
ERR: symbol is protected in function set : FOO
> _
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 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:
;; file db.lsp, commonly used database functions
(context 'db)
;; Variables used throughout this namespace
(define db:handle)
(define db:host "http://localhost")
;; Constants
(constant 'Max_N 1000000)
(constant 'Path "/usr/data/")
;; Functions
(define (db:open ... )
... )
(define (db:close ... )
... )
(define (db:update ... )
... )
The example shows a good practice of predefining variables, which are global inside the namespace, and defining as constants the variables that will not change.
If a file must contain more than one context, then the end of the context should be marked with a switch back to MAIN:
;; Multi context file multi.lsp (context 'A-ctx) ... (context MAIN) (context 'B-ctx) ... (context MAIN) (context 'C-ctx) ... (context MAIN)
In any case load will always switch back to the context from where it was called.
Contexts are frequently uses as data containers, e.g. for configuration data:
;; Config.lsp - configuration setup (context 'Config) (set 'user-name "admin") (set 'password "secret") (set 'db-name "/usr/data/db.lsp") ... ;; eof
Loading the Config namespace will now load a whole variable set into memory at once:
(load "Config.lsp") (set 'file (open Config:db-name "read")) ... ...
In a similar fashion a whole data set can be saved:
(save "Config.lsp" 'Config)
Read more about this in the section Serializing 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.
;; pre-declaring contexts, finish with Main to return
(map context '(Utilities Config Acquisition Analysis SysLog MAIN))
;; loading context module files
(load "Utilities.lsp" "Acquisition.lsp")
(load "http://192.168.1.34/Config.lsp") ; load module from remote location
(load "Analysis.lsp" "SysLog.lsp")
(define (run)
... )
(run)
;; end of file
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.
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:
(save "mycontext.lsp" 'MyCtx) ; save MyCtx to mycontext.lsp (load "mycontext.lsp") ; loads MyCtx into memory (save "mycontexts.lsp" 'Ctx1 'Ctx2 'Ctx3) ; save multiple contexts at once
For details, see the functions save (mentioned above) and source (for serializing to a newLISP string).
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 default function
(define (Foo:Foo a b c) (+ a b c))
(Foo 1 2 3) → 6
If a default function is called from a context other than MAIN, the context must already exist or be declared with a forward declaration, which creates the context and the function symbol:
;; forward declaration of a default function
(define Fubar:Fubar)
(context 'Foo)
(define (Foo:Foo a b c)
…
(Fubar a b) ; forward reference
(…)) ; to default function
(context MAIN)
;; definition of previously declared default function
(context 'Fubar)
(define (Fubar:Fubar x y)
(…))
(context MAIN)
Default functions work like global functions, but they are lexically separate from the context in which they are called.
Like a lambda or lambda-macro function, default functions can be used with map or apply.
A default function can update the lexically isolated static variables contained inside its namespace:
;; a function with memory
(define (Gen:Gen x)
(if Gen:acc
(inc Gen:acc x)
(setq Gen:acc x)))
(Gen 1) → 1
(Gen 1) → 2
(Gen 2) → 4
(Gen 3) → 7
gen:acc → 7
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.
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:
(define Myhash:Myhash) ; create namespace and default functor ; or as a safer alternative (new Tree 'Myhash) ; create from built-in template
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:
(Myhash "var" 123) ; create and set variable/value pair (Myhash "var") → 123 ; retrieve value ; keys can be integers and will be converted to strings internally (Myhash 456 "hello") (Myhash 456) → "hello" ; internally an underscore is prepended to the symbol name (symbols Myhash) → (Myhash:Myhash Myhash:_456 Myhash:_var)
Symbol variables created this way can contain spaces or other characters normally not allowed in newLISP symbol names:
(define Foo:Foo) ; or to protect the default functor from change ; (new Tree 'Foo) (Foo "John Doe" 123) → 123 (Foo "#1234" "hello world") → "hello world" (Foo "var" '(a b c d)) → (a b c d) (Foo "John Doe") → 123 (Foo "#1234") → "hello world" (Foo "var") → (a b c d)
An entry which doesn't exist will return nil:
(Foo "bar") → nil
Setting an entry to nil will effectively delete it from the namespace.
An association list can be generated from the contents of the namespace:
(Foo) → (("#1234" "hello world") ("John Doe" 123) ("var" (a b c d)))
Entries in the dictionary can also be created from a list:
(Foo '(("#1234" "hello world") ("John Doe" 123) ("var" (a b c d))) → Foo
The list can also be used to iterate through the sorted key -> value pairs:
(dolist (item (Foo)) (println (item 0) " -> " (item 1))) #1234 -> hello world John Doe -> 123 var -> (a b c d)
Like many built-in functions hash expressions return a reference to their content which can be modified directly:
(pop (Foo "var")) → a (Foo "var") → (b c d) (push 'z (Foo "var")) → (z b c d) (Foo "var") → (z b c d)
When setting hash values the anaphoric system variable $it can be used to refer to the old value when setting the new:
(Foo "bar" "hello world")
(Foo "bar" (upper-case $it))
(Foo "bar") → "HELLO WORLD"
Hash values also can be modified using setf:
(Foo "bar" 123) → 123 (setf (Foo "bar") 456) → 456 (Foo "bar") → 456
But supplying the value as a second parameter to the hash functions is shorter to write and faster.
Dictionaries can easily be saved to a file and reloaded later:
; save dictionary (save "Foo.lsp" 'Foo) ; load dictionary (load "Foo.lsp")
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:
(Foo) → (("#1234" "hello world") ("John Doe" 123) ("var" (a b c d))) (symbols Foo) → (Foo:Foo Foo:_#1234 Foo:_John Doe Foo:_var)
In the first line hash symbols are shown as strings without the preceding underscore characters. The second line shows the internal form of the symbols with prepended underscore characters.
For a more detailed introduction to namespaces, see the chapter on Contexts.
A default functor can also be used to hold data. If this data contains a list or string, the context name can be used as a reference to the data:
;; the default functor for holding data (define Mylist:Mylist '(a b c d e f g)) (Mylist 3) → d (setf (Mylist 3) 'D) → D Mylist:Mylist → (a b c D e f g) ;; access list or string data from a default functor (first Mylist) → a (reverse Mylist) → (g f e D c b a) (set 'Str:Str "acdefghijklmnop") (upper-case Str) → "ACDEFGHIJKLMNOP"
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:
;; use a default functor to hold a list
(set 'Mydb:Mydb (sequence 1 100000))
(define (change-db obj idx value)
(setf (obj idx) value))
; pass by context reference
(change-db Mydb 1234 "abcdefg")
(Mydb 1234) → "abcdefg"
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:
(define (change-list aList) (push 999 (eval aList))) (set 'data '(1 2 3 4 5)) ; note the quote ' in front of data (change-list 'data) → (999 1 2 3 4 5) data → (999 1 2 3 4 5)
Although this method is simple to understand and use, it poses the potential problem of variable capture when passing the same symbol as used as a function parameter:
;; pass data by symbol reference
> (set 'aList '(a b c d))
(a b c d)
> (change-list 'aList)
ERR: list or string expected : (eval aList)
called from user defined function change-list
>
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:
;; pass data by context reference
(set 'Mydb:data (sequence 1 100000))
(define (change-db obj idx value)
(setf (obj:data idx) value))
(change-db Mydb 1234 "abcdefg")
(nth 1234 Mydb:data) → "abcdefg"
; or
(Mydb:data 1234) → "abcdefg"
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).
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.
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:
; built-in generic FOOP object constructor
(define (Class:Class)
(cons (context) (args)))
; create some new classes
(new Class 'Rectangle) → Rectangle
(new Class 'Circle) → Circle
; create some objects using the default constructor
(set 'rect (Rectangle 10 20)) → (Rectangle 10 20)
(set 'circ (Circle 10 10 20)) → (Circle 10 10 20)
; create a list of objects
; building the list using the list function instead of assigning
; a quoted list ensures that the object constructors are executed
(set 'shapes (list (Circle 5 8 12) (Rectangle 4 8) (Circle 7 7 15)))
→ ((Circle 5 8 12) (Rectangle 4 8) (Circle 7 7 15))
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:
(context 'Geometry) (new Class 'MAIN:Rectangle) (new Class 'MAIN:Circle) ...
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:
; overwrite simple constructor
(define (Circle:Circle x y radius)
(list Circle x y radius))
A constructor can also specify defaults:
; constructor with defaults
(define (Circle:Circle (x 10) (y 10) (radius 3))
(list Circle x y radius))
(Circle) → (Circle 10 10 3)
In many cases the constructor as created when using new is sufficient and overwriting it is not necessary.
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:
(set 'myrect (Rectangle 5 5 10 20)) → (Rectangle 5 5 10 20) (set 'mycircle (Circle 1 2 10)) → (Circle 1 2 10)
An object created is identical to the function necessary to create it (hence FOOP). Nested objects can be created in a similar manner:
; create classes
(new Class 'Person)
(new Class 'Address)
(new Class 'City)
(new Class 'Street)
; create an object containing other objects
(set 'JohnDoe (Person (Address (City "Boston") (Street 123 "Main Street"))))
→ (Person (Address (City "Boston") (Street 123 "Main Street")))
Objects in FOOP not only resemble functions they also resemble associations. The assoc function can be used to access object data by name:
(assoc Address JohnDoe) → (Address (City "Boston") (Street 123 "Main Street")) (assoc (list Address Street) JohnDoe) → (Street 123 "Main Street")
In a similar manner setf together with assoc can be used to modify object data:
(setf (assoc (list Address Street) JohnDoe) '(Street 456 "Main Street"))
→ (Street 456 "Main Street")
The street number has been changed from 123 to 456.
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.
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.
;; class methods for rectangles
(define (Rectangle:area)
(mul (self 3) (self 4)))
(define (Rectangle:move dx dy)
(inc (self 1) dx)
(inc (self 2) dy))
;; class methods for circles
(define (Circle:area)
(mul (pow (self 3) 2) (acos 0) 2))
(define (Circle:move dx dy)
(inc (self 1) dx)
(inc (self 2) dy))
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:
(:area myrect) → 200 ; same as (: area myrect) (:area mycircle) → 314.1592654 ; same as (: area mycircle) ;; map class methods uses curry to enclose the colon operator and class function (map (curry :area) (list myrect mycircle)) → (200 314.1592654) (map (curry :area) '((Rectangle 5 5 10 20) (Circle 1 2 10))) → (200 314.1592654) ;; objects are mutable (since v10.1.8) (:move myrect 2 3) (:move mycircle 4 5) myrect → (Rectangle 7 8 10 20) mycircle → (Circle 5 7 10)
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.
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:
; file MAIN.lsp - declare all classes used in MAIN (new Class 'Rectangle) (new Class 'Circle) ; start up code (load "Rectangle.lsp") (load "Circle.lsp") ; main control code ; end of file
Each class is in a separate file:
; file Rectangle.lsp - class methods for rectangles (context Rectangle) (define (Rectangle:area) (mul (self 3) (self 4))) (define (Rectangle:move dx dy) (inc (self 1) dx) (inc (self 2) dy)) ; end of file
And the Circle class file follows:
; file Circle.lsp - class methods for circles
(context Circle)
(define (Circle:area)
(mul (pow (self 3) 2) (acos 0) 2))
(define (Circle:move dx dy)
(inc (self 1) dx)
(inc (self 2) dy))
; end of file
All sets of class functions are now lexically separated from each other.
newLISP has high-level APIs to control multiple processes on the same CPU or distributed onto different computer nodes on a TCP/IP network.
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.
Internally, newLISP uses the lower level fork, wait-pid, destroy, and share functionalities to control processes and synchronize the passing of computed results via a shared memory interface.
Only on macOS and other Unixes will the Cilk API parallelize tasks. On MS Windows, the API is not available.
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.
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.
XML supportnewLISP's built-in support for XML-encoded data or documents comprises three functions: xml-parse, xml-type-tags, and xml-error.
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.
XML source:<?xml version="1.0"?> <DATABASE name="example.xml"> <!--This is a database of fruits--> <FRUIT> <NAME>apple</NAME> <COLOR>red</COLOR> <PRICE>0.80</PRICE> </FRUIT> </DATABASE>
(xml-parse (read-file "example.xml"))
→ (("ELEMENT" "DATABASE" (("name" "example.xml")) (("TEXT" "\r\n")
("COMMENT" "This is a database of fruits")
("TEXT" "\r\n ")
("ELEMENT" "FRUIT" () (
("TEXT" "\r\n\t ")
("ELEMENT" "NAME" () (("TEXT" "apple")))
("TEXT" "\r\n\t\t")
("ELEMENT" "COLOR" () (("TEXT" "red")))
("TEXT" "\r\n\t\t")
("ELEMENT" "PRICE" () (("TEXT" "0.80")))
("TEXT" "\r\n\t")))
("TEXT" "\r\n"))))
S-XML can be generated directly from XML using xml-type-tags and the special option parameters of the xml-parse function:
(xml-type-tags nil nil nil nil)
(xml-parse (read-file "example.xml") (+ 1 2 4 8 16))
→ ((DATABASE (@ (name "example.xml"))
(FRUIT (NAME "apple")
(COLOR "red")
(PRICE "0.80"))))
S-XML is XML reformatted as newLISP S-expressions. The @ (at symbol) denotes an XML attribute specification.
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.
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.
For more information about XML, visit www.xmlrpc.com.
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.
(load "xmlrpc-client.lsp") ; load XML-RPC client routines
(XMLRPC:newLISP.evalString
"http://localhost:8080/xmlrpc.cgi"
"(+ 3 4)") → "7"
In a similar fashion, standard system.xxx calls can be issued.
All functions return either a result if successful, or nil if a request fails. In case of failure, the expression (XMLRPC:error) can be evaluated to return an error message.
For more information, please consult the header of the file modules/xmlrpc-client.lsp.
All built-in primitives in newLISP can be easily renamed:
(constant 'plus +)
Now, plus is functionally equivalent to + and runs at the same speed.
The constant function, rather than the set function, must be used to rename built-in primitive symbols. By default, all built-in function symbols are protected against accidental overwriting.
It is possible to redefine all integer arithmetic operators to their floating point equivalents:
(constant '+ add) (constant '- sub) (constant '* mul) (constant '/ div)
All operations using +, -, *, and / are now performed as floating point operations.
Using the same mechanism, the names of built-in functions can be translated into languages other than English:
(constant 'wurzel sqrt) ; German for 'square-root' ; make the new symbol global at the same time (constant (global 'imprime) print) ; Spanish for 'print' …
The new symbol can be made global at the same time using global.
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.
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.
The following countries use a period as a decimal separator:
Australia, Botswana, Canada (English-speaking), China, Costa Rica, Dominican Republic, El Salvador, Guatemala, Honduras, Hong Kong, India, Ireland, Israel, Japan, Korea (both North and South), Malaysia, Mexico, Nicaragua, New Zealand, Panama, Philippines, Puerto Rico, Saudi Arabia, Singapore, Switzerland, Thailand, United Kingdom, and United States.
The following countries use a comma as a decimal separator:
Albania, Andorra, Argentina, Austria, Belarus, Belgium, Bolivia, Brazil, Bulgaria, Canada (French-speaking), Croatia, Cuba, Chile, Colombia, Czech Republic, Denmark, Ecuador, Estonia, Faroes, Finland, France, Germany, Greece, Greenland, Hungary, Indonesia, Iceland, Italy, Latvia, Lithuania, Luxembourg, Macedonia, Moldova, Netherlands, Norway, Paraguay, Peru, Poland, Portugal, Romania, Russia, Serbia, Slovakia, Slovenia, Spain, South Africa, Sweden, Ukraine, Uruguay, Venezuela, and Zimbabwe.
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:
(println (char 937)) ; displays Greek uppercase omega (println (lower-case (char 937))) ; displays lowercase omega
While the uppercase omega (Ω) looks like a big O on two tiny legs, the lowercase omega (ω) has a shape similar to a small w in the Latin alphabet.
Note: Only the output of println will be displayed as a character; println's return value will appear on the console as a multi-byte ASCII character.
When UTF-8–enabled newLISP is used on a non-UTF-8–enabled display, both the output and the return value will be two characters. These are the two bytes necessary to encode the omega character.
When UTF-8–enabled newLISP is used, the following string functions work on one- or multi-byte characters rather than one 8-bit byte boundaries:
| function | description |
|---|---|
| char | translates between characters and ASCII/Unicode |
| chop | chops characters from the end of a string |
| date | converts date number to string (when used with the third argument) |
| dostring | evaluates once for each character in a string |
| explode | transforms a string into a list of characters |
| first | gets first element in a list (car, head) or string |
| last | returns the last element of a list or string |
| lower-case | converts a string to lowercase characters |
| nth | gets the nth element of a list or string |
| pop | deletes an element from a list or string |
| push | inserts a new element in a list or string |
| rest | gets all but the first element of a list (cdr, tail) or string |
| select | selects and permutes elements from a list or string |
| title-case | converts the first character of a string to uppercase |
| trim | trims a string from both sides |
| upper-case | converts a string to uppercase characters |
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.
| function | description |
|---|---|
| unicode | converts UTF-8 or ASCII strings into USC-4 Unicode |
| utf8 | converts UCS-4 Unicode strings to UTF-8 |
| utf8len | returns the number of UTF-8 characters in a string |
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.
For further details on UTF-8 and Unicode, consult UTF-8 and Unicode FAQ for Unix/Linux by Markus Kuhn.
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.
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.
The following rules apply to the naming of symbols used as variables or functions:
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:
(set (sym "(#:L*") 456) → 456 ; the symbol '(#:L*' (eval (sym "(#:L*")) → 456 (set (sym 1) 123) → 123 (eval (sym 1)) → 123 1 → 1 (+ 1 2) → 3
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.
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.
123456789012345678901234567890 ; will automatically be converted to big int -123L ; appended L forces conversion 0L
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
To describe the types and names of a function's parameters, the following naming convention is used throughout the reference section:
syntax: (format str-format exp-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.
An array (constructed with the array function).
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
true, nil, or an expression evaluating to one of these two.
true, nil, (<= X 10)
An expression evaluating to a context (namespace) or a variable symbol holding a context.
MyContext, aCtx, TheCTX
Any data type described in this chapter.
A symbol or an expression evaluating to an operator symbol or lambda expression.
+, add, (first '(add sub)), (lambda (x) (+ x x))
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)
A list of elements (any type) or an expression evaluating to a list.
(a b c "hello" (+ 3 4))
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)
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.
((1 2 3 4) (5 6 7 8) (9 10 11 12)) ; 3 rows 4 columns ((1 2) (3 4) (5 6)) ; 3 rows 2 columns
A place referenced by a symbol or a place defined in a list, array or string by indexing with nth or implicit indexing or a place referenced by functions like first, last, assoc or lookup.
A string or an expression that evaluates to a string.
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.
(print "<A href=\"http://mysite.com\">" ) ; the cryptic way
(print {<A href="http://mysite.com">} ) ; the readable way
; path names on MS Windows
(set 'path "C:\\MyDir\\example.lsp")
; no escaping when using braces
(set 'path {C:\MyDir\example.lsp})
; on MS Windows the forward slash can be used in path names
(set 'path "C:/MyDir/example.lsp")
; inner braces are balanced
(regex {abc{1,2}} line)
(print [text]
this could be
a very long (> 2048 characters) text,
i.e. HTML.
[/text])
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.
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.
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.
Some functions appear in more than one group.
| +, -, *, /, % | integer arithmetic |
| ++ | increment integer numbers |
| -- | decrement integer numbers |
| <, >, = | compares any data type: less, greater, equal |
| <=, >=, != | compares any data type: less-equal, greater-equal, not-equal |
| : | constructs a context symbol and applies it to an object |
| and | logical and |
| append | appends lists ,arrays or strings to form a new list, array or string |
| apply | applies a function or primitive to a list of arguments |
| args | retrieves the argument list of a function or macro expression |
| assoc | searches for keyword associations in a list |
| begin | begins a block of functions |
| bigint | convert a number to big integer format |
| bind | binds variable associations in a list |
| case | branches depending on contents of control variable |
| catch | evaluates an expression, possibly catching errors |
| chop | chops elements from the end of a list |
| clean | cleans elements from a list |
| collect | repeat evaluating an expression and collect results in a list |
| cond | branches conditionally to expressions |
| cons | prepends an element to a list, making a new list |
| constant | defines a constant symbol |
| count | counts elements of one list that occur in another list |
| curry | transforms a function f(x, y) into a function fx(y) |
| define | defines a new function or lambda expression |
| define-macro | defines a macro or lambda-macro expression |
| def-new | copies a symbol to a different context (namespace) |
| difference | returns the difference between two lists |
| doargs | iterates through the arguments of a function |
| dolist | evaluates once for each element in a list |
| dostring | evaluates once for each character in a string |
| dotimes | evaluates once for each number in a range |
| dotree | iterates through the symbols of a context |
| do-until | repeats evaluation of an expression until the condition is met |
| do-while | repeats evaluation of an expression while the condition is true |
| dup | duplicates a list or string a specified number of times |
| ends-with | checks the end of a string or list against a key of the same type |
| eval | evaluates an expression |
| exists | checks for the existence of a condition in a list |
| expand | replaces a symbol in a nested list |
| explode | explodes a list or string |
| extend | extends a list or string |
| first | gets the first element of a list or string |
| filter | filters a list |
| find | searches for an element in a list or string |
| flat | returns the flattened list |
| fn | defines a new function or lambda expression |
| for | evaluates once for each number in a range |
| for-all | checks if all elements in a list meet a condition |
| if | evaluates an expression conditionally |
| index | filters elements from a list and returns their indices |
| intersect | returns the intersection of two lists |
| lambda | defines a new function or lambda expression |
| last | returns the last element of a list or string |
| length | calculates the length of a list or string |
| let | declares and initializes local variables |
| letex | expands local variables into an expression, then evaluates |
| letn | initializes local variables incrementally, like nested lets |
| list | makes a list |
| local | declares local variables |
| lookup | looks up members in an association list |
| map | maps a function over members of a list, collecting the results |
| match | matches patterns against lists; for matching against strings, see find and regex |
| member | finds a member of a list or string |
| not | logical not |
| nth | gets the nth element of a list or string |
| or | logical or |
| pop | deletes and returns an element from a list or string |
| pop-assoc | removes an association from an association list |
| push | inserts a new element into a list or string |
| quote | quotes an expression |
| ref | returns the position of an element inside a nested list |
| ref-all | returns a list of index vectors of elements inside a nested list |
| rest | returns all but the first element of a list or string |
| replace | replaces elements inside a list or string |
| reverse | reverses a list or string |
| rotate | rotates a list or string |
| select | selects and permutes elements from a list or string |
| self | Accesses the target object inside a FOOP method |
| set | sets the binding or contents of a symbol |
| setf setq | sets contents of a symbol or list, array or string reference |
| set-ref | searches for an element in a nested list and replaces it |
| set-ref-all | searches for an element in a nested list and replaces all instances |
| silent | works like begin but suppresses console output of the return value |
| slice | extracts a sublist or substring |
| sort | sorts the members of a list |
| starts-with | checks the beginning of a string or list against a key of the same type |
| swap | swaps two elements inside a list or string |
| unify | unifies two expressions |
| unique | returns a list without duplicates |
| union | returns a unique list of elements found in two or more lists. |
| unless | evaluates an expression conditionally |
| until | repeats evaluation of an expression until the condition is met |
| when | evaluates a block of statements conditionally |
| while | repeats evaluation of an expression while the condition is true |
| address | gets the memory address of a number or string |
| bigint | convert a number to big integer format |
| bits | translates a number into binary representation |
| char | translates between characters and ASCII codes |
| chop | chops off characters from the end of a string |
| dostring | evaluates once for each character in a string |
| dup | duplicates a list or string a specified number of times |
| ends-with | checks the end of a string or list against a key of the same type |
| encrypt | does a one-time–pad encryption and decryption of a string |
| eval-string | compiles, then evaluates a string |
| explode | transforms a string into a list of characters |
| extend | extends a list or string |
| find | searches for an element in a list or string |
| find-all | returns a list of all pattern matches found in string |
| first | gets the first element in a list or string |
| float | translates a string or integer into a floating point number |
| format | formats numbers and strings as in the C language |
| get-char | gets a character from a memory address |
| get-float | gets a double float from a memory address |
| get-int | gets a 32-bit integer from a memory address |
| get-long | gets a long 64-bit integer from a memory address |
| get-string | gets a string from a memory address |
| int | translates a string or float into an integer |
| join | joins a list of strings |
| last | returns the last element of a list or string |
| lower-case | converts a string to lowercase characters |
| member | finds a list or string member |
| name | returns the name of a symbol or its context as a string |
| nth | gets the nth element in a list or string |
| pack | packs newLISP expressions into a binary structure |
| parse | breaks a string into tokens |
| pop | pops from a string |
| push | pushes onto a string |
| regex | performs a Perl-compatible regular expression search |
| regex-comp | pre-compiles a regular expression pattern |
| replace | replaces elements in a list or string |
| rest | gets all but the first element of a list or string |
| reverse | reverses a list or string |
| rotate | rotates a list or string |
| select | selects and permutes elements from a list or string |
| setf setq | sets contents of a string reference |
| slice | extracts a substring or sublist |
| source | returns the source required to bind a symbol as a string |
| starts-with | checks the start of the string or list against a key string or list |
| string | transforms anything into a string |
| sym | translates a string into a symbol |
| title-case | converts the first character of a string to uppercase |
| trim | trims a string on one or both sides |
| unicode | converts ASCII or UTF-8 to UCS-4 Unicode |
| utf8 | converts UCS-4 Unicode to UTF-8 |
| utf8len | returns length of an UTF-8 string in UTF-8 characters |
| unpack | unpacks a binary structure into newLISP expressions |
| upper-case | converts a string to uppercase characters |
| abs | returns the absolute value of a number |
| acos | calculates the arc-cosine of a number |
| acosh | calculates the inverse hyperbolic cosine of a number |
| add | adds floating point or integer numbers and returns a floating point number |
| array | creates an array |
| array-list | returns a list conversion from an array |
| asin | calculates the arcsine of a number |
| asinh | calculates the inverse hyperbolic sine of a number |
| atan | calculates the arctangent of a number |
| atanh | calculates the inverse hyperbolic tangent of a number |
| atan2 | computes the principal value of the arctangent of Y / X in radians |
| beta | calculates the beta function |
| betai | calculates the incomplete beta function |
| binomial | calculates the binomial function |
| ceil | rounds up to the next integer |
| cos | calculates the cosine of a number |
| cosh | calculates the hyperbolic cosine of a number |
| crc32 | calculates a 32-bit CRC for a data buffer |
| dec | decrements a number in a variable, list or array |
| div | divides floating point or integer numbers |
| erf | calculates the error function of a number |
| exp | calculates the exponential e of a number |
| factor | factors a number into primes |
| fft | performs a fast Fourier transform (FFT) |
| floor | rounds down to the next integer |
| flt | converts a number to a 32-bit integer representing a float |
| gammai | calculates the incomplete Gamma function |
| gammaln | calculates the log Gamma function |
| gcd | calculates the greatest common divisor of a group of integers |
| ifft | performs an inverse fast Fourier transform (IFFT) |
| inc | increments a number in a variable, list or array |
| inf? | checks if a floating point value is infinite |
| log | calculates the natural or other logarithm of a number |
| min | finds the smallest value in a series of values |
| max | finds the largest value in a series of values |
| mod | calculates the modulo of two numbers |
| mul | multiplies floating point or integer numbers |
| NaN? | checks if a float is NaN (not a number) |
| round | rounds a number |
| pow | calculates x to the power of y |
| sequence | generates a list sequence of numbers |
| series | creates a geometric sequence of numbers |
| sgn | calculates the signum function of a number |
| sin | calculates the sine of a number |
| sinh | calculates the hyperbolic sine of a number |
| sqrt | calculates the square root of a number |
| ssq | calculates the sum of squares of a vector |
| sub | subtracts floating point or integer numbers |
| tan | calculates the tangent of a number |
| tanh | calculates the hyperbolic tangent of a number |
| uuid | returns a UUID (Universal Unique IDentifier) |
| det | returns the determinant of a matrix |
| invert | returns the inversion of a matrix |
| mat | performs scalar operations on matrices |
| multiply | multiplies two matrices |
| transpose | returns the transposition of a matrix |
| append | appends arrays |
| array | creates and initializes an array with up to 16 dimensions |
| array-list | converts an array into a list |
| array? | checks if expression is an array |
| det | returns the determinant of a matrix |
| first | returns the first row of an array |
| invert | returns the inversion of a matrix |
| last | returns the last row of an array |
| mat | performs scalar operations on matrices |
| multiply | multiplies two matrices |
| nth | returns an element of an array |
| rest | returns all but the first row of an array |
| setf | sets contents of an array reference |
| slice | returns a slice of an array |
| transpose | transposes a matrix |
| <<, >> | bit shift left, bit shift right |
| & | bitwise and |
| | | bitwise inclusive or |
| ^ | bitwise exclusive or |
| ~ | bitwise not |
| atom? | checks if an expression is an atom |
| array? | checks if an expression is an array |
| bigint? | checks if a number is a big integer |
| context? | checks if an expression is a context |
| directory? | checks if a disk node is a directory |
| empty? | checks if a list or string is empty |
| even? | checks the parity of an integer number |
| file? | checks if a file exists |
| float? | checks if an expression is a float |
| global? | checks if a symbol is global |
| inf? | checks if a floating point value is infinite |
| integer? | checks if an expression is an integer |
| lambda? | checks if an expression is a lambda expression |
| legal? | checks if a string contains a legal symbol |
| list? | checks if an expression is a list |
| macro? | checks if an expression is a lambda-macro expression |
| NaN? | checks if a float is NaN (not a number) |
| nil? | checks if an expression is nil |
| null? | checks if an expression is nil, "", (), 0 or 0.0 |
| number? | checks if an expression is a float or an integer |
| odd? | checks the parity of an integer number |
| protected? | checks if a symbol is protected |
| primitive? | checks if an expression is a primitive |
| quote? | checks if an expression is quoted |
| string? | checks if an expression is a string |
| symbol? | checks if an expression is a symbol |
| true? | checks if an expression is not nil |
| zero? | checks if an expression is 0 or 0.0 |
| date | converts a date-time value to a string |
| date-list | returns a list of year, month, day, hours, minutes, seconds from a time value in seconds |
| date-parse | parses a date string and returns the number of seconds passed since January 1, 1970, (formerly parse-date) |
| date-value | calculates the time in seconds since January 1, 1970 for a date and time |
| now | returns a list of current date-time information |
| time | calculates the time it takes to evaluate an expression in milliseconds |
| time-of-day | calculates the number of milliseconds elapsed since the day started |
| amb | randomly selects an argument and evaluates it |
| bayes-query | calculates Bayesian probabilities for a data set |
| bayes-train | counts items in lists for Bayesian or frequency analysis |
| corr | calculates the product-moment correlation coefficient |
| crit-chi2 | calculates the Chi² statistic for a given probability |
| crit-f | calculates the F statistic for a given probability |
| crit-t | calculates the Student's t statistic for a given probability |
| crit-z | calculates the normal distributed Z for a given probability |
| kmeans-query | calculates distances to cluster centroids or other data points |
| kmeans-train | partitions a data set into clusters |
| normal | makes a list of normal distributed floating point numbers |
| prob-chi2 | calculates the tail probability of a Chi² distribution value |
| prob-f | calculates the tail probability of a F distribution value |
| prob-t | calculates the tail probability of a Student's t distribution value |
| prob-z | calculates the cumulated probability of a Z distribution value |
| rand | generates random numbers in a range |
| random | generates a list of evenly distributed floats |
| randomize | shuffles all of the elements in a list |
| seed | seeds the internal random number generator |
| stats | calculates some basic statistics for a data vector |
| t-test | compares means of data samples using the Student's t statistic |
| ends-with | tests if a list or string ends with a pattern |
| find | searches for a pattern in a list or string |
| find-all | finds all occurrences of a pattern in a string |
| match | matches list patterns |
| parse | breaks a string along around patterns |
| ref | returns the position of an element inside a nested list |
| ref-all | returns a list of index vectors of elements inside a nested list |
| regex | finds patterns in a string |
| replace | replaces patterns in a string |
| search | searches for a pattern in a file |
| starts-with | tests if a list or string starts with a pattern |
| unify | performs a logical unification of patterns |
| fv | returns the future value of an investment |
| irr | calculates the internal rate of return |
| nper | calculates the number of periods for an investment |
| npv | calculates the net present value of an investment |
| pv | calculates the present value of an investment |
| pmt | calculates the payment for a loan |
| append-file | appends data to a file |
| close | closes a file |
| current-line | retrieves contents of last read-line buffer |
| device | sets or inquires about current print device |
| exec | launches another program, then reads from or writes to it |
| load | loads and evaluates a file of newLISP code |
| open | opens a file for reading or writing |
| peek | checks file descriptor for number of bytes ready for reading |
| prints to the console or a device | |
| println | prints to the console or a device with a line-feed |
| read | reads binary data from a file |
| read-char | reads an 8-bit character from a file |
| read-file | reads a whole file in one operation |
| read-key | reads a keyboard key |
| read-line | reads a line from the console or file |
| read-utf8 | reads UTF-8 character from a file |
| save | saves a workspace, context, or symbol to a file |
| search | searches a file for a string |
| seek | sets or reads a file position |
| write | writes binary data to a file or string |
| write-char | writes a character to a file |
| write-file | writes a file in one operation |
| write-line | writes a line to the console or a file |
| ! | shells out to the operating system |
| abort | aborts a child process started with spawn |
| destroy | destroys a process created with fork or process |
| exec | runs a process, then reads from or writes to it |
| fork | launches a newLISP child process |
| pipe | creates a pipe for interprocess communication |
| process | launches a child process, remapping standard I/O and standard error |
| receive | receive a message from another process |
| semaphore | creates and controls semaphores |
| send | send a message to another process |
| share | shares memory with other processes |
| spawn | launches a child process for Cilk process management |
| sync | waits for child processes launched with spawn and collects results |
| wait-pid | waits for a child process to end |
| change-dir | changes to a different drive and directory |
| copy-file | copies a file |
| delete-file | deletes a file |
| directory | returns a list of directory entries |
| file-info | gets file size, date, time, and attributes |
| make-dir | makes a new directory |
| real-path | returns the full path of the relative file path |
| remove-dir | removes an empty directory |
| rename-file | renames a file or directory |
| base64-enc | encodes a string into BASE64 format |
| base64-dec | decodes a string from BASE64 format |
| delete-url | deletes a file or page from the web |
| get-url | reads a file or page from the web |
| json-error | returns error information from a failed JSON translation. |
| json-parse | parses JSON formatted data |
| post-url | posts info to a URL address |
| put-url | uploads a page to a URL address |
| xfer-event | registers an event handler for HTTP byte transfers |
| xml-error | returns last XML parse error |
| xml-parse | parses an XML document |
| xml-type-tags | shows or modifies XML type tags |
| net-accept | accepts a new incoming connection |
| net-close | closes a socket connection |
| net-connect | connects to a remote host |
| net-error | returns the last error |
| net-eval | evaluates expressions on multiple remote newLISP servers |
| net-interface | Sets the default interface IP address on multihomed computers. |
| net-ipv | Switches between IPv4 and IPv6 internet protocol versions. |
| net-listen | listens for connections to a local socket |
| net-local | returns the local IP and port number for a connection |
| net-lookup | returns the name for an IP number |
| net-packet | send a custom configured IP packet over raw sockets |
| net-peek | returns the number of characters ready to be read from a network socket |
| net-peer | returns the remote IP and port for a net connect |
| net-ping | sends a ping packet (ICMP echo request) to one or more addresses |
| net-receive | reads data on a socket connection |
| net-receive-from | reads a UDP on an open connection |
| net-receive-udp | reads a UDP and closes the connection |
| net-select | checks a socket or list of sockets for status |
| net-send | sends data on a socket connection |
| net-send-to | sends a UDP on an open connection |
| net-send-udp | sends a UDP and closes the connection |
| net-service | translates a service name into a port number |
| net-sessions | returns a list of currently open connections |
| display-html | display an HTML page in a web browser |
| eval-string-js | evaluate JavaScript in the current web browser page |
| command-event | pre-processes the command-line and HTTP requests |
| error-event | defines an error handler |
| history | returns the call history of a function |
| last-error | report the last error number and text |
| macro | create a reader expansion macro |
| ostype | contains a string describing the OS platform |
| prefix | Returns the context prefix of a symbol |
| prompt-event | customizes the interactive newLISP shell prompt |
| read-expr | reads and translates s-expressions from source |
| reader-event | preprocess expressions before evaluation event-driven |
| set-locale | switches to a different locale |
| source | returns the source required to bind a symbol to a string |
| sys-error | reports OS system error numbers |
| sys-info | gives information about system resources |
| term | returns the term part of a symbol or its context as a string |
| $ | accesses system variables $0 -> $15 |
| callback | registers a callback function for an imported library |
| catch | evaluates an expression, catching errors and early returns |
| context | creates or switches to a different namespace |
| copy | copies the result of an evaluation |
| debug | debugs a user-defined function |
| delete | deletes symbols from the symbol table |
| default | returns the contents of a default functor from a context |
| env | gets or sets the operating system's environment |
| exit | exits newLISP, setting the exit value |
| global | makes a symbol accessible outside MAIN |
| import | imports a function from a shared library |
| main-args | gets command-line arguments |
| new | creates a copy of a context |
| pretty-print | changes the pretty-printing characteristics |
| read-expr | translates a string to an s-expression without evaluating it |
| reset | goes to the top level |
| signal | sets a signal handler |
| sleep | suspends processing for specified milliseconds |
| sym | creates a symbol from a string |
| symbols | returns a list of all symbols in the system |
| throw | causes a previous catch to return |
| throw-error | throws a user-defined error |
| timer | starts a one-shot timer, firing an event |
| trace | sets or inquires about trace mode |
| trace-highlight | sets highlighting strings in trace mode |
| address | returns the memory address of a number or string |
| callback | registers a callback function for an imported library |
| flt | converts a number to a 32-bit integer representing a float |
| float | translates a string or integer into a floating point number |
| get-char | gets a character from a memory address |
| get-float | gets a double float from a memory address |
| get-int | gets a 32-bit integer from a memory address |
| get-long | gets a long 64-bit integer from a memory address |
| get-string | gets a string from a memory address |
| import | imports a function from a shared library |
| int | translates a string or float into an integer |
| pack | packs newLISP expressions into a binary structure |
| struct | Defines a data structure with C types |
| unpack | unpacks a binary structure into newLISP expressions |
| command-event | pre-processes the command-line and HTTP requests |
| cpymem | copies memory between addresses |
| dump | shows memory address and contents of newLISP cells |
| prompt-event | customizes the interactive newLISP shell prompt |
| read-expr | reads and translates s-expressions from source |
| reader-event | preprocess expressions before evaluation event-driven |
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.
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).
(set 'str "http://newlisp.org:80") (find "http://(.*):(.*)" str 0) → 0 $0 → "http://newlisp.org:80" $1 → "newlisp.org" $2 → "80" ($ 0) → "http://newlisp.org:80" ($ 1) → "newlisp.org" ($ 2) → "80"
Returns the sum of all numbers in int-1 —.
Subtracts int-2 from int-1, then the next int-i from the previous result. If only one argument is given, its sign is reversed.
The product is calculated for int-1 to int-i.
Each result is divided successively until the end of the list is reached. Division by zero causes an error.
Each result is divided successively by the next int, then the rest (modulo operation) is returned. Division by zero causes an error. For floating point numbers, use the mod function.
(+ 1 2 3 4 5) → 15 (+ 1 2 (- 5 2) 8) → 14 (- 10 3 2 1) → 4 (- (* 3 4) 6 1 2) → 3 (- 123) → -123 (map - '(10 20 30)) → (-10 -20 -30) (* 1 2 3) → 6 (* 10 (- 8 2)) → 60 (/ 12 3) → 4 (/ 120 3 20 2) → 1 (% 10 3) → 1 (% -10 3) → -1 (+ 1.2 3.9) → 4
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).
The ++ operator works like inc, but performs integer arithmetic. Without the optional argument in num, ++ increments the number in place by 1.
If floating point numbers are passed as arguments, their fractional part gets truncated first.
Calculations resulting in numbers greater than 9,223,372,036,854,775,807 wrap around to negative numbers. Results smaller than -9,223,372,036,854,775,808 wrap around to positive numbers.
place is either a symbol or a place in a list structure holding a number, or a number returned by an expression.
(set 'x 1) (++ x) → 2 (set 'x 3.8) (++ x) → 4 (++ x 1.3) → 5 (set 'lst '(1 2 3)) (++ (lst 1) 2)) → 4 lst → (1 4 3)
If the symbol for place contains nil, it is treated as if containing 0.
See -- for decrementing numbers in integer mode. See inc for incrementing numbers in floating point mode.
The -- operator works like dec, but performs integer arithmetic. Without the optional argument in num-2, -- decrements the number in place by 1.
If floating point numbers are passed as arguments, their fractional part gets truncated first.
Calculations resulting in numbers greater than 9,223,372,036,854,775,807 wrap around to negative numbers. Results smaller than -9,223,372,036,854,775,808 wrap around to positive numbers.
place is either a symbol or a place in a list structure holding a number, or a number returned by an expression.
(set 'x 1) (-- x) → 0 (set 'x 3.8) (-- x) → 2 (-- x 1.3) → 1 (set 'lst '(1 2 3)) (-- (lst 1) 2)) → 0 lst → (1 0 3)
If the symbol for place contains nil, it is treated as if containing 0.
See ++ for incrementing numbers in integer mode. See dec for decrementing numbers in floating point mode.
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.
Atoms: nil, true, integer or float, string, symbol, primitive
Lists: quoted list/expression, list/expression, lambda, lambda-macro
(< 3 5 8 9) → true (> 4 2 3 6) → nil (< "a" "c" "d") → true (>= duba aba) → true (< '(3 4) '(1 5)) → nil (> '(1 2 3) '(1 2)) → true (= '(5 7 8) '(5 7 8)) → true (!= 1 4 3 7 3) → true (< 1.2 6 "Hello" 'any '(1 2 3)) → true (< nil true) → true (< '(((a b))) '(((b c)))) → true (< '((a (b c)) '(a (b d)) '(a (b (d))))) → true ; with single argument compares against 0 (> 1) → true ; checks for positive (> -1) → nil ; checks for negative (= 123) → nil ; checks for zero (map > '(1 3 -4 -3 1 2)) → (true true nil nil true true)
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):
(>> 0x8000000000000000 1) → 0xC000000000000000 ; not 0x0400000000000000!
(<< 1 3) → 8 (<< 1 2 1) → 8 (>> 1024 10) → 1 (>> 160 2 2) → 10 (<< 3) → 6 (>> 8) → 4
When int-1 is the only argument << and >> shift by one bit.
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
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
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
A bitwise not operation is performed on the number in int, reversing all of the bits.
(format "%X" (~ 0xFFFFFFAA)) → "55" (~ 0xFFFFFFFF) → 0
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.
(define (Rectangle:area)
(mul (self 3) (self 4)))
(define (Circle:area)
(mul (pow (self 3) 2) (acos 0) 2))
(define (Rectangle:move dx dy)
(inc (self 1) dx)
(inc (self 2) dy))
(define (Circle:move p dx dy)
(inc (self 1) dx) (inc (self 2) dy))
(set 'myrect '(Rectangle 5 5 10 20)) ; x y width height
(set 'mycircle '(Circle 1 2 10)) ; x y radius
;; using the : (colon) operator to resolve to a specific context
(:area myrect) → 200
(:area mycircle) → 314.1592654
;; map class methods uses curry to enclose the colon operator and class function
(map (curry :area) (list myrect mycircle)) → (200 314.1592654)
(map (curry :area) '((Rectangle 5 5 10 20) (Circle 1 2 10))) → (200 314.1592654)
;; change object attributes using a function and re-assigning
;; to the objects name
(:move myrect 2 3)
myrect → (Rectangle 7 8 10 20)
(:move mycircle 4 5)
mycircle → (Circle 5 7 10)
Inside the FOOP methods the self function is used to access the target object of the method.
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.
Returns the absolute value of the number in num.
(abs -3.5) → 3.5
The arc-cosine function is calculated from the number in num-radians.
(acos 1) → 0 (cos (acos 1)) → 1
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
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
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.
(set 's "\001\002\003\004") (get-char (+ (address s) 3)) → 4 (set 'x 12345) ; x is a 64-bit long int ; on a big-endian CPU, i.e. PPC or SPARC (get-long (address x)) → 12345 ; the 32-bit int is in high 32-bit part of the long int (get-int (+ (address x) 4)) → 12345 ; on a little-endian CPU, i.e. Intel i386 ; the 32-bit int is in the low 32-bit part of the long int (get-int (address x)) → 12345 ; on both architectures (integers are 64 bit in newLISP) (set 'x 1234567890) (get-long (address x)) → 1234567890
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.
See also the get-char, get-int, get-long and get-float functions.
One of the expressions exp-1 ... n is selected at random, and the evaluation result is returned.
(amb 'a 'b 'c 'd 'e) → one of: a, b, c, d, or e at random (dotimes (x 10) (print (amb 3 5 7))) → 35777535755
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.
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.
(set 'x 10) → 10 (and (< x 100) (> x 2)) → true (and (< x 100) (> x 2) "passed") → "passed" (and '()) → () (and true) → true (and) → true
In the first form, append works with lists, appending list-1 through list-n to form a new list. The original lists are left unchanged.
(append '(1 2 3) '(4 5 6) '(a b)) → (1 2 3 4 5 6 a b) (set 'aList '("hello" "world")) → ("hello" "world") (append aList '("here" "I am")) → ("hello" "world" "here" "I am")
In the second form append works on arrays:
(set 'A (array 3 2 (sequence 1 6))) → ((1 2) (3 4) (5 6)) (set 'B (array 2 2 (sequence 7 10))) → ((7 8) (9 10)) (append A B) → ((1 2) (3 4) (5 6) (7 8) (9 10)) (append B B B) → ((7 8) (9 10) (7 8) (9 10) (7 8) (9 10))
In the third form, append works on strings. The strings in str-n are concatenated into a new string and returned.
(set 'more " how are you") → " how are you" (append "Hello " "world," more) → "Hello world, how are you"
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.
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.
(write-file "myfile.txt" "ABC")
(append-file "myfile.txt" "DEF")
(read-file "myfile.txt") → "ABCDEF"
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.
See also read-file and write-file.
Applies the contents of func (primitive, user-defined function, or lambda expression) to the arguments in list. Only functions and operators with standard evaluation of their arguments can be applied.
In the second syntax apply is used on functions without any arguments.
(apply + '(1 2 3 4)) → 10 (set 'aList '(3 4 5)) → (3 4 5) (apply * aList) → 60 (apply sqrt '(25)) → 5 (apply (lambda (x y) (* x y)) '(3 4)) → 12
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:
(apply op '(1 2 3 4 5) 2)
;; is equivalent to
(op (op (op (op 1 2) 3) 4) 5)
;; find the greatest common divisor
;; of two or more integers
;; note that newLISP already has a gcd function
(define (gcd_ a b)
(let (r (% b a))
(if (= r 0) a (gcd_ r a))))
(define-macro (my-gcd)
(apply gcd_ (map eval (args)) 2))
(my-gcd 12 18 6) → 6
(my-gcd 12 18 6 4) → 2
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.
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.
(define-macro (print-line)
(dolist (x (args))
(print x "\n")))
(print-line "hello" "World")
This example prints a line-feed after each argument. The macro mimics the effect of the built-in function println.
In the second syntax, args can take one or more indices (int-idx-n).
(define-macro (foo)
(print (args 2) (args 1) (args 0)))
(foo x y z)
zyx
(define (bar)
(args 0 2 -1))
(bar '(1 2 (3 4))) → 4
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.
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.
(array 5) → (nil nil nil nil nil) (array 5 (sequence 1 5)) → (1 2 3 4 5) (array 10 '(1 2)) → (1 2 1 2 1 2 1 2 1 2)
Arrays can be initialized with objects of any type. If fewer initializers than elements are provided, the list is repeated until all elements of the array are initialized.
(set 'myarray (array 3 4 (sequence 1 12)))
→ ((1 2 3 4) (5 6 7 8) (9 10 11 12))
Arrays are modified and accessed using most of the same functions used for modifying lists:
(setf (myarray 2 3) 99) → 99) myarray → ((1 2 3 4) (5 6 7 8) (9 10 11 99)) (setf (myarray 1 1) "hello") → "hello" myarray → ((1 2 3 4) (5 "hello" 7 8) (9 10 11 99)) (setf (myarray 1) '(a b c d)) → (a b c d) myarray → ((1 2 3 4) (a b c d) (9 10 11 99)) (nth 1 myarray) → (a b c d) ; access a whole row ;; use implicit indexing and slicing on arrays (myarray 1) → (a b c d) (myarray 0 -1) → 4 (2 myarray) → ((9 10 11 99)) (-3 2 myarray) → ((1 2 3 4) (a b c d))
Care must be taken to use an array when replacing a whole row.
array-list can be used to convert arrays back into lists:
(array-list myarray) → ((1 2 3 4) (a b c d) (1 2 3 99))
To convert a list back into an array, apply flat to the list:
(set 'aList '((1 2) (3 4))) → ((1 2) (3 4)) (set 'aArray (array 2 2 (flat aList))) → ((1 2) (3 4))
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.
(set 'myarray (array 3 4 (sequence 1 12))) (save "array.lsp" 'myarray) ;; contents of file arraylsp ;; (set 'myarray (array 3 4 (flat '( (1 2 3 4) (5 6 7 8) (9 10 11 12)))))
Returns a list conversion from array, leaving the original array unchanged:
(set 'myarray (array 3 4 (sequence 1 12))) → ((1 2 3 4) (5 6 7 8) (9 10 11 12)) (set 'mylist (array-list myarray)) → ((1 2 3 4) (5 6 7 8) (9 10 11 12)) (list (array? myarray) (list? mylist)) → (true true)
Checks if exp is an array:
(set 'M (array 3 4 (sequence 1 4))) → ((1 2 3 4) (1 2 3 4) (1 2 3 4))) (array? M) → true (array? (array-list M)) → nil
Calculates the arcsine function from the number in num-radians and returns the result.
(asin 1) → 1.570796327 (sin (asin 1)) → 1
Calculates the inverse hyperbolic sine of num-radians, the value whose hyperbolic sine is num-radians.
(asinh 2) → 1.443635475 (sinh (asinh 2)) → 2
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.
(assoc 1 '((3 4) (1 2))) → (1 2) (set 'data '((apples 123) (bananas 123 45) (pears 7))) (assoc 'bananas data) → (bananas 123 45) (assoc 'oranges data) → nil
Together with setf assoc can be used to change an association.
(setf (assoc 'pears data) '(pears 8))
data → ((apples 123) (bananas 123 45) (pears 8))
In the second syntax more then one key expressions can be specified to search in nested, multilevel association lists:
(set 'persons '(
(id001 (name "Anne") (address (country "USA") (city "New York")))
(id002 (name "Jean") (address (country "France") (city "Paris")))
))
(assoc '(id001 address) persons) → (address (country "USA") (city "New York"))
(assoc '(id001 address city) persons) → (city "New York")
The list in list-aList can be a context which will be interpreted as its default functor. This way very big lists can be passed by reference for speedier access and less memory usage:
(set 'persons:persons '(
(id001 (name "Anne") (address (country "USA") (city "New York")))
(id002 (name "Jean") (address (country "France") (city "Paris")))
))
(define (get-city db id)
(last (assoc (list id 'address 'city) db ))
)
(get-city persons 'id001) → "New York"
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.
The arctangent of num-radians is calculated and returned.
(atan 1) → 0.7853981634 (tan (atan 1)) → 1
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.
(atan2 1 1) → 0.7853981634 (div (acos 0) (atan2 1 1)) → 2 (atan2 0 -1) → 3.141592654 (= (atan2 1 2) (atan (div 1 2))) → true
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.
(atanh 0.5) → 0.5493061443 (tanh (atanh 0.5)) → 0.5 (atanh 1.1) → NaN (atanh 1) → inf
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.
(atom? '(1 2 3)) → nil (and (atom? 123) (atom? "hello") (atom? 'foo)) → true (atom? ''foo) → nil
The BASE64 string in str is decoded. Note that str is not verified to be a valid BASE64 string. The decoded string is returned.
(base64-dec "SGVsbG8gV29ybGQ=") → "Hello World"
For encoding, use the base64-enc function.
newLISP's BASE64 handling is derived from routines found in the Unix curl utility and conforms to the RFC 4648 standard.
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).
(base64-enc "Hello World") → "SGVsbG8gV29ybGQ=" (base64-enc "") → "====" (base64-enc "" true) → ""
Note that base64-enc does not insert carriage-return/line-feed pairs in longer BASE64 sequences but instead returns a pure BASE64-encoded string.
For decoding, use the base64-dec function.
newLISP's BASE64 handling is derived from routines found in the Unix curl utility and conforms to the RFC 4648 standard.
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.
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.
;; from Project Gutenberg: http://www.gutenberg.org/catalog/
;; The Adventures of Sherlock Holmes - Sir Arthur Conan Doyle
(bayes-train (parse (lower-case (read-file "Doyle.txt"))
"[^a-z]+" 0) '() 'DoyleDowson)
;; A Comedy of Masks - Ernest Dowson and Arthur Moore
(bayes-train '() (parse (lower-case (read-file "Dowson.txt"))
"[^a-z]+" 0) 'DoyleDowson)
(save "DoyleDowson.lsp" 'DoyleDowson)
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:
(load "DoyleDowson.lsp")
(bayes-query (parse "he was putting the last touches to a picture")
'DoyleDowson)
→ (0.0359554723158327 0.964044527684167)
(bayes-query (parse "immense faculties and extraordinary powers of observation")
'DoyleDowson)
→ (0.983569359827141 0.0164306401728594)
The queries correctly identify the first sentence as a Dowson sentence, and the second one as a Doyle sentence.
The second example is frequently found in introductory literature on Bayesian statistics. It shows the Chain Bayesian method of using bayes-query on the data of a previously processed data set:
(set 'Data:test-positive '(8 18)) (set 'Data:test-negative '(2 72)) (set 'Data:total '(10 90))
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?
(bayes-query '(test-positive) Data true) → (0.3076923077 0.6923076923) (bayes-query '(test-positive test-positive) Data true) → (0.64 0.36) (bayes-query '(test-positive test-positive test-positive) Data true) → (0.8767123288 0.1232876712)
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.
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:
(set 'Data:test-positive '(0.8 0.2)) (set 'Data:test-negative '(0.2 0.8)) (set 'Data:total '(0.1 0.9)) (bayes-query '(test-positive) Data true true) → (0.3076923077 0.6923076923) (bayes-query '(test-positive test-positive) Data true true) → (0.64 0.36) (bayes-query '(test-positive test-positive test-positive) Data true true) → (0.8767123288 0.1232876712)
As expected, the results are the same for probabilities as they are for frequencies.
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.
(bayes-train '(A A B C C) '(A B B C C C) 'L) → (5 6) L:A → (2 1) L:B → (1 2) L:C → (2 3) L:total → (5 6) (bayes-train '("one" "two" "two" "three") '("three" "one" "three") '("one" "two" "three") 'S) → (4 3 3) S:_one → (1 1 1) S:_two → (2 0 1) S:_three → (1 2 1) S:total → (4 3 3)
The first example shows training with two lists of symbols. The second example illustrates how an _ is prepended when training with strings.
bayes-train creates symbols from strings prepending an underscore character. This is the same way hashes are created and contexts populates with symbols by bayes-train can be used like hashes:
; use a bayes-trained context namespace like a hash dictionary (S "two") → (2 0 1) (S "three") → (1 2 1) (S) → (("one" (1 1 1)) ("three" (1 2 1)) ("two" (2 0 1)))
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:
(set 'Data:tested-positive '(8 18)) (set 'Data:tested-negative '(2 72)) (set 'Data:total '(10 90))
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:
(bayes-train shakespeare1 '() 'data) (bayes-train shakespeare2 '() 'data) (bayes-train '() hemingway1 'data) (bayes-train '() hemingway2 'data) (bayes-train shakepeare-rest hemingway-rest 'data)
bayes-train will correctly update word counts and totals.
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.
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.
(begin (print "This is a block of 2 expressions\n") (print "================================"))
Some built-in functions like cond, define, doargs, dolist, dostring, dotimes, when and while already allow multiple expressions in their bodies, but begin is often used in an if expression.
The silent function works like begin, but suppresses console output on return.
The Beta function, beta, is derived from the log Gamma gammaln function as follows:
beta = exp(gammaln(a) + gammaln(b) - gammaln(a + b))
(beta 1 2) → 0.5
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.
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.
(bigint 12345) → 12345L (bigint 1.234567890e30) → 1234567889999999957361000000000L (set 'num 567890) (bigint num) → 567890L (bigint "-54321") → -54321L (bigint "123.45") → 123L (bigint "123hello") → 123L
See also the manual chapter Big integer, unlimited precision arithmetic
Check if a number is formatted as a big integer.
(set 'x 12345) (set 'y 12345L) (set 'z 123456789012345678901234567890) (set 'p 1.2345e20) (set 'q (bigint p)) (bigint? x) → nil (bigint? y) → true (bigint? z) → true (bigint? p) → nil (bigint? q) → true
See also the manual chapter Big integer, unlimited precision arithmetic
list-variable-associations contains an association list of symbols and their values. bind sets all symbols to their associated values.
The associated values are evaluated if the bool-eval flag is true:
(set 'lst '((a (+ 3 4)) (b "hello"))) (bind lst) → "hello" a → (+ 3 4) b → "hello" (bind lst true) → "hello" a → 7
The return value of bind is the value of the last association.
bind is often used to bind association lists returned by unify.
(bind (unify '(p X Y a) '(p Y X X))) → a X → a Y → a
This can be used for de-structuring:
(set 'structure '((one "two") 3 (four (x y z)))) (set 'pattern '((A B) C (D E))) (bind (unify pattern structure)) A → one B → "two" C → 3 D → four E → (x y z)
unify returns an association list and bind binds the associations.
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.
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.
(bits 1234) → "10011010010" (int (bits 1234) 0 2) → 1234 (bits 1234 true) → (nil true nil nil true nil true true nil nil true) ((bits 1234 true) 0) → nil ; indexing of the result
int with a base of 2 is the inverse function to bits.
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.
...
(define (draw)
(glClear GL_COLOR_BUFFER_BIT )
(glRotated rotx 0.0 1.0 0.0)
(glRotated roty 1.0 0.0 0.0)
(glutWireTeapot 0.5)
(glutSwapBuffers))
(define (keyboard key x y)
(if (= (& key 0xFF) 27) (exit)) ; exit program with ESC
(println "key:" (& key 0xFF) " x:" x " y:" y))
(define (mouse button state x y)
(if (= state 0)
(glutIdleFunc 0) ; stop rotation on button press
(glutIdleFunc (callback 4 'rotation)))
(println "button: " button " state:" state " x:" x " y:" y))
(glutDisplayFunc (callback 0 'draw))
(glutKeyboardFunc (callback 1 'keyboard))
(glutMouseFunc (callback 2 'mouse))
...
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:
; C void qsort(...) takes an integer array with number and width
; of array elements and a pointer to the comparison function
(import "libc.dylib" "qsort" "void" "void*" "int" "int" "void*")
(set 'rlist '(2 3 1 2 4 4 3 3 0 3))
; pack the list into an C readable 32-bit integer array
(set 'carray (pack (dup "ld " 10) rlist))
; the comparison callback function receives pointers to integers
(define (cmp a b)
(- (get-int a) (get-int b)))
; generate a C callable address for cmp
(set 'func (callback 'cmp "int" "void*" "void*"))
; sort the carray
(qsort carray 10 4 func)
; unpack the sorted array into a LISP list
(unpack (dup "ld" 10) carray) → (0 1 2 2 3 3 3 3 4 4)
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.
Note that newLISP as already a fast built-in sort function.
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.
(define (translate n)
(case n
(1 "one")
(2 "two")
(3 "three")
(4 "four")
(true "Can't translate this")))
(translate 3) → "three"
(translate 10) → "Can't translate this"
The example shows how, if no match is found, the last expression in the body of a case function can be evaluated.
In the first syntax, catch will return the result of the evaluation of exp or the evaluated argument of a throw executed during the evaluation of exp:
(catch (dotimes (x 1000)
(if (= x 500) (throw x)))) → 500
This form is useful for breaking out of iteration loops and for forcing an early return from a function or expression block:
(define (foo x)
…
(if condition (throw 123))
…
456)
;; if condition is true
(catch (foo p)) → 123
;; if condition is not true
(catch (foo p)) → 456
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.
(catch (func 3 4) 'result) → nil result → "ERR: invalid function in function catch : (func 3 4)" (constant 'func +) → + <4068A6> (catch (func 3 4) 'result) → true result → 7
When a throw is executed during the evaluation of exp, catch will return true, and the throw argument will be stored in symbol:
(catch (dotimes (x 100) (if (= x 50) (throw "fin"))) 'result) → true result → "fin"
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.
Returns the next highest integer above number as a floating point.
(ceil -1.5) → -1 (ceil 3.4) → 4
See also the floor function.
Changes the current directory to be the one given in str-path. If successful, true is returned; otherwise nil is returned.
(change-dir "/etc")
Makes /etc the current directory.
Given a string argument, extracts the character at int-index from str, returning either the ASCII value of that character or the Unicode value on UTF-8 enabled versions of newLISP.
If int-index is omitted, 0 (zero) is assumed. If int-idx is followed by a boolean true value, than the index treats str as an 8-bit byte array instead of an array of multi-byte UTF-8 characters.
The empty string returns nil. Both (char 0) and (char nil) will return "\000".
See Indexing elements of strings and lists.
Given an integer argument, char returns a string containing the ASCII character with value int.
On UTF-8–enabled versions of newLISP, the value in int is taken as Unicode and a UTF-8 character is returned.
(char "ABC") → 65 ; ASCII code for "A" (char "ABC" 1) → 66 ; ASCII code for "B" (char "ABC" -1) → 67 ; ASCII code for "C" (char "B") → 66 ; ASCII code for "B" (char "Ω") → 937 ; UTF-8 code for "Ω" (char "Ω" 1 true) → 169 ; byte value at offset 1 (char 65) → "A" (char 66) → "B" (char (char 65)) → 65 ; two inverse applications (map char (sequence 1 255)) ; returns current character set ; The Zen of UTF-8 (char (& (char "生") (char "死"))) → 愛 ; by @kosh_bot
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).
(set 'str "newLISP") → "newLISP" (chop str) → "newLIS" (chop str 2) → "newLI" str → "newLISP" (set 'lst '(a b (c d) e)) (chop lst) → (a b (c d)) (chop lst 2) → (a b) lst → (a b (c d) e)
The predicate exp-predicate is applied to each element of list. In the returned list, all elements for which exp-predicate is true are eliminated.
clean works like filter with a negated predicate.
(clean symbol? '(1 2 d 4 f g 5 h)) → (1 2 4 5) (filter symbol? '(1 2 d 4 f g 5 h)) → (d f g h) (define (big? x) (> x 5)) → (lambda (x) (> x 5)) (clean big? '(1 10 3 6 4 5 11)) → (1 3 4 5) (clean <= '(3 4 -6 0 2 -3 0)) → (3 4 2) (clean (curry match '(a *)) '((a 10) (b 5) (a 3) (c 8) (a 9))) → ((b 5) (c 8))
The predicate may be a built-in predicate or a user-defined function or lambda expression.
For cleaning numbers from one list using numbers from another, use difference or intersect (with the list mode option).
See also the related function index, which returns the indices of the remaining elements, and filter, which returns all elements for which a predicate returns true.
Closes the file specified by the file handle in int-file. The handle would have been obtained from a previous open operation. If successful, close returns true; otherwise nil is returned.
(close (device)) → true (close 7) → true (close aHandle) → true
Note that using close on device automatically resets it to 0 (zero, the screen device).
Evaluates the expression in exp and collects the results in a list until evaluation of exp returns nil.
Optionally a maximum count of elements can be specified in int-max-count.
; collect results until nil is returned (set 'x 0) (collect (if (<= (inc x) 10) x)) → (1 2 3 4 5 6 7 8 9 10) ; collect results until nil is returned or 6 results are collected (set 'x 0) (collect (if (<= (inc x) 10) x) 6) → (1 2 3 4 5 6)
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.
(command-event (fn (s) (if (starts-with s "[a-zA-Z]" 0) (append "!" s) s)))
See also the related prompt-event which can be used for further customizing interactive mode by modifying the newLISP prompt.
The following program can be used either stand-alone or included in newLISP's init.lsp startup file:
#!/usr/local/bin/newlisp
; set the prompt to the current directory name
(prompt-event (fn (ctx) (append (real-path) "> ")))
; pre-process the command-line
(command-event (fn (s)
(if
(starts-with s "cd")
(string " " (true? (change-dir (last (parse s " ")))))
(starts-with s "[a-zA-Z]" 0)
(append "!" s)
true s)))
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:
;; httpd-conf.lsp
;;
;; filter and translate HTTP requests for newLISP
;; -c or -http server modes
;; reject query commands using CGI with .exe files
(command-event (fn (s)
(let (request s)
(when (find "?" s) ; is this a query
(set 'request (first (parse s "?")))
; discover illegal extension in queries
(when (ends-with request ".exe")
(set 'request "GET /errorpage.html")) )
request)
))
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.
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.
(define (classify x)
(cond
((< x 0) "negative")
((< x 10) "small")
((< x 20) "medium")
((>= x 30) "big")))
(classify 15) → "medium"
(classify 22) → "nil"
(classify 100) → "big"
(classify -10) → "negative"
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.
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.
(cons 'a 'b) → (a b) (cons 'a '(b c)) → (a b c) (cons (+ 3 4) (* 5 5)) → (7 25) (cons '(1 2) '(3 4)) → ((1 2) 3 4) (cons nil 1) → (nil 1) (cons 1 nil) → (1 nil) (cons 1) → (1) (cons) → ()
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):
(cons (first '(a b c)) (rest '(a b c))) → (a b c) (cons (first '(x y)) (last '(x y))) → (x y)
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.
Symbols initialized with set, define, or define-macro can still be protected by using the constant function:
(constant 'aVar 123) → 123 (set 'aVar 999) ERR: symbol is protected in function set: aVar (define (double x) (+ x x)) (constant 'double) ;; equivalent to (constant 'double (fn (x) (+ x x)))
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.
(constant 'squareroot sqrt) → sqrt <406C2E> (constant '+ add) → add <4068A6>
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.
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.
(context 'GRAPH) ; create / switch context GRAPH
(define (foo-draw x y z) ; function resides in GRAPH
(…))
(set 'var 12345)
(symbols) → (foo-draw var) ; GRAPH has now two symbols
(context MAIN) ; switch back to MAIN (quote not required)
(print GRAPH:var) → 12345 ; contents of symbol in GRAPH
(GRAPH:foo-draw 10 20 30) ; execute function in GRAPH
(set 'GRAPH:var 6789) ; assign to a symbol in GRAPH
If a context symbol is referred to before the context exists, the context will be created implicitly.
(set 'person:age 0) ; no need to create context first (set 'person:address "") ; useful for quickly defining data structures
Contexts can be copied:
(new person 'JohnDoe) → JohnDoe
(set 'JohnDoe:age 99)
Contexts can be referred to by a variable:
(set 'human JohnDoe) human:age → 99 (set 'human:address "1 Main Street") JohnDoe:address → "1 Main Street"
An evaluated context (no quote) can be given as an argument:
> (context 'FOO) FOO FOO> (context MAIN) MAIN > (set 'old FOO) FOO > (context 'BAR) BAR BAR> (context MAIN:old) FOO FOO>
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.
;; create a symbol and store data in it (context 'Ctx "abc" 123) → 123 (context 'Ctx 'xyz 999) → 999 ;; retrieve contents from symbol (context 'Ctx "abc") → 123 (context 'Ctx 'xyz) → 999 Ctx:abc → 123 Ctx:xyz → 999
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.
In the first syntax, context? is a predicate that returns true only if exp evaluates to a context; otherwise, it returns nil.
(context? MAIN) → true (set 'x 123) (context? x) → nil (set 'FOO:q "hola") → "hola" (set 'ctx FOO) (context? ctx) → true ; ctx contains context foo
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.
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.
(set 'aList '(a b c d e f)) (replace 'c (copy aList)) → (a b d e f) aList → (a b c d e f) (set 'str "newLISP") → "newLISP" (rotate (copy str)) → "PnewLIS" str → "newLISP"
Using copy the functions replace and rotate are prevented from changing the data. A modified version of the data is returned.
The second syntax, marked by the true in bool-flag, copies a newLISP expression from a memory address.The following two expressions are equivalent:
(set 'x "hello world") (copy x) → "hello world" (copy (first (dump x)) true) → "hello world"
The second syntax can be useful when interfacing with C-code generating newLISP expressions.
Copies a file from a path-filename given in str-from-name to a path-filename given in str-to-name. Returns true if the copy was successful or nil, if the copy was unsuccessful.
(copy-file "/home/me/newlisp/data.lsp" "/tmp/data.lsp")
Calculates the Pearson product-moment correlation coefficient as a measure of the linear relationship between the two variables in list-vector-X and list-vector-Y. Both lists must be of same length.
corr returns a list containing the following values:
| name | description |
|---|---|
| r | Correlation coefficient |
| b0 | Regression coefficient offset |
| b1 | Regression coefficient slope |
| t | t - statistic for significance testing |
| df | Degrees of freedom for t |
| p | Two tailed probability of t under the null hypothesis |
(set 'study-time '(90 100 130 150 180 200 220 300 350 400))
(set 'test-errors '(25 28 20 20 15 12 13 10 8 6))
(corr study-time test-errors) → (-0.926 29.241 -0.064 -6.944 8 0.0001190)
The negative correlation of -0.926 between study time and test errors is highly significant with a two-tailed p of about 0.0001 under the null hypothesis.
The regression coefficients b0 = 29.241 and b1 = -0.064 can be used to estimate values of the Y variable (test errors) from values in X (study time) using the equation Y = b0 + b1 * X.
Calculates the cosine of num-radians and returns the result.
(cos 1) → 0.5403023059 (set 'pi (mul 2 (acos 0))) → 3.141592654 (cos pi) → -1
Calculates the hyperbolic cosine of num-radians. The hyperbolic cosine is defined mathematically as: (exp (x) + exp (-x)) / 2. An overflow to inf may occur if num-radians is too large.
(cosh 1) → 1.543080635 (cosh 10) → 11013.23292 (cosh 1000) → inf (= (cosh 1) (div (add (exp 1) (exp -1)) 2)) → true
Counts elements of list-1 in list-2 and returns a list of those counts.
(count '(1 2 3) '(3 2 1 4 2 3 1 1 2 2)) → (3 4 2) (count '(z a) '(z d z b a z y a)) → (3 2) (set 'lst (explode (read-file "myFile.txt"))) (set 'letter-counts (count (unique lst) lst))
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).
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.
(set 's "0123456789")
(cpymem "xxx" (+ (address s) 5) 3)
s → "01234xxx89")
The example copies a string directly into a string variable.
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:
55 push ebp 8B EC mov ebp, esp 8B 45 08 mov eax, [ebp+08] 03 45 0C add eax, [ebp+0c] 5D pop ebp C3 ret ; for Win32/stdcall change last line C2 08 00 ret
The binary representation is attached to a new function created in newLISP:
; set up 32-bit version of machine code
; on Windows use 32-bit version of newLISP
(set 'foo-code (append
(pack "bbbbbbbbbb" 0x55 0x8B 0xEC 0x8B 0x45 0x08 0x03 0x45 0x0C 0x5D)
(if (= ostype "Windows") (pack "bbb" 0xC2 0x08 0x00) (pack "b" 0xC3))))
; put a function cell template into foo, protect symbol from deletion
(constant 'foo print)
; put the correct type, either 'stdcall' or 'cdecl'
(cpymem (pack "ld" (if (= ostype "Windows") 8456 4360)) (first (dump foo)) 4)
; put the address of foo-code into the new function cell
(cpymem (pack "ld" (address foo-code)) (+ (first (dump foo)) 12) 4)
; take the name address from the foo symbol, copy into function cell
(set 'sym-name (first (unpack "lu" (+ (address 'foo) 8))))
(cpymem (pack "ld" sym-name) (+ (first (dump foo)) 8) 4)
; test the new function
(println "3 * 4 -> " (foo 3 4))
The last example will not work on all hardware platforms and OSs.
Use the dump function to retrieve binary addresses and the contents from newLISP cells.
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.
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-chi2 0.01 4) → 13.27670443
See also the inverse function prob-chi2.
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-f 0.05 10 12) → 2.753386727
See also the inverse function prob-f.
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.
(crit-t 0.05 14) → 1.761310142
See also the inverse function prob-t.
Calculates the critical normal distributed Z value of a given cumulated probability num-probability for testing of statistical significance and confidence intervals.
(crit-z 0.999) → 3.090232372
See also the inverse function prob-z.
Retrieves the contents of the last read-line operation. current-line's contents are also implicitly used when write-line is called without a string parameter.
The following source shows the typical code pattern for creating a Unix command-line filter:
#!/usr/local/bin/newlisp
(set 'inFile (open (main-args 2) "read"))
(while (read-line inFile)
(if (starts-with (current-line) ";;")
(write-line)))
(exit)
The program is invoked:
./filter myfile.lsp
This displays all comment lines starting with ;; from a file given as a command-line argument when invoking the script filter.
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.
(set 'f (curry + 10)) → (lambda ($x) (+ 10 $x)) (f 7) → 17 (filter (curry match '(a *)) '((a 10) (b 5) (a 3) (c 8) (a 9))) → ((a 10) (a 3) (a 9)) (clean (curry match '(a *)) '((a 10) (b 5) (a 3) (c 8) (a 9))) → ((b 5) (c 8)) (map (curry list 'x) (sequence 1 5)) → ((x 1) (x 2) (x 3) (x 4) (x 5))
curry can be used on all functions taking two arguments.
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.
(date) → "Fri Oct 29 09:56:58 2004" (date (date-value)) → "Sat May 20 11:37:15 2006" (date (date-value) 300) → "Sat May 20 16:37:19 2006" ; 5 hours offset (date 0) → "Wed Dec 31 16:00:00 1969" (date 0 (now 0 -2)) → "Thu Jan 1 00:00:00 1970" ; Unix epoch
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:
(set-locale "german") → "de_DE" ; on Linux - no leading 0 on day with %-d (date (date-value) 0 "%A %-d. %B %Y") → "Montag 7. März 2005" (set-locale "C") ; default POSIX (date (date-value) 0 "%A %B %d %Y") → "Monday March 07 2005" ; suppressing leading 0 on MS Windows using # (date (date-value) 0 "%a %#d %b %Y") → "Mon 7 Mar 2005" (set-locale "german") (date (date-value) 0 "%x") → "07.03.2005" ; day month year (set-locale "C") (date (date-value) 0 "%x") → "03/07/05" ; month day year
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".
See also date-value, date-list, date-parse, time-of-day, time, and now.
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).
The week-day value ranges from 1 to 7 for Monday thru Sunday.
(date-list 1282479244) → (2010 8 22 12 14 4 234 1) (date-list 1282479244 0) → 2010 ; year (date-list 1282479244 -2) → 234 ; day of year (date-value (date-list 1282479244)) → 1282479244 (date-list 0) → (1970 1 1 0 0 0 1 4) ; Thursday 1st, Jan 1970
A second optional int-index parameter can be used to return a specific member of the list.
date-list is the inverse operation of date-value.
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-parse "2007.1.3" "%Y.%m.%d") → 1167782400 (date-parse "January 10, 07" "%B %d, %y") → 1168387200 ; output of date-parse as input value to date-list produces the same date (date-list (date-parse "2010.10.18 7:00" "%Y.%m.%d %H:%M")) → (2010 10 18 7 0 0 290 1)
See the date function for all possible format descriptors.
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.
(date-value 2002 2 28) → 1014854400 (date-value '(2002 2 28)) → 1014854400 (date-value 1970 1 1 0 0 0) → 0 (date (date-value (now))) → "Wed May 24 10:02:47 2006" (date (date-value)) → "Wed May 24 10:02:47 2006" (date) → "Wed May 24 10:02:47 2006"
The function date-list can be used to transform a date-value back into a list:
(date-list 1014854400) → (2002 2 28 0 0 0) (date-value (date-list 1014854400)) → 1014854400
See also date, date-list, date-parse, time-of-day, time, and now.
Calls trace and begins evaluating the user-defined function in func. debug is a shortcut for executing (trace true), then entering the function to be debugged.
;; instead of doing (trace true) (my-func a b c) (trace nil) ;; use debug as a shortcut (debug (my-func a b c))
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.
See also the trace function.
The number in place is decremented by 1.0 or the optional number num and returned. dec performs float arithmetic and converts integer numbers passed into floating point type.
place is either a symbol or a place in a list structure holding a number, or a number returned by an expression.
(set x 10) → 10 (dec x) → 9 x → 9 (dec x 0.25) → 8.75 x → 8.75
If the symbol for place contains nil, it is treated as if containing 0.0:
z → nil (dec z) → -1 (set z nil) (dec z 0.01) → -0.01
Places in a list structure or a number returned by another expression can be updated too:
(set 'l '(1 2 3 4)) (dec (l 3) 0.1) → 3.9 (dec (first l)) → 0 l → (0 2 3 3.9) (dec (+ 3 4)) → 6
Use the -- function to decrement in integer mode. Use the inc function to increment numbers floating point mode.
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.
def-new returns the symbol created:
> (set 'foo:var '(foo:x foo:y)) (foo:x foo:y) > (def-new 'foo:var 'ct:myvar) ct:myvar > ct:myvar (ct:x ct:y) > (context 'K) K> (def-new 'foo:var) var K> var (x y)
The following example shows how a statically scoped function can be created by moving it its own namespace:
> (set 'temp (lambda (x) (+ x x))) (lambda (x) (+ x x)) > (def-new 'temp 'double:double) double:double > (double 10) 20 > double:double (lambda (double:x) (+ double:x double:x))
The following definition of def-static can be used to create functions living in their own lexically protected name-space:
(define (def-static s body)
(def-new 'body (sym s s)))
(def-static 'acc (lambda (x)
(inc sum x)))
> (acc 1)
1
> (acc 1)
2
> (acc 8)
10
>
The function def-new can also be used to configure contexts or context objects in a more granular fashion than is possible with new, which copies a whole context.
Return the contents of the default functor in context.
(define Foo:Foo 123) (default Foo) → 123 (setf (default Foo) 456) (set 'ctx Foo) (default ctx) → 456 Foo:Foo → 456
In many situations newLISP defaults automatically to the default functor when seeing a context name. In circumstances where this is not the case, the default function can be used.
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:
((lambda ( x y) (* x y)) 2 3) → 6 ((fn ( x y) (* x y)) 2 3) → 6
fn is just a shorter form of writing lambda.
Parameters can have default values specified:
(define (foo (a 1) (b 2))
(list a b))
(foo) → (1 2)
(foo 3) → (3 2)
(foo 3 4) → (3 4)
Expressions in exp-default are evaluated in the function's current environment.
(define (foo (a 10) (b (div a 2))) (list a b)) (foo) → (10 5) (foo 30) → (30 15) (foo 3 4) → (3 4)
The second version of define works like the set function.
(define x 123) → 123 ;; is equivalent to (set 'x 123) → 123 (define area (lambda ( x y) (* x y))) ;; is equivalent to (set 'area (lambda ( x y) (* x y))) ;; is equivalent to (define (area x y) (* x y))
Trying to redefine a protected symbol will cause an error message.
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.
Since v.10.5.8, newLISP also has expansion macros using macro.
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.
(define-macro (my-setq p1 p2) (set p1 (eval p2))) → (lambda-macro (p1 p2) (set p1 (eval p2))) (my-setq x 123) → 123 x → 123
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.
(define-macro (foo (a 1) (b 2))
(list a b))
(foo) → (1 2)
(foo 3) → (3 2)
(foo 3 4) → (3 4)
Expressions in exp-default are evaluated in the function's current environment.
(define-macro (foo (a 10) (b (div a 2))) (list a b)) (foo) → (10 5) (foo 30) → (30 15) (foo 3 4) → (3 4)
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:
;; not a good definition! (define-macro (my-setq x y) (set x (eval y))) ;; symbol name clash for x (my-setq x 123) → 123 x → nil
There are several methods that can be used to avoid this problem, known as variable capture, by writing hygienic define-macros:
;; a define-macro as a lexically isolated function ;; avoiding variable capture in passed parameters (context 'my-setq) (define-macro (my-setq:my-setq x y) (set x (eval y))) (context MAIN) (my-setq x 123) → 123 ; no symbol clash x → 123
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.
The second possibility is to refer to passed parameters using args:
;; avoid variable capture in macros using the args function (define-macro (my-setq) (set (args 0) (eval (args 1))))
See also the macro expansion function not susceptible to variable capture.
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.
(set 'lst '(a b aVar c d)) (delete 'aVar) ; aVar deleted, references marked nil lst → (a b nil c d) (set 'lst '(a b aVar c d)) (delete 'aVar true) → nil ; protect aVar if referenced lst → (a b aVar c d) ;; delete all symbols in a context (set 'foo:x 123) (set 'foo:y "hello") (delete 'foo) → foo:x, foo:y deleted
In the last example only the symbols inside context foo will be deleted but not the context symbol foo itself. It will be converted to a normal unprotected symbol and contain nil.
Note that deleting a symbol that is part of an expression which is currently executing can crash the system or have other unforeseen effects.
Deletes a file given in str-file-name. Returns true if the file was deleted successfully.
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.
The file name can be given as a URL.
(delete-file "junk") (delete-file "http://asite.com/example.html") (delete-file "file://aFile.txt")
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.
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.
(delete-url "http://www.aserver.com/somefile.txt") (delete-url "http://site.org:8080/page.html" 5000) ; delete on the local file system (delete-url "file:///home/joe/somefile.txt")
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.
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.
(set 'pid (process "/usr/local/bin/bc" bcin bcout)) (destroy pid) (set 'pid (fork (dotimes (i 1000) (println i) (sleep 10)))) (sleep 100) (destroy pid)
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.
(set 'A '((-1 1 1) (1 4 -5) (1 -2 0))) (det A) → -1 ; treatment of singular matrices (det '((2 -1) (4 -2))) → nil (det '((2 -1) (4 -2)) 0) → -0 (det '((2 -1) (4 -2)) 1e-20) → -4e-20
If the matrix is singular and float-pivot is not specified, nil is returned.
See also the other matrix operations invert, mat, multiply and transpose.
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.
The I/O channel specified by device is used internally by the functions print, println, write, write-line and read-char, read-line. When the current I/O device is 0 or 1, print sends output to the console window and read-line accepts input from the keyboard. If the current I/O device has been set by opening a file, then print and read-line work on that file.
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.
(device (open "myfile" "write")) → 5 (print "This goes in myfile") → "This goes in myfile" (close (device)) → true
Note that using close on device automatically resets device to 0 (zero).
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.
(difference '(2 5 6 0 3 5 0 2) '(1 2 3 3 2 1) true) → (5 6 0 5 0)
See also the set functions intersect, unique and union.
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.
(directory "." "\\.c") → ("foo.c" "bar.c") ;; or using braces as string pattern delimiters (directory "." {\.c}) → ("foo.c" "bar.c") ; show only hidden files (starting with dot) (directory "." "^[.]") → ("." ".." ".profile" ".rnd" ".ssh")
The regular expression forces directory to return only file names containing the string ".c".
Other functions that use regular expressions are find, find-all, parse, regex, replace, and search.
Checks if str-path is a directory. Returns true or nil depending on the outcome.
(directory? "/etc") → true (directory? "/usr/local/bin/emacs/") → nil
Using the first syntax, the function replaces the current page in the browser with the HTML page found in str-html.
If bool-flag evaluates to true, the page gets opened in a new browser tab and the current page is not affected.
This function is only available on newLISP compiled to JavaScript.
(set 'page [text]
<html>
<head>
<title>Hello App</title>
</head>
<body>
<h2>Hello World</h2>
</body>
</html>
[/text])
; open the page in a new browser tab
(display-html page true) → "92"
The function returns the length of the HTML document displayed as a string.
See also the function eval-string-js for evaluation of JavaScript in the current page.
Successively divides num-1 by the number in num-2—. div can perform mixed-type arithmetic, but it always returns floating point numbers. Any floating point calculation with NaN also returns NaN.
(div 10 3) → 3.333333333 (div 120 (sub 9.0 6) 100) → 0.4 (div 10) → 0.1
When num-1 is the only argument, div calculates the inverse of num-1.
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-until also updates the system iterator symbol $idx.
(set 'x 1) (do-until (> x 0) (inc x)) x → 2 (set 'x 1) (until (> x 0) (inc x)) x → 1
While do-until goes through the loop at least once, until never enters the loop.
See also the functions while and do-while.
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.
do-while also updates the system iterator symbol $idx.
(set 'x 10) (do-while (< x 10) (inc x)) x → 11 (set 'x 10) (while (< x 10) (inc x)) x → 10
While do-while goes through the loop at least once, while never enters the loop.
See also the functions until and do-until.
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:
(define-macro (foo)
(doargs (i (= i 'x))
(println i)))
> (foo a b x c d e)
a
b
true
Use the args function to access the entire argument list at once.
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.
(set 'x 123)
(dolist (x '(a b c d e f g)) ; prints: abcdefg
(print x)) → g ; return value
(dolist (x '(a b c d e f g) (= x 'e)) ; prints: abcd
(print x))
;; x is local in dolist
;; x has still its old value outside the loop
x → 123 ; x has still its old value
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:
(dolist (x '(a b d e f g))
(println $idx ":" x)) → g
0:a
1:b
2:d
3:e
4:f
5:g
The console output is shown in boldface. $idx is protected and cannot be changed by the user.
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.
; ASCII example (set 'str "abcdefg") (dostring (c str) (println c " - " (char c))) 97 - a 98 - b 99 - c 100 - d 101 - e 102 - f 103 - g ; UTF8 example (set 'utf8str "我能吞下玻璃而不伤身体。") (dostring (c utf8str) (println c " - " (char c))) 25105 - 我 33021 - 能 21534 - 吞 ... 20307 - 体 12290 - 。
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.
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.
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.
dotree also updates the system iterator symbol $idx.
;; faster and less memory overhead (dotree (s SomeCTX) (print s " ")) ;; slower and higher memory usage (dolist (s (symbols SomeCTX)) (print s " "))
This example prints the names of all symbols inside SomeCTX to the console window.
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.
(dump 'a) → (9586996 5 9578692 9578692 9759280) (dump 999) → (9586996 130 9578692 9578692 999)
The list contains the following memory addresses and information:
| offset | description |
|---|---|
| 0 | memory address of the newLISP cell |
| 1 | cell->type: major/minor type, see newlisp.h for details |
| 2 | cell->next: linked list ptr |
| 3 | cell->aux: string length+1 or low (little endian) or high (big endian) word of 64-bit integer or low word of IEEE 754 double float |
| 4 | 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.
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.
Without the repetition parameter, dup assumes 2.
(dup "A" 6) → "AAAAAA" (dup "A" 6 true) → ("A" "A" "A" "A" "A" "A") (dup "A" 0) → "" (dup "AB" 5) → "ABABABABAB" (dup 9 7) → (9 9 9 9 9 9 9) (dup 9 0) → () (dup 'x 8) → (x x x x x x x x) (dup '(1 2) 3) → ((1 2) (1 2) (1 2)) (dup "\000" 4) → "\000\000\000\000" (dup "*") → "**"
The last example shows handling of binary information, creating a string filled with four binary zeroes.
See also the functions sequence and series.
exp is tested for an empty list (or str for an empty string). Depending on whether the argument contains elements, true or nil is returned.
(set 'var '()) (empty? var) → true (empty? '(1 2 3 4)) → nil (empty? "hello") → nil (empty? "") → true
The first example checks a list, while the second two examples check a string.
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:
(set 'secret (encrypt "A secret message" "my secret key")) → ",YS\022\006\017\023\017TM\014\022\n\012\030E" (encrypt secret "my secret key") → "A secret message"
The second example encrypts a whole file:
(write-file "myfile.enc" (encrypt (read-file "myfile") "29kH67*"))
In the first syntax, ends-with tests the string in str-data to see if it ends with the string specified in str-key. It returns true or nil depending on the outcome.
If a regular expression option number is specified, str-key contains a regular expression pattern. See regex for valid numbers for option.
(ends-with "newLISP" "LISP") → true (ends-with "newLISP" "lisp") → nil ;; use regular expressions (ends-with "newLISP" "lisp|york" 1) → true
In the second syntax, ends-with checks if a list ends with the list element in exp. true or nil is returned depending on outcome.
(ends-with '(1 2 3 4 5) 5) → true (ends-with '(a b c d e) 'b) → nil (ends-with '(a b c (+ 3 4)) '(+ 3 4)) → true
The last example shows that exp could be a list by itself.
See also the starts-with function.
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.
(env "NEWLISPBIN" "/usr/local/bin/") → true (env "NEWLISPBIN") → "/usr/bin/" (env "NEWLISPBIN" "") → true (env "NEWLISPBIN") → nil
erf calculates the error function of a number in num. The error function is defined as:
erf (x) = 2/sqrt(pi) * integral from 0 to x of exp(-t^2) dt
(map erf (sequence 0.0 6.0 0.5))
→
(0 0.5204998778 0.8427007929 0.9661051465 0.995322265 0.999593048
0.9999779095 0.9999992569 0.9999999846 0.9999999998 1 1 1)
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.
To cancel error-event, use the second syntax.
(define (my-handler) (print "error # " (first (last-error)) " has occurred\n") ) (error-event 'my-handler) → my-handler ;; specify a function directly (error-event my-handler) → $error-event (error-event (fn () (print "error # " (first (last-error)) " has occurred\n"))) (error-event exit) → $error-event
For a different way of handling errors, see the catch function. Use throw-error to throw user-defined errors.
eval evaluates the result of evaluating exp in the current variable environment.
(set 'expr '(+ 3 4)) → (+ 3 4) (eval expr) → 7 (eval (list + 3 4)) → 7 (eval ''x) → x (set 'y 123) (set 'x 'y) x → y (eval x) → 123
As usual, evaluation of variables happens in the current variable environment:
; eval in global (top level) environment (set 'x 3 'y 4) (eval '(+ x y)) → 7 ; eval in local environment (let ( (x 33) (y 44) ) (eval '(+ x y))) → 77 ; old environment after leaving local let environment (eval '(+ x y)) → 7
newLISP passes all arguments by value. Using a quoted symbol, expressions can be passed by reference through the symbol. eval can be used to access the original contents of the symbol:
(define (change-list aList) (push 999 (eval aList)))
(set 'data '(1 2 3 4 5))
(change-list 'data) → (999 1 2 3 4 5)
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.
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.
(eval-string "(+ 3 4)") → 7 (set 'X 123) → 123 (eval-string "X") → 123 (define (repl) ; read print eval loop (while true (println "=> " (eval-string (read-line) MAIN (last-error))) ) ) (set 'a 10) (set 'b 20) (set 'foo:a 11) (set 'foo:b 22) (eval-string "(+ a b)") → 30 (eval-string "(+ a b)" 'foo) → 33
The second example shows a simple newLISP interpreter eval loop.
The last example shows how to specify a target context for translation. The symbols a and b now refer to symbols and their values in context foo instead of MAIN.
See also the function read-expr which translates a string without evaluating it.
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.
Checks if an integer number is even divisible by 2, without remainder. When a floating point number is passed for int-number, it will be converted to an integer by cutting off its fractional part.
(even? 123) → nil (even? 8) → true (even? 8.7) → true
Use odd? to check if an integer is not divisible by 2.
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.
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.
(exists string? '(2 3 4 6 "hello" 7)) → "hello" (exists string? '(3 4 2 -7 3 0)) → nil (exists zero? '(3 4 2 -7 3 0)) → 0 ; check for 0 or 0.0 (exists < '(3 4 2 -7 3 0)) → -7 ; check for negative (exists (fn (x) (> x 3)) '(3 4 2 -7 3 0)) → 4 (exists (fn (x) (= x 10)) '(3 4 2 -7 3 0)) → nil
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.
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)
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
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.
(set 'x 2 'a '(d e)) (set 'foo 'a) (expand foo 'a) → (d e) (expand '(a x b) 'x) → (a 2 b) (expand '(a x (b c x)) 'x) → (a 2 (b c 2)) (expand '(a x (b c x)) 'x 'a) → ((d e) 2 (b c 2))
expand is useful when composing lambda expressions and doing variable expansion as in rewrite macros.
(define (raise-to power) (expand (fn (base) (pow base power)) 'power)) (define square (raise-to 2)) (define cube (raise-to 3)) (square 5) → 25 (cube 5) → 125
If more than one symbol is present, expand will work in an incremental fashion:
(set 'a '(b c))
(set 'b 1)
(expand '(a b c) 'a 'b) → ((1 c) 1 c)
Like the apply function, expand reduces its argument list.
The second syntax of expand allows expansion bindings to be specified on the fly, without performing a set on the participating variables:
If the bool evaluates to true, the value parts in the association list are evaluated.
(expand '(a b c) '((a 1) (b 2))) → (1 2 c) (expand '(a b c) '((a 1) (b 2) (c (x y z)))) → (1 2 (x y z)) (expand '(a b) '((a (+ 1 2)) (b (+ 3 4)))) → ((+ 1 2) (+ 3 4)) (expand '(a b) '((a (+ 1 2)) (b (+ 3 4))) true) → (3 7)
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.
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:
(set 'A 1 'Bvar 2 'C nil 'd 5 'e 6)
(expand '(A (Bvar) C d e f)) → (1 (2) C d e f)
Only the symbols A and Bvar are expanded because they have capitalized names and non-nil contents.
The currying function in the example demonstrating the first syntax of expand can now be written even more simply using an uppercase variable:
(define (raise-to Power) (expand (fn (base) (pow base Power)))) > (define cube (raise-to 3)) (lambda (base) (pow base 3)) > (cube 4) 64 > _
See the letex function, which also provides an expansion mechanism, and the function unify, which is frequently used together with expand.
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.
(explode "newLISP") → ("n" "e" "w" "L" "I" "S" "P") (join (explode "keep it together")) → "keep it together" (explode "newLISP" 2) → ("ne" "wL" "IS" "P") (explode "newLISP" 3) → ("new" "LIS" "P") ; omit last chunk if too short (explode "newLISP" 3 true) → ("new" "LIS")
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:
(set 'str "\001\002\003\004") → "\001\002\003\004" (unpack (dup "c" (length str)) str) → (1 2 3 4) (unpack (dup "s" (length str)) str) → ("\001" "\002" "\003" "\004")
In the second syntax, explode explodes a list (list) into sublists of chunk size int-chunk, which is 1 (one) by default.
The following shows an example of the last chunk being omitted when the value for bool is other than nil, and the chunk does not have the full length specified in int-chunk.
(explode '(a b c d e f g h)) → ((a) (b) (c) (d) (e) (f) (g) (h)) (explode '(a b c d e f g) 2) → ((a b) (c d) (e f) (g)) ; omit last chunk if too short (explode '(a b c d e f g) 2 true) → ((a b) (c d) (e f)) (transpose (explode '(a b c d e f g h) 2)) → ((a c e g) (b d f h))
The join and append functions are inverse operations of explode.
The list in list-1 is extended by appending list-2. More than one list may be appended.
The string in string-1 is extended by appending string-2. More than one string may be appended. The string can contain binary 0 (zero) characters.
The first parameter can be an un-initialized variable.
The extended list or string is returned.
; extending lists (extend lst '(a b) '(c d)) → (a b c d) (extend lst '(e f g)) → (a b c d e f) lst → (a b c d e f g) ; extending strings (extend str "ab" "cd") → "abcd" (extend str "efg") → "abcdefg" str → "abcdefg" ; extending in place (set 'L '(a b "CD" (e f))) (extend (L 2) "E") L → (a b "CDE" (e f)) (extend (L 3) '(g)) L → (a b "CDE" (e f g))
For a non-destructive list or string extension see append.
Factors the number in int into its prime components. When floating point numbers are passed, they are truncated to their integer part first.
(factor 123456789123456789) → (3 3 7 11 13 19 3607 3803 52579) ;; check correctness of factoring (= (apply * (factor 123456789123456789)) 123456789123456789) → true ;; factor the biggest integer (factor 9223372036854775807) → (7 7 73 127 337 92737 649657) ;; primes.lsp - return all primes in a list, up to n (define (primes n , p) (dotimes (e n) (if (= (length (factor e)) 1) (push e p -1))) p) (primes 20) → (2 3 5 7 11 13 17 19)
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.
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.
(ifft (fft '((1 0) (2 0) (3 0) (4 0)))) → ((1 0) (2 0) (3 0) (4 0)) ;; when imaginary part is 0, plain numbers work too ;; plain numbers and complex numbers can be intermixed (fft '(1 2 3 4)) → ((10 0) (-2 -2) (-2 0) (-2 2)) (fft '(1 2 (3 0) 4)) → ((10 0) (-2 -2) (-2 0) (-2 2))
The inverse operation of fft is the ifft function.
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).
(file-info ".bashrc") → (124 33188 0 500 0 920951022 920951022 920953074) (file-info ".bashrc" 0) → 124 (date (file-info "/etc" -1)) → "Mon Mar 8 18:23:17 2005"
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.
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.
(if (file? "afile") (set 'fileNo (open "afile" "read"))) (file? "/usr/local/bin/newlisp" true) → "/usr/local/bin/newlisp" (file? "/usr/bin/foo" true) → nil
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.
(filter symbol? '(1 2 d 4 f g 5 h)) → (d f g h) (define (big? x) (> x 5)) → (lambda (x) (> x 5)) (filter big? '(1 10 3 6 4 5 11)) → (10 6 11) ; filter with comparison functor (set 'L '((a 10 2 7) (b 5) (a 8 3) (c 8) (a 9))) (filter (curry match '(a *)) L) → ((a 10 2 7) (a 8 3) (a 9)) (filter (curry match '(? ?)) L) → ((b 5) (c 8) (a 9)) (filter (curry match '(* 8 *)) L) → ((a 8 3) (c 8))
The predicate may be a built-in predicate, a user-defined function, or a lambda expression.
For filtering a list of elements with the elements from another list, use the difference function or intersect (with the list option).
See also the related function index, which returns the indices of the filtered elements and clean, which returns all elements of a list for which a predicate is false.
If the second argument evaluates to a list, then find returns the index position (offset) of the element derived from evaluating exp-key.
Optionally, an operator or user-defined function can be specified in func-compare. If the exp-key is a string, a regular expression option can be specified with the regex-option parameter.
When using regular expressions or comparison functors the system variable $0 is set to the last element found.
; find an expression in a list (find '(1 2) '((1 4) 5 6 (1 2) (8 9))) → 3 (find "world" '("hello" "world")) → 1 (find "hi" '("hello" "world")) → nil (find "newlisp" '("Perl" "Python" "newLISP") 1) → 2 ; same with string option (find "newlisp" '("Perl" "Python" "newLISP") "i") → 2 ; use the comparison functor (find 3 '(8 4 3 7 2 6) >) → 4 $0 → 2 (find "newlisp" '("Perl" "Python" "newLISP") (fn (x y) (regex x y 1))) → 2 $0 → "newLISP" (find 5 '((l 3) (k 5) (a 10) (z 22)) (fn (x y) (= x (last y)))) → 1 $0 → (k 5) (find '(a ?) '((l 3) (k 5) (a 10) (z 22)) match) → 2 $0 → (a 10) (find '(X X) '((a b) (c d) (e e) (f g)) unify) → 2 $0 → (e e) ; define the comparison functor first for better readability (define (has-it-as-last x y) (= x (last y))) (find 22 '((l 3) (k 5) (a 10) (z 22)) has-it-as-last) → 3 $0 → (z 22)
Using match and unify, list searches can be formulated which are as powerful as regular expression searches are for strings.
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.
; simple string search (find "world" "Hello world") → 6 (find "WORLD" "Hello woRLd") → nil ; case-insensitive regex (find "WorlD" "Hello woRLd" 1) → 6 ; or (find "WorlD" "Hello woRLd" "i") → 6 (find "hi" "hello world") → nil (find "Hello" "Hello world") → 0 ; regex with default options (find "cat|dog" "I have a cat" 0) → 9 $0 → "cat" (find "cat|dog" "my dog" 0) → 3 $0 → "dog" (find "cat|dog" "MY DOG" 1) → 3 $0 → "DOG" ; use an optional offset (find "cat|dog" "I have a cat and a dog" 0) → 9 (find "cat|dog" "I have a cat and a dog" 0 12) → 19 ;; find with subexpressions in regular expression ;; and access with system variables (set 'str "http://nuevatec.com:80") (find "http://(.*):(.*)" str 0) → 0 $0 → "http://nuevatec.com:80" $1 → "nuevatec.com" $2 → "80" ;; system variables as an indexed expression (since 8.0.5) ($ 0) → "http://nuevatec.com:80" ($ 1) → "nuevatec.com" ($ 2) → "80"
For other functions using regular expressions, see directory, find-all, parse, regex, replace, and search.
To find expressions in nested or multidimensional lists, use the ref and ref-all functions.
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).
(find-all {\d+} "lkjhkljh34ghfdhgfd678gfdhfgd9")
→ ("34" "678" "9")
$count → 3
(find-all {(new)(lisp)} "newLISPisNEWLISP" (append $2 $1) 1)
→ ("LISPnew" "LISPNEW")
(unique (sort
(find-all {[a-zA-Z]+}
(replace "<[^>]+>" (get-url "http://newlisp.org") "" 0) )
))
→ ("A" "ACC" "AI" "API" "About" "All" "Amazing" "Apps"
...
"where" "whole" "width" "wiki" "will" "with" "work" "written")
; use $count in evaluated expr
(find-all "a" "ababab" (string $count $it)) → ("1a" "2a" "3a")
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.
(find-all '(? 2) '((a 1) (b 2) (a 2) (c 4))) → ((b 2) (a 2)) (find-all '(? 2) '((a 1) (b 2) (a 2) (c 4)) (first $it)) → (b a) $count → 2
find-all for list matches always uses match to compare when searching for sublists and always needs a list for the pattern expression.
In the third syntax, find-all can specify a built-in or user-defined function used for comparing list elements with the key expression in exp-key:
(find-all 5 '(2 7 4 5 9 2 4 9 7 4 8) $it <) → (7 9 9 7 8) ; process the found element available in $it (find-all 5 '(2 7 4 5 9 2 4 9 7 4 8) (* 3 $it) <) → (21 27 27 21 24) ; same as (find-all 5 '(2 7 4 5 9 2 4 9 7 4 8) (* 3 $it) (fn (x y) (< x y))) → (21 27 27 21 24) (find-all 5 '(2 7 4 5 9 2 4 9 7 4 8) ("abcdefghijk" $it) <) → ("h" "j" "j" "h" "i") $count → 5 ; use $count (find-all 'a '(a b a b a b) (list $count $it)) → ((1 a) (2 a) (3 a))
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.
Returns the first element of a list or the first character of a string. The operand is not changed. This function is equivalent to car or head in other Lisp dialects.
(first '(1 2 3 4 5)) → 1 (first '((a b) c d)) → (a b) (set 'aList '(a b c d e)) → (a b c d e) (first aList) → a aList → (a b c d e) (set 'A (array 3 2 (sequence 1 6))) → ((1 2) (3 4) (5 6)) (first A) → (1 2) (first '()) → ERR: list is empty
In the third syntax, the first character is returned from the string in str as a string.
(first "newLISP") → "n" (first (rest "newLISP")) → "e"
Note that first works on character boundaries rather than byte boundaries when the UTF-8–enabled version of newLISP is used. See also the functions last and rest.
Returns a flattened list from a list:
(set 'lst '(a (b (c d)))) (flat lst) → (a b c d) ; extract a list of index vectors of all elements (map (fn (x) (ref x lst)) (flat lst)) → ((0) (1 0) (1 1 0) (1 1 1))
The optional int-level parameter can be used to limit the recursion level when flattening the list:
(flat '(a b (c d (e f)) (g h (i j))) ) → (a b c d e f g h i j) (flat '(a b (c d (e f)) (g h (i j))) 1) → (a b c d (e f) g h (i j)) (flat '(a b (c d (e f)) (g h (i j))) 2) → (a b c d e f g h i j)
If int-level is 0, no flattening will occur.
flat can be used to iterate through nested lists.
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.
(float "1.23") → 1.23 (float " 1.23") → 1.23 (float ".5") → 0.50 (float "-1.23") → -1.23 (float "-.5") → nil (float "#1.23") → nil (float "#1.23" 0.0) → 0 (float? 123) → nil (float? (float 123)) → true (float '(a b c)) → nil (float '(a b c) 0) → 0 (float nil 0) → 0 (float "abc" "not a number") → "not a number" (float "1e500") → inf (float "-1e500") → -inf (print "Enter a float num:") (set 'f-num (float (read-line)))
Use the int function to parse integer numbers.
true is returned only if exp evaluates to a floating point number; otherwise, nil is returned.
(set 'num 1.23)
(float? num) → true
Returns the next lowest integer below number as a floating point.
(floor -1.5) → -2 (floor 3.4) → 3
See also the ceil function.
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.
(flt 1.23) → 1067282596 ;; pass 32-bit float to C-function: foo(float value) (import "mylib.so" "foo") (foo (flt 1.23)) (get-int (pack "f" 1.23)) → 1067282596 (unpack "f" (pack "ld" (flt 1.2345))) → (1.234500051)
The last two statements illustrate the inner workings of flt.
Use the import function to import libraries.
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:
(map (fn (x) (+ x x)) '(1 2 3 4 5)) → (2 4 6 8 10) (sort '(".." "..." "." ".....") (fn (x y) (> (length x) (length y)))) → ("....." "..." ".." ".")
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.
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.
> (for (x 1 10 2) (println x)) 1 3 5 7 9 > (for (x 8 6 0.5) (println x)) 8 7.5 7 6.5 6 > (for (x 1 100 2 (> (* x x) 30)) (println x)) 1 3 5 true > _
The second example uses a range of numbers from highest to lowest. Note that the step size is always a positive number. In the third example, a break condition is tested.
Use the sequence function to make a sequence of numbers.
Applies the function in func-condition to all elements in list. If all elements meet the condition in func-condition, the result is true; otherwise, nil is returned.
(for-all number? '(2 3 4 6 7)) → true (for-all number? '(2 3 4 6 "hello" 7)) → nil (for-all (fn (x) (= x 10)) '(10 10 10 10 10)) → true
Use the exists function to check if at least one element in a list meets a condition.
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.
> (set 'x 0) 0 > (fork (while (< x 20) (println (inc x)) (sleep 1000))) 176 > 1 2 3 4 5 6
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.
#!/usr/local/bin/newlisp
(define (count-down-proc x channel)
(while (!= x 0)
(write-line channel (string x))
(dec x)))
(define (observer-proc channel)
(do-until (= i "1")
(println "process " (setq i (read-line channel)))))
(map set '(in out) (pipe))
(set 'observer (fork (observer-proc in)))
(set 'counter (fork (count-down-proc 5 out)))
; avoid zombies
(wait-pid observer)
(wait-pid counter)
(exit)
The following output is generated by observer-proc
process 5 process 4 process 3 process 2 process 1
The count-down-proc writes numbers to the communication pipe, where they are picked up by the observer-process and displayed.
A forked process can either exit by itself or it can be destroyed using the destroy function.
(define (fork-destroy-demo)
(set 'pid (fork (dotimes (i 1000) (println i) (sleep 10))))
(sleep 50)
(destroy pid)
)
> (fork-destroy-demo)
0
1
2
3
4
true
>
The process started by fork-destroy-demo will not finish but is destroyed 50 milli-seconds after start by a call to destroy.
Use the semaphore function for synchronizing processes and share for sharing memory between processes.
See spawn for a much simpler and automated way to synchronize processes and collect results.
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.
The format string has the following general format:
"%w.pf"The % (percent sign) starts a format specification. To display a % inside a format string, double it: %%
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.
(format ">>>%6.2f<<<" 1.2345) → ">>> 1.23<<<" (format ">>>%-6.2f<<<" 1.2345) → ">>>1.23 <<<" (format ">>>%+6.2f<<<" 1.2345) → ">>> +1.23<<<" (format ">>>%+6.2f<<<" -1.2345) → ">>> -1.23<<<" (format ">>>%-+6.2f<<<" -1.2345) → ">>>-1.23 <<<" (format "%e" 123456789) → "1.234568e+08" (format "%12.10E" 123456789) → "1.2345678900E+08" (format "%10g" 1.23) → " 1.23" (format "%10g" 1.234) → " 1.234" (format "Result = %05d" 2) → "Result = 00002" (format "%14.2f" 12345678.12) → " 12345678.12" ; on UNIX glibc compatible platforms only (Linux, MAC OS X 10.9) on some locales (format "%'14.2f" 12345678.12) → " 12,345,678.12" (format "%8d" 12345) → " 12345" ; on UNIX glibc compatible platforms only (Linux, MAC OS X 10.9) on some locales (format "%'8d" 12345) → " 12,345" (format "%-15s" "hello") → "hello " (format "%15s %d" "hello" 123) → " hello 123" (format "%5.2s" "hello") → " he" (format "%-5.2s" "hello") → "he " (format "%o" 80) → "120" (format "%x %X" -1 -1) → "ffffffff FFFFFFFF" ; 64 bit numbers on Windows (format "%I64X" 123456789012345678) → "1B69B4BA630F34E" ; 64 bit numbers on Unix (except TRU64) (format "%llX" 123456789012345678) → "1B69B4BA630F34E" (format "%c" 65) → "A"
The data to be formatted can be passed inside a list:
(set 'L '("hello" 123))
(format "%15s %d" L) → " hello 123"
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
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.
See also the functions irr, nper, npv, pmt, and pv.
Calculates the incomplete Gamma function of values a and b in num-a and num-b, respectively.
(gammai 4 5) → 0.7349740847
The incomplete Gamma function is used to derive the probability of Chi² to exceed a given value for a degree of freedom, df, as follows:
Q(Chi²|df) = Q(df/2, Chi²/2) = gammai(df/2, Chi²/2)
See also the prob-chi2 function.
Calculates the log Gamma function of the value x in num-x.
(exp (gammaln 6)) → 120
The example uses the equality of n! = gamma(n + 1) to calculate the factorial value of 5.
The log Gamma function is also related to the Beta function, which can be derived from it:
Beta(z,w) = Exp(Gammaln(z) + Gammaln(w) - Gammaln(z+w))
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.
(gcd 0) → 0 (gcd 0 0) → 0 (gcd 10) → 10 (gcd 12 36) → 12 (gcd 15 36 6) → 3
See Wikipedia for details and theory about gcd numbers in mathematics.
Gets an 8-bit character from an address specified in int-address. This function is useful when using imported shared library functions with import.
char * foo(void)
{
char * result;
result = "ABCDEFG";
return(result);
}
Consider the above C function from a shared library, which returns a character pointer (address to a string).
(import "mylib.so" "foo") (print (get-char (foo) )) → 65 ; ASCII "A" (print (get-char (+ (foo) 1))) → 66 ; ASCII "B"
Note that it is unsafe to use the get-char function with an incorrect address in int-address. Doing so could result in the system crashing or becoming unstable.
See also the address, get-int, get-long, get-float, get-string, pack, and unpack functions.
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.
double float * foo(void)
{
double float * result;
…
*result = 123.456;
return(result);
}
The previous C function is compiled into a shared library.
(import "mylib.so" "foo")
(get-float (foo)) → 123.456
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.
See also the address, get-int, get-long, get-char, get-string, pack, and unpack functions.
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.
int * foo(void)
{
int * result;
…
*result = 123;
return(result);
}
int foo-b(void)
{
int result;
…
result = 456;
return(result);
}
Consider the C function foo (from a shared library), which returns an integer pointer (address of an integer).
(import "mylib.so" "foo") (get-int (foo)) → 123 (foo-b) → 456
Note that using get-int with an incorrect address in int-address is unsafe and could result in the system crashing or becoming unstable.
See also the address, get-char, get-float, get-long, get-string, pack, and unpack functions.
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.
long long int * foo(void)
{
int * result;
…
*result = 123;
return(result);
}
long long int foo-b(void)
{
int result;
…
result = 456;
return(result);
}
Consider the C function foo (from a shared library), which returns an integer pointer (address of an integer).
(import "mylib.so" "foo") (get-int (foo)) → 123 (foo-b) → 456
Note that using get-long with an incorrect address in int-address is unsafe and could result in the system crashing or becoming unstable.
See also the address, get-char, get-float, get-int, get-string, pack, and unpack functions.
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.
char * foo(void)
{
char * result;
result = "ABCDEFG";
return(result);
}
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:
(set 'buff "ABC\000\000\000DEF") → "ABC\000\000\000DEF" (length buff) → 9 (get-string buff) → "ABC" (length (get-string buff)) → 3 ; get a string from offset into a buffer (get-string (+ (address buff) 6)) → "DEF"
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:
(set 'buff "ABC\000\000EFG\000DQW") → "ABC\000\000EFG\000DQW" ; buff is eqivalent to (address buff) (get-string buff 4 "FG") → "ABC\000" (get-string buff 10) → "ABC\000\000EFG\000D" (get-string buff 10 "FG") → "ABC\000\000E"
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:
(set 'utf32 (unicode "我能吞下玻璃而不伤身体。")) (set 'addr (address utf32)) → 140592856255712 ; get-string automatically takes the address when a buffer is passed ; utf32 is equivalent to (address utf32) for get-string (get-string utf32 80 "\000\000\000\000") → "\017b\000\000??\000\000\030T\000\000\011N\ 000\000?s\ 000\000?t\000\000\f?\000\000\rN\000\000$O\000\000??\000\000SO\000\000\0020\000\000"
When using "\000\000" or "\000\000\000\000" as limit strings, the search for these limits is aligned to a 2-byte or 4-byte border.
See also the get-char, get-int, get-float, pack, and unpack functions.
Note that get-string can crash the system or make it unstable if the wrong address is specified.
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.
get-url requests are also understood by newLISP server nodes.
(get-url "http://www.nuevatec.com") (get-url "http://www.nuevatec.com" 3000) (get-url "http://www.nuevatec.com" "header") (get-url "http://www.nuevatec.com" "header" 5000) (get-url "http://www.nuevatec.com" "list") (get-url "file:///home/db/data.txt") ; access local file system (env "HTTP_PROXY" "http://ourproxy:8080") (get-url "http://www.nuevatec.com/newlisp/")
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:
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:
(get-url "http://somehost.com" 5000)
newLISP will configure and send the request and header below:
GET / HTTP/1.1 Host: somehost.com User-Agent: newLISP v10603 Connection: close
As an alternative, the str-header option could be used:
(get-url "http://somehost.com" 5000 "User-Agent: Mozilla/4.0\r\nCookie: name=fred\r\n")
newLISP will now send the following request and header:
GET / HTTP/1.1 Host: somehost.com User-Agent: Mozilla/4.o Cookie: name=fred Connection: close
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.
See an HTTP transactions reference for valid header entries.
Custom headers can also be used in the put-url and post-url functions.
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.
(global 'aVar 'x 'y 'z) → z
(define (foo x)
(…))
(constant (global 'foo))
The second example shows how constant and global can be combined into one statement, protecting and making a previous function definition global.
Checks if symbol in sym is global. Built-in functions, context symbols, and all symbols made global using the function global are global:
global? 'print) → true (global 'var) → var (global? 'var) → true (constant (global 'foo)) (global? 'foo) → true
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.
(define (foo x y)
(bar (+ x 1) (* y 2)))
(define (bar a b)
(history))
; history returns names of calling functions
(foo 1 2) → (bar foo)
; the addtional 'true' forces inclusion of callpatterns
(define (bar a b)
(history true))
(foo 1 2) → ((bar (+ x 1) (* y 2)) (foo 1 2))
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.
(set 'x 50) → 50 (if (< x 100) "small" "big") → "small" (set 'x 1000) → 1000 (if (< x 100) "small" "big") → "big" (if (> x 2000) "big") → nil ; more than one statement in the true or false ; part must be blocked with (begin ...) (if (= x y) (begin (some-func x) (some-func y)) (begin (do-this x y) (do-that x y)) ) ; if also sets the anaphoric system variable $it (set 'lst '(A B C)) (if lst (println (last $it))) → C
The second form of if works similarly to cond, except it does not take parentheses around the condition-body pair of expressions. In this form, if can have an unlimited number of arguments.
(define (classify x) (if (< x 0) "negative" (< x 10) "small" (< x 20) "medium" (>= x 30) "big" "n/a")) (classify 15) → "medium" (classify 100) → "big" (classify 22) → "n/a" (classify -10) → "negative"
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.
See also the when and unless functions.
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.
(ifft (fft '((1 0) (2 0) (3 0) (4 0)))) → ((1 0) (2 0) (3 0) (4 0)) ;; when imaginary part is 0, plain numbers work too (ifft (fft '(1 2 3 4))) → ((1 0) (2 0) (3 0) (4 0))
The inverse operation of ifft is the fft function.
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.
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.
If pointers are returned to strings or structures the following helper functions can be used extract data: get-char, get-int, get-float, get-string, unpack
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.
;; define LIBC platform independent
(define LIBC (lookup ostype '(
("Windows" "msvcrt.dll")
("OSX" "libc.dylib")
(import LIBC "printf")
(printf "%g %s %d %c\n" 1.23 "hello" 999 65)
1.23 hello 999 A
→ 17 ; return value
;; import MS Windows DLLs in 32-bit versions
(import "kernel32.dll" "GetTickCount") → GetTickCount
(import "user32.dll" "MessageBoxA") → MessageBoxA
(GetTickCount) → 3328896
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.
;;this pops up a message box (MessageBoxA 0 "This is the body" "Caption" 1)
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.
(import "kernel32.dll" "GetWindowsDirectoryA") ;; allocating space for a string return value (set 'str (dup "\000" 64)) ; reserve space and initialize (GetWindowsDirectoryA str (length str)) str → "C:\\WINDOWS\000\000\000 ... " ;; use trim or get-string to cut of trailing binary zeros (get-string str) → "C:\\WINDOWS" (trim str) → "C:\\WINDOWS" (import "kernel32.dll" "GetComputerNameA") ;; allocate memory and initialize to zeros (set 'str (dup "\000" 64)) (set 'len (length str) ;; call the function ;; the length of the string is passed as address reference ;; string str is automatically past by address (C pointer) (GetComputerNameA str (address len)) str → "LUTZ-PC\000\000 ... " (trim str) → "LUTZ-PC"
import returns the address of the function, which can be used to assign a different name to the imported function.
(set 'imprime (import "libc.so.6" "printf")) → printf@400862A0 (imprime "%s %d" "hola" 123) → "hola 123"
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.
;; force cdecl calling conventions on MS Windows
(import "sqlite.dll" "sqlite_open" "cdecl") → sqlite_open <673D4888>
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 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:
| label | C type for return value and arguments | newLISP return and argument type |
|---|---|---|
| "void" | void | nil is returned for return type |
| "byte" | byte unsigned 8 bit | integer |
| "char" | char signed 8 bit | integer |
| "unsigned short int" | unsigned short int 16 bit | integer |
| "short int" | short int signed 16 bit | integer |
| "unsigned int" | unsigned int 32 bit | integer |
| "int" | int signed 32 bit | integer |
| "long" | long signed 32 or 64 bit depending on platform | integer |
| "long long" | long long signed 64 bit | integer |
| "float" | float 32 bit | IEEE-754 64 bit float cut to 32-bit precision |
| "double" | double 64 bit | IEEE-754 64 bit float |
| "char*" | char* 32 or 64 bit ptr depending on platform | displayable string return (zero terminated) string buffer arg (no addr. since 10.4.2) |
| "void*" | void* 32 or 64 bit ptr depending on platform | integer address return either string buffer or integer address arg |
The types "char*" and "void* can be interchanged and are treated identical inside libffi. Depending on the type of arguments passed and the type of return values, one or the other is used.
Aggregate types can be composed using the struct function and can be used for arguments and return values.
The following examples show how the extended import syntax can handle return values of floating point values and strings:
;; return a float value, LIBC was defined earlier ; name return arg (import LIBC "atof" "double" "char*") (atof "3.141") → 3.141 ;; return a copied string ; name return arg-1 arg-2 (import LIBC "strcpy" "char*" "char*" "char*") (set 'from "Hello World") (set 'to (dup "\000" (length from))) ; reserve memory (strcpy to from) → "Hello World"
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*:
(import LIBC "strcpy" "void*" "char*" "char*") (set 'from "Hello World") (set 'to (dup "\000" (length from))) (strcpy to from) → 2449424 (address to) → 2449424 (unpack "s11" 2449424) → "Hello World" (get-string 2449424) → "Hello World" to → "Hello World"
A newLISP string is always passed by it's address reference.
For a more complex example see this OpenGL demo.
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.
Increments the number in place by 1.0 or by the optional number num and returns the result. inc performs float arithmetic and converts integer numbers passed into floating point type.
place is either a symbol or a place in a list structure holding a number, or a number returned by an expression.
(set 'x 0) → 0 (inc x) → 1 x → 1 (inc x 0.25) → 1.25 x → 1.25 (inc x) → 2.25
If a symbol for place contains nil, it is treated as if containing 0.0:
z → nil (inc z) → 1 (set 'z nil) (inc z 0.01) → 0.01
Places in a list structure or a number returned by another expression can be updated too:
(set 'l '(1 2 3 4)) (inc (l 3) 0.1) → 4.1 (inc (first l)) → 2 l → (2 2 3 4.1) (inc (+ 3 4)) → 8
Use the ++ function for incrementing numbers in integer mode. Use dec to decrement numbers in floating point mode.
Applies the predicate exp-predicate to each element of the list exp-list and returns a list containing the indices of the elements for which exp-predicate is true.
(index symbol? '(1 2 d 4 f g 5 h)) → (2 4 5 7) (define (big? x) (> x 5)) → (lambda (x) (> x 5)) (index big? '(1 10 3 6 4 5 11)) → (1 3 6) (select '(1 10 3 6 4 5 11) '(1 3 6)) → (10 6 11)
The predicate may be a built-in predicate, a user-defined function, or a lambda expression.
Use the filter function to return the elements themselves.
If the value in float is infinite the function returns true else nil.
(inf? (div 1 0)) → true (div 0 0) → NaN
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.
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).
(int "123") → 123 (int " 123") → 123 (int "a123" 0) → 0 (int (trim " 123")) → 123 (int "0xFF") → 255 (int "0b11111") → 31 (int "055") → 45 (int "1.567") → 1 (int 1.567) → 1 (integer? 1.00) → nil (integer? (int 1.00)) → true (int "1111" 0 2) → 15 ; base 2 conversion (int "0FF" 0 16) → 255 ; base 16 conversion (int 'xyz) → nil (int 'xyz 0) → 0 (int nil 123) → 123 (int "abc" (throw-error "not a number")) → ERR: user error : not a number (print "Enter a num:") (set 'num (int (read-line))) (int (bits 12345) 0 2) → 12345
The inverse function to int with base 2 is bits.
Use the float function to convert arguments to floating point numbers.
Returns true only if the value of exp is an integer; otherwise, it returns nil.
(set 'num 123) → 123 (integer? num) → true
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.
(intersect '(3 0 1 3 2 3 4 2 1) '(1 4 2 5) true)
→ (1 2 4 2 1)
See also the set functions difference, unique and union.
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.
(set 'A '((-1 1 1) (1 4 -5) (1 -2 0))) (invert A) → ((10 2 9) (5 1 4) (6 1 5)) (invert (invert A)) → ((-1 1 1) (1 4 -5) (1 -2 0)) ; solve Ax = b for x (multiply (invert A) '((1) (2) (3))) → ((41) (19) (23)) ; treatment of singular matrices (invert '((2 -1) (4 -2))) → nil (invert '((2 -1) (4 -2)) 0.0) → ((inf -inf) (inf -inf)) (invert '((2 -1) (4 -2)) 1e-20) → ((5e+19 -2.5e+19) (1e+20 -5e+19))
invert will return nil if the matrix is singular and cannot be inverted, and float-pivot is not specified.
All operations shown here on lists can be performed on arrays, as well.
See also the matrix functions det, mat, multiply and transpose.
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.
irr is often used to decide between different types of investments.
(irr '(-1000 500 400 300 200 100)) → 0.2027 (npv 0.2027 '(500 400 300 200 100)) → 1000.033848 ; ~ 1000 (irr '(-1000 500 400 300 200 100) '(0 3 4 5 6 7)) → 0.0998 (irr '(-5000 -2000 5000 6000) '(0 3 12 18)) → 0.0321
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.
See also the fv, nper, npv, pmt, and pv functions.
When json-parse returns nil due to a failed JSON data translation, this function retrieves an error description and the last scan position of the parser.
; failed parse returns nil
(json-parse [text]{"address" "http://example.com"}[/text]) → nil
; inspect the error information
(json-error) → ("missing : colon" 11)
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:
{
"name": "John Smith",
"age": 32,
"employed": true,
"address": {
"street": "701 First Ave.",
"city": "Sunnyvale, CA 95125",
"country": "United States"
},
"children": [
{
"name": "Richard",
"age": 7
},
{
"name": "Susan",
"age": 4
},
{
"name": "James",
"age": 3
}
]
}
The file is read, parsed and the resulting S-expression stored in jsp:
(set 'jsp (json-parse (read-file "person.json")))
→
( ("name" "John Smith")
("age" 32)
("employed" true)
("address" ( ("street" "701 First Ave.")
("city" "Sunnyvale, CA 95125")
("country" "United States")) )
("children" (
(("name" "Richard") ("age" 7))
(("name" "Susan") ("age" 4))
(("name" "James") ("age" 3))) )
)
Data can be extracted using assoc, lookup or ref:
; the address (lookup "address" jsp) → (("street" "701 First Ave.") ("city" "Sunnyvale, CA 95125") ("country" "United States")) ; the city of the address (lookup "city" (lookup "address" jsp)) → "Sunnyvale, CA 95125" ; a child named Susan (ref '(( * "Susan") *) jsp match true) → (("name" "Susan") ("age" 4)) ; all names (map last (ref-all '("name" *) jsp match true)) → ("John Smith" "Richard" "Susan" "James") ; only names of children (map last (ref-all '("name" *) (lookup "children" jsp) match true)) → ("Richard" "Susan" "James") ; names of children other method (map last (map first (lookup "children" jsp))) → ("Richard" "Susan" "James")
Although most of the time JSON object types are parsed, all JSON data types can be parsed directly, without occurring as part of a JSON object. The following examples show parsing of a JSON array:
; parse a JSON array data type
(json-parse "[1, 2, 3, 4, 5]") → (1 2 3 4 5)
When the UTF-8 capable version of newLISP is used, JSON formatted Unicode gets translated into UTF-8:
; parse a JSON object data type ands Unicode
; the outer {,} are newLISP string delimiters [text],[/text] tags could also be used
; the inner {,} are JSON object delimiters
(json-parse { {"greek letters" : "\u03b1\u03b2\u03b3\u03b4"} }) → (("greek letters" "αβγδ"))
; strings longer than 2047 bytes should be delimted with [text], [/text] tags
(json-parse [text]{"greek letters" : "\u03b1\u03b2\u03b3\u03b4"}[/text]) → (("greek letters" "αβγδ"))
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.
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.
(set 'lst '("this" "is" "a" "sentence"))
(join lst " ") → "this is a sentence"
(join (map string (slice (now) 0 3)) "-") → "2003-11-26"
(join (explode "keep it together")) → "keep it together"
(join '("A" "B" "C") "-") → "A-B-C"
(join '("A" "B" "C") "-" true) → "A-B-C-"
See also the append, string, and explode functions, which are the inverse of the join operation.
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.
; centroids from previous kmeans-train K:centroids → ( (6.39 7.188333333 5.935) (7.925714286 3.845714286 9.198571429) (2.207142857 2.881428571 0.8885714286) ) (kmeans-query '(1 2 3) K:centroids) → (8.036487279 9.475994267 2.58693657) ; distances to cluster 1, 2 and 3
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:
(kmeans-query '(1 2 3) data) → (10.91671196 3.190626898 9.19723328 3.014415366 9.079763213 6.83130295 8.533111976 9.624816881 6.444261013 2.013107051 3.186549858 9.475199206 9.32936761 2.874786949 7.084638311 10.96221237 10.50080473 3.162419959 2.423674896 9.526436899) ; show distances to members in each cluster ; for cluster labeled 1 (select (kmeans-query '(1 2 3) data) (K:clusters 0)) → (9.079763213 6.83130295 9.624816881 6.444261013 7.084638311 10.50080473) ; for cluster labeled 2 (select (kmeans-query '(1 2 3) data) (K:clusters 1)) → (10.91671196 9.19723328 8.533111976 9.475199206 9.32936761 10.96221237 9.526436899) ; for cluster labeled 3 (select (kmeans-query '(1 2 3) data) (K:clusters 2)) → (3.190626898 3.014415366 2.013107051 3.186549858 2.874786949 3.162419959 2.423674896)
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.
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 * m matrix-data and the optional k * m matrix-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.
(set 'data '( (6.57 4.96 11.91) (2.29 4.18 1.06) (8.63 2.51 8.11) (1.85 1.89 0.11) (7.56 7.93 5.06) (3.61 7.95 5.11) (7.18 3.46 8.7) (8.17 6.59 7.49) (5.44 5.9 5.57) (2.43 2.14 1.59) (2.48 2.26 0.19) (8.16 3.83 8.93) (8.49 5.31 7.47) (3.12 3.1 1.4) (6.77 6.04 3.76) (7.01 4.2 11.9) (6.79 8.72 8.62) (1.17 4.46 1.02) (2.11 2.14 0.85) (9.44 2.65 7.37))) (kmeans-train data 3 'MAIN:K) → (439.7949357 90.7474276 85.06633163 82.74597619) ; cluster membership K:labels → (2 3 2 3 1 1 2 1 1 3 3 2 2 3 1 2 1 3 3 2) ; the centroid for each cluster K:centroids → ( (6.39 7.188333333 5.935) (7.925714286 3.845714286 9.198571429) (2.207142857 2.881428571 0.8885714286) )
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:
; average inner deviations of cluster members to the centroid ; deviation = sqrt(ssq-of-cluster / n-of-cluster) K:deviations → (2.457052209 2.260089397 1.240236975) ; calculating inner SSQs from cluster deviations (map mul '(6 7 7) (map mul K:deviations K:deviations)) → (36.22263333 35.75602857 10.76731429) ; inner SSQs ; SSQ from last iteration as sum of inner SSQs (apply add '(36.22263333 35.75602857 10.76731429)) → 82.74597619
K:clusters gives indices of data records into the original data for each cluster. With these, individual clusters can be extracted from the data for further analysis:
; ceach of the result clusters with indices into the data set K:clusters → ( (4 5 7 8 14 16) (0 2 6 11 12 15 19) (1 3 9 10 13 17 18) ) ; cluster of data records labeled 1 at offset 0 (select data (K:clusters 0)) → ( (7.56 7.93 5.06) (3.61 7.95 5.11) (8.17 6.59 7.49) (5.44 5.9 5.57) (6.77 6.04 3.76) (6.79 8.72 8.62) ) ; cluster of data records labeled 2 at offset 1 (select data (K:clusters 1)) → ( (6.57 4.96 11.91) (8.63 2.51 8.11) (7.18 3.46 8.7) (8.16 3.83 8.93) (8.49 5.31 7.47) (7.01 4.2 11.9) (9.44 2.65 7.37) ) ; cluster of data records labeled 3 at offset 2 (select data (K:clusters 2)) → ( (2.29 4.18 1.06) (1.85 1.89 0.11) (2.43 2.14 1.59) (2.48 2.26 0.19) (3.12 3.1 1.4) (1.17 4.46 1.02) (2.11 2.14 0.85) )
In the last example the cluster labels (from 1 to 3) are added to the data:
; append a cluster label to each data record
(set 'labeled-data (transpose (push K:labels (transpose data) -1)))
labeled-data: →
( (6.57 4.96 11.91 2)
(2.29 4.18 1.06 3)
(8.63 2.51 8.11 2)
(1.85 1.89 0.11 3)
(7.56 7.93 5.06 1)
(3.61 7.95 5.11 1)
... ...
(2.11 2.14 0.85 3)
(9.44 2.65 7.37 2) )
The result context should be prefixed with MAIN when code is written in a namespace context. If the context does not exists already, it will be created.
Results in K:labels, K:clusters, K:centroids and K:deviations will be overwritten, if already present from previous runs of kmeans-train.
See the description of fn, which is a shorter form of writing lambda.
See the description of define-macro.
Returns true only if the value of exp is a lambda expression; otherwise, returns nil.
(define (square x) (* x x)) → (lambda (x) (* x x)) square → (lambda (x) (* x x)) (lambda? square) → true
See define and define-macro for more information about lambda expressions.
Returns the last element of a list or a string.
(last '(1 2 3 4 5)) → 5 (last '(a b (c d))) → (c d) (set 'A (array 3 2 (sequence 1 6))) → ((1 2) (3 4) (5 6)) (last A) → (5 6) (last '()) → ERR: list is empty
In the second version the last character in the string str is returned as a string.
(last "newLISP") → "P"
Note that last works on character boundaries rather than byte boundaries when the UTF-8–enabled version of newLISP is used. See also first, rest and nth.
Reports the last error generated by newLISP due to syntax errors or exhaustion of some resource. For a summary of all possible errors see the chapter Error codes in the appendix.
If no error has occurred since the newLISP session was started, nil is returned.
When int-error is specified, a list of the number and the error text is returned.
(last-error) → nil (abc) ERR: invalid function : (abc) (last-error) → (24 "ERR: invalid function : (abc)") (last-error 24) → (24 "invalid function") (last-error 1) → (1 "not enough memory") (last-error 12345) → (12345 "Unknown error")
For error numbers out of range the string "Unknown error" is given for the error text.
Errors can be trapped by error-event and user defined error handlers.
See also net-error for errors generated by networking conditions and sys-error for errors generated by the operating system.
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:
(symbol? (sym "one two")) → true (legal? "one two") → nil ; contains a space (set (sym "one two") 123) → 123 (eval (sym "one two")) → 123
The example shows that the string "one two" does not contain a legal symbol although a symbol can be created from this string and treated like a variable.
Returns the number of elements in a list, the number of rows in an array and the number of bytes in a string or in a symbol name.
Applied to a number, length returns the number of digits for normal and big integers and the number of digits before the decimal separator for floats.
length returns 0 on all other types.
Before version 10.5.6 length returned the storage size in bytes for integers (4 or 8) and floats (8).
; number of top level elements in a list (length '(a b (c d) e)) → 4 (length '()) → 0 (set 'someList '(q w e r t y)) → (q w e r t y) (length someList) → 6 ; number of top level elements in an array (set 'ary (array 2 4 '(0))) → ((1 2 3 4) (5 6 7 8)) (length ary) → 2 ; number of bytes in a string or byte buffer (length "Hello World") → 11 (length "") → 0 (length "\000\001\003") → 3 ; number of bytes in a symbol name string (length 'someVar) → 7 ; number of int digits in a number (length 0) → 0 (length 123) → 3 (length 1.23) → 1 (length 1234567890123456789012345L) → 25
Use utf8len to calculate the number of UTF-8 characters in a string.
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.
(define (sum-sq a b)
(let ((x (* a a)) (y (* b b)))
(+ x y)))
(sum-sq 3 4) → 25
(define (sum-sq a b) ; alternative syntax
(let (x (* a a) y (* b b))
(+ x y)))
The variables x and y are initialized, then the expression (+ x y) is evaluated. The let form is just an optimized version and syntactic convenience for writing:
((lambda (sym1 [sym2 ... ]) exp-body ) exp-init1 [ exp-init2 ])
See also letn for an incremental or nested form of let and local for initializing to nil. See local for automatic initialization of variables to nil.
This function combines let and expand to expand local variables into an expression before evaluating it. In the fully parenthesized first syntax initializers are optional and assumed nil if missing.
Both forms provide the same functionality, but in the second form the parentheses around the initializers can be omitted:
(letex (x 1 y 2 z 3) '(x y z)) → (1 2 3) (letex ( (x 1) (y '(a b c)) (z "hello") ) '(x y z)) → (1 (a b c) "hello")
Before the expression '(x y z) gets evaluated, x, y and z are literally replaced with the initializers from the letex initializer list. The final expression which gets evaluated is '(1 2 3).
In the second example a function make-adder is defined for making adder functions:
(define (make-adder n)
(letex (c n) (lambda (x) (+ x c))))
(define add3 (make-adder 3)) → (lambda (x) (+ x 3))
(add3 10) → 13
; letex can expand symbols into themselves
; the following form also works
(define (make-adder n)
(letex (n n) (lambda (x) (+ x n))))
letex evaluates n to the constant 3 and replaces c with it in the lambda expression. The second examples shows, how a letex variable can be expanded into itself.
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.
The following comparison of let and letn show the difference:
(set 'x 10) (let ((x 1) (y (+ x 1))) (list x y)) → (1 11) (letn ((x 1) (y (+ x 1))) (list x y)) → (1 2)
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.
(letn (x 1 y x)
(+ x y)) → 2
;; same as nested let's
(let (x 1)
(let (y x)
(+ x y))) → 2
letn works like several nested let. The parentheses around the initializer expressions can be omitted.
The exp are evaluated and the values used to construct a new list. Note that arguments of array type are converted to lists. See the chapter Arrays for dealing with multidimensional lists.
(list 1 2 3 4 5) → (1 2 3 4 5) (list 'a '(b c) (+ 3 4) '() '*) → (a (b c) 7 () *)
See also cons and push for other forms of building lists.
Returns true only if the value of exp is a list; otherwise returns nil. Note that lambda and lambda-macro expressions are also recognized as special instances of a list expression.
(set 'var '(1 2 3 4)) → (1 2 3 4) (list? var) → true (define (double x) (+ x x)) (list? double) → true
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.
(load "myfile.lsp") (load "a-file.lsp" "b-file.lsp") (load "file.lsp" "http://mysite.org/mypro") (load "http://192.168.0.21:6000//home/test/program.lsp") (load "a-file.lsp" "b-file.lsp" 'MyCTX) (load "file:///usr/local/share/newlisp/mysql.lsp")
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.
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.
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).
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.
See also Indexing elements of strings and lists.
lookup is similar to assoc but goes one step further by extracting a specific element found in the list.
(set 'params '(
(name "John Doe")
(age 35)
(gender "M")
(balance 12.34)
))
(lookup 'age params) → 35
; use together with setf to modify and association list
(setf (lookup 'age params) 42) → 42
(lookup 'age params) → 42
(set 'persons '(
("John Doe" 35 "M" 12.34)
("Mickey Mouse" 65 "N" 12345678)
))
(lookup "Mickey Mouse" persons 2) → "N"
(lookup "Mickey Mouse" persons -3) → 65
(lookup "John Doe" persons 1) → 35
(lookup "John Doe" persons -2) → "M"
(lookup "Jane Doe" persons 1 "N/A") → "N/A"
See also assoc
Converts the characters of the string in str to lowercase. A new string is created, and the original is left unaltered.
(lower-case "HELLO WORLD") → "hello world" (set 'Str "ABC") (lower-case Str) → "abc" Str → "ABC"
See also the upper-case and title-case functions.
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.
Symbols defined with macro are protected from re-definition.
(macro (double X) (+ X X)) → (lambda-macro (X) (expand '(+ X X))) (double 123) → 246 (protected? 'double) → true
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:
; change existing macro 'double' to allow floating point parameters ; use upper-case for variables for expansion (constant 'double (lambda-macro (X) (expand '(add X X)))) → (lambda-macro (X) (expand '(add X X))) (double 1.23) → 2.46
Note, that constant can be used only to re-define macros, not to create new macros. Internally newLISP knows that macro defined symbols are executed during source reading, not evaluation.
The redefinition will only affect future read code, it will not affect code already load and translated by the reader routines.
When mapping macros using map or apply the expansion function is mapped:
> (macro (double X) (+ X X)) (lambda-macro (X) (expand '(+ X X))) > (map double '(1 2 3 4 5)) ((+ 1 1) (+ 2 2) (+ 3 3) (+ 4 4) (+ 5 5)) > (map eval (map double '(1 2 3 4 5))) (2 4 6 8 10) > (apply double '(10)) (+ 10 10) >
This is useful to find out how the expansion mechanism of our macro definition works during source load time.
macro definitions are not susceptible to variable capture as are fexprs made with define-macro:
(define-macro (fexpr-add A B)
(+ (eval A) (eval B)))
(macro (mac-add A B)
(+ A B))
(set 'A 11 'B 22)
; variable capture when using the same symbols
; used as locals in define-macro for callling
(fexpr-add A B) →
; or
(fexpr-add B A) →
ERR: value expected : A
called from user defined function fexpr-add
; no variable capture when doing the same with
; expansion macros
(mac-add A B) → 33
(mac-add B A) → 33
But expansion macros using macro are susceptible to unwanted double evaluation, just like define-macro is:
(define-macro (fexpr-double X)
(+ (eval X) (eval X)))
(macro (mac-double X)
(+ X X))
(set 'a 10)
(fexpr-double (inc a)) → 23 ; not 22 as expected
(set 'a 10)
(mac-double (inc a)) → 23 ; not 22 as expected
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.
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.
(define-macro (mysetq lv rv) (set lv (eval rv))) (macro? mysetq) → true (macro (my-setq Lv Rv) (set 'Lv Rv)) → (lambda-macro (Lv Rv) (expand '(set 'Lv Rv))) ; my-setq contains a lambda-macro expression (macro? my-setq) → true ; my-setq symbol was created with macro function (macro? 'my-setq) → true
main-args returns a list with several string members, one for program invocation and one for each of the command-line arguments.
newlisp 1 2 3
> (main-args)
("/usr/local/bin/newlisp" "1" "2" "3")
After newlisp 1 2 3 is executed at the command prompt, main-args returns a list containing the name of the invoking program and three command-line arguments.
Optionally, main-args can take an int-index for indexing into the list. Note that an index out of range will cause nil to be returned, not the last element of the list like in list-indexing.
newlisp a b c > (main-args 0) "/usr/local/bin/newlisp" > (main-args -1) "c" > (main-args 2) "b" > (main-args 10) nil
Note that when newLISP is executed from a script, main-args also returns the name of the script as the second argument:
#!/usr/local/bin/newlisp
#
# script to show the effect of 'main-args' in script file
(print (main-args) "\n")
(exit)
# end of script file
;; execute script in the OS shell:
script 1 2 3
("/usr/local/bin/newlisp" "./script" "1" "2" "3")
Try executing this script with different command-line parameters.
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---).
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.
(map + '(1 2 3) '(50 60 70)) → (51 62 73) (map if '(true nil true nil true) '(1 2 3 4 5) '(6 7 8 9 10)) → '(1 7 3 9 5) (map (fn (x y) (* x y)) '(3 4) '(20 10)) → (60 40)
The second example shows how to dynamically create a function for map:
(define (foo op p)
(append (lambda (x)) (list (list op p 'x))))
We can also use the shorter fn:
(define (foo op p)
(append (fn (x)) (list (list op p 'x))))
foo now works like a function-maker:
(foo 'add 2) → (lambda (x) (add 2 x)) (map (foo add 2) '(1 2 3 4 5)) → (3 4 5 6 7) (map (foo mul 3) '(1 2 3 4 5)) → (3 6 9 12 15)
Note that the quote before the operand can be omitted because primitives evaluate to themselves in newLISP.
By incorporating map into the function definition, we can do the following:
(define (list-map op p lst)
(map (lambda (x) (op p x)) lst))
(list-map + 2 '(1 2 3 4)) → (3 4 5 6)
(list-map mul 1.5 '(1 2 3 4)) → (1.5 3 4.5 6)
map also sets the internal list index $idx.
(map (fn (x) (list $idx x)) '(a b c)) → ((0 a) (1 b) (2 c))
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).
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.
(set 'A '((1 2 3) (4 5 6))) (set 'B A) (mat + A B) → ((2 4 6) (8 10 12)) (mat - A B) → ((0 0 0) (0 0 0)) (mat * A B) → ((1 4 9) (16 25 36)) (mat / A B) → ((1 1 1) (1 1 1)) ; specify the operator in a variable (set 'op +) (mat op A B) → ((2 4 6) (8 10 12))
Using the second syntax, all cells in matrix-A are operated on with a scalar in number:
(mat + A 5) → ((6 7 8) (9 10 11)) (mat - A 2) → ((-1 0 1) (2 3 4)) (mat * A 3) → ((3 6 9) (12 15 18)) (mat / A 10) → ((.1 .2 .3) (.4 .5 .6))
See also the other matrix operations det, invert, multiply, and transpose.
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.
match is frequently employed as a functor parameter in find, ref, ref-all and replace and is internally used by find-all for lists.
(match '(a ? c) '(a b c)) → (b) (match '(a ? ?) '(a b c)) → (b c) (match '(a ? c) '(a (x y z) c)) → ((x y z)) (match '(a ? c) '(a (x y z) c) true) → (a (x y z) c) (match '(a ? c) '(a x y z c)) → nil (match '(a * c) '(a x y z c)) → ((x y z)) (match '(a (b c ?) x y z) '(a (b c d) x y z)) → (d) (match '(a (*) x ? z) '(a (b c d) x y z)) → ((b c d) y) (match '(+) '()) → nil (match '(+) '(a)) → ((a)) (match '(+) '(a b)) → ((a b)) (match '(a (*) x ? z) '(a () x y z)) → (() y) (match '(a (+) x ? z) '(a () x y z)) → nil
Note that the * operator tries to grab the fewest number of elements possible, but match backtracks and grabs more elements if a match cannot be found.
The + operator works similarly to the * operator, but it requires at least one list element.
The following example shows how the matched expressions can be bound to variables.
(map set '(x y) (match '(a (? c) d *) '(a (b c) d e f))) x → b y → (e f)
Note that match for strings has been eliminated. For more powerful string matching, use regex, find, find-all or parse.
unify is another function for matching expressions in a PROLOG like manner.
Evaluates the expressions num-1— and returns the largest number.
(max 4 6 2 3.54 7.1) → 7.1
See also the min function.
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.
(set 'aList '(a b c d e f g h)) → (a b c d e f g h) (member 'd aList) → (d e f g h) (member 55 aList) → nil
In the second syntax, member searches for str-key in str. If str-key is found, all of str (starting with str-key) is returned. nil is returned if nothing is found.
(member "LISP" "newLISP") → "LISP" (member "LI" "newLISP") → "LISP" (member "" "newLISP") → "newLISP" (member "xyz" "newLISP") → nil (member "li" "newLISP" 1) → "LISP"
See also the related functions slice and find.
Evaluates the expressions num-1— and returns the smallest number.
(min 4 6 2 3.54 7.1) → 2
See also the max function.
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.
(mod 10.5 3.3) → 0.6 (mod -10.5 3.3) → -0.6 (mod -10.5) → -0.5
Use the % (percent sign) function when working with integers only.
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
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.
(set 'A '((1 2 3) (4 5 6))) (set 'B '((1 2) (1 2) (1 2))) (multiply A B) → ((6 12) (15 30)) (set 'v '(10 20 30)) (multiply A (transpose (list v))) → ((140) (320))
When multiplying a matrix with a vector of n elements, the vector must be transformed into n rows by 1 column matrix using transpose.
All operations shown here on lists can be performed on arrays, as well.
See also the matrix operations det, invert, mat and transpose.
This function is deprecated, use term instead.
Tests if the result of a floating point math operation is a NaN. Certain floating point operations return a special IEEE 754 number format called a NaN for 'Not a Number'.
; floating point operation on NaN yield NaN (set 'x (sqrt -1)) → NaN (NaN? x) → true (add x 123) → NaN (mul x 123) → NaN ; integer operations treat NaN as zero (+ x 123) → 123 (* x 123) → 0 ; comparisons with NaN values yield nil (> x 0) → nil (<= x 0) → nil (= x x) → nil (set 'infinity (mul 1.0e200 1.0e200)) → inf (NaN? (sub infinity infinity)) → true
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 not true when using ANSI C. Integer operations treat NaN as 0 (zero) values.
See also inf? for testing a floating point value for infinity.
Accepts a connection on a socket previously put into listening mode. Returns a newly created socket handle for receiving and sending data on this connection.
(set 'socket (net-listen 1234)) (net-accept socket)
Note that for ports less than 1024, newLISP must be started in superuser mode on Unix-like operating systems.
See also the files server and client examples in the examples/ directory of the source distribution.
Closes a network socket in int-socket that was previously created by a net-connect or net-accept function. Returns true on success and nil on failure.
(net-close aSock)
The optional true flag suppresses immediate shutdown of sockets by waiting for pending data transmissions to finish.
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.
(set 'socket (net-connect "example.com" 80)) (net-send socket "GET /\r\n\r\n") (net-receive socket buffer 10000) (println buffer) (exit)
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:
(set 'host (main-args 2))
(println "Scanning: " host)
(for (port 1 1024)
(if (set 'socket (net-connect host port 500))
(println "open port: " port " " (or (net-service port "tcp") ""))
(print port "\r"))
)
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.
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.
;; example server (net-listen 4096 "226.0.0.1" "udp") → 5 (net-receive-from 5 20) ;; example client I (net-connect "226.0.0.1" 4096 "udp") → 3 (net-send 3 "hello") ;; example client II (net-connect "" 4096 "udp") → 3 (net-send-to "226.0.0.1" 4096 "hello" 3)
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.
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.
;; example client I (net-connect "" 4096 "multi") → 3 (net-send-to "226.0.0.1" 4096 "hello" 3) ;; example client II (net-connect "226.0.0.1" 4096 "multi") → 3 (net-send 3 "hello") ;; example server (net-listen 4096 "226.0.0.1" "multi") → 5 (net-receive-from 5 20) → ("hello" "192.168.1.94" 32769)
On the server side, net-peek or net-select can be used for non-blocking communications. In the above example, the server would block until a datagram is received.
The address 226.0.0.1 is just one multicast address in the Class D range of multicast addresses from 224.0.0.0 to 239.255.255.255.
The net-send and net-receive functions can also be used instead of net-send-to and net-receive-from.
Specifying the string "broadcast" or "b" in the third parameter, str-mode, causes UDP broadcast communications to be set up. In this case, the broadcast address ending in 255 is used.
;; example client (net-connect "192.168.2.255" 3000 "broadcast") → 3 (net-send 3 "hello") ;; example server (net-listen 3000 "" "udp") → 5 (net-receive 5 buff 10) buff → "hello" ;; or (net-receive-from 5 10) → ("hello" "192.168.2.1" 46620)
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.
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.
(net-connect "/tmp/mysocket") → 3
; on OS/2 use "\\socket\\" prefix
(net-connect "\\socket\\mysocket")
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.
Retrieves the last error that occurred when calling a any of the following functions: net-accept, net-connect, net-eval, net-listen, net-lookup, net-receive, net-receive-udp, net-select, net-send, net-send-udp, and net-service. Whenever one of these functions fails, it returns nil and net-error can be used to retrieve more information.
Functions that communicate using sockets close the socket automatically and remove it from the net-sessions list.
Each successful termination of a net-* function clears the error number.
The following messages are returned:
| no | description |
|---|---|
| 1 | Cannot open socket |
| 2 | DNS resolution failed |
| 3 | Not a valid service |
| 4 | Connection failed |
| 5 | Accept failed |
| 6 | Connection closed |
| 7 | Connection broken |
| 8 | Socket send() failed |
| 9 | Socket recv() failed |
| 10 | Cannot bind socket |
| 11 | Too many sockets in net-select |
| 12 | Listen failed |
| 13 | Badly formed IP |
| 14 | Select failed |
| 15 | Peek failed |
| 16 | Not a valid socket |
| 17 | Cannot unblock socket |
| 18 | Operation timed out |
| 19 | HTTP bad formed URL |
| 20 | HTTP file operation failed |
| 21 | HTTP transfer failed |
| 22 | HTTP invalid response from server |
| 23 | HTTP no response from server |
| 24 | HTTP no content |
| 25 | HTTP error in header |
| 26 | HTTP error in chunked format |
(net-error) → nil (net-connect "jhghjgkjhg" 80) → nil (net-error) → (2 "ERR: "DNS resolution failed")
When int-error is specified the number and error text for that error number is returned.
(net-error 10) → (10 "Cannot bind socket")
See also last-error and sys-error.
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 remote TCP/IP servers are started in the following way:
newlisp -c -d 4711 & ; preloading function definitions newlisp preload.lsp -c -d 12345 & ; logging connections newlisp -l -c -d 4711 & ; communicating via Unix local domain sockets newlisp -c /tmp/mysocket
The -c option is necessary to suppress newLISP emitting prompts.
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 code to be evaluated is given in a quoted expression (net-eval "192.168.1.94" 4711 '(+ 3 4)) → 7 ; expression as a string (only one expression should be in the string) (net-eval "192.168.1.94" 4711 "(+ 3 4)") → 7 ; with timeout (net-eval "192.168.1.94" 4711 '(+ 3 4) 1) → nil ; 1ms timeout too short (net-error) → (17 "ERR: Operation timed out") (net-eval "192.168.1.94" 4711 '(+ 3 4) 1000) → 7 ; program contained in a variable (set 'prog '(+ 3 4)) (net-eval "192.168.1.94" 4711 prog) → 7 ; specify a local-domain Unix socket (not available on MS Windows) (net-eval "/tmp/mysocket" 0 '(+ 3 4)) → 7
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.
; two different remote nodes different IPs
(net-eval '(
("192.168.1.94" 4711 '(+ 3 4))
("192.168.1.95" 4711 '(+ 5 6))
) 5000)
→ (7 11)
; two persistent nodes on the same CPU different ports
(net-eval '(
("localhost" 8081 '(foo "abc"))
("localhost" 8082 '(myfunc 123)')
) 3000)
; inetd or xinetd nodes on the same server and port
; nodes are loaded on demand
(net-eval '(
("localhost" 2000 '(foo "abc"))
("localhost" 2000 '(myfunc 123))
) 3000)
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.
(define (myhandler param)
(if param
(println param))
)
(set 'Nodes '(
("192.168.1.94" 4711)
("192.168.1.95" 4711)
))
(set 'Progs '(
(+ 3 4)
(+ 5 6)
))
(net-eval (map (fn (n p) (list (n 0) (n 1) p)) Nodes Progs) 5000 myhandler)
→
("192.168.1.94" 4711 7)
("192.168.1.95" 4711 11)
The example shows how the list of node specs can be assembled from a list of nodes and sources to evaluate. This may be useful when connecting to a larger number of remote nodes.
(net-eval (list (list (Nodes 0 0) (Nodes 0 1) (Progs 0)) (list (Nodes 1 0) (Nodes 1 1) (Progs 1)) ) 3000 myhandler)
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.
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-interface "192.168.1.95") → "192.168.1.95" (net-interface "localhost") → "127.0.0.1"
An interface address can be defined as either an IP address or a name. The return value is the address given in str-ip-addr
Switches between IPv4 and IPv6 internet protocol versions. int-version contains either a 4 for IPv4 or a 6 for IPv6. When no parameter is given, net-ipv returns the current setting.
(net-ipv) → 4 (net-ipv 6) → 6
By default newLISP starts up in IPv4 mode. The IPv6 protocol mode can also be specified from the commandline when starting newlisp:
newlisp -6
Once a socket is connected with either net-connect or listened on with net-listen, the net-accept, net-select, net-send, net-receive and net-receive-from functions automatically adjust to the address protocol used when creating the sockets. Different connections with different IPv4/6 settings can be open at the same time.
Note, that currently net-packet does not support IPv6 and will work in IPv4 mode regardless of settings.
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.
(set 'port 1234)
(set 'listen (net-listen port))
(unless listen (begin
(print "listening failed\n")
(exit)))
(print "Waiting for connection on: " port "\n")
(set 'connection (net-accept listen))
(if connection
(while (net-receive connection buff 1024 "\n")
(print buff)
(if (= buff "\r\n") (exit)))
(print "Could not connect\n"))
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")
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.
(net-listen "/tmp/mysocket") → 5
; on OS/2 use "\\socket\\" prefix
(net-listen "\\socket\\mysocket")
(net-accept 5)
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.
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.
(net-listen 10002 "192.168.1.120" "udp") (net-listen 10002 "" "udp")
The first example listens on a specific network adapter, while the second example listens on the default adapter. Both calls return a socket number that can be used in subsequent net-receive, net-receive-from, net-send-to, net-select, or net-peek function calls.
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.
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.
;; example client (net-connect "226.0.0.1" 4096 "multi") → 3 (net-send-to "226.0.0.1" 4096 "hello" 3) ;; example server (net-listen 4096 "226.0.0.1" "multi") → 5 (net-receive-from 5 20) → ("hello" "192.168.1.94" 32769)
On the server side, net-peek or net-select can be used for non-blocking communications. In the example above, the server would block until a datagram is received.
The net-send and net-receive functions can be used instead of net-send-to and net-receive-from.
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.
The net-receive-from and net-send-to functions are used to read and write raw packets on the divert socket created and returned by the net-listen statement. The same address received by net-receive-from is used in the net-send-to call when re-injecting the packet:
; rules have been previously configured for a divert port
(set 'divertSocket (net-listen divertPort "" "divert"))
(until (net-error)
(set 'rlist (net-receive-from divertSocket maxBytes))
(set 'buffer (rlist 1))
; buffer can be processed here before reinjecting
(net-send-to (rlist 0) divertPort buffer divertSocket)
)
For more information see the Unix man pages for divert and the ipfw (BSDs) or ipchains (Linux) configuration utilities.
Returns the IP number and port of the local computer for a connection on a specific int-socket.
(net-local 16) → ("204.179.131.73" 1689)
Use the net-peer function to access the remote computer's IP number and port.
Returns either a hostname string from str-ip-number in IP dot format or the IP number in dot format from str-hostname:
(net-lookup "209.24.120.224") → "www.nuevatec.com" (net-lookup "www.nuevatec.com") → "209.24.120.224" (net-lookup "216.16.84.66.sbl-xbl.spamhaus.org" true) → "216.16.84.66"
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.
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.
When custom configured packets contain zeros in the checksum fields, net-packet will calculate and insert the correct checksums. Already existing checksums stay untouched.
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.
; packet as generated by: (net-send-udp "192.168.1.92" 12345 "Hello World")
(set 'udp-packet (pack (dup "b" 39) '(
0x45 0x00 0x00 0x27 0x4b 0x8f 0x00 0x00 0x40 0x11 0x00 0x00 192 168 1 95
192 168 1 92 0xf2 0xc8 0x30 0x39 0x00 0x13 0x00 0x00 0x48 0x65 0x6c 0x6c
0x6f 0x20 0x57 0x6f 0x72 0x6c 0x64)))
(unless (net-packet udp-packet)
(println "net-error: " (net-error))
(println "sys-error: " (sys-error)))
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.
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.
(set 'aSock (net-connect "aserver.com" 123))
(while ( = (net-peek aSock) 0)
(do-something-else))
(net-receive aSock buff 1024)
After connecting, the program waits in a while loop until aSock can be read.
Use the peek function to check file descriptors and stdin.
Returns the IP number and port number of the remote computer for a connection on int-socket.
(net-peer 16) → ("192.100.81.100" 13)
Use the net-local function to access the local computer's IP number and port number.
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.
(net-ping "newlisp.org") → (("66.235.209.72" 634080)) (net-ping "127.0.0.1") → (("127.0.0.1" 115)) (net-ping "yahoo.com" 3000) → nil
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.
(net-ping '("newlisp.org" "192.168.1.255") 2000 20)
→ (("66.235.209.72" 826420) ("192.168.1.1" 124) ("192.168.1.254" 210))
(net-ping "192.168.1.*" 500) ; from 1 to 254
→ (("192.168.1.1" 120) ("192.168.1.2" 245) ("192.168.2.3" 180) ("192.168.2.254" 234))
(net-ping "192.168.1.*" 500 2) ; returns after 2 responses
→ (("192.168.1.3" 115) ("192.168.1.1" 145))
(net-ping "192.168.1.1-10" 1000) ; returns after 1 second
→ (("192.168.1.3" 196) ("192.168.1.1" 205))
(net-ping '("192.168.1.100-120" "192.168.1.124-132") 2000) ; returns after 2 seconds
→ ()
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.
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.
(define (gettime)
(set 'socket (net-connect "netcom.com" 13))
(net-receive socket buf 256)
(print buf "\n")
(net-close socket))
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.
(define (net-receive-line socket sBuff)
(net-receive socket sBuff 256 "\n"))
(set 'bytesReceived (net-receive-line socket 'sm))
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 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.
;; bind port 1001 and the default address (net-listen 1001 "" "udp") → 1980 ;; optionally poll for arriving data with 100ms timeout (while (not (net-select 1980 "r" 100000)) (do-something ... )) (net-receive-from 1980 20) → ("hello" "192.168.0.5" 3240) ;; send answer back to sender (net-send-to "192.168.0.5" 3240 "hello to you" 1980) (net-close 1980) ; close socket
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.
For blocking short UDP transactions, see the net-send-udp and net-receive-udp functions.
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.
;; wait for datagram with maximum 20 bytes (net-receive-udp 10001 20) ;; or (net-receive-udp 10001 20 5000000) ; wait for max 5 seconds ;; executed on remote computer (net-send-udp "nuevatec.com" 1001 "Hello") → 4 ;; returned from the net-receive-udp statement → ("Hello" "128.121.96.1" 3312) ;; sending binary information (net-send-udp "ahost.com" 2222 (pack "c c c c" 0 1 2 3)) → 4 ;; extracting the received info (set 'buff (first (net-receive-udp 2222 10))) (print (unpack "c c c c" buff)) → (0 1 2 3)
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.
As an alternative, UDP communication can be set up using net-listen, or net-connect together with the "udp" option to make non-blocking data exchange possible with net-receive-from and net-send-to.
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.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.
(set 'listen-socket (net-listen 1001))
;; wait for connection
(while (not (net-select listen-socket "read" 1000))
(if (net-error) (print (net-error))))
(set 'connection (net-accept listen-socket))
(net-send connection "hello")
;; wait for incoming message
(while (not (net-select connection "read" 1000))
(do-something))
(net-receive connection buff 1024)
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:
(set 'listen-list '(1001 1002))
; accept-connection, read-connection and write-connection
; are user defined functions
(while (not (net-error))
(dolist (conn (net-select listen-list "r" 1000))
(accept-connection conn)) ; build an accept-list
(dolist (conn (net-select accept-list "r" 1000))
(read-connection conn)) ; read on connected sockets
(dolist (conn (net-select accept-list "w" 1000))
(write-connection conn))) ; write on connected sockets
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.
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.
On failure, use net-error to get more error information.
(set 'buf "hello there") (net-send sock buf) → 11 (net-send sock buf 5) → 5 (net-send sock "bye bye") → 7
The first net-send sends the string "hello there", while the second net-send sends only the string "hello".
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.
;;;;;;;;;;;;;;;;;; UDP server
(set 'socket (net-listen 10001 "" "udp"))
(if socket (println "server listening on port " 10001)
(println (net-error)))
(while (not (net-error))
(set 'msg (net-receive-from socket 255))
(println "-> " msg)
(net-send-to (nth 1 msg) (nth 2 msg)
(upper-case (first msg)) socket))
;;;;;;;;;;;;;;;;;; UDP client
(set 'socket (net-listen 10002 "" "udp"))
(if (not socket) (println (net-error)))
(while (not (net-error))
(print "> ")
(net-send-to "127.0.0.1" 10001 (read-line) socket)
(net-receive socket buff 255)
(println "-> " buff))
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.
See also the net-receive-from function and the net-listen function with the "udp" option.
For blocking short UDP transactions use net-send-udp and net-receive-udp.
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 bool true 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.
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"
Returns a list of active listening and connection sockets.
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.
(new CTX 'CTX-2) → CTX-2 ;; force overwrite of existing symbols (new CTX MyCTX true) → MyCTX
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:
(set 'foo:x 123) (set 'bar:y 999) (set 'ctxa foo) (set 'ctxb bar) (new ctxa ctxb) ; from foo to bar bar:x → 123 ; x has been added to bar bar:y → 999)
The example refers to contexts in variables and merges context foo into bar.
See also the function def-new for moving and merging single functions instead of entire contexts. See the context function for a more comprehensive example of new.
If the expression in exp evaluates to nil, then nil? returns true; otherwise, it returns nil.
(map nil? '(x nil 1 nil "hi" ())) → (nil true nil true nil nil) (nil? nil) → true (nil? '()) → nil ; nil? means strictly nil (nil? (not '())) → nil
The nil? predicate is useful for distinguishing between nil and the empty list ().
Note that nil? means strictly nil while true? means everything not nil or the empty list ().
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.
(normal 10 3 10)
→ (7 6.563476562 11.93945312 6.153320312 9.98828125
7.984375 10.17871094 6.58984375 9.42578125 12.11230469)
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.
If exp evaluates to nil or the empty list (), then true is returned; otherwise, nil is returned.
(not true) → nil (not nil) → true (not '()) → true (not (< 1 10)) → nil (not (not (< 1 10))) → true
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.
(now) → (2002 2 27 18 21 30 140000 57 3 -300 0) (now 0 -2) → -300 ; minutes west of GMT (date-value (now)) → 1014834090
The numbers represent the following date-time fields:
| format | description |
|---|---|
| year | Gregorian calendar |
| month | (1–12) |
| day | (1–31) |
| hour | (0–23) UTC |
| minute | (0–59) |
| second | (0–59) |
| microsecond | (0–999999) OS-specific, millisecond resolution |
| day of current year | Jan 1st is 1 |
| day of current week | (1–7) starting Monday |
| time zone offset in minutes | west of GMT including daylight savings bias |
| daylight savings time type | (0–6) on Linux/Unix or (0–2) on MS Windows |
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:
| UNIX type | area |
|---|---|
| 0 | not on daylight savings |
| 1 | USA style dst |
| 2 | Australian style daylight savings |
| 3 | Western European daylight savings |
| 4 | Middle European daylight savings |
| 5 | Eastern European daylight savings |
| 6 | Canada dst |
| Windows type | |
|---|---|
| 0 | Daylight saving time is not used |
| 1 | Standard date time range is used |
| 2 | Daylig |