Code Patterns in newLISP^TM

Contents

1. Introduction
2. newLISP script files
• Specifying command line options in script files
• Scripts as pipes
• File filters
3. Writing software in modules
• Sructuring an application
• More than one context per file
• Simple context objects and the default function
• Packaging data with contexts
• Passing context objects by reference
4. Local variables
• Locals in looping functions
• Local symbols using let, letn and local
• Unused parameters as local symbols
• Using args as local substitute
5. Walking through lists
• Recursion or not?
• Generators
• Walking a tree
• Walking a directory tree
6. Creating, accessing and modifying lists
• push and pop
• Accessing lists
• Selecting more than one element
• Filtering and differencing lists
• Changing list elements
• The new element as a function of the replaced
• Changing more than one element in a list
• Passing lists by reference using the default functor
7. Program flow
• Loops
• Blocks
• Branching
• Fuzzy flow
• Change flow with catch and throw
• Leave loops with a break condition
• Change flow with and or or
8. Error handling
• System errors
• User defined errors
• Error event handlers
• Catching errors
9. Functions as data
• Manipulate functions after definition
• Mapping and applying functions
• Function currying: functions making functions
10. Text processing
• Regular expressions
• Scanning text
• Appending strings
• Growing strings in place
• Rearranging strings
11. Dictionaries
• Creating and modifying symbols
• Iterating through dictionaries
• Object oriented implementation of a dictionary
12. TCP/IP client server communications
• Client - server TCP/IP - open connection
• Client - server TCP/IP - closed connection
13. UDP communications
• Open communications with UDP
• Closed transaction oriented UDP
• UDP multi-cast communications
14. Non-blocking communications
• Using net-select
• Using net-peek
15. Controlling other apps
• Communications via STD I/O
• Communications via TCP/IP
• Communicate via named FIFO
• Communicate via UDP
16. Launching applications blocking
• Shell execution
• Execution capturing std-out in a list
• Execution feeding std-in
17. Threads, semaphores and shared memory
18. Databases, lookup tables
• Association lists
• Symbol creation and lookup
19. Distributed computing
• Setting up a newLISP server node
• Evaluating multiple expressions remotely
• Transferring files to and from remote nodes
• Loading and saving code from and to remote nodes
• HTTPD-only mode, newLISP as a webserver
• Media types in HTTP modes
20. Extending newLISP
• Compile a shared library on Linux/UNIX/MacOSX
• Compile a DLL on Win32
• Using data structures in imported libraries
• Unevenly aligned data structures
• Passing parameters in library calls
• Extracting return values from library calls
21. Appendix
• GNU Free Documentation License

1. Introduction

When programming in newLISP certain functions and usage patterns occur repeatedly. For some problems an optimal way to solve them evolves over time. The following chapters present example code and explanations for the solution of specific problems when programming in newLISP.

Some content is overlapping with material covered in the newLISP Users Manual and Reference or presented here with a different slant.

Only a subset of newLISP's total function repertoire is used here. Some functions demonstrated have additional calling patterns or applications not mentioned on these pages.

This collection of patterns and solutions is a work in progress. Over time material will be added or existing material improved.

2. newLISP script files

Specifying command line options in script files

On Linux/UNIX put the following in the first line of the script/program file:

	#!/usr/bin/newlisp

specifying a bigger stack:

	#!/usr/bin/newlisp -s 100000

or

	#!/usr/bin/newlisp -s100000

Operating systems shells behave differently when parsing the first line and extract parameters. newLISP takes both, attached or detached parameters. Put the following lines in small script to test the behavior of the underlying OS and platform. The script changes the stack size allocated to 100,000 and limits LISP cell memory to about 10 M bytes.

	#!/usr/bin/newlisp -s 100000 -m 10

	(println (main-args))
	(println (sys-info))

A typical output executing the script from the system shell would be:

	./arg-test
	
	("/usr/bin/newlisp" "-s" "100000" "-m" "10" "./arg-test")	
	(308 655360 299 2 0 100000 8410 2)

Note that few programs in newLISP need a bigger stack configured, most programs run on the internal default of 2048. Each stack position takes an average of 80 bytes. Other options are available to start newLISP. See the Users Manual for details.

Scripts as pipes

	The following examples shows how a file can be piped into a newLISP script.
	#!/usr/bin/newlisp
	#
	# uppercase - demo filter script as pipe
	#
	# usage: 
	#          ./uppercase < file-spec
	#
	# example: 
	#          ./uppercase < my-text
	#
	#

	(while (read-line) (println (upper-case (current-line))))

	(exit)

The file will be printed to stdout translated to uppercase.

File filters

The following script works like a Unix grep utility iterating through files and filtering each line in a file using a regular expression pattern.

#!/usr/bin/newlisp
#
# nlgrep - grep utility on newLISP
#
# usage: 
#          ./nlgrep "regex-pattern" file-spec
#
# file spec can contain globbing characters
#
# example: 
#          ./nlgrep "this|that" *.c
#
# will print all line containing 'this' or 'that' in *.c files
#

(dolist (file-name (3 (main-args))) 
	(set 'file (open file-name "read"))
	(println "file ---> " file-name)
	(while (read-line file)
		(if (find (main-args 2) (current-line) 0)
		(write-line)))
	(close file))
                
(exit)

The expression:

(3 (main-args))

is a short form of writing:

(rest (rest (rest (main-args))))

It returns a list of all the filenames. This form of specifying indices for rest is called implicit indexing. See the Users Manual for implicit indexing with other functions. The expression (main-args 2) extracts the 3rd argument from the commandline containing the regular expression pattern.

3. Writing software in modules

Structuring an application

When writing bigger applications or when several programmers are working on the same code base it is necessary to divide the code base into modules. Modules in newLISP are implemented using contexts, which are namespaces. Namespaces allow lexical isolation between modules. Variables of the same name in one module cannot clash with variables of the same name in another module.

Typically moudules will be organized in one context per file. One file module may contain database access routines.

	; database.lsp
	;
	(context 'db)
	
	
	(define (update x y z)
	...
	)
	
	(define (erase x y z)
	...
	)

Another module may contain various utilities

	; auxiliary.lsp
	;
	(context 'aux)
	
	(define (getval a b)
	...
	)

Typically there will be one MAIN module loading and controlling all others:

	; application.lsp
	;
	
	(load "auxiliary.lsp")
	(load "database.lsp")
	
	(define (run)
		(db:update ....)
		(aux:putval ...)
		...
		...
	)
	
	(run)

More than one context per file

When using more than one context per file, each context section should be closed with a (context MAIN) statement:

	; myapp.lsp
	;
	(context 'A)
	
	(define (foo ...)
	...
	)
	
	(context MAIN)
	
	(context 'B)
	
	(define (bar ...)
	...
	)
	
	(context MAIN)
	
	(define (main-func)
	    (A:foo ...)
	    (B:bar ...)
	...
	)

Note that in the namespace statements for contexts A and B the context names are quoted because they are newly created, while MAIN already exists when newLISP starts up and can stay unquoted, although quoting it would not represent a problem.

Simple objects and the default function

A function in a context may have the same name as the host context itself. This function has special characteristics:

	(context 'foo)
	
	(define (foo:foo a b c)
	...
	)

The function foo:foo is called the default function, because when using the context name foo like a function it will default to foo:foo:

	(foo x y z)
	; same as
	(foo:foo x y z)

The default function make is possible to write functions which look like normal functions but carry their own lexical namespace. We can use this to write functions which keep state:

	(context 'generator)
	
	(set 'acc 0)
	
	(define (generator:generator)
		(inc 'acc))
	
	(context MAIN)
	
	(generator) → 1
	(generator) → 2
	(generator) → 3

The following is a more complex example for a function generating a fibonacci sequence:

	(define (fibo:fibo)
		(if (not fibo:mem) (set 'fibo:mem '(0 1)))
		(push (+ (fibo:mem -1) (fibo:mem -2)) fibo:mem -1))
	
	(fibo) → 1
	(fibo) → 2
	(fibo) → 3
	(fibo) → 5
	(fibo) → 8
	...

This example also shows how a default function is defined on the fly wihtout the need of explicit context statements. As an alternative the function could also have been written creating the context explicitely:

	(context 'fibo)
	(define (fibo:fibo)
			(if (not mem) (set 'mem '(0 1)))
			(push (+ (mem -1) (mem -2)) mem -1))
	(context MAIN)
	
	(fibo) → 1
	(fibo) → 2
	(fibo) → 3
	(fibo) → 5
	(fibo) → 8

while the first form is shorter, the second form is more readable.

Packaging data with contexts

The previous examples already presented functions packaged with data in a namespace. In the generator example the acc variable kept state. In the fibo example the variable mem kept a growing list. In both cases functions and data are living together in a namespace. The follwing example shows how a namespace just holds data only in a default functor:

	(set 'db:db '(a "b" (c d) 1 2 3 x y z))

Just like we used the default function to refer to fibo and generator we can refer to the list in db:db by only using db. This will work in all situations wher we do list indexing:

	(db 0)    → a
	(db 1)    → "b"
	(db 2 1)  → d
	(db -z)   → p
	(db -x)   → o
 
	(3 db)    → (1 2 3 x y z)
	(2 1 db)  → ((c d))
	(-6 2 db) → (1 2)

Passing context objects by reference

The default functor when used as an argument in a user defined function, is passed by reference. That means that no copy of the list or string is passed but a reference to the original contents. This is useful when handling large lists or strings:

	(define (update data idx expr)
		(if (not (or (lambda? expr) (primitive? expr)))
			(nth-set (data idx) expr)
			(nth-set (data idx) (expr $0))))
		
	(update db 0 99) → a
	db:db → (99 "b" (c d) 1 2 3 x y z)
	
	(update db 1 upper-case) → "b"
	db:db → (99 "B" (c d) 1 2 3 x y z)
	
	(update db 4 (fn (x) (mul 1.1 x))) →
	db:db → (99 "B" (c d) 1 2.2 3 x y z)

The data in db:db is passed via the update function parameter data, which now holds a reference to the context db. The expr parameter passed is checked if a built-in function, operator or a user defined lambda expression and than works on $0, the system variable containing the old content referenced by (data idx).

The function update is also a good example how to pass operators or functions as function argument. Read more about thois in chapter 9. Functions as data.

when using destructive functions which take the un-indexed list like replace, rotate, sort and swap the function default can be used to extract the default functor and access the list or string in it by reference:

	(set 'foo:foo '( 6 3 5 8 6 7 4 1))

	(define (my-sort clist)
		(sort (eval (default clist))))

	(my-sort foo) 

	foo:foo  → (1 3 4 5 6 6 7 8)

4. Local variables

Locals in looping functions

All looping functions like dolist, dotimes, dotree and for, use local variables. During loop execution the variable takes different values, but after leaving the looping function the variable regains its old value. let, define, and lambda expressions are another method for making variables local:

Local symbols using let, letn and local

let is the usual way in LISP to declare symbols as local to a block.

	(define (sum-sq a b)
    	(let ((x (* a a)) (y (* b b)))
        	(+ x y)))

	(sum-sq 3 4) → 25

	; alternative syntax
	(define (sum-sq a b)         
    	(let (x (* a a) y (* b b))
        	(+ x y)))

	; using local
	(define (sum-sq a b)
		(local (x y)
			(set 'x (* a a))
			(set '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 ...])

When initializing several parameters, a nested let, letn can be used to reference previously initialized variables in subsequent initializer expressions:

	(letn ((x 1) (y (+ x 1))) 
	    (list x y))          	→ (1 2)

The function local works like a let but initializing all variables to nil.

Unused parameters as local symbols

In newLISP all parameters in user defined functions are optional. Unused parameters are filled with nil and local to the dynamic scope of the function. Defining a user function with more parameters than required is a convenient method to create local variable symbols:

	(define (sum-sq a b , x y)
		(set 'x (* a a))
		(set 'y (* b b))
		(+ x y))

The comma is not a special syntax feature but only a visual helper to separate normal parameters from local variable symbols.

Using args as local substitute

Using the args function no parameter symbols need to be used at all and args returns a list of all parameters passed but not taken by declared parameters:

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

The second example shows how args only contains the list of arguments not bound by the variable symbols a and b.

Indices can be used to access members of the (args) list:

	(define (foo) 
	  	(+ (args 0) (args 1)))
	  
	(foo 3 4)   → 7 

5. Walking through lists

Recursion or iteration?

Although recursion is a powerful feature to express many algorithms in a readable form, they are also inefficient in some instances. newLISP has many iterative constructs and high level functions like flat or the built-in XML functions, which use recursion internally. In many cases this makes defining a recursive algorithm not necessary.

Some times a non-recursive solution can be much faster and lighter on system resources.

	;; classic recursion
	;; slow and resource hungry
	 (define (fib n)
	    (if (< n 2) 1
	      (+  (fib (- n 1))
	          (fib (- n 2)))))

The recursive solution is slow because of frequent calling overhead incurred. The recursive solution uses also a lot of memory for holding intermediate results.

	
	;; iteration
	;; fast and also returns the whole list
	(define (fibo n , f)
	    (set 'f '(1 0))
	    (dotimes (i n)
	     (push (+ (f 0) (f 1)) f) -1)
	    (rest f))

The iterative solution is fast and uses very little memory.

Generators

A generator is a function which keeps and changed state between invocations and returns a new value on each call:

	;; generator uses a namespace to keep state
	;; the default funcion (fibo) gets called repeatedly
	;;
	;; (fibo) → 1
	;; (fibo) → 2
	;; (fibo) → 3, 5, 8, 13, 21 ...
	;;
	;; fibo:mem → (0 1 1 2 3 5 8 13 21 ...)
	(define (fibo:fibo)
		(if (not fibo:mem) (set 'fibo:mem '(0 1))) 
		(push (+ (fibo:mem -2) (fibo:mem -1)) fibo:mem -1))

Namespaces in newLISP together with default functions are a convenient method to package a function with local static variables. mem is used in the fibo name space to keep the Fibonacci sequence.

Walking a tree

Tree walks are a typical pattern in traditional LISP and in newLISP as well for walking through a nested list. But many times a tree walk is only used to iterate through all elements of an existing tree or nested list. In this case the built-in flat function is much faster than using recursion:

	(set 'L '(a b c (d e (f g) h i) j k))

	;; classic car/cdr and recursion
	;; 
	(define (walk-tree tree)
	   (cond ((= tree '()) true)
	       ((atom? (first tree))
	         (println (first tree)) 
	         (walk-tree (rest tree)))
	       (true
	         (walk-tree (first tree)) 
	         (walk-tree (rest tree)))))
	
	;; classic recursion
	;; 3 times faster
	;;
	(define (walk-tree tree)
	  (dolist (elmnt tree)
	      (if (list? elmnt) 
	          (walk-tree elmnt)
	          (println elmnt))))
	          
	(walk-tree L) →
	a
	b
	c
	d
	e
	...

Using the built-in flat in newLISP a nested list can be transformed int a flat list. Now the list can be processed with a dolist or map:

	;; fast and short using 'flat'
	;; 30 times faster with map
	;;
	(map println (flat L))
	
	(dolist (item (flat L)) (println item)

Walking a directory tree

Walking a directory tree is a task where recursion works well:

	; walks a disk directory and prints all path-file names
	;
	(define (show-tree dir)
	    (if (directory dir)
	        (dolist (nde (directory dir))
	           (if (and (directory? (append dir "/" nde)) 
	                    (!= nde ".") (!= nde ".."))
	                 (show-tree (append dir "/" nde))
	                 (println (append dir "/" nde))))))

In this example recursion is the only solution, because the entire nested list off files is not available when the function is called but gets created recursively during function execution.

6. Creating, accessing and modifying lists

newLISP has facilities for multidimensional indexing into nested lists. There are destructive functions like push, pop, set-nth, nth-set, sort and reverse and many others for non-destructive operations, like nth, first, last, rest etc.. Many of the list functions in newLISP also work on strings.

Note that any list or string index in newLISP can be negative starting with -1 from the right side of a list:

	(set 'L '(a b c d))
	(L -1)   → d
	(L -2)   → c
	(-3 2 L) → (b c)
	
	(set 'S  "abcd")
	
	(S -1)   → d
	(S -2)   → c
	(-3 2 S) → "bc")

push and pop

One of the most used list functions are push and pop. There are both destructive, changing the contents of a list:

	(set 'L '(b c d e f))
	 
	(push 'a L)
	(push 'g L -1) ;; push at the end with negative index
	(pop L) ; pop first
	(pop L -1) ; pop last
	(pop L -2) ; pop second to last
	(pop L 1)  ; pop second
	; multidimensional push / pop
	(set 'L '(a b (c d (e f) g) h i))
	(push 'x L 2 1)
	L → (a b (c x d (e f) g) h i)
	(pop L 2 1) → x 

Pushing to the end of a list repeatedly is optimized in newLISP and as fast as pushing in front of a list.

When pushing an element with index vector V it can be popped with the same index vector V:

	(set 'L '(a b (c d (e f) g) h i))
	(set 'V '(2 1))
	(push 'x L V)
	L → (a b (c x d (e f) g) h i))
	(ref 'x L) → (2 1) ; search for a nested member
	(pop L V) → 'v

Accessing lists

Multiple indexes can be specified to access elements in a nested list structure:

	(set 'L '(a b (c d (e f) g) h i))
	(nth 2 2 1 L) → f
	(nth 2 2 L) → (e f)
	
	; implicit indexing (after version 8.4.5)
	(L 2 2 1) → f
	(L 2 2)   → (e f)
	
	; implicit indexing with vector
	(set 'vec '(2 2 1))
	(L vec)   → f

Implicit indexing shown in the last example makes code more readable. Implicit indexing also allows an unlimited number of indices, while nth is limited to 16. Indices after a list select list elements. Indices before a list select subsections of a list, which in turn are always lists.

Implicit indexing is also available for rest and slice

	(rest '(a b c d e))      → (b c d e)
	(rest (rest '(a b c d e) → (c d e)
	; same as
	(1 '(a b c d e)) → (b c d e)
	(2 '(a b c d e)) → (c d e)
	; negative indices
	(-2 '(a b c d e)) → (d e)
	; slicing
	(2 2 '(a b c d e f g))   → (c d)
	(-5 3 '(a b c d e f g)) → (c d e)

Selecting more than one element

Sometimes more than one element must be selected from a list in different places.

This can be done using select:

	;; pick several elements from a list
	;;
	(set 'L '(a b c d e f g))
	(select L 1 2 4 -1) → (b c e g)
	The indices can be delivered in an index vector:
	;; indices in vector
	;;
	(set 'vec '(1 2 4 -1))
	(select L vec) → (b c e g)

The selecting process can re-arrange or double elements at the same time:

	(select L 2 2 1 1) → (c c b b)

Filtering and differencing lists

Sometimes lists need to be filterer for a specific conditions applied to its elements:

	(filter (fn(x) (< 5 x)) '(1 6 3 7 8))    → (6 7 8)
	(filter symbol? '(a b 3 c 4 "hello" g)) → (a b c g)
	(difference '(1 3 2 5 5 7) '(3 7)) → (1 2 5)

The first example could be rewritten shorter as follows:

	(filter (curry < 5) '(1 6 3 7 8))

The curry function makes a one-argument function out of a two argument function:

	 (curry < 5) → (lambda (_x) (< 5 _x))

Using curry a function taking two arguments quickly is converted into a predicate taking one argument.

Changing list elements

set-nth and nth-set have the same effect on the list they are working on but the first returns the whole list while nth-set returns the changed old element:

	(set 'L '(a b (c d (e f) g) h i))
	; return the changed list (old deprecated syntax)
	(set-nth 2 2 1 L 'x) → (a b (c d (e x) g) h i)
	
	; return the replaced element (old deprecated syntax)
	(nth-set 2 2 1 L 'z) → x
	; since 8.8.9 a more readable syntax is available
	(set-nth (L 2 2 1) 'x) → (a b (c d (e x) g) h i)
	(nth-set (L 2 2 1) 'z) → z

The new element as a function of the replaced

An internal system variable $0 in newLISP holds the old list element. This can be used to configure the new one:

	(set 'L '(0 0 0))
	(nth-set (L 1) (+ $0 1)) → 0 ; the old value
	(nth-set (L 1) (+ $0 1)) → 1
	(nth-set (L 1) (+ $0 1)) → 2
	L → '(0 3 0)

Changing more than one element in a list

Sometimes several elements in a list have to be changed. Typically all elements which should be changed have a characteristic in common:

	(set 'aList '(a b c d e a b c d))

	(replace 'b aList 'B) → (a B c d e a B c d)

The function replace can take a comparison function for picking list elements:

	; replace all numbers where 10 < number
	(set 'L '(1 4 22 5 6 89 2 3 24))

	(replace 10 L 10 <) → (1 4 10 5 6 10 2 3 10)

Using the built-in functions match and unify more complex selection criteria can be defined:

	; replace only sublists starting with 'mary'

	(replace '(mary *)  AL (list 'mary (apply + (rest $0))) match)
	→ ((john 5 6 4) (mary 14) (bob 4 2 7 9) (jane 3))

	; make sum in all expressions

	(set 'AL '((john 5 6 4) (mary 3 4 7) (bob 4 2 7 9) (jane 3)))

	(replace '(*) AL (list ($0 0) (apply + (rest $0))) match)
	→ ((john 15) (mary 14) (bob 22) (jane 3))

	$0 → 4  ; replacements made

	; change only sublists where both elements are the same

	(replace '(X X) '((3 10) (2 5) (4 4) (6 7) (8 8)) (list ($0 0) 'double ($0 1)) unify)
	→ ((3 10) (2 5) (4 double 4) (6 7) (8 double 8))

	$0 → 2  ; replacements made

After a replacement statement is executed the newLISP system variable $0 contains the number of replacements made.

Passing lists by reference using the default functor

Sometimes a larger list (more than a few hundred elements) must passed to a function for changing elemements in it. Normally newLISP passes all parameters to user-defined functions by value. The following snipped shows a technique that can be used to pass a bigger list or string object by reference:

	(set 'data:data '(a b c d e f g h))

	(define (change db i value)
	    (nth-set (db i) value))

	(change data 3 999) → d
	data:data → '(a b c 999 d e f g h)

In this example the list is encapsulated in a context data holding a variable data with the same name.

7. Program flow

Program flow in newLISP is mostly functional but it also has looping and branching constructs and a catch and throw to break out of normal flow.

Looping expressions as a whole behave like a function or block returning the last expression evaluated inside.

Loops

Most of the traditional looping patterns are supported. Whenever there is a looping variable, it is local in scope to the loop, behaving according the rules of dynamic scoping inside the current name-space or context:

	; loop a number of times
	; i goes from 0 to N - 1
	(dotimes (i N)
	   ....
	)
	
	; demonstrate locality of i
	(dotimes (i 3) 
	    (print i ":") 
	    (dotimes (i 3) (print i))
	    (println))
	
	→ ; will output
	0:012
	1:012
	2:012
	
	; loop through a list
	; takes the value of each top level element in aList
	(dolist (e aList)
	   ...
	)
	
	; loop through the symbols of a context in
	; alphabetical order of the symbol name
	(dotree (s CTX)
	   ...
	)
	
	; loop from to with optional step size
	; i goes from init to <= N inclusive with step size step
	; Note that the sign in step is irrelevant, N can be greater
	; or less then init.
	(for i init N step)
	   ...
	)
	
	; loop while a condition is true
	; first test condition then perform body
	(while condition
	   ...
	)
	
	; loop while a condition is false
	; first test condition then perform body
	(until condition
	   ....
	)
	
	; loop while a condition is true
	; first perform body then test
	; body is performed at least once
	(do-while condition
	  ...
	)
	
	; loop while a condition is false
	; first perform body then test
	; body is performed at least once
	(do-until condition
	  ...
	)

Note that the looping functions dolist, dotimes and for can also take a break condition as an additional argument. When the break condition evaluates to true the loop finishes:

	(dolist (x '(a b c d e f g) (= x 'e)) 
    	(print x))
	→ ; will output
	abcd

Blocks

Blocks are collections of s-expressions evaluated sequentially. All looping constructs may have expression blocks after the condition expression as a body.

Blocks can also be constructed by enclosing them in a begin expression:

	(begin
	    s-exp1
	    s-exp2
	    .....
	    s-expN)

Looping constructs do not need to use an explicit begin after the looping conditions. begin is mostly used to block expressions in if and cond statements.

The functions and, or, let, letn and local can also be used to form blocks and do not require begin for blocking statements.

Branching

	(if condition true-expr false-expr)
	 
	;or
	(if condition true-expr)
	
	;or unary if for (filter if '(...))
	(if condition)  
	
	;; more then 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)))

Depending on condition the true-expr or false-expr part is evaluated and returned.

More then one condition true-expr pair can occur in an if expression, making it look like a cond:

	(if condition-1 true-expr-1 
	    condition-2 true-expr-2 
	          .....
	    condition-n true-expr-n
	    false-expr)

The first true-expr-i of which the condition-i is not nil is evaluated and returned or the false-expr if none of the condition-i is true.

cond works like the multiple condition form of if but each part of condition-i true-expr-i must be braced in parenthesis:

	(cond 
	     (condition-1 true-expr-1 )
	     (condition-2 true-expr-2 )
	           .....
	     (condition-n true-expr-n )
	     (true true-expr))

Fuzzy flow

Using amb the program flow can be regulated in a probabilistic fashion:

	(amb
	    expr-1
	    expr-2
	    .....
	    expr-n)

One of the alternative expressions expr-1 to expr-n is evaluated with a probability of 1 / n and the result is returned from the amb expression.

Change flow with catch and throw

Any loop or other expression block can be enclosed in a catch expression. The moment a throw expression is evaluated, the whole catch expression returns the value of the throw expression.

	(catch 
	   (dotimes (i 10)
	       (if (= i 5) (throw "The End"))
	        (print i " ")))
	; will output
	 
	0 1 2 3 4
	; and the return value will be
	→ "The End"

Several catch may be nested.

Leave loops with a break condition

Loops built using dotimes, dolist of for can specify a break condition under which the loop is left early:

	(dotimes (x 10 (> (* x x) 9)) 
	    (println x))
	→
	0
	1
	2
	3
	
	(dolist (i '(a b c nil d e) (not i))
	    (println i))
	→
	a
	b
	c

Change flow with and or or

Similar to programming in Prolog the logical and and or can be used to control program flow depending on the outcome of expressions logically connected:

	(and
	   expr-1
	   expr-2
	    ...
	   expr-n)

Expressions are evaluated sequentially until one expr-i evaluates to nil or the empty list'() or until all expr-i are exhausted. The last expression evaluated is the return value of the whole and expression.

	(or
	   expr-1
	   expr-2
	    ...
	   expr-n)

Expressions are evaluated sequentially until one expr-i evaluates to not nil and not '() or until all expr-i are exhausted. The last expression evaluated is the return value of the whole or expression.

8. Error handling

Several conditions during evaluation of a newLISP expression can cause error exceptions. For a complete list of errors see the newLISP Reference Manual Appendix.

System errors

System errors are caused by wrong syntax, of function invocation, not supplying the right amount of parameters, or supplying parameters with the wrong data type. Other system errors are caused by trying to evaluate non existing functions.

	 ; examples of system errors
	 ;
	 (foo foo)   → invalid function : (foo foo)
	 (+ "hello") → value expected in function + : "hello"

User defined errors

User errors are error exceptions thrown using the function throw-error:

	; user defined error
	;
	(define (double x)
	    (if (= x 99) (throw-error "illegal number"))
	    (+ x x))

	(double 8)   → 16
	(double 10)  → 20
	(double 99) 
	→
	user error : illegal number
	called from user defined function double

Error event handlers

System and user defined errors can be caught using the function error-event to define an event handler. Note that this method will only work when newLISP is run as a library newlisp.so (on Linux/UNIX) or newlisp.dll (on Win32), or when the program file is loaded interactively. For newLISP script file use error handlers written with catch, as described in the next sub chapter.

	; define an error event handler
	;
	(define (myHandler)
	   (println "An error #" (error-number) " has occurred"))

	(error-event 'MyHandler)

	(foo) → An error #23 has occurred

Catching errors

A fine grainier, more specific error exception handling can be achieved using a special syntax of the function catch.

	(define (double x)
	    (if (= x 99) (throw-error "illegal number"))
	    (+ x x))

catch with a second parameter can be used to catch system and user defined errors:

	(catch (double 8) 'result) → true
	result → 16
	(catch (double 99) 'result) → nil
	(print result) 
	→ 
	user error : illegal number
	called from user defined function double

	(catch (double "hi") 'result) → nil
	(print result)  
	→ 
	value expected in function + : x
	called from user defined function double

The catch expression returns true when no error exception occurred and the result of the expression is found in the symbol result specified as a second parameter.

If an error exception occurs, it is caught and the catch clause returns nil. In this case the symbol result contains the error message.

9. Functions as data

Manipulate functions after definition

	(define (double x) (+ x x)) 
	→ (lambda (x) (+ x x))
	
	(first double) → (x)
	(last double) → (+ x x)
	
	;; make a ''fuzzy'' double
	(nth-set (double 1) '(mul (normal x (div x 10)) 2))
	
	(double 10) → 20.31445313
	(double 10) → 19.60351563

lambda in newLISP is not an operator or symbol, but rather a special s-expression or list attribute:

	(first double) → (x)   ; not lambda

The lambda attribute of an s-expression is right-associative in append:

	(append (lambda) '((x) (+ x x))) → (lambda (x) (+ x x))
	(set 'double (append (lambda) '((x) (+ x x)))
	
	(double 10) → 20

and left-associative when using cons:

	(cons '(x) (lambda) → (lambda (x))

Lambda expressions in newLISP never loose their first class object property.

Mapping and applying functions

Functions or operators can be applied to a list of data at once and all results are returned in a list

	(define (double (x) (+ x x))
	  (map double '(1 2 3 4 5)) → (2 4 6 8 10)

Functions can be applied to parameters occurring in a list:

	(apply + (sequence 1 10)) → 55

Function currying: functions making functions

Here and expression is passed as a parameter:

	(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

The built-in function curry can be used to make a function taking one argument from a function taking two arguments.

	(define add-one (curry add 1))  → (lambda (_x) (add 1 _x))

	(define by-ten (curry mul 10))  → (lambda (_x) (mul 10 _x))

	(add-one 5)  → 6

	(by-ten 1.23)  → 12.3

Note that the curried parameter is always the first (left) one.

10. Text processing

Regular expressions

Regular expression in newLISP can be used together with a variety of functions:

The functions find, regex, replace and search store pattern matching results in the system variable $0 to $15. See the newLISP Users Manual for details.

The following paragraphs show frequently used algorithms for scanning and tokenizing text.

Scanning text

replace together with a regular expression pattern can be used to scan text. The pattern in this case describes the tokens scanned for. As each token is found it is pushed on a list. The work is done in the replacement expression part of replace. This example saves all files linked on a web page:

	; tokenize using replace with regular expressions
	
	(set 'page (get-url "http://www.nodep.nl/newlisp/index.html"))
	
	(replace {href="(http://.*lsp)"} page (push $1 links) 0)
	
	(dolist (link links)
	   (set 'file (last (parse link "/")))
	   (write-file file (get-url link))
	   (println "->" file))

Curly braces {,} are used in the regular expression pattern to avoid escaping the quotes ".

The following technique is better but could not be used before version 8.9.0 of newLISP. The new find-all function puts all pattern matching strings into a list:

	(set 'links (find-all {href="(http://.*lsp)"} page))

	(dolist (link links)
	   (set 'file (last (parse link "/")))
	   (write-file file (get-url link))
	   (println "->" file))

find-all works in this example similar to replace with the push expression, but the find-all approach is more readable.

In an additional expressions find-all can be directed to do additional work with subexpressions found:

	(find-all {(new)(lisp)} "newLISPisNEWLISP" (append $2 $1) 1)
	
	→ ("LISPnew" "LISPNEW")

In the last example find-all appends the sub expressions found in reverse order before returning them in the result list.

Another technique for tokenizing text uses parse. While with replace and find-all the regular expression defined the token, when using parse the regex pattern describes the space between the tokens:

	; tokenize using parse
	(set 'str "1 2,3,4 5, 6 7  8"
	(parse str {,\ *|\ +,*} 0) 
	→ ("1" "2" "3" "4" "5" "6" "7" "8")

Without the curly braces {,} in the parse pattern the backslashes would need to be doubled.

Appending strings

When appending strings append and join can be used to form a new string:

	(set 'lstr (map string (rand 1000 100))) 
	→ ("976" "329" ... "692" "425")

	;; the wrong slowest way
	(dolist (s lstr) 
	    (set 'bigStr (append bigStr s)))

	;; smarter way - 50 times faster
	;;
	(apply append lstr)

Sometimes strings are not readily available in a list like in the above examples. In this case push can be used to push strings on a list while they get produced. The list then can be used as an argument for join, making the fastest method for putting strings together from existing pieces:

	;; smartest way - 300 times faster
	;; join an existing list of strings
	;;
	(join lstr) → "97632936869242555543 ...."

	;; join can specify a string between the elements
	;; to be joined	 
	(join lstr "-") → "976-329-368-692-425-555-43 ...." 

Growing strings in place

Very often the best method is to grow a string in place. The functions write-buffer, write-line and push can be used not only to write to file handles or push on lists but also to write/append to existing strings:

	;; smartest way - 150 times faster
	;; grow a string in place
	;;
	;; using write-buffer
	(set 'bigStr "")
	(dolist (s lstr) (write-buffer bigStr s))
	
	;; using push
	(set 'bigStr "")
	(dolist (s lstr) (push s bigStr -1))

Rearranging strings

The function select for selecting elements from lists can also be used to select and re-arrange characters from strings:

	(set 'str "eilnpsw")
	(select str '(3 0 -1 2 1 -2 -3)) → "newlisp"
	
	; alternative syntax
	(select str 3 0 -1 2 1 -2 -3) → "newlisp"

The second syntax is useful when ineces are specied not as constants but occur as variables.

11. Dictionaries

Creating and modifying symbols

After scanning and tokenizing text frequently dictionaries are built to store tokens together with their frequencies or other statistics or attributes.

	; create a symbol from a string and set it to a value
	;
	(set 'token "hello")
	(set (sym token 'Words) '(0 0 0 0))
	
	; a shorter method since 8.7.4
	(context 'Words token '(0 0 0 0))
	
	; read contents of a word in dictionary
	;
	(eval (sym token 'Words)) → (0 0 0 0)
	
	; a shorter method since 8.7.4
	(context 'Words token)    → (0 0 0 0)
	
	; update a word, using the old data
	; incrementing a counter by one
	;
	(nth-set 0 (eval (sym token 'Words)) (+ $0 1)) → 0  ; the old value
	(nth-set 0 (eval (sym token 'Words)) (+ $0 1)) → 1
	(nth-set 0 (eval (sym token 'Words)) (+ $0 1)) → 2
	; same as previous, but alternative shorter syntax
	(nth-set ((context 'Word token) 0) (+ $0 1)) → 3
	(nth-set ((context 'Word token) 0) (+ $0 1)) → 4
	
	(eval (sym token 'Words)) → (5 0 0 0)
	; same in alternative shorter syntax
	(context 'Words token) → (5 0 0 0)

The dictionary can be easily saved to a file by serializing the context Words:

	; save the dictionary to a file
	;
	(save "words.db" 'Words)
	Just as easy you can reload the dictionary:
	; load dictionary from a file
	;
	(load "words.db")

Test if a symbol exist in a namespace:

	(context 'foo "abc" 123)

	(context? 'foo "abc") → true
	(context? 'foo "def") → nil

Iterating through dictionaries

Dictionaries are a collection of symbols in a namespace, constructed via a binary tree. Yhe functions symbols or dotree can be used to iterate through all symbols in a namespace in alphabbetical fashion:

	; make a dictionary 
	(context 'foo "sdfg" 111) 
	(context 'foo "yete" 222) 
	(context 'foo "asdf" 333) 

	; display all key value pairs in alphabetical order 

	(dotree (s foo) 
		(println s "->" (eval s))) 

	; or an alternative method 

	(dolist (s (symbols foo)) 
		(println s "->" (eval s))) 

	; generates the output 

	foo:asdf->333 
	foo:sdfg->111 
	foo:yete->222 

The first method using dotree is really only a faster shortcut od the second method using symbols.

Object oriented implementation of a dictionary

The quickest shortest way to define and handle dictionaries is the folllowing function definition using a default functor for the dictionary:

(define (myhash:myhash key value) 
   (if value 
       (context 'myhash key value) 
       (context 'myhash key)))
       
(myhash "hello" 123)

(myhash "hello")     → 123

The default functor is the getter/setter function and namespace identifier for the dictionary at the same time.

12. TCP/IP client server communications

Client - server TCP/IP - open connection

In this pattern the server keeps the connection open until the client closes the connection, then the server loops into a new listen:

	;;;;;;;;;;;;;;;;;;;;;; the server
	; maximum bytes to receive
	(constant 'max-bytes 1024)
	(if (not (set 'listen (net-listen 123)))
	    (print (net-error)))
	(while (not (net-error))
	    (set 'connection (net-accept listen)) ;; blocking here
	    (while (not (net-error))
	         (net-receive connection 'message-from-client max-bytes)
	         .... process message from client ...
	         .... configure message to client ...
	         (net-send connection message-to-client)) )
	         
	;;;;;;;;;;;;;;;;;;;;; the client
	; client connect
	(if (not (set 'connection (net-connect "host.com" 123)))
	    (println (net-error)))
	; maximum bytes to receive
	(constant 'max-bytes 1024)
	; message send-receive loop
	(while (not (net-error))
	  .... configure message to server ...
	  (net-send connection message-to-server)
	  (net-receive connection 'message-from-server max-bytes)
	  .... process message-from-server ...
	  )

Client - server TCP/IP - closed transaction

In this pattern the server closes the connection after each transaction exchange of messages.

	;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; server
	(while (not (net-error))
	    (set 'connection (net-accept listen)) ;; blocking here
	    (net-receive connection 'message-from-client max-bytes)
	         .... process message from client ...
	         .... configure message to client ...
	    (net-send connection message-to-client)
	    (close connection))
	    
	;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; client 
	(if (not (set 'connection (net-connect "host.com" 123)))
	    (println (net-error)))
	; maximum bytes to receive
	(constant 'max-bytes 1024)
	  .... configure message to server ...
	(net-send connection message-to-server)
	(net-receive connection 'message-from-server max-bytes)
	  .... process message-from-server ...

There are many different ways to set up a client/server connection, see also the examples in the newLISP manual.

13. UDP communications

They are fast and need less setup than TCP/IP and offer ''multi casting''. UDP is also less reliable because the protocol does less checking, i.e. of correct packet sequence or if all packets are received. This is normally no problem when not working on the Internet but in a well controlled local network or when doing machine control. A simple more specific protocol could be made part of the message.

Open communications with UDP

In this example the server keeps the connection open. UDP communications with net-listen, net-receive-from and net-send-to can block on receiving.

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

	;;;;;;;;;;;;;;;;;; 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))
	closed transaction oriented UDP

Closed transaction oriented UDP

This form is some times used for controlling hardware or equipment. No setup is required, just one function for sending, another one for receiving:

	;;;;;;;;;;;;;;;;;; server
	;; wait for data gram with maximum 20 bytes 
	(net-receive-udp 1001 20) 
	;; or
	(net-receive-udp 1001 20 5000000)  ;; wait for max 5 seconds

	;;;;;;;;;;;;;;;;;; client
	(net-send-udp "host.com" 1001 "Hello")

Win32 and Linux show different behavior when sending less or more bytes then specified on the receiving end.

UDP multi-cast communications

In this scheme the server subscribes to one of a range of multi cast addresses using the net-listen function.

	;; example server
	(net-listen 4096 "226.0.0.1" "multi") → 5
	(net-receive-from 5 20)             
	;; example client
	(net-connect "226.0.0.1" 4096 "multi") → 3
	(net-send-to "226.0.0.1" 4096 "hello" 3)

The connection in the example is blocking on net-receive but could be de-blocked using net-select or net-peek

14. Non-blocking communications

Using net-select

In all previous patterns the client blocks when in receive. The net-select call can be used to unblock communications:

	;; optionally poll for arriving data with 100ms timeout
	(while (not (net-select connection "r" 100000)) 
	    (do-something-while-waiting ...))
	
	(net-receive...)

connection can be a single number for a connection socket or a list of numbers to wait on various sockets.

Using net-peek

	(while ( = (net-peek aSock) 0) 
	   (do-something-while-waiting ...))
	(net-receive...)

15. Controlling other apps.

In this chapter all external applications are launched using process. This function returns immediately after launching the other application and does not block.

In all of the following patterns the server is not independent but controlled by the client, which launches the server and then communicated via a line oriented protocol:

	-> launch server
	-> talk to server
	<- wait for response from server
	-> talk to server
	<- wait for response from server
	    .....

Often a sleep time is necessary on the client side to wait for the server to be ready loading. Most of these examples are condensed snippets from GTK-Server from www.gtk-server.org.

Communications via STD I/O

process allows specifying 2 pipes for communications with the launched application.

	# Define communication function
	(define (gtk str)
	   (write-line str myout)
	   (if (!= str "gtk_exit 0") 
	       (read-line myin)))
	       
	# Launch gtk-server
	(map set '(myin gtkout) (pipe))
	(map set '(gtkin myout) (pipe))
	(process "gtk-server stdin" gtkin gtkout)
	(gtk "gtk_init NULL NULL")
	(gtk "gtk_window_new 0")
	          .....

communications via TCP/IP

	; Define communication function
	(define (gtk str , tmp)
	    (net-send connection str)
	    (net-receive connection 'tmp 64)
	    tmp)
	
	; Start the gtk-server
	(process "gtk-server tcp localhost:50000")
	(sleep 1000)

	; Connect to the GTK-server
	(set 'connection (net-connect "localhost" 50000))
	(set 'result (gtk "gtk_init NULL NULL"))
	(set 'result (gtk "gtk_window_new 0"))
	          .....

Communicate via named FIFO

Make a FIFO first (looks like a special file node):

	 (exec "mkfifo myfifo")

	;; or alternatively
	
	(import "/lib/libc.so.6" "mkfifo")
	(mkfifo "/tmp/myfifo" 0777)
	
	; Define communication function
	(define (gtk str)
	    (set 'handle (open "myfifo" "write"))
	    (write-buffer handle str)
	    (close handle)
	    (set 'handle (open "myfifo" "read"))
	    (read-buffer handle 'tmp 20)
	    (close handle)
	    tmp)

Communicate via UDP

Note that the listen function with "udp" option just binds the sockets to a address/hardware but not actually listens as in TCP/IP.

	; Define communication function
	(define (gtk str , tmp)
	   (net-send-to "localhost" 50000 str socket)
	   (net-receive socket 'tmp net-buffer)
	   tmp)
	   
	; Start the gtk-server
	(define (start)
	   (process "gtk-server udp localhost:50000")
	   (sleep 500)
	   (set 'socket (net-listen 50001 "localhost" "udp")) )
	
	(set 'result (gtk "gtk_init NULL NULL"))
	
	(set 'result (gtk "gtk_window_new 0"))
	         .....

16. Launching applications blocking

Shell execution

This is frequently used from newLISP's interactive command line to execute processes in a blocking fashion, which need a shell to run:

	(! "ls -ltr")

There is an interesting variant of this form working not inside a newLISP expression, but only on the command line:

	!ls -ltr

The ! should be the first character on the command line. This form works like as shell escape like in the VI editor. It is useful for invoking an editor or doing quick shell work without completely leaving the newLISP console.

Execution capturing std-out in a list

	(exec "ls /") → ("bin" "etc" "home" "lib")

Execution feeding std-in

	(exec "script.cgi" cgi-input)

In this example cgi-input contains a string feeding. i.e.: a query input, normally coming from a web server. Note that output in this case is written directly to the screen, and cannot be returned to newLISP. Use process and pipe for two way std i/o communications with other applications.

17. Threads, semaphores and shared memory

Shared memory, semaphores and threads work frequently together. Semaphores can synchronize tasks in different threads and shared memory can be used to communicate between threads.

The following is a more complex example showing the working of all three mechanisms at the same time.

The producer loops through all n values from i = 0 to n - 1 and puts each value into shared memory where it is picked up by the consumer thread. Semaphores are used to signal that a data value is ready for reading.

	#!/usr/bin/newlisp
	# prodcons.lsp -  Producer/consumer
	#
	# usage of 'fork', 'wait-pid', 'semaphore' and 'share'
	
	(if (> (& (last (sys-info)) 0xF) 4) 
	   (begin
	       (println "this will not run on Win32")
	       (exit)))
	       
	(constant 'wait -1 'signal 1 'release 0)
	
	(define (consumer n)
	    (set 'i 0)
	    (while (< i n)
	       (semaphore cons-sem wait)
	       (println (set 'i (share data)) " <-")
	       (semaphore prod-sem signal))  
	       (exit))
	                
	(define (producer n)
	    (for (i 1 n)
	       (semaphore prod-sem wait)
	       (println "-> " (share data i))
	       (semaphore cons-sem signal))   
	       (exit))
	       
	(define (run n)
	    (set 'data (share)) 
	    (share data 0)
	    (set 'prod-sem (semaphore)) ; get semaphores
	    (set 'cons-sem (semaphore))
	    (set 'prod-pid (fork (producer n))) ; start threads
	    (set 'cons-pid (fork (consumer n)))
	    (semaphore prod-sem signal) ; get producer started
	    (wait-pid prod-pid) ; wait for threads to finish
	    (wait-pid cons-pid) ; 
	    (semaphore cons-sem release) ; release semaphores
	    (semaphore prod-sem release))
	    
	(run 10)
	
	(exit)

18. Databases and lookup tables

While association lists are the traditional means for associative data access in LISP and newLISP, other modern scripting languages use hashing to build memory based associative data tables. A hash is a table position calculated from a association key.

newLISP uses symbols instead of hashes. Symbols in name spaces can also be serialized to a file, as will be shown in the chapter about symbol creation and lookup.

Association lists

The association list is a classic LISP data structure for storing information for associative retrieval:

	;; creating association lists
	;; pushing at the end with -1 is optimized and 
	;; as fast as pushing in front
	
	(push '("John Doe" "123-5555" 1200.00) Persons -1)
	(push '("Jane Doe" "456-7777" 2000.00) Persons -1)
	    .....
	
	Persons →  (
	    ("John Doe" "123-5555" 1200.00) 
	    ("Jane Doe" "456-7777" 2000.00) ...)
	    
	;; access/lookup data records
	(assoc "John Doe" Persons) 
	
	→ ("John Doe" "123-5555" 1200.00 male)
	
	(assoc "Jane Doe" Persons) 
	 
	→ ("Jane Doe" "456-7777" 2000.00 female)

newLISP has a lookup function similar to what is used in spreadsheet software. This function which works like a combination of assoc and nth can find the association and pick a specific member of the data record at the same time:

	(lookup "John Doe" Persons 0)   → "123-555"
	(lookup "John Doe" Persons -1)  → make
	(lookup "Jane Doe" Persons 1)   → 2000.00
	(lookup "Jane Doe" Persons -2)  → 2000.00
	
	;; update data records
	(replace-assoc "John Doe" Persons 
	               '("John Doe" "123-5555" 900.00 male))
	
	;; replace as a function of existing/replaced data
	(replace-assoc "John Doe" Persons (update-person $0))
	
	;; delete data records
	(replace (assoc "John Does" Persons) Persons)

Symbol creation and lookup

lookup and assoc are fine for small tables and databases with only a few hundred data records, but are too slow for look-ups in thousands or millions of records.

newLISP has a fast and highly scalable symbol implementation. Together with name spaces and object serialization symbols can be used to maintain large data sets in memory and on disk with associative access.

	;; creating the database
	(set (sym "John Doe" 'Persons) '("123-5555" 1200.00 male))
	(set (sym "Jane Doe" 'Persons) '("456-7777" 2000.00 female))
	;; alternative shorter syntax
	
	(context 'Persons "John Doe") '("123-5555" 1200.00 male))
	(context 'Persons "Jane Doe") '("456-7777" 2000.00 female))
	     .....
	;; save the database to a file (serialization of context Persons)
	(save "persons.db" 'Persons)
	
	;; load database from a file
	(load "persons.db")
	
	;; access data records
	(eval (sym "John Doe" 'Persons)) → '("123-5555" 1200.00 male)
	
	;; alternative shorter syntax to access data records
	(context 'Persons "John Doe") → '("123-5555" 1200.00 male)
	
	;; update data records
	(set (sym "John Doe" 'Persons) '("John Doe" "123-5555" 900.00 male))
	
	;; update using alternative syntax
	(context 'Persons "John Doe") → '("John Doe" "123-5555" 900.00 male))
	
	;; delete data records
	(delete (sym "John Doe" 'Persons))

19. Distributed computing

Many of todays applications are distributed on to several computers on the network or distibuted on to several processes on one CPU. Often both methods of distributing an application are used at the same time.

newLISP has facilities to evaluate many expressions in parallel on different network nodes or processes running newLISP. The net-eval function does all the work necessary to communicate to other nodes, distribute expressions for evaluation and collect results in either a blocking or event driven fashion.

The functions read-file, write-file, append-file and delete-file can also be used to access with files on remote nodes when using URLs in file specifications. In a similar way the functions load and save can be used to load and save code from and to remote nodes.

newLISP uses existing HTTP protocols and newLISP commandline behaviour to implement this functionality. This means that programs can be debugged and tested using standard UNIX applications like terminal, telnet or a web browser. This also enables easy integration of other tools and programs into distributed applications built with newLISP. For example the UNIX utility netcat, nc could be used to evaluate expressions remotely or a web browser could be used to retrieve webpages from nodes running a newLISP server.

Setting up a newLISP server node

A newLISP server node is essentially a newLISP process listening to a network port and behaving like a newLISP commandline console and HTTP server for HTTP GET, PUT, POST and DELETE requests. Since version 9.1 newLISP server mode also answers CGI queries received by either GET or POST request.

Two methods are used to start a newLISP server node. One results in a stateful server, maintaining state in between communications with different clients, the other method a server with no state, reloading for every new client connection.

	newlisp -c -d 4711 &

	newlisp myprog.lsp -c -d 4711 &

	newlisp myprog.lsp -c -w /home/node25 -d 4711 &

newLISP is now listening on port 4711, the & (ampersand) sign tells newLISP to run in the background (UNIX only). The -c switch suppresses command line prompts. newLISP now behaves like a newLISP console without prompts listening on port 4711 for command line like input. Any other available port could have been chosen. Note that on UNIX ports below 1024 need administrator access rights.

The second example also preloads code. The third example also specifies a working directory using the -w option. If no working directory is specified using -w the startup directoruy is assumed to be the working directory.

On UNIX the inetd or xindetd facility can be used to start a stateless server. In this case the TCP/IP net connections are managed by a special UNIX utility with the ability to handle multiple requests at the same time. For each connection made by a client the inetd or xinetd utility will start a fresh newLISP process. After the connection is closed the newLISP process will shut down.

When nodes are not required to keep state, this is the preferred method for a newLISP server node, for handeling multiple connections at the same time.

The inetd or xinetd process needs to be configured using configuration files found in the /etc directory of most UNIX installations.

For both the inetd and xinetd configurations add the following line to the /etc/services file:

	net-eval        4711/tcp     # newLISP net-eval requests

Note that any other port than 4711 could be supplied.

When configuring inetd add also the following lines to the /etc/inetd.conf file:

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

	# a working directory can also be specified

	net-eval  stream  tcp  nowait  newlisp  /usr/bin/newlisp -c -w /usr/home/newlisp

The last line also specified a working directory and a user newlisp instead of the root user. This is a more secure mode limiting newLISP server node access to a specific user account with restricted permissions.

On Mac OS X and some other UNIX system a modern flavor of inetd: the xinetd facility is used. Add the following configuration to a file /etc/xinet.d/net-eval:

	service net-eval
	{
    	socket_type = stream
    	wait = no
    	user = root
    	server = /usr/bin/newlisp
    	port = 4711
    	server_args = -c -w /home/node
	}

Note that a variety of parameter combinations are possible to restrict access from different places or limit access to certain users. Consult the manpages for inetd and xinetd for details.

After condiguring inetd or xinetd either process must be restarted to re-read the configuration files. This can be accomplished by sending the UNIX HUP signal to either the inetd or xinetd process using the UNIX kill or UNIX nohup utility.

A newLISP server node can be tested using the UNIX telnet utility:

	telnet localhost 4711

	; or when running on a different computer i.e. ip 192.168.1.100

	telnet 192.168.1.100 4711

Multi-line expressions can be entered by enclosing them in [cmd], [/cmd] tags, each tag on a separate line.

	echo '(symbols) (exit)' | nc localhost 4711

Or talking to a remote node:

	echo '(symbols) (exit)' | nc 192.168.1.100 4711

In both examples netcat will echo back the result of evaluating the (symbols) expression.

Multi-line expressions can be entered by enclosing them in [cmd], [/cmd] tags, each tag on a separate line.

The net-eval function as a syntax form for connecting to only one remote server node. This mode is practical for quick testing from the newLISP command line:

	(net-eval "localhost" 4711 "(+ 3 4)" 1000) → 7

	; to a remote node

	(net-eval "192.168.1.100" 4711 {(upper-case "newlisp")} 1000) → "NEWLISP"

In the second example curly braces {,} are used to limit the program string for evaluation. This way quotes can be used to limit a string inside the expression.

No [cmd], [/cmd] tags are required when sending multi-line expressions. net-eval supplies these tags automatically.

A newLISP server also understands simple HTTP GET and PUT requests (currently UNIX only). Enter the full path of a file in the addressbar of the browser:

	http://localhost:4711//usr/share/newlisp/doc/newlisp_manual.html

The manual file is almost 800 Kbyte in size and will take a few seconds to load into the browser. Specify the portnumber with a colon separated from the hostname or host IP. Note the double slash // necessary to specify a file address relative to the root directory.

Evaluating multiple expressions remotely

When testing the correct installation of newLISP server nodes, we were already sending expressions to remote node for evaluation. Many times remote evlaluation is used to split up a lengthy task into shorter subtasks for remote evaluation on different nodes.

The first example is trivial, because it only evaluates several very simple expressions remotely, but it shows the principles involved in a way easy to understand:

	#!/usr/bin/newlisp

	(set 'result (net-eval '(	
		("192.168.1.100" 4711 {(+ 3 4)})
		("192.168.1.101" 4711 {(+ 5 6)})
		("192.168.1.102" 4711 {(+ 7 8)})
		("192.168.1.103" 4711 {(+ 9 10)})
		("192.168.1.104" 4711 {(+ 11 12)})  
	) 1000))


	(println "result: " result)

	(exit)

Running this program will produce the following output:

	result: (7 11 15 19 23)

When running UNIX and using an inetd or xinetd configured newLISP server, the servers and programs can be run on just one CPU replacing all IP numbers with "localhost" or the same local IP number. The indetd or xinetd daemon will then start 5 independent newLISP processes. On Win32 5 statefull newLISP servers could be started on different port numbers to accomplish the same.

Instead of collecting all results at one on the return of net-eval, a call back function can be used to receive and process results as they become available:

	#!/usr/bin/newlisp

	(define (idle-loop p)
		(if p (println p)))

	(set 'result (net-eval '(	
		("192.168.1.100" 4711 {(+ 3 4)})
		("192.168.1.101" 4711 {(+ 5 6)})
		("192.168.1.102" 4711 {(+ 7 8)})
		("192.168.1.103" 4711 {(+ 9 10)})
		("192.168.1.104" 4711 {(+ 11 12)})  
	) 1000 idle-loop))

	(exit)

While net-eval is waiting for results it calls the function idle-loop repeatedly with parameter p. The parameter p is nil when no result was received during the last 100 micro seconds or p contains a list sent back from the remote node. The list contains the remote address and port and the evaluation result. The example shown would generate the following output:

	("192.168.1.100" 4711 7)
	("192.168.1.101" 4711 11)
	("192.168.1.102" 4711 15)
	("192.168.1.103" 4711 19)
	("192.168.1.104" 4711 23)

For testing on just one CPU replace addresses with "localhost" the UNIX inetd or xinetd daemon will start a separate process for each connection made and all listening on port 4711. When using a stateful server on the same Win32 CPU specify a different port number for each server

In a networked environment where an application gets moved around, or server nodes with changing IP nubers are used, it is necessary to set up the node parameters in the net-eval parameter list as variables. The following more complex example shows how this can be done. The example also shows how a bigger piece of program text can be transferred to a remote node for evaluation and how this program piece can be customized for each node differently:

#!/usr/bin/newlisp

; node parameters
(set 'nodes '(
    ("192.168.1.100" 4711)
    ("192.168.1.101" 4711)
    ("192.168.1.102" 4711)
    ("192.168.1.103" 4711)
    ("192.168.1.104" 4711)
))

; program template for nodes
(set 'program [text]
(begin
    (map set '(from to node) '(%d %d %d))
    (for (x from to)
        (if (= 1 (length (factor x)))
            (push x primes -1)))
    primes)
[/text])

; call back routine for net-eval
(define (idle-loop p)
    (if p
        (begin
            (println (p 0) ":" (p 1))
            (push (p 2) primes))))

(println "Sending request to nodes, and waiting ...")

; machines could be on different IP addresses.
; For this test 5 nodes are started on localhost
(set 'result (net-eval '(
    ((nodes 0 0) (nodes 0 1) (format program 0 99999 1))
    ((nodes 1 0) (nodes 1 1) (format program 100000 199999 2))
    ((nodes 2 0) (nodes 2 1) (format program 200000 299999 3))
    ((nodes 3 0) (nodes 3 1) (format program 300000 399999 4))
    ((nodes 4 0) (nodes 4 1) (format program 400000 499999 5))
) 20000 idle-loop))

(set 'primes (sort (flat primes)))
(save "primes" 'primes)

(exit)

At the beginning of the program a nodes list structure contains all the relevant node information for hostname and port.

The program calculates all prime numbers in a given range. The from, to and node variables are configured into the program text using format. All instructions are placed into a begin expression block, so only one expression result will be send back from the remote node.

Many other schemes to configure a net-eval paramneter list are possible. The example shows, that net-eval evaluates the node parameter specifications inside the quoted list. The following scheme would give the same resuls:

	(set 'node-eval-list '(
		((nodes 0 0) (nodes 0 1) (format program 0 99999 1))
		((nodes 1 0) (nodes 1 1) (format program 100000 199999 2))
		((nodes 2 0) (nodes 2 1) (format program 200000 299999 3))
		((nodes 3 0) (nodes 3 1) (format program 300000 399999 4))
		((nodes 4 0) (nodes 4 1) (format program 400000 499999 5))
	))

	(set 'result (net-eval node-eval-list  20000 idle-loop))

The function idle-loop aggregates all lists of primes received and generates the following output:

	192.168.1.100:4711
	192.168.1.101:4711
	192.168.1.102:4711
	192.168.1.103:4711
	192.168.1.104:4711

As with the previous examples all IP numbers could be replaced with "localhost" or any other hostname or IP number to test a distributed application on a single host before deployment in a distributed environment with many networked hosts.

Transferring files to and from remote nodes

Files can be read from or written to remote nodes with the same functions used to read and write files to a local file system. This functionality is currently only available on UNIX systems when talking to newLISP servers. As functions are based on standard GET and PUT HTTP protocols they can also be used communicating with web servers. Note that few Apache webserver installations have enabled the PUT protocol by default.

The functions read-file, write-file and append-file can all take URLs in their filename specifications for reading from and writing to remote nodes running a newLISP server or a webserver:

	(write-file "http://127.0.0.1:4711//Users/newlisp/afile.txt" "The message - ")
	→ "14 bytes transferred for /Users/lutz/afile.txt\r\n"

	(append-file "http://127.0.0.1:4711//Users/newlisp/afile.txt" "more text")
	→ "9 bytes transferred for /Users/lutz/afile.txt\r\n"

	(read-file "http://127.0.0.1:4711//Users/newlisp/afile.txt")
	→ "The message - more text"

The first two function return a message starting with the numbers of bytes transferred and the name of the remote file affected. The -read-file function returns the contents received.

Under all error conditions an error message startriong with the characters ERR: would be returned:

	(read-file "http://127.0.0.1:4711//Users/newlisp/somefile.txt")
	→ "ERR:404 File not found: /Users/newlisp/somefile.txt\r\n"

Note the double backslash necessary to reference files relative to root on the server node.

All functions can be used to transfer binary non-ascii contents containing zero characters. Internally newLISP uses the functions get-url and put-url, which could be used instead of the functions read-file, write-file and append-file. Additional options like used with get-url and put-url could be used with the functions read-file, write-file and append-file as well. For more detail see the newLISP function reference for these functions.

Loading and saving data from and to remote nodes

The same load and save fuctions used to load program or LISP data from a local file system can be used to load or save programs and LISP data from or to remote nodes.

By using URLs in the file specifications of load and save these functions can work over the network commuicating with a newLISP server node.:

	(load "http://192.168.1.2:4711//usr/share/newlisp/mysql5.lsp")

	(save "http://192.168.1.2:4711//home/newlisp/data.lsp" 'db-data)

Although the load and save functions inernally use get-url and put-url to perform its works they behave exactly as when used on a local filesystem, but instead of a file path URLs are specified. Both function will timeout after 60 seconds if a connection could not be established. When finer control is necessary use the functions get-url and put-url together with eval-string and source to realize a similar result as when using the load and save in HTTP mode.

HTTPD-only mode, newLISP as a webserver

In all previous chapters the -c server mode was used. This mode can act as a net-eval server and at the same time answer HTTP requests for serving web pages or transfer of files and programs. The -c mode is the preferred mode for secure operation behind a firewall. newLISP also has a -http mode which works like a resticted -c mode. In -http mode only HTTP requests are served and commandline like formatted requests and net-eval requests are not answered. In this mode newLISP can act like a web server answering HTTP GET, PUT, POST and DELETE requests as well as CGI requests, but additional efforts should be made to restrict the access to aunauthorized files and directories to secure the server when exposed to the internet.

When newLISP server answers any HTTP request, it first calls a function httpd-conf. This function can be supplied in a startup file:

    server_args = httpd-conf.lsp -http -w /home/node

The above snippet shows part of a xinetd configuration file. A startup program httpd-conf.lsp has been added which will be loaded upon invocation of newLISP. The -c options has been replaced with the -http option. Now neither net-eval nor commandline requests will be answered but only HTTP requests.

The file httpd-conf.lsp contains a user-defined function http-conf which takes as arguments the HTTP path-name string of the request and the query string part of the request string. If the http-conf function returns nil the request will be aborted, else whatever string is returned will be taken as the path-name for further processing. This can be used to transform or redirect requested file names. http-conf can also be used to analyze headers for redirection or to respond with customized error pages. The function does not need to process the query string but must either return a valid path-name for further processing or nil to abort request processing.

The following small httpd-conf.lsp file will transform the path-name into a request for errorpage.html if the original path-name ends either with .exe or starts with / trying to access the root directory of the server, or tries the access any other directory outside the current directory:

    (define (httpd-conf path-name query)
            (if 
            (or
                (ends-with path-name ".exe")
                (starts-with path-name "/")
                (find ".." path-name)
            )
            "errorpage.html"
            ; else
            path-name
    ))

The following requests would all be rejected:

    http://asite.com/cgi-bin/prog.exe   ; trying to access prog.exe
    http://asite.com//usr/etc/passwd    ; trying to access path from / root
    http://asite.com/../../var/log      ; trying to hop out of web directory

A more elaborate httpd-conf file can be found in the source distribution of newLISP in the example directory. On UNIX systems this file is also installed as /usr/share/newlisp/httpd-conf.lsp. This fille contains a httpd-conf function which also sends back a Location: response with appended forward slash (/) for directory requests without a trailing /. When a directory is requested, newLISP HTTP mode will try to access either index.html or index.cgi in that directory.

Media types in HTTP modes

In both the -c and -http HTTP modes the following file types are recognized and a correctly formatted Content-Type: header is sent back:

20. Extending newLISP

newLISP has an import function, which allows importing function from DLLs (Dynamic Link Libraries) on Win32 or shared libraries on Linux/UNIX (ending in .so).

This chapter shows how to compile and use libraries on both, Win32 and Linux/UNIX platforms. We will compile a DLL and a Linux/UNIX shared library from the following 'C' program:

	#include <stdio.h>
	#include <stdlib.h>
	#include <ctype.h>>
	
	int foo1(char * ptr, int number)
	{
	printf("the string: %s the number: %d\n", ptr, number);
	return(10 * number);
	}
	
	char * foo2(char * ptr, int number)
	{
	char * upper;
	printf("the string: %s the number: %d\n", ptr, number);
	upper = ptr;
	while(*ptr) { *ptr = toupper(*ptr); ptr++; }
	return(upper);
	}
	
	/* eof */ 

Both functions foo1 and foo2 print their arguments, but while foo1 returns the number multiplied 10 times, foo2 returns the uppercase of a string to show how to return strings from 'C' functions.

Compile a shared library on Linux/UNIX/MacOSX

On Linux/UNIX we can compile and link testlib.so in one step:

	gcc testlib.c -shared -o testlib.so

Or On Mac OSX/darwin do:

	gcc -bundle -o testlib.so

The library testlib.so will be built with Linux/UNIX default cdecl conventions. Importing the library is very similar on both Linux and Win32 platforms, but on Win32 the library can be found in the current directory. You may have to specify the full path or put the library in the library path of the os:

	 newLISP v.8.4.3 on Linux, execute 'newlisp -h' for more info.
	
	> (import "/home/newlisp/testlib.so" "foo1")
	foo1 <6710118F>
	
	> (import "/home/newlisp/testlib.so" "foo2")
	foo2 <671011B9>
	
	> (foo1 "hello" 123)
	the string: hello the number: 123
	1230
	
	> (foo2 "hello" 123)
	the string: hello the number: 123
	4054088
	
	> (get-string (foo2 "hello" 123))
	the string: hello the number: 123
	"HELLO"
	>	

Again, the number returned from foo2 is the string address pointer and get-string can be used to access the string. When using get-string only character up to a zero byte are returned. When returning the addresses to binary buffers different techniques using unpack are used to access the information.

Compile a DLL on Win32

DLLs on Win32 can be made using the MinGW, Borland or CYGWIN compilers. This example shows, how to do it using the MinGW compiler.

Compile it:

	gcc -c testlib.c -o testlib.o

Before we can transform testlib.o into a DLL we need a testlib.def declaring the exported functions:

	LIBRARY    testlib.dll 
	EXPORTS
	    foo1 @1 foo1
	    foo2 @2 foo2

Now wrap the DLL:

	dllwrap testlib.o --def testlib.def -o testlib.dll -lws2_32

The library testlib.dll will be built with default Win32 stdcall conventions. The following shows an interactive session, importing the library and using the functions:

	 newLISP v.8.4.3 on Win32 MinGW, execute 'newlisp -h' for more info.
	> (import "testlib.dll" "foo1")
	foo1 <6710118F>

	> (import "testlib.dll" "foo2")
	foo2 <671011B9>

	> (foo1 "hello" 123)
	the string: hello the number: 123
	1230

	> (foo2 "hello" 123)
	the string: hello the number: 123
	4054088

	> (get-string (foo2 "hello" 123))
	the string: hello the number: 123
	"HELLO"

	>
	; import a library compiled for cdecl
	; calling conventsions
	> (import "foo.dll" "func" "cdecl")

Note that the first time using foo2 the return value 4054088 is the memory address of the string returned. Using get-string the string belonging to it can be accessed. If the library is compiled using cdecl calling conventions, the cdecl keyword must be used in the import expression.

Using data structures in imported libraries

Just like 'C' strings are returned using string pointers, 'C' structures can be returned using structure pointers and functions like get-string, get-int or get-char can be used to access the members. The following example illustrates this:

	typedef struct mystruc 
	   {
	   int number;
	   char * ptr;
	   } MYSTRUC;
	
	MYSTRUC * foo3(char * ptr, int num )
	   {
	   MYSTRUC * astruc;
	   astruc = malloc(sizeof(MYSTRUC));
	   astruc->ptr = malloc(strlen(ptr) + 1);
	   strcpy(astruc->ptr, ptr);
	   astruc->number = num;
	   return(astruc);
	   }

The newLISP program would access the structure members as follows:

	> (set 'astruc (foo3 "hello world" 123))
	4054280

	> (get-string (get-integer (+ astruc 4)))
	"hello world"

	> (get-integer astruc)
	123
	>

The return value from foo is the address to the structure astruc. To access the string pointer, 4 must be added as the size of an integer type in the 'C' programming language. The string in the string pointer then gets accessed using get-string.

Unevenly aligned data structures

Sometimes data structures contain data types of different length than the normal CPU register word:

	sruct mystruct 
	   {
	   short int x;
	   int z;
	   short int y;
	   } data;
	
	struct mystruct * foo(void)
	   {
	   data.x = 123;
	   data.y = 456;
	   data.z = sizeof(data);
	   return(&data);
	   }

The x and y variables are 16 bit wide and only z takes 32 bit. When a compiler on a 32bit CPU packs this structure the variables x and y will each fill up 32 bits instead of the 16 bit each. This is necessary so the 32 bit variable z can be aligned properly. The following code would be necessary to access the structure members:

	> (import "/usr/home/nuevatec/test.so" "foo")
	   foo <281A1588>

	> (unpack "lu lu lu" (foo))
	   (123 12 456)

The whole structure consumes 3 by 4 = 12 bytes, because all members have to be aligned to 32 bit borders in memory.

The following data structure packs the short 16 bit variables next to each other. This time only 8 bytes are required: 2 each for x and y and 4 bytes or z. Because x and y are together in one 32 bit word, none of the variables needs to cross a 32 bit boundary:

	struct mystruct 
	    {
	    short int x;
	    short int y;
	    int z;
	    } data;
	
	struct mystruct * foo(void)
	   {
	   data.x = 123;
	   data.y = 456;
	   data.z = sizeof(data);
	   return(&data);
	   }

This time the access code in newLISP reflects the size of the structure members:

	> (import "/usr/home/nuevatec/test.so" "foo")
	   foo <281A1588>

	> (unpack "u u lu" (foo))
	   (123 456 8)

Passing parameters in library calls

Note that floats and double floats are only passed correctly on x86 platforms with cdecl calling conventions or when passed by pointer reference as in variable argument functions, i.e: printf().

Extracting return values from library calls

Floats and doubles can only be returned via address pointer references.

When returning array types the number of elements in the array must be known. The examples always assume 3 elements.

All pack and unpack and formats can also be given without spaces, but are spaced in the examples for better readability.

The formats "ld" and "lu" are interchangeable, but the 16 bit formats "u" and "d" may produce different results, because of sign expansion from 16 to 32 bits.

Flags are available for changing endian byte order during pack and unpack.

The purpose of this License is to make a manual, textbook, or other functional and useful document "free" in the sense of freedom: to assure everyone the effective freedom to copy and redistribute it, with or without modifying it, either commercially or noncommercially. Secondarily, this License preserves for the author and publisher a way to get credit for their work, while not being considered responsible for modifications made by others.

This License is a kind of "copyleft", which means that derivative works of the document must themselves be free in the same sense. It complements the GNU General Public License, which is a copyleft license designed for free software.

We have designed this License in order to use it for manuals for free software, because free software needs free documentation: a free program should come with manuals providing the same freedoms that the software does. But this License is not limited to software manuals; it can be used for any textual work, regardless of subject matter or whether it is published as a printed book. We recommend this License principally for works whose purpose is instruction or reference.

1. APPLICABILITY AND DEFINITIONS

This License applies to any manual or other work, in any medium, that contains a notice placed by the copyright holder saying it can be distributed under the terms of this License. Such a notice grants a world-wide, royalty-free license, unlimited in duration, to use that work under the conditions stated herein. The "Document", below, refers to any such manual or work. Any member of the public is a licensee, and is addressed as "you". You accept the license if you copy, modify or distribute the work in a way requiring permission under copyright law.

A "Modified Version" of the Document means any work containing the Document or a portion of it, either copied verbatim, or with modifications and/or translated into another language.

A "Secondary Section" is a named appendix or a front-matter section of the Document that deals exclusively with the relationship of the publishers or authors of the Document to the Document's overall subject (or to related matters) and contains nothing that could fall directly within that overall subject. (Thus, if the Document is in part a textbook of mathematics, a Secondary Section may not explain any mathematics.) The relationship could be a matter of historical connection with the subject or with related matters, or of legal, commercial, philosophical, ethical or political position regarding them.

The "Invariant Sections" are certain Secondary Sections whose titles are designated, as being those of Invariant Sections, in the notice that says that the Document is released under this License. If a section does not fit the above definition of Secondary then it is not allowed to be designated as Invariant. The Document may contain zero Invariant Sections. If the Document does not identify any Invariant Sections then there are none.

The "Cover Texts" are certain short passages of text that are listed, as Front-Cover Texts or Back-Cover Texts, in the notice that says that the Document is released under this License. A Front-Cover Text may be at most 5 words, and a Back-Cover Text may be at most 25 words.

A "Transparent" copy of the Document means a machine-readable copy, represented in a format whose specification is available to the general public, that is suitable for revising the document straightforwardly with generic text editors or (for images composed of pixels) generic paint programs or (for drawings) some widely available drawing editor, and that is suitable for input to text formatters or for automatic translation to a variety of formats suitable for input to text formatters. A copy made in an otherwise Transparent file format whose markup, or absence of markup, has been arranged to thwart or discourage subsequent modification by readers is not Transparent. An image format is not Transparent if used for any substantial amount of text. A copy that is not "Transparent" is called "Opaque".

Examples of suitable formats for Transparent copies include plain ASCII without markup, Texinfo input format, LaTeX input format, SGML or XML using a publicly available DTD, and standard-conforming simple HTML, PostScript or PDF designed for human modification. Examples of transparent image formats include PNG, XCF and JPG. Opaque formats include proprietary formats that can be read and edited only by proprietary word processors, SGML or XML for which the DTD and/or processing tools are not generally available, and the machine-generated HTML, PostScript or PDF produced by some word processors for output purposes only.

The "Title Page" means, for a printed book, the title page itself, plus such following pages as are needed to hold, legibly, the material this License requires to appear in the title page. For works in formats which do not have any title page as such, "Title Page" means the text near the most prominent appearance of the work's title, preceding the beginning of the body of the text.

A section "Entitled XYZ" means a named subunit of the Document whose title either is precisely XYZ or contains XYZ in parentheses following text that translates XYZ in another language. (Here XYZ stands for a specific section name mentioned below, such as "Acknowledgements", "Dedications", "Endorsements", or "History".) To "Preserve the Title" of such a section when you modify the Document means that it remains a section "Entitled XYZ" according to this definition.

The Document may include Warranty Disclaimers next to the notice which states that this License applies to the Document. These Warranty Disclaimers are considered to be included by reference in this License, but only as regards disclaiming warranties: any other implication that these Warranty Disclaimers may have is void and has no effect on the meaning of this License.

2. VERBATIM COPYING

You may copy and distribute the Document in any medium, either commercially or noncommercially, provided that this License, the copyright notices, and the license notice saying this License applies to the Document are reproduced in all copies, and that you add no other conditions whatsoever to those of this License. You may not use technical measures to obstruct or control the reading or further copying of the copies you make or distribute. However, you may accept compensation in exchange for copies. If you distribute a large enough number of copies you must also follow the conditions in section 3.

You may also lend copies, under the same conditions stated above, and you may publicly display copies.

3. COPYING IN QUANTITY

If you publish printed copies (or copies in media that commonly have printed covers) of the Document, numbering more than 100, and the Document's license notice requires Cover Texts, you must enclose the copies in covers that carry, clearly and legibly, all these Cover Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on the back cover. Both covers must also clearly and legibly identify you as the publisher of these copies. The front cover must present the full title with all words of the title equally prominent and visible. You may add other material on the covers in addition. Copying with changes limited to the covers, as long as they preserve the title of the Document and satisfy these conditions, can be treated as verbatim copying in other respects.

If the required texts for either cover are too voluminous to fit legibly, you should put the first ones listed (as many as fit reasonably) on the actual cover, and continue the rest onto adjacent pages.

If you publish or distribute Opaque copies of the Document numbering more than 100, you must either include a machine-readable Transparent copy along with each Opaque copy, or state in or with each Opaque copy a computer-network location from which the general network-using public has access to download using public-standard network protocols a complete Transparent copy of the Document, free of added material. If you use the latter option, you must take reasonably prudent steps, when you begin distribution of Opaque copies in quantity, to ensure that this Transparent copy will remain thus accessible at the stated location until at least one year after the last time you distribute an Opaque copy (directly or through your agents or retailers) of that edition to the public.

It is requested, but not required, that you contact the authors of the Document well before redistributing any large number of copies, to give them a chance to provide you with an updated version of the Document.

4. MODIFICATIONS

You may copy and distribute a Modified Version of the Document under the conditions of sections 2 and 3 above, provided that you release the Modified Version under precisely this License, with the Modified Version filling the role of the Document, thus licensing distribution and modification of the Modified Version to whoever possesses a copy of it. In addition, you must do these things in the Modified Version:

• A. Use in the Title Page (and on the covers, if any) a title distinct from that of the Document, and from those of previous versions (which should, if there were any, be listed in the History section of the Document). You may use the same title as a previous version if the original publisher of that version gives permission.
• B. List on the Title Page, as authors, one or more persons or entities responsible for authorship of the modifications in the Modified Version, together with at least five of the principal authors of the Document (all of its principal authors, if it has fewer than five), unless they release you from this requirement.
• C. State on the Title page the name of the publisher of the Modified Version, as the publisher.
• D. Preserve all the copyright notices of the Document.
• E. Add an appropriate copyright notice for your modifications adjacent to the other copyright notices.
• F. Include, immediately after the copyright notices, a license notice giving the public permission to use the Modified Version under the terms of this License, in the form shown in the Addendum below.
• G. Preserve in that license notice the full lists of Invariant Sections and required Cover Texts given in the Document's license notice.
• H. Include an unaltered copy of this License.
• I. Preserve the section Entitled "History", Preserve its Title, and add to it an item stating at least the title, year, new authors, and publisher of the Modified Version as given on the Title Page. If there is no section Entitled "History" in the Document, create one stating the title, year, authors, and publisher of the Document as given on its Title Page, then add an item describing the Modified Version as stated in the previous sentence.
• J. Preserve the network location, if any, given in the Document for public access to a Transparent copy of the Document, and likewise the network locations given in the Document for previous versions it was based on. These may be placed in the "History" section. You may omit a network location for a work that was published at least four years before the Document itself, or if the original publisher of the version it refers to gives permission.
• K. For any section Entitled "Acknowledgements" or "Dedications", Preserve the Title of the section, and preserve in the section all the substance and tone of each of the contributor acknowledgements and/or dedications given therein.
• L. Preserve all the Invariant Sections of the Document, unaltered in their text and in their titles. Section numbers or the equivalent are not considered part of the section titles.
• M. Delete any section Entitled "Endorsements". Such a section may not be included in the Modified Version.
• N. Do not retitle any existing section to be Entitled "Endorsements" or to conflict in title with any Invariant Section.
• O. Preserve any Warranty Disclaimers.

If the Modified Version includes new front-matter sections or appendices that qualify as Secondary Sections and contain no material copied from the Document, you may at your option designate some or all of these sections as invariant. To do this, add their titles to the list of Invariant Sections in the Modified Version's license notice. These titles must be distinct from any other section titles.

You may add a section Entitled "Endorsements", provided it contains nothing but endorsements of your Modified Version by various parties--for example, statements of peer review or that the text has been approved by an organization as the authoritative definition of a standard.

You may add a passage of up to five words as a Front-Cover Text, and a passage of up to 25 words as a Back-Cover Text, to the end of the list of Cover Texts in the Modified Version. Only one passage of Front-Cover Text and one of Back-Cover Text may be added by (or through arrangements made by) any one entity. If the Document already includes a cover text for the same cover, previously added by you or by arrangement made by the same entity you are acting on behalf of, you may not add another; but you may replace the old one, on explicit permission from the previous publisher that added the old one.

The author(s) and publisher(s) of the Document do not by this License give permission to use their names for publicity for or to assert or imply endorsement of any Modified Version.

5. COMBINING DOCUMENTS

You may combine the Document with other documents released under this License, under the terms defined in section 4 above for modified versions, provided that you include in the combination all of the Invariant Sections of all of the original documents, unmodified, and list them all as Invariant Sections of your combined work in its license notice, and that you preserve all their Warranty Disclaimers.

The combined work need only contain one copy of this License, and multiple identical Invariant Sections may be replaced with a single copy. If there are multiple Invariant Sections with the same name but different contents, make the title of each such section unique by adding at the end of it, in parentheses, the name of the original author or publisher of that section if known, or else a unique number. Make the same adjustment to the section titles in the list of Invariant Sections in the license notice of the combined work.

In the combination, you must combine any sections Entitled "History" in the various original documents, forming one section Entitled "History"; likewise combine any sections Entitled "Acknowledgements", and any sections Entitled "Dedications". You must delete all sections Entitled "Endorsements."

6. COLLECTIONS OF DOCUMENTS

You may make a collection consisting of the Document and other documents released under this License, and replace the individual copies of this License in the various documents with a single copy that is included in the collection, provided that you follow the rules of this License for verbatim copying of each of the documents in all other respects.

You may extract a single document from such a collection, and distribute it individually under this License, provided you insert a copy of this License into the extracted document, and follow this License in all other respects regarding verbatim copying of that document.

7. AGGREGATION WITH INDEPENDENT WORKS

A compilation of the Document or its derivatives with other separate and independent documents or works, in or on a volume of a storage or distribution medium, is called an "aggregate" if the copyright resulting from the compilation is not used to limit the legal rights of the compilation's users beyond what the individual works permit. When the Document is included in an aggregate, this License does not apply to the other works in the aggregate which are not themselves derivative works of the Document.

If the Cover Text requirement of section 3 is applicable to these copies of the Document, then if the Document is less than one half of the entire aggregate, the Document's Cover Texts may be placed on covers that bracket the Document within the aggregate, or the electronic equivalent of covers if the Document is in electronic form. Otherwise they must appear on printed covers that bracket the whole aggregate.

8. TRANSLATION

Translation is considered a kind of modification, so you may distribute translations of the Document under the terms of section 4. Replacing Invariant Sections with translations requires special permission from their copyright holders, but you may include translations of some or all Invariant Sections in addition to the original versions of these Invariant Sections. You may include a translation of this License, and all the license notices in the Document, and any Warranty Disclaimers, provided that you also include the original English version of this License and the original versions of those notices and disclaimers. In case of a disagreement between the translation and the original version of this License or a notice or disclaimer, the original version will prevail.

If a section in the Document is Entitled "Acknowledgements", "Dedications", or "History", the requirement (section 4) to Preserve its Title (section 1) will typically require changing the actual title.

9. TERMINATION

You may not copy, modify, sublicense, or distribute the Document except as expressly provided for under this License. Any other attempt to copy, modify, sublicense or distribute the Document is void, and will automatically terminate your rights under this License. However, parties who have received copies, or rights, from you under this License will not have their licenses terminated so long as such parties remain in full compliance.

10. FUTURE REVISIONS OF THIS LICENSE

The Free Software Foundation may publish new, revised versions of the GNU Free Documentation License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns. See http://www.gnu.org/copyleft/.

Each version of the License is given a distinguishing version number. If the Document specifies that a particular numbered version of this License "or any later version" applies to it, you have the option of following the terms and conditions either of that specified version or of any later version that has been published (not as a draft) by the Free Software Foundation. If the Document does not specify a version number of this License, you may choose any version ever published (not as a draft) by the Free Software Foundation.