Included Example Programs

cat.munger

is a version of the cat utility, the simplest possible filter.

grep.munger

is an egrep-like filter.

options.munger

is a module that simplifies the processing of command-line arguments.

fmt.munger

is a version of the fmt utility.

cal.munger

prints a calender of the current month to stdout.

filter.munger

is a simple filter that expands documents with embedded munger code in them.

transform.munger

performs a set of regular expression based substitutions destructively over a set of files.

view.munger

is a file viewer resembling vi when invoked as view.

mush.munger

is a job control shell.

xml2alist.munger

is a minimal XML parser that converts a standalone XML 1.0 document into an alist.

xml2buffer.munger

is another XML parser that inserts the alist into the current buffer.

xmlquery.munger

is a module that can be used to extract data from XML alists.

xml2sqlite.munger

is another XML parser that serializes the XML document into an SQLite database file.

xmlsqlite.munger

is a module providing helper functions to access a SQLite database containing serialized XML.

rss.munger

prints to stdout an RSS feed that has been converted into a SQLite database.

echo.munger

is a TCP echo server.

httpd.munger

is a basic HTTP/1.1 server.

STARTUP

Command line arguments can be accessed from lisp programs with the "current", "rewind", "next", and "prev" intrinsics.

COMMENTS

SYMBOLS

NUMBERS

> (setq max (maxidx))
1073741823
> (+ max 1)
-1073741824

When an integer value is read by the lisp reader the integer is represented internally as a fixnum. If the integer is too large or too small to be represented in that form, the value is silently truncated to fit.

STRINGS

> "asd\""
"asd""

A backslash occurring at the end of a string is interpreted as escaping the closing " character. Backslashes are escaped with themselves.

> "asd\\"
"asd\"

A backslash is interpreted as an escape only when the backslash occurs before another backslash or a " character. Other backslashes are inserted into the string. The following two strings are therefore identical.

> "\a"
"\a"
> "\\a"
"\a"

It is only necessary to employ these escapes in strings to be parsed by the lisp reader. Escape characters can be inserted into strings programmatically.

> (char 34)
"""
> (char 92)
"\"

Munger's strings are 8-bit clean, but not all of the intrinsics that use strings tolerate embedded zeroes. The following intrinsics are 8-bit clean.

getline, getchar, getchars, print, cgi_read, cgi_print, code, substring,
stringify, concat, join, chop, chomp, insert, retrieve, slice, strcmp,
child_read, child_write, getline_ub

The "split" intrinsic works correctly when its first argument is the empty string and its second argument contains NULs.

STACKS, TABLES, AND RECORDS

Munger supports a dynamically-resizable unidimensional array type called a stack. Stacks can be treated as push-down stacks or indexed as arrays. Any lisp object can be stored in a stack. Multi-dimensional arrays can be simulated using stacks of stacks.

In addition to stacks and tables, an aggregate type called a record is provided. Records are fixed-size unidimensional arrays. They are more time-and-space-efficient means of representing fixed-size structures than lists, tables, or stacks.

Tables, stacks, and records are opaque constant atoms that evaluate to themselves.

FILES

> (with_input_file "README"
>> (for (a 1 4) (print a (char 9) (getline))))
1  Munger
2  ======
3
4  Munger is a lexically scoped, naive lisp interpreter specialized for

All redirections are undone on return to toplevel. Redirections made with "redirect" are explicitly undone with the "resume" intrinsic.

Redirections made with the "with_input_file", "with_output_file", and "with_error_file" macros are undone automatically when those macros return. Redirections made with these macros are dynamically-scoped.

Nested redirections shadow enclosing redirections.

> (with_input_file "README"
>> (print (getline))
Munger
>> (with_input_file "lisp.h"
>>> (print (getline)))
/*
>> (print (getline)))
======

The "temporary" intrinsic redirects stdout onto a temporary file opened for writing with mkstemp(2). The intrinsic returns the name of the file. A convenience macro is provided, "with_temporary_output_file".

> (setq filename (with_temporary_output_file (print "foobar")))
"/tmp/munger2nvIa8D98M"

> (with_input_file filename
>> (print (getline)))
"foobar"

> (unlink filename)
1

Two macros simplify the writing of filters: "foreach_line" and "foreach_line_callback". Both accept a function to be applied successively to each line of input. The second macro also accepts an additional function to be called when the input source changes. Both macros read data from files specified on the command line or stdin. Here is "cat" in munger.

(next)
(foreach_line print)
(exit 0)

COMMUNICATING WITH CHILD PROCESSES

> (with_input_process "jot 100"
>> (with_input_process "fmt"
>>> (while (setq l (getline))
>>>> (print l))))
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25
26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47
48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69
70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91
92 93 94 95 96 97 98 99 100

On return to toplevel, all redirections are undone. Redirections are explicitly undone with the "resume" intrinsic. The first argument is passed to the shell (always /bin/sh). We could let the shell create the pipeline for us.

> (with_input_process "jot 100 | fmt" ...

The curl(1) utility can be used to redirect standard input onto a remote file via ftp or http:

> (with_input_process "curl -s 'ftp://www.freebsd.org/pub/FreeBSD/README.TXT'"
>> (for (n 1 10) (print n (char 9) (getline))))
1  Welcome to the FreeBSD archive!
2  -------------------------------
3
4  Here you will find the official releases of FreeBSD, along with
5  the ports and packages collection and other FreeBSD-related
6  material.  For those who have World Wide Web access, we encourage
7  you to visit the FreeBSD home page at:
8
9   http://www.FreeBSD.org/
10

The munger code below is the equivalent of the shell command.

# cmd < infile 2> errfile | cmd2 > outfile

(redirect 0 "infile")
(redirect 2 "errfile")
(pipe 0 "cmd")
(redirect 1 "outfile")
(resume 2)
(exec "cmd2")

The "getstring" library function forks a program and accumulates all its output into a string.

> (getstring "curl -s 'http://www.mammothcheese.ca/robots.txt'")
"User-Agent: *
Disallow: /cgi-bin/"

A full duplex socket is connected to a child process or a network server with "child_open".

> (child_open "www.mammothcheese.ca" 80)
1
> (child_write "GET /robots.txt HTTP/1.0" (char 13) (char 10) (char 13) (char 10))
1
> (while (stringp (setq line (child_read)))
>>  (print line))
HTTP/1.0 200 OK
Content-Type: text/plain; charset=utf-8
Content-Length: 24
Last-Modified: Tue, 12 Jun 2007 16:10:51 GMT
Server: Drood/1.14 (FreeBSD/6.1/i386)
Date: Sun, 02 Sep 2007 01:27:20 GMT

User-agent: *
Disallow:

Only one full-duplex connection can be active at any time, but the connection exists independently of whatever source the standard descriptors are connected to. With a port argument of 0, "child_open" attempts to connect to another process listening on a UNIX domain socket. Without a port number, "child_open" forks a local program.

> (child_open "munger")
1
> (child_write "(setq foobar 43)")
1
> (chomp (child_read))
"43"
> (child_close)
1

TEXT BUFFERS

A number of intrinsics are provided that act upon the current buffer. Lines can be retrieved whole or in slices with tabs expanded. A range of buffer lines is filtered through an external program with the "filter" intrinsic. The "find" intrinsic is used to find non-overlapping matches of regular expressions. A range of lines can be copied from one buffer to another with the "transfer" intrinsic. There are intrinsics to set and find bookmarks in buffers.

; Loading a buffer from a file:

> (open)
0
> (read 0 "README")
38 ; Number of lines read.
> (for (a 1 5) (print (retrieve a)))
Munger
======

Munger is a simple, statically-scoped, interpreted lisp that has
line-editor-like access to multiple text buffers, for use on the FreeBSD

; Loading a buffer from a process:

> (empty)
1
> (input 0 "ls")
20
> (for (a 1 (lastline)) (print (retrieve a)))
LICENSE
Makefile
README
cat.munger
client.munger
err.munger
cgi.munger
fmt.munger
grep.munger
intrinsics.c
library.munger
lisp.c
lisp.h
options.munger
munger.man
transform.munger

; Filtering buffer content through a process:

> (filter 1 (lastline) "fmt")
3 ; Number of lines received back from filter.

> (for (a 1 (lastline)) (print (retrieve a)))
LICENSE Makefile README cat.munger client.munger err.munger cgi.munger
fmt.munger grep.munger intrinsics.c library.munger lisp.c lisp.h options.munger
munger.man transform.munger

; Loading a buffer from a remote file using curl(1):

> (empty)
1
> (input 0 "curl -s 'http://www.mammothcheese.ca/index.html'")
296 ; Number of lines read.

; Finding the location of a match on a regular expression:

> (setq rx (regcomp "<body[^>]*>"))
<REGEX#1>
> (find 1 1 0 rx 0)
(27 3 6)
> (slice 27 3 6 1 0)
"<body>"

; Filtering a buffer through an HTTP server:

> (empty)
1
> (insert 1 (concat "GET /Slashdot/slashdot HTTP/1.0" (char 13) (char 10)) 0)
1
> (insert 2 (concat (char 13) (char 10)) 0)
1
> (filter_server 1 2 "rss.slashdot.org" 80)
272

; Get rid of the HTTP header and condense a possibly chunked response body:

> (remove_http_stuff)
0

; Filter the XML document left in the buffer through the xml2alist example
; program:

> (filter 1 (lastline) (join "/" (libdir) "xml2alist.munger"))
264

; The buffer now contains a lisp representation of the XML we can use
; the xmlquery.munger example module with:

> (load (join "/" (libdir) "xmlquery.munger"))
<CLOSURE#24>

; Evaluate the buffer content as lisp:

> (eval_buffer)
[ Converted document scrolls by dramatically! ]

; Make a query.  Let's see the cdata content of the title elements of the
; RSS feed:

> (dynamic_let (document (get_elements "item" "document" 1 "rdf:RDF" 1))
>> (while document
>>> (println (get_cdata "item" 1 "title" 1))
>>> (setq document (cdr document))))

Unrefined "Musician" Gains a Global Audience
Open Source Laser Business Opens In New York
OpenOffice.org 2.1 Released With New Templates
Texas Lawmaker Wants To Let the Blind Hunt
Designer Glasses With Microdisplay Unveiled
Arctic Ice May Melt By 2040
DIY Service Pack For Windows 2000/XP/2003
Sea Snail Toxin Offers Promise For Pain
A Press Junket To Redmond
The Dutch Kill Analog TV Nationwide
Google  Web Toolkit Now 100% Open Source
Novell and Microsoft Claim Customer Support
Wikipedia Founder to Give Away Web Hosting
How Craigslist is Keeping up Internet Ideals
Norman &amp; Spolsky - Simplicity is Out

REGULAR EXPRESSIONS

> (set 'rx (regcomp "munger"))
<REGEXP#1>

> (set 's "/usr/local/share/munger/library.munger")

> (match rx s)
(17 23)

; Text before match:

> (substring s 0 17)
"/usr/local/share/"

; Text of match:

> (substring s 17 (- 23 17))
"munger"

; Text after match:

> (substring s 23 0)
"/library.munger"

> (set 'rx (regcomp "^/?([^/]+/)*([^/]+)"))
<REGEXP#2>

; Full match and matched subexpressions:

> (matches rx s)
("/usr/local/share/munger/library.munger" "munger/" "library.munger"
"" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "")

; Ex-like substitution:

> (substitute rx "\U\2" "/usr/local/bin/munger" 1)
"MUNGER"

; Dynamically-generated replacement strings for each match:

(let ((r0 (regcomp "%([0-9A-Fa-f][0-9A-Fa-f])"))
      (r1 (regcomp "\+")))

   (defun decode (str)
      (replace r0
         (char (hex2dec m1))
         (substitute r1 " " str 0))))

> (decode "foobar+tooley%7Efunbag%24%25%26")
"foobar tooley~funbag$%&"

FUNCTIONS

> (let ((a 10))
>> (defun booger () a))
<CLOSURE#32>
> (booger)
10

Functions can accept variable-length argument lists. To specify that a function accepts a varying number of arguments, pass a final parameter to enclosed in parentheses.

(lambda ((a)) (print a))

The previous code defines a function that accepts zero or more arguments. Upon invocation, all arguments passed to the function are collected into a list and bound to "a" inside the function body. If no arguments are passed to the function, "a" is bound to the empty list.

The following function accepts 2 or more mandatory arguments followed by optional arguments.

(lambda (a b (c)) (print a b c))

The "labels" intrinsic creates locally visible function bindings. Each function in the function list is visible to the other functions.

>(labels ((even (lambda (n) (or (eq n 0) (tailcall odd (- n 1)))))
>>>       (odd  (lambda (n) (and (not (eq n 0)) (tailcall even (- n 1))))))
>> (print (even 11))
>> (newline)
>> (print (even 12))
>> (newline))
0
1
1 ; this is the return value of the last (newline).

There are "let", "letn", and "letf" macros to facilitate the creation of new lexical bindings. "letn" corresponds to let* in other lisp dialects. "letf" corresponds to a named let in Scheme or flet in lisp.

Inside a lexical environment, new bindings can be dynamically created with the "extend" intrinsic. These bindings have unlimited extent just as all lexical bindings do.

> (defun (a)
>> (extend 'b (* a a))
>> (lambda () b))

You can limit the extent of a new binding with "dynamic_extent".

> (lambda (a)
>> (extend 'f (lambda () b))

>> (dynamic_extent
>>> (extend 'b (* a a))
>>> (print (f))) ; Works here inside "dynamic_extent"
                 ; even though f was closed before "extend" was invoked.
                 ; b suddenly "pops-up" into the lexical environment.
>> (f)) ; ERROR: b is no longer extant here.

Tail recursion is not recognized by the interpreter. The "tailcall" intrinsic turns its continuation into tail position. This mechanism allows even anonymous functions to perform tail recursion.

> (let ((n 10)
>>>     (a 1))
>> (if (< n 2)
>>> a
>>> (tailcall 0 (- n 1) (* a n))))
3628800

MACROS

(set 'quit (macro () '(exit 0)))

(set 'with_input_file
   (macro (file (code))
      (qquote
         (when (> (redirect 0 ,file) 0)
            (protect ,(cons 'progn code)
               (resume 0))))))

The "test" intrinsic displays a macro expansion.

> (test (with_input_file "library.munger" (getline)))
(when (> (redirect 0 "library.munger") 0)
   (protect (progn (getline))
      (resume 0)))

The "defmac" macro make macro definitions simpler.

(defmac with_input_file (file (code))
   (qquote
      (when (> (redirect 0 ,file) 0)
         (protect ,(cons 'progn code)
            (resume 0)))))

PROGRAMMING STYLE

(defun fact (n)
   (extend 'a 1)
   (iterate n (setq a (* a n)) (dec n))
   a)

cons: (cons expr1 expr2)

> (cons 'a (b c)
(a b c)

car: (car expr1)

> (car '(a b c))
a

cdr: (cdr expr1)

> (cdr '(a b c))
(b c)

boundp: (boundp expr1)

caar, cadr, cdar, caddr, cadddr, caddddr, cddr, cdddr, cddddr: (form expr)

> (caar '((a) b c)) ; is equivalent to: (car (car '((a) b c)))
a

> (cadr '(a b c)) ; is equivalent to: (car (cdr '(a b c)))
b

> (cdar '((a) b c)) ; is equivalent to: (cdr (car '((a) b c)))
()

> (cddr '(a b c)) ; is equivalent to: (cdr (cdr '(a b c)))
(c)

eq: (eq expr1 expr2)

> (eq 'a 'a)
1

> (eq '(a b c) '(a b c))
0

> (set 'l '(a b c))
(a b c)
> (eq l l)
1

> (eq 0001 1)
1

equal: (equal expr1 expr2)

> (equal '(a b c) '(a b c))
1

> (set 'l '(a b c))
(a b c)
> (equal l l)
1

> (equal '(00 01 02) '(0 1 2))
1

atomp: (atomp expr)

> (atomp 'a)
1

> (atomp '(a b c))
0

set: (set expr1 expr2)

> (set 's '(a b c))
(a b c)
> s
(a b c)

> (set (car '(a b c)) ((lambda (x) (* x x)) 4))
16
> a
16

setq: (setq symbol expr)

(setq a b)

is equivalent to:

(set 'a b)

eval_buffer: (eval_buffer)

The code in the current buffer can open new buffers. The "eval_buffer" function continues to parse the code in the buffer that was current when it was invoked.

eval_string: (eval_string expr)

blind_eval_string: (blind_eval_string expr)

With "eval_string", the code parsed from the string is evaluated in the current lexical context. With "blind_eval_string", only the global environment is visible.

eval: (eval expr)

> (set 'a (quote (set 'b 'booger)))
(set (quote b) (quote (booger)))
> b
evaluate: b has no value.
> (eval a)
booger
> b
booger

quote: (quote expr) or 'expr

> (quote (a b c))
(a b c)
> '(a b c)
a

protect: (protect expr expr ...)

> (catch
>> (protect (throw 0)
>>> (print 'booger)
>>> (newline)))
booger
0
>

qquote: (qquote expr)

The commas escaping sub-expressions are separate tokens in Munger unlike in other lisps. For example ,token is parsed by Munger as two tokens, "," and "token". This means ',token parses to "(quote ,) token" and not "(quote ,token)".

if: (if expr1 expr2 [exp3...])

> (if (> 3 4) 'yes 'no)
no
> (if (> 3 4) 'yes)
0

and: (and expr1 [expr2 ...])

> (and 1 'a 0 1)
0
> (and 1 'a "string")
"string"

or: (or expr1 [expr2 ...])

> (or 1 0)
1
> (or 0 0)
0

list: (list expr1 [expr2 ...])

> (list 'a 'b 'c) ; is equivalent to (cons 'a (cons 'b (cons 'c ())))
(a b c)
> (list '(a b c) 4 "hello")
((a b c) 4 "hello")

progn: (progn expr...)

> (progn
>> (set 'f (lambda (n) (+ n 1)))
>> (set 'x 1)
>> (f x))
2

prog1: (prog1 ...)

> (prog1
>> (+ 2 2)
>> (+ 3 3))
4

not: (not expr)

> (not 0)
1
> (not "hello")
0

nullp: (nullp expr)

> (nullp ())
1
> (nullp 'a)
0

pairp: (pairp expr)

> (pairp '(a b c))
1
(pairp ())
0
(pairp 'a)
0

warn: (warn expr [expr...])

setenv: (setenv expr1 expr2)

unsetenv: (unsetenv expr)

getenv: (getenv expr)

> (getenv "HOME")
"/usr/home/jbailie"
> (getenv "foobar")
0

directory: (directory expr)

> (directory "/usr/local")
("man" "bin" "share" "include" "lib" "etc" "info" "libexec" "sbin" "libdata")
> (directory "/foobar")
"No such file or directory"

chomp: (chomp expr)

> (chomp (getline))
hello[return]
"hello"

> (getline)
hello[return]
"hello
"
>

chop: (chop expr)

> (chop "hello")
"hell"
> (chop "")
""

beep: (beep)

suspend: (suspend)

stderr2stdout: (stderr2stdout)

stdout2stderr: (stdout2stderr)

pipe: (pipe expr1 expr2)

The function accepts 2 arguments. The first argument must evaluate to 0, 1, or 2 and specifies the interpreter descriptor to be redirected. 0 is the interpreter's standard input. 1 is the interpreter's standard output. 2 is the interpreter's standard error. The second argument must evaluate to a string specifying a command line to run.

If the descriptor argument is 0, the other end of the pipe is connected to the other process's stdout. If the descriptor is 1 or 2, the other end of the pipe is connected to the process's stdin.

The command is passed to the shell (/bin/sh) for execution. Errors stop evaluation. On success "pipe" returns 1.

Redirection is undone by the "resume" intrinsic. Successive invocations of "pipe" on the same descriptor create a pipeline. If interpretation returns to the toplevel, all redirections are undone.

>(progn
>> (pipe 1 "fmt")
>> (pipe 1 "sort -n")
>> (for (a 100 1)
>>>   (print a)
>>>>  (newline)))
1
> 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25
26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47
48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69
70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91
92 93 94 95 96 97 98 99 100

Note the last line of output from the pipeline is a short line. After all the data was written to the pipeline, the "fmt" utility blocked, reading on its stdin, waiting for enough data to fill another line. When the "progn" returned to toplevel and the interpreter did an implicit "resume" on descriptor 1, the pipeline processes read EOF on the pipe, and "fmt" spat out the last line.

The output of the pipeline and the interpreter process are mixed up because they both have their standard outputs connected to the terminal. The 1 after the lisp is the return value of the lisp expression. This is followed by a the lisp prompt >, which is then followed by the output from the pipeline.

It is necessary to wrap the whole example in a "progn" to prevent the interpreter from returning to toplevel between subexpressions and undoing the redirections. The child process spawned by the second invocation of "pipe" inherited the redirection made by the first invocation of "pipe".

redirect: (redirect expr1 expr2 [expr3 [expr 4]])

If "redirect" is successful, the specified file descriptor is redirected onto the specified file, and 1 is returned. If an attempt is made to redirect descriptor 0 to a non-existent file, -1 is returned. If an attempt is made to redirect any descriptor onto a file to which the user lacks write permission, -2 is returned. If a lock cannot be acquired, -3 is returned. If "redirect" encounters any other error from the open() system call, a string string describing the error is returned. Errors from other sources stop the interpreter.

If execution returns to toplevel while, all redirections are undone by the interpreter.

temporary: (temporary)

with_temporary_output_file: (with_temporary_output_file expr...)

resume: (resume expr)

with_input_file: (with_input_file expr1 expr2 ...)

> (with_input_file "library.munger"
>> (print (getline)))
; This file contains the lisp library code for the Munger interpreter.
1

Calls to "with_input_file" can be nested.

> (with_input_file "library.munger"
>> (print (getline))
>> (with_input_file "INSTALL"
>>> (print (getline)))
>> (print (getline)))
; This file contains the lisp library code for the Munger interpreter.
Munger Installation
; Copyright (c) 2001, 2002, 2003, James Bailie <jimmy@mammothcheese.ca>.
1
>

with_output_file: (with_output_file expr1 expr2 ...)

> (with_output_file "tmp" (print "hello") (newline))
1
> (with_input_file "tmp" (print (getline)))
hello
1
(unlink "tmp")
1

with_output_file_appending: (with_output_file_appending expr1 expr2 ...)

with_error_file: (with_error_file expr1 expr2 ...)

with_error_file_appending: (with_error_file_appending expr1 expr2 ...)

with_input_process:

with_output_process:

> (with_input_process "ls"
   (while (set 'l (getline))
      (print l)))
INSTALL
LICENSE
Makefile
README
cat.munger
cgi.munger
cgi.munger
echo.cgi
err.munger
grep.munger
intrinsics.c
library.munger
lisp.c
lisp.h
munger.man
transform.munger

foreach_line: (foreach_line expr)

The argument pointer must be positioned so that the next call to (next) returns the first of the command line arguments. A script would normally process any option arguments, advancing the argument pointer as it did so, and then call foreach_line. "foreach_line" returns when it has processed all the specified files, or when it encounters EOF on stdin.

; Skip over the interpreter name, so that the argument pointer is now
; pointing to the script name.  The next invocation of (next)
; returns the next argument or 0.

(next)
(foreach_line (lambda (line) [do something with line] ))
(exit 0)

foreach_line_callback: (foreach_line_callback expr1 expr2 (expr3))

The "grep.munger" example program in (libdir) demonstrates using the third argument. The following script does not supply a third argument, and simulates wc -l:

(next)
(set 'script (current))
(set 'count 0)
(set 'total 0)

(set 'callback
   (lambda ()

      (let ((name (if (eq script (current)) "stdin" (current))))

         (print count " " name)
         (newline)
         (set 'total (+ total count))
         (set 'count 0))))

(foreach_line_callback (lambda (x) (inc count)) callback)
(print total  " total")
(newline)
(exit 0)

unlink: (unlink expr)

access: (access expr1 expr2)

mkdir: (mkdir expr)

rmdir: (unlink expr)

words: (words)

time: (time)

timediff: (timediff expr1 expr2)

timethen: (timethen expr)

> (timethen -3600)
"1124553616"

date2days: (date2days expr1 expr2 expr3)

days2date: (days2date expr)

week: (week expr)

weekday: (weekday expr)

month: (month expr)

localtime: (localtime expr)

utctime: (utctime expr)

date2time: (date2time expr1 expr2 expr3...)

The first 3 arguments represent the year (1970-), the month (1-12), and the day of the month (1-31). The fourth, fifth, and sixth optional arguments represent the hour, minute, and seconds. Omitted optional arguments default to 0. The presence of an optional argument implies the presence of all preceding optional arguments. This means if you include a value for minutes, you must include a value for hours as well, and if you include a value for seconds, you must include values for hours and minutes as well.

random: (random expr)

date: (date [expr [expr ]])

A non-zero second argument changes the UTC abbreviation to GMT.

> (date)
"Fri, 04 Oct 2002 12:06:11 EDT"
> (date 1)
"Fri, 04 Oct 2002 16:06:13 UTC"
> (date 1 1)
"Fri, 04 Oct 2002 16:06:16 GMT"

datethen: (datethen expr1 [expr2 [expr3 ]])

"datethen" returns a string describing the time argument formatted identically to the strings produced by the "date" intrinsic. If the second argument is 1, the returned time string is expressed in UTC. Otherwise, the time is specified relative to the local time zone. If the third argument evaluates to 1, then the timzone abbreviation is GMT instead of UTC.

Invoking (datethen (time)) is equivalent to invoking (date). Invoking (datethen (time) 1) is equivalent to invoking (date 1).

print: (print expr...)

println: (println expr...)

Intrinsic "println" functions similarly to "print", but "println" outputs a single newline character after printing its arguments.

> (print "hello there")
hello there
1

> (set 'f '(a b c))
(a b c)
1
> (print f)
(a b c)

> (print 'hello)
hello1

> (progn
>> (print 'hello)
>> (newline))
hello
1

The "newline" intrinsic outputs a newline character (ASCII 10) to stdout.

load: (load expr)

getline_ub: (getline_ub [expr])

"getline_ub" is an unbuffered version of the "getline" intrinsic. "getline_ub" allows the user to read lines of text from stdin and subsequently "fork" or "forkpipe" the interpreter and "exec" or "shexec" a new program without the child process losing access to data buffered by the parent. If the child does not call "exec" or "shexec", "getline_ub" is not necessary because the child has its own copy of the buffered data.

"getline_ub" reads a line from standard input and returns the line as a string that includes the terminating newline. If "getline_ub" does not encounter a newline after reading 2048 characters, the 2048 characters read are returned without a terminating newline. If EOF is encountered before a newline or 2048 characters is read, the returned string contains all the remaining data in the input stream. If no characters remain in the input stream, the intrinsic returns 0. If the read() system call fails the intrinsic returns 0.

The optional argument is a timeout value. "getline_ub" reads data a character at a time from stdin. If any invocation of the read() system call blocks for a longer number of seconds than that specified by the timeout value, read() is interrupted and "getline_ub" returns any characters already read. If no characters were read, the empty string is returned. If invoked without a timeout value, "getline_ub" blocks until at least one character can be read from stdin or EOF is encountered and return either a non-empty string or 0 on EOF.

getline: (getline [expr1 [expr2]])

"getline" reads a line from stdin and returns it as a string that includes the terminating newline. If "getline" does not encounter a newline before reading 2048 characters, the 2048 characters read are returned without a terminating newline. If EOF is encountered while searching for the next newline, all the remaining characters in the stream are returned. If no characters remain in the stream, "getline" returns 0. Any subsequent invocations of "getline" on the same input source continues to return 0. "getline" returns 0 when it encounters any error condition.

IF STDIN IS A TERMINAL:

The terminal is put into raw mode, and the interpreter simulates the UNIX terminal line discipline (ctrl-h => backspace; ctrl-w => werase; ctrl-u => kill). If Control-D (EOF) is encountered as the first character of input, "getline" returns 0. Otherwise EOF is ignored, and getline continues to accumulate characters until either a carriage return or a newline is input.

Carriage returns are converted into newlines. The strings returned by "getline" invoked on a terminal are always newline-terminated. The function drops the cursor to the last line of the terminal device and echoes input there. The echoed input scrolls horizontally if the input line grows longer than the width of the terminal device.

The function accepts two optional arguments that are ignored if stdin is not a terminal. The first argument must evaluate to a string and is printed as a prompt to the user.

The second argument must evaluate to a fixnum and specifies the location of tabstops in the onscreen echoed string. For example, a value of 4 causes tabstops to appear to the user to be set every four characters. If the second argument is not present, tabstops default to every 8 characters. Pass the empty string as the first argument if you wish to submit a second argument to the function, but you do not wish to print a prompt.

If the second argument is 0, the input of a tab character triggers filename completion. If the second argument is -1, tab triggers command and/or filename completion, depending upon the state of the input line when the tab is received. If the second argument is -2, tab triggers filename completion, but the filename completion mechanism does not work recursively. If the second argument is -3, tab triggers command and/or filename completion, but the filename completion mechanism does not work recursively. For the cases where the filename completion mechanism does not work recursively (second argument of -2 -3), "getline" completes one level of the path. If completion is invoked again at this point, "getline" completes another level. For the cases where the filename completion works recursively, "getline" completes as much of the path as possible.

When command and filename completion have been requested and the text entered so far consists of only non-whitespace characters, then command completion is attempted. Otherwise, filename completion is attempted upon the last contiguous segment of non-whitespace characters. If the first character input is either '/' or '.' then filename completion is attempted in the initial position instead of command completion.

Completions work with a command or filename that contains whitespace only if the portion before the cursor does not contain whitespace. Quoting mechanisms are not available. "getline" appends a single space character to the input string after an unambiguous completion.

When completions are requested, each string created with "getline" is placed onto a 500-line history list and can be recalled, edited and re-entered. Pressing Contol-P or Control-N causes the current text to be replaced with the previous or the next text on the history list. While in the history list, invoking Control-X restores the original text.

When completions are requested, pressing Control-R or Control-S causes the interpreter to enter history search mode. The interpreter searches forward (C-S) or backward (C-R) in the history list for a line containing the input text. Pressing C-s or C-r again causes the interpreter to search forward or backward for another matching history line. Both Control-R and Control-S wraparound the ends of the history list. Control-H and Backspace erase the last character of the search term.

The history is cleared with the "reset_history" intrinsic.

When completions are requested, these command-line editing commands are recognized by "getline" in addition to C-h, C-w, and C-u:

M-f - moves the cursor to the beginning of the next word in the line.
M-b - moves the cursor to the beginning of the previous word in the line.
C-k - deletes the text from the cursor location to the end of the line.
C-d - deletes the character the cursor is on.
M-d - deletes the word or word-portion the cursor is before.
C-a - moves the cursor to the beginning of the line.
C-e - moves the cursor to the end of the line.
C-y - pastes the last deletion into the line before the cursor.

Additionally, when completions are active, C-u does not delete the entire
line but only the portion before the cursor.

reset_history (reset_history)

load_history (load_history expr)

save_history (save_history expr)

rescan_path: (rescan_path)

stringp: (stringp expr)

> (stringp "0")
1
> (stringp 0)
0

fixnump: (fixnump expr)

> (fixnump 0)
1
> (fixnump "0")
0

symbolp: (symbolp expr)

regexpp: (regexpp expr)

tablep: (tablep expr)

stackp: (stackp expr)

intrinsicp: (intrinsicp expr)

closurep: (closurep expr)

macrop: (macrop expr)

recordp: (recordp expr)

sqlitep: (sqlitep expr)

regcomp: (regcomp expr1 [expr2 [expr 3]])

If the second optional argument is present, it must evaluate to a fixnum. If non-zero, the argument causes "regcomp" to produce a compiled regular expression that matches text case-insensitively. Without the second argument, "regcomp" defaults to case-sensitive matching. If the third optional argument is present, it must evaluate to a fixnum. If non-zero, the argument prevents "regcomp" from recognizing regular expression operators in the first argument. The resulting compiled expression matches the literal string value of the first argument.

In the first argument, the escape-sequences \t, \b, \r, and \n represent the tab, space, carriage return, and newline characters, and the zero width assertions \< and \> match the null string at the beginning and end of a word. All escape sequences are ignored if a non-zero third argument has been passed to "regcomp".

substitute: (substitute expr1 expr2 expr3 [expr4])

The "substitute" function takes 3 or 4 arguments. The first argument must evaluate to a compiled regular expression. The second and third arguments must evaluate to strings and are interpreted as the replacement string and the string to search for matches in. The fourth optional argument must evaluate to a number that specifies the number of matches that should be replaced. A value of 0 indicates the substitution should replace all the matches of the pattern in the text of the third argument. The absence of the fourth argument is the same as having a fourth argument of 1. Only the first match is replaced.

The text matched by the first ten subexpressions in the regular expression is inserted into the replacement string by including an escape sequence of the form \[0-9] in the replacement text where one wishes the matched text to appear. The first subexpression is referred to by \1 and the tenth subexpression is referred to by \0. The text matched by the entire regular expression is inserted into the replacement text by inserting \& into the replacement string. In the replacement string, unrecognized escape sequences are ignored. To escape a backslash, you must insert a total of four backslashes in the replacement string. A level of escaping is removed by the lisp string parser leaving two backslashes for "substitute" to see, the first one escaping the second.

> (substitute (regcomp "string") "booger" "string string string string" 2)
"booger booger string string"

> (substitute (regcomp "[a-z]+") "{\&}"  "one two three" 0)
"{one} {two} {three}"

> (substitute (regcomp "([a-zA-Z]+) ([a-zA-Z]+)") "\2 \1"
>> "is This sentence a."  0)
"This is a sentence."

The "substitute" intrinsic interprets the two-character escape-sequences \t and \b as the tab and space characters. Five other escape sequences are embedded in the replacement string to control the case of portions of the returned string. These escape sequences work for strings of ASCII alphanumeric characters only:

\U Turns on conversion to uppercase.
\u Turns on conversion to uppercase for the next character only.
\L Turns on conversion to lowercase.
\l Turns on conversion to lowercase for the next character only.
\e Turns off \U or \L.

> (substitute (regcomp "foo") "\U\&\e" "foobar")
"FOObar"

The effects of \U and \L extend beyond the replacement string if they are not terminated:

> (substitute (regcomp "foo") "\U\&"  "foobar")
"FOOBAR"

\U and \L override each other:

> (substitute (regcomp "foo") "\U\&\L" "foobar FUNBAG")
"FOObar funbag"

match: (match expr1 expr2)

> (set 'rx (regcomp "foobar"))
<REGEXP#3>
> (set 's "---foobar---")
"---foobar---"
> (match rx s)
(3 9)
> (substring s 0 3) ; text before the match
"---"
> (substring s 3 (- 9 3)) ; text of the match
"foobar"
> (substring s 9 0) ; text after the match
"---"

In the previous exampe, if the first returned index were 0, the first invocation of "substring" would have returned the whole string. Passing a third length argument of 0 to "substring" means "to the end of the string." The user must check for this situation before invoking "substring".

matches: (matches expr1 expr2)

If no match is found, the list is empty. Otherwise, a list of twenty strings is returned. The first string is the text matched by the entire regular expression. The subsequent elements are the text matched by the first nineteen parenthesized subexpressions in the regular expression. If nineteen subexpressions are not present in the regular expression, empty strings are returned for the missing subexpressions. If a subexpression fails to match, an empty string is returned in the corresponding list position.

> (matches (regcomp "[0-9]+") "I have 22 figurines.")
("22" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "")
> (matches (regcomp "([0-9])+") "12345")
("12345"  "5" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "")
> (matches (regcomp "([0-9]+)") "12345")
("12345"  "12345" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" ")

split: (split expr1 expr2 [expr3])

> (split " "  "one two three four")
("one" "two" "three" "four")
> (split " "  "one two three four" 3)
("one" "two" "three four")
> (split "" "one two three four" 3)
("o" "n" "e two three four")
> (split ":" ":a:b:c:")
("" "a" "b" "c" "")

split_rx: (split_rx expr1 expr2 [expr3])

> (setq rx (regcomp "[\b\t]+"))
<REGEXP#34>
> (split_rx rx "foobar    tooley marzipan  loopy    ")
("foobar" "tooley" "marzipan" "loopy")

rootname: (rootname expr)

> (rootname "foobar.tar.gz")
"foobar.tar"
> (rootname (rootname "foobar.tar.gz"))
"foobar"

suffix: (suffix expr)

> (suffix "foobar.tar.gz")
".gz"
> (suffix (rootname "foobar.tar.gz"))
".tar"

tokenize: (tokenize expr)

> (tokenize "  foobar tooley   hot-cha-cha!")
("foobar" "tooley" "hot-cha-cha!")

replace: (replace expr1 expr2 expr3 [expr4])

The macro accepts 3 or 4 arguments. The first argument must evaluate to a compiled regular expression. The second argument is evaluated in a lexical context where the symbols m0...m19 are bound to the text of the full match and the text matched by the first nineteen parenthesized subexpressions.

The string produceshd by this argument undergoes escape-processing when it is ultimately used as the replacement pattern for a call to the "substitute" intrinsic. You can pass a string as the second argument, but it is much more efficient to use "substitute" with a string argument.

The third argument must evaluate to the string the regular expression is to be matched against. The fourth optional argument must evaluate to a fixnum specifying a repeat count. The count limits the number of replacements made in the string. Unlike "substitute", "replace" interprets a repeat count of 0 as a request to inhibit all substitutions. If the repeat count is not present, all matches in the string undergo replacement. If the regular expression matches the second argument, "replace" returns a new string containing the specified substitutions. If no match is found, "replace" returns the original string.

The following example uses "replace" to decode x-www-form-url-encoded characters in a specified string.

> (setq str "foobar+tooley%7Efunbag%24%25%26")
"foobar+tooley%7Efunbag%24%25%26"

> (setq r0 (regcomp "%([0-9A-Fa-f][0-9A-Fa-f])"))
<REGEXP#10>
> (setq r1 (regcomp "\+"))
<REGEXP#11>

; Decode encoded spaces.

> (setq str (substitute r1 " " str 0))
"foobar tooley%7Efunbag%24%25%26"

; Decoded hex encodings.

>(setq str
>> (replace r0
>>>        (char (hex2dec m1))
>>>        str))
"foobar tooley~funbag$%&"

concat: (concat expr ...)

> (concat "foo" "bar")
"foobar"
> (concat '("foo" "bar"))
"foobar"

explode: (explode expr)

> (explode "foobar")
("f" "o" "o" "b" "a" "r")

join: (join expr1 expr2 expr3...)

> (join " "  "This" "will" "be" "a" "sentence.")
"This will be a sentence."
> (join ""  "this" "will" "be" "run" "together")
"thiswillberuntogether"
> (join ":" '("a" ("b" ("c") "d") "e"))
"a:b:c:d:e"

length: (length expr)

> (length "fiver")
5
> (length '(a b c))
3

sort: (sort [expr...])

> (sort "D" "c" "B" "a")
("a" "B" "c" "D")
> (sort 3 2 1)
(3 2 1)

sortlist: (sort expr)

> (sortlist '("c" "b" "a"))
("a" "b" "c")
> (sortlist '(0 -23 1))
(-23 0 1)

sortcar: (sortcar expr)

The following example sorts a stack-of-stacks, using the second element of each substack as the sort key.

> (set 's (stack 3))
<STACK1>
> (store s 0 (assign (stack) '(f 2 f)))
<STACK2>
> (store s 1 (assign (stack) '(f 1 f)))
<STACK3>
> (store s 2 (assign (stack) '(f 0 f)))
<STACK4>
> (flatten s)
(<STACK2> <STACK3> <STACK4>)
> (assign s (mapcar (lambda (x) (cadr x))
                    (sortcar (mapcar (lambda (x) (list (index x 1) x))
                                     (flatten s)))))
<STACK1>
> (flatten s)
(<STACK4> <STACK3> <STACK2>)

until: (until expr1 [expr2 ...])

while: (while expr1 [expr2 ...])

"until" behaves similarly "while", but the logic of the test is inverted. The body of an "until" loop is executed when the test condition evaluates to a false value. "until" returns the final evaluation of the test, which is a true value.

> (setq n 10)
10
> (while n
>>> (print n)
>>> (newline)
>>> (setq n (- n 1)))
10 9 8 7 6 5 4 3 2 1
1
> (setq n 0)
0
> (setq l ())
()
> (until (eq n 10)
>> (setq l (cons (inc n) l)))
1
> l
(10 9 8 7 6 5 4 3 2 1)

do: (do expr1 [expr2 ...])

> (set 'n 0)
0
> (do
>> (print n)
>> (newline)
>> (set 'n (+ n 1)))
> (< n 10))
0 1 2 3 4 5 6 7 8 9
1
>

fatal: (fatal)

nofatal: (nofatal)

die: (die [expr...])

throw: (throw expr)

catch: (catch [expr1]...)

If "throw" is invoked outside of a "catch", the interpreter returns to toplevel.

> (catch
>> (print (catch 0 (throw 'hello) 2 3 4))
>> (newline)
>> (throw 'goodbye)
>> (print 'not_reached))
hello
goodbye
>

stringify: (stringify expr...)

> (stringify 12 ","  43)
"12,43"
> (stringify 'hello " "  'there)
"hello there"

digitize: (digitize expr)

> (digitize '42)
42
> (digitize "-3")
-3
> (digitize "abc")
0

mapcar: (mapcar expr1 expr2)

> (set 'l '(a b c))
(a b c)
> (set 'f (lambda (n) (list n n n)))
<CLOSURE#23>
> (mapcar f l)
((a a a) (b b b) (c c c))

map: (map expr1 expr2 ...)

> (map (lambda (x y z) (+ x y z)) '(1 2 3) '(4 5 6) '(7 8 9))
(12 15 18)

remove: (remove expr1 expr2)

> (remove 'a '(a a a b))
(b)

> (remove '(a b) '((a b) c (a b) (a b) d e f g))
(c d e f g)

nthcdr: (nthcdr expr1 expr2)

> (nthcdr '(a b c) 1)
(b c)
> (nthcdr '(a b c) 2)
(c)
> (nthcdr '(a b c) 3)
()

nth: (nth expr1 expr2)

> (setq l '(a b c))
(a b c)
> (for (n (length l) 0)
>>  (println (nth l n)))
()
c
b
a
0 ; This is the return value of "while"

member: (member expr1 expr2)

> (member 'a '(a b c))
1

reverse: (reverse expr1)

> (reverse '(a b c))
(c b a)
> (reverse "hello")
"olleh"

append: (append expr1 ...)

(append '(a b c) '(d e f))
(a b c d e f)

loop: (loop expr1 ...)

> (catch
>> (loop
>>> (if (setq line (getline))
>>>> (print line)
>>>> (throw line))))

iterate: (iterate expr1 ...)

> (iterate 10 (print "A"))
AAAAAAAAAA1

The 1 is the return value of the "print" intrinsic, which is in turn the return value of "iterate".

for: (for (symbol expr1 expr2 [expr3]) expr ...)

for: (for (([expr...]) (expr [...]) ([expr...])) expr ...)

FIRST FORM.

The first form implements loops with an index variable. "iterate" is the most efficient means of iterating a fixed number of times. "iterate" accepts 2 or more arguments. The first argument must be a three or four element list. The first 3 arguments must be a symbol to be used for the loop index variable, an expression evaluating to the initial fixnum value for the index variable, and an expression evaluating to the fixnum value the index variable should have on the last iteration of the loop. The fourth optional element is an increment value.

If the start value is less than or equal to the stop value, the index variable is incremented on each iteration. Otherwise, the index variable is decremented on each iteration. Each of the remaining arguments is evaluated in each iteration of the loop. "for" returns the evaluation of the last argument evaluated on the last iteration.

The optional fourth element in the first argument list must evaluate to a fixnum specifying the increment or decrement value. The absolute value of the argument is added if the first element is less than or equal to the second element. The absolute value of the argument is subtracted from the index variable if the first element is greater than the second element. If the fourth element is not present, the increment value defaults to 1. If incrementing or decrementing the index variable results in values that do not become the stop value, the index on the last iteration of the loop is the last value that was within the inclusive range specified by the start and stop values.

A "for" loop introduces a new environment for the loop's index variable. If a closure is formed in the body of a "for" loop, the closure captures the new environment. Any invocations of "extend" or "dynamic_extent" inside of a "for" loop body affect the environment of the loop and not the environment in which the loop is embedded.

> (for (n 0 10 2)
>> (println n))
0
2
4
6
8
10
1 ; return value of "println"

> (set 'a 5)
5
> (for (a a 1)
>> (for (a a (+ a a))
>>> (print a " "))
>> (newline))
5 6 7 8 9 10
4 5 6 7 8
3 4 5 6
2 3 4
1 2
1 ; return value of inner "newline"
>

It is possible to invoke "continue" inside a for loop such that no return value is ever generated by any of the contained expressions. In that case, "for" returns 0.

SECOND FORM

The second form of the "for" intrinsic provides a more generic looping facility. With this form, the first argument must also be a three-element list, and the subsequent arguments are the loop's body expressions, but each sublist of the first argument list must also be a list. The first sublist is a list of expressions to be evaluated in order before any other part of the loop is evaluated. The first sublist can be empty. The second sublist consists of 1 or more expressions. The first expression is the test condition, and is evaluated before every entry into the loop body. The remaining elements are the final expressions that are evaluated as the last act of the loop. The elements after the test expression can be omitted. The third sublist contains the update expressions to be evaluated after evaluation of the loop body expressions. The third sublit can be empty.

Evaluation of the loop proceeds as follows. The initialization expressions are evaluated.

LABEL: REPEAT

The test condition is evaluated. If the evaluation of the test condition results in a false value, the elements after the test condition are evaluated in order. "for" returns the last evaluation. If there are no expressions after the test expression, the evaluation of the failed test expression is the return value of the loop. The loop is finished.

If the evaluation of the test condition results in a true value, each of the body expressions are evaluated in order, and then each of the elements of the update sublist are evaluated. Goto REPEAT.

(defun fact (n)
   (for (((extend 'a 1)) ((> n 1) a) ((dec n)))
      (setq a (* n a))))

downcase: (downcase expr1 expr2)

upcase: (upcase expr1 expr2)

The "downcase" library function behaves similarly to "upcase" except that "downcase" converts lowercase characters to uppercase.

alist_lookup: (alist_lookup expr1 expr2)

> (set 'y '((a b) (b c)))
((a b) (b c))
> (alist_lookup 'b y)
(c)
>

alist_remove: (alist_remove expr1 expr2)

> (set 'y '((a b) (b c)))
((a b) (b c))
> (alist_remove 'b y)
((a b))
> y
((a b) (b c))
>

alist_replace: (alist_replace expr1 expr2 expr3)

> (set 'y '((a b) (b c)))
((a b) (b c))
> (alist_replace 'b y '(d e f))
((b d e f) (a b))
> (set 'y ())
()
> (alist_replace 'b y '(d e f))
((b d e f))
>

when: (when expr1 expr2...)

> (when (eq 1 1)
>> (print 'hello)
>> (newline))
hello
1
>

unless: (unless expr1 expr2...)

> (unless (eq 1 1)
>> (print 'hello)
>> (newline))
1
>

apply: (apply expr1 expr2)

> (apply 'set '('q 2))
2

inc: (inc symbol [expr])

dec: (dec symbol [expr])

> (set 'a 1)
1
> (inc a)
2
> (dec a)
1
> (inc a 10)
11

test: (test expr1)

> (test (quit))
(exit 0)

continue: (continue)

If "continue" is invoked outside of the body of a loop, the interpreter returns to toplevel.

> (set 'n 10)
10
> (while n
>> (print n)
>> (newline)
>> (set 'n (- n 1))
>> (continue)
>> (set 'n 0))
10
9
8
7
6
5
4
3
2
1
0
>
The last 0 is the return value of the "while" intrinsic.

block: (block)

unblock: (unblock)

The interpreter starts out in the unblocked state. When in the unblocked state, the interpreter is killed upon receipt of SIGINT, SIGQUIT, and SIGHUP. The interpreter generates a core dump upon receipt of SIGQUIT. When in the unblocked state, the interpreter is stopped upon receipt of SIGTSTP, SIGTTIN, or SIGTTOU. Invoking "block" renders all of these signals impotent. Both of these intrinsics always return 1.

SIGTERM is caught by the interprepter. The "sigtermp" intrinsic can be used to detect the occurrence of SIGTERM.

sigtermp: (sigtermp)

exists: (exists expr)

If stat() succeeds, "exists" returns a value in the range of 1 to 8. If stat() fails, "exists" returns 0 or -1. If the file does not exist, "exists" returns 0. If the interpreter lacks permission to search one of the directories in the filename, "exists" returns -1. The interpreter does not need permission to read the file itself in order to stat() it. Successful return values are as follows.

1 == regular file
2 == directory
3 == character device
4 == block device
5 == fifo
6 == symbolic link
7 == socket
8 == unknown type

stat: (stat expr)

Upon successful return of stat(), "stat" returns a 5-element list. The first element is a string describing the user name of the file. If the uid does not map to a user on the system, the first element is the uid as a fixnum. The second element is a string describing the group name of the file. If the gid does not map to a group on the system, the first element is the gid as a fixnum. The third element is the time of the last access of the file as a string. The fourth element is the time of the last modification of the file as a string. The fifth element is the size of the file. The time values are expressed in seconds elapsed since the UNIX Epoch (00:00:00 January 1, 1970 UTC).

> (stat (current))
("root" "wheel" "1097210850" "1097210836" 417214)

rename: (rename expr1 expr2)

current: (current)

prev: (prev)

next: (next)

rewind: (rewind)

interact: (interact)

Control-D or "_" input causes the program that invoked "interact" to resume. "interact" returns 1. Recursive invocations of "interact" cause a string to be returned with an error message, but evalution at the prompt of the original invocation continues normally. Note that the "fatal" intrinisic has no effect when lisp errors are generated inside "interact". The interpreter does not exit when an error is generated by the user working at the "interact" prompt.

The current local environment is hidden from "interact".

pwd: (pwd)

let: (let [list] expr2 ...)

"let" accepts 2 or more arguments. The first argument is not evaluated and must be a parameter list of the form: ((symbol1 expr1) (symbol2 expr2)...). The result of evaluating each exprN in the current scope gets bound to its paired symbolN in the new scope. The remaining arguments are evaluated in the new scope. "let" returns last evaluation.

> (let ((a 1) (b 2))
>> (print "a: "  a "  b: "  b)
>> (newline))
a: 1
b: 2
1 ; This is the return value of (newline)
> (set 'a 2)
2
> (let ((a (* a a)))
>> (while a
>>>> (print "a: "  a)
>>>> (newline)
>>>> (set 'a (- a 1))))
a: 4
a: 3
a: 2
a: 1
0
> a
2

letn: (letn [list] expr2 ...)

"letn" accepts 2 or more arguments. The first argument is not evaluated and must be a parameter list of the form: ((symbol1 expr1) (symbol2 expr2)...). The result of evaluating each exprN in the current scope gets bound to its paired symbolN in the new scope. The remaining arguments are evaluated in the new scope. "letn" returns the last evaluation.

Intrinsic "letn" is different from intrinsic "let" in that each binding made to symbolN is visible in exprN+1, exprN+2, etc. This form is called "let*" in Scheme and Common Lisp.

> (letn ((a 1)
>>>      (b (+ a 1)))
>> (print "b: "  b)
>> (newline))
b: 2
1
>

letf: (letf [list] expr2 ...)

> (setq a 10)
10
> (letf fact ((n a))
>> (if (< n 2)
>>>    n
>>>    (* n (fact (- n 1)))))
3628800
>

tailcall: (tailcall expr1 ...)

Note that invoking "tailcall" from a non-tail position, results in that position becoming a tail position. Any pending computation in the function is abandoned.

labels: (labels [list] expr2 ...)

> (labels ((even (lambda (n) (or (eq n 0) (tailcall odd (- n 1)))))
>>>        (odd  (lambda (n) (and (not (eq n 0)) (tailcall even (- n 1))))))
>> (print (even 11))
>> (newline))
0
1 ; This is the return value of the "newline".

extract: (extract expr)

> mapcar
<CLOSURE#17>
> (extract mapcar)
(lambda (f l) (if (pairp l) (cons (f (car l)) (mapcar f (cdr l))) ()))

cond: (cond [list] ...)

> (set 'a 10)
10
> (cond ((eq a 12) 'no)
>>      ((eq a 10) 'yes))
yes
>

case: (case expr expr2 ...)

If the first element of any of the argument lists is a question mark, the elements of that list are evaluated if none of the preceding lists are evaluated.

> (setq n 3)
3
> (case n
>> (1 'one)
>> (2 'two)
>> (3 'three)
>> (4 'four)
>> (5 'five))
three
(setq n 11)
> (case n
>> (6 'six)
>> (7 'seven)
>> (8 'eight)
>> (9 'nine)
>> (10 'ten)
>> (? "no match"))
"no match"

foreach: (foreach expr1 expr2)

> (set 'print_each
>> (lambda (x) (print x) (newline)))
<CLOSURE#34>
> (foreach print_each '(a b c d))
a
b
c
d
()
>

+: (+ expr...)

> (+ 1 1 1 1)
4
> (+ 1 "hello")
+: argument 2 did not evaluate to a number.

-: (- expr1 expr2)

> (- 1 2)
-1
> (- (+ 1 1) 2)
0

*: (* expr...)

> (* 1 12 2)
24
> (* (+ 23 3) 4)
104

/: (/ expr1 expr2)

> (/ 4 3)
1

%: (% expr1 expr2)

> (% 4 3)
1

>: (> expr1 expr2)

> (> 4 3)
1
> (> -4 3)
0

>=: (>= expr1 expr2)

> (>= 4 3)
1

<: (< expr1 expr2)

> (< 4 3)
0

<=: (<= expr1 expr2)

> (<= 3 4)
0

negate: (negate expr)

> (negate 3)
-3
> (negate -3)
3

abs: (abs expr)

intern: (intern expr1)

> (set 'hello 4)
4 (eval (intern "hello"))
4

char: (char expr1)

code: (code expr1)

open: (open)

close: (close)

insert: (insert expr1 expr2 expr3)

"insert" returns 1, 0 on failure.

> (open)
1
> (insert 1 "This is the first line." 0)
1

delete: (remove expr1)

retrieve: (retrieve expr1)

lastline: (lastline)

filter: (filter expr1 expr2 expr3)

Upon success, "filter" returns the number of lines read from the stdout of the child process. Errors stop evaluation.

filter_server: (filter_server expr1 expr2 expr3 expr4)

The third and fourth arguments are passed to the "child_open" intrinsic. See the entry in this manual for that function for what these 2 arguments can be. "filter_server" returns the number of lines read back from the server.

> (open)
0
> (insert 1 (concat "GET / HTTP/1.0" (char 10)) 0)
1
> (insert 2 (char 10) 0)
1
> (filter_server 1 2 "www.mammothcheese.ca" 80)
306

remove_http_stuff: (remove_http_stuff)

write: (write expr1 expr2 expr3 expr4 [expr5])

The first line number argument does not have to be less than the second line number argument, but the lines in the region are written to the file in ascending order regardless of how the region was specified.

Whitespace in the filename can either be literally present or represented with the \t and \b escapes. If you wish to use a literal \b or \t in the filename, escape the backslash itself and use \\\\b or \\\\t instead.

On success, "write" returns the number of lines written. If an error occurs when opening the file, "write" returns a string describing the error. Other errors stop evaluation.

read: (read expr1 expr2)

Whitespace in the filename can either be literally present or represented with the \t and \b escapes to represent the tab and the space character, respectively. If you wish to use a literal \b or \t in the filename, escape the backslash itself and use \\\\b or \\\\t instead.

empty: (empty)

slice: (slice expr1 expr2 expr3 expr4 expr5)

The fifth argument specifies what "slice" returns. A value of 0 indicates that the caller wishes to receive the specified slice as a string. A value of 1 indicates that the caller wishes to receive a two-element list describing the specified slice. The first element of this list is the length of the slice in characters, which can be less than the specified length if the specified length extended past the end of the line. The first element describes the actual length of the slice in the buffer before tab expansion. The second element is the number of extra characters that would be added to the line during tab expansion from the beginning of the line to the end of the specified slice.

find: (find expr1 expr2 expr3 expr4 expr5)

The first 3 arguments and the 3 argument must evaluate to fixnums. The fourth argument must evaluate to a compiled regular expression. The first argument specifies the direction of the search. A positive value causes the search to proceed forward in the buffer. A negative value causes the search to proceed backwards in the buffer. The second argument is the line number at which to start the search. The third argument is the character position within the line at which to start the search. Lines in the buffer are numbered from 1. Characters positions are numbered from 0. The fifth argument specifies if the search should "wraparound". A non-zero value enables wraparound. 0 disables wraparound.

The fourth argument is the compiled regular expression to search with. A match starting exactly at the specified starting place is ignored, and the position of the next non-overlapping match is sought. Newlines are temporarily removed from the end of buffer lines before matching. ^$ matches empty lines.

"find" returns a list of 3 numbers. If a match was found, the first element is the index of the line containing the match. The second element is the character position of the start of the matched text. The third element is the length in characters of the match. If no match is found, all three values are zero.

> (open)
0
> (insert 1 "this is the first line in the buffer." 0)
1
> (set 'f (find 1 1 0 (regcomp "buffer") 0)
(1 30 7)
> (substring (retrieve (car f)) (cadr f) (car (cddr f)))
"buffer"

The following function counts the number of blank lines in the buffer.

(set 'blank
(lambda ()

   (let ((idx 1)
         (regexp (regcomp "^[\b\t]*$"))
         (count 0))

       (while (setq idx (car (find 1 idx 0 regexp 0)))
         (inc count))

       count)))

buffer: (buffer)

buffers: (buffers)

switch: (switch expr)

setmark: (setmark expr1 expr2)

getmark: (getmark expr1)

transfer: (transfer b1 f1 t1 b2 t2)

with_buffer: (with_buffer expr1 expr2 ...)

version: (version)

gensym: (gensym)

(let ((buff (gensym)))

   (set 'with_buffer
      (macro (x (y))

         (qquote
            (let ((,buff (buffer)))
               (switch ,x)
               (protect ,(cons 'progn y)
                  (switch ,buff)))))))

libdir: (libdir)

> (libdir)
"/usr/local/share/munger"
>

strcmp: (strcmp expr1 expr2)

> (strcmp "a" "b")
-1
> (strcmp "b" "a")
1
> (strcmp "a" "a")
0
> (strcmp "A" "a")
-32

substring: (substring expr1 expr2 expr3)

> (substring "foobar" 0 0)
"foobar"
> (substring "foobar" 3 0)
"bar"
> (substring "foobar" 0 3)
"foo"
> (substring "foobar" 0 10)
"foobar"

expand: (expand expr1 expr2)

lines: (line)

cols: (cols)

exit: (exit)

complete: (complete expr)

> (complete "/usr/share/pe")
("/usr/share/perl/man/" "./     ../    man3/  whatis cat3/
                        ")

A leading ~ in the argument to "complete" triggers home directory abbreviation expansion. "complete" does not complete an incompletely named home directory.

input: (input expr1 expr2)

Whitespace in the filename can either be present literally or represented with the \t and \b escapes. If you wish to use a literal \b or \t in the filename, you must escape the backslash itself and use \\b or \\t instead.

output: (output expr1 expr2 expr3)

Whitespace in the filename can either be present literally or represented with the \t and \b escapes. If you wish to use a literal \b or \t in the filename, you must escape the backslash itself and use \\b or \\t instead.

system: (system expr1)

maxidx: (maxidx)

chdir: (chdir expr1)

table: (table)

hash: (hash expr1 expr2 expr3)

> (set 't (table))
<TABLE#0>
> (hash 'zero "zero")
"zero"

keys: (keys expr1)

> (set 't (table))
<TABLE#0>
> (hash t "0" "zero")
"zero"
> (hash t "1" "one")
"one"
> (keys t)
("1" "0")

values: (values expr1)

> (set 't (table))
<TABLE#0>
> (hash t "0" "zero")
"zero"
> (hash t "1" "one")
"one"
> (hash t "2" "two")
"two"
> (values t)
("two" "zero" "one")

unhash: (unhash expr1 expr2)

> (set 't (table))
<TABLE#0>
> (hash t "0" "zero")
"zero"
> (unhash t "0")
0
> (keys t)
()

lookup: (lookup expr1 expr2)

> (set 't (table))
<TABLE#0>
> (hash t "1" "one")
"one"
> (hash t "0" "zero")
"zero"
> (lookup t "1")
"one"
> (lookup t "0")
"zero"
> (lookup t "2")
()

sqlite_open: (sqlite_open expr)

sqlite_close: (sqlite_close expr)

sqlite_exec: (sqlite_exec expr1 expr2)

sqlite_prepare: (sqlite_prepare db sql)

> (setq db (sqlite_open "document.db"))
<db#1>
> (setq sql (sqlite_prepare "SELECT path FROM document WHERE parent = 0"))
<sql#1>

sqlite_bind: (sqlite_bind sql index text)

Note that "sqlite_bind" must be invoked on a SQL statement after a call to "sqlite_prepare" or "sqlite_reset", and before any call to "sqlite_step".

> (setq db (sqlite_open "example.db"))
<DB#1>
> (setq sql (sqlite_prepare db "SELECT name FROM employees WHERE job = ?"))
<SQL#1>
> (sqlite_bind sql 1 "supervisor")
1

> (for (((setq more (sqlite_step sql)))
        (more)
        ((setq more (sqlite_step sql))))
>> (print (sqlite_row sql))
>> (newline))

("Bob")

> (sqlite_reset sql)
1
> (sqlite_bind sql 1 "technician")
1

> (for (((setq more (sqlite_step sql)))
        (more)
        ((setq more (sqlite_step sql))))
>> (print (sqlite_row))
>> (newline)

("Sally")
("Jeffrey")
("Boodles the cat")
("George")

sqlite_step: (sqlite_step sql)

sqlite_row: (sqlite_row sql)

> (setq db (sqlite_open "document.db"))
<db#1>
> (setq sql (sqlite_prepare "SELECT * FROM table1"))
<sql#1>
> (for (((setq more (sqlite_step sql))) (more) ((setq more (sqlite_step sql))))
>> (print (sqlite_row sql))
>> (newline))
("first column first row" "second_column first row")
("first column second row" "second_column second row")

sqlite_reset: (sqlite_reset sql)

sqlite_finalize: (sqlite_finalize sql)

sqlp: (sqlp expr)

stack: (stack [expr])

> (set 's (stack))
<STACK1>
> (used s)
0
> (set 's (stack 10))
<STACK2>
> (used s)
10

push: (push expr1 expr2)

> (set 's (stack))
<STACK1>
> (push s 'foo)
foo
> (index s 0)
foo

pop: (pop expr)

> (set 's (stack))
<STACK1>
> (push s 'foo)
foo
> (push s 'bar)
bar
> (pop s)
bar
> (pop s)
foo
> (pop s)
()
> (used s)
0

unshift: (unshift expr1 expr2)

> (set 's (assign (stack) '(1 2 3 4)))
<STACK1>
> (flatten s)
(1 2 3 4)
> (unshift s 0)
0
> (flatten s)
(0 1 2 3 4)

shift: (shift expr)

> (set 's (assign (stack) '(0 1 2 3 4)))
<STACK1>
> (flatten s)
(0 1 2 3 4)
> (shift s)
0
> (shift s)
1
> (flatten s)
(2 3 4)

index: (index expr1 expr2)]

> (set 's (assign (stack) '(a b c)))
<STACK1>
> (index s 0)
a
> (index s 2)
c
> (index s 3)
<INDEX>: index 3 out of range.
>

topidx: (topidx expr)

> (topidx (stack 1))
0

used: (used expr)

> (used (stack 10))
10

store: (store expr1 expr2 expr3)

> (set 's (stack 3))
<STACK1>
> (store s 0 'foo)
foo
> (store s 1 'bar)
bar
> (store s 2 'wumpus)
wumpus
> (flatten s)
(foo bar wumpus)
> (store s 3 'error)
<STORE>: index 3 out of range.
>

clear: (clear expr1 expr2)

> (setq s (assign (stack) '(1 2 3 4 5)))
<STACK#1>
> (clear s 4)
1
> (flatten s)
(1)
> (assign s '(1 2 3 4 5))
<STACK#1>
> (clear s (used s))
1
> (flatten s)
()

assign: (assign expr1 expr2)

> (set 's (assign (stack) '(a b c d e)))
<STACK1>
> (used s)
5

flatten: (flatten expr)

> (flatten (assign (stack) '(a b c d e)))
(a b c d e)

child_open: (child_open expr [expr])

With 1 argument, the argument must evaluate to a string specifying a command to pass to the shell. On success, "child_open" returns 1. On error, "child_open" returns a string describing the error. If the child process cannot run the specified program, the child process prints an error to stderr and exits. The user can invoke "child_running" to verify the successful launch of the program.

With 2 arguments, "child_open" opens a full-duplex stream with another process over a TCP or UNIX socket. For TCP connections, the first argument must evaluate to a string that specifies the remote hostname or IP address. For UNIX connections, the first argument must evaluate to a string that names the socket file. For TCP connections, the second argument must evaluate to a string specifying a service defined in /etc/services or to a fixnum specifying a port number. For UNIX connections, the second argument must be 0.

On success "child_open" returns 1. On error "child_open" returns a string describing the error.

child_running: (child_running)

child_ready: (child_ready)

child_wait: (child_wait)

child_close: (child_close)

child_eof: (child_eof)

child_write: (child_write expr1 ...)

> (child_open "/usr/local/bin/munger")
1
> (for (a 1 10)
>> (child_write a (char 10)))
1 ; this is the return value of the "child_write"
>> (print (child_read)))
1
2
3
4
5
6
7
8
9
10

child_read: (child_read)

> (child_open "munger")
1
> (child_write "(set 'foo 'bar)" (char 10))
1
> (child_read)
"bar
"
1

clearscreen: (clearscreen)

clearline: (clearline expr1 expr2)

goto: (goto expr1 expr2)

getchar: (getchar)

"getchar" returns -1 when EOF is read. "getchar" returns -2 if a SIGWINCH is received by the interpreter. On Error, "getchar" returns a string describing the error.

pushback: (pushback expr1)

display: (display expr1 expr2 expr3)

The second argument specifies a buffer column to start printing at. If non-zero, only the portions of the lines from the specified column onward is printed. The second argument does not specify a screen column but a buffer column. Tab expansion is performed before the slice is taken. Slices are printed starting at screen column 0. Lines longer than the terminal width are truncated to the terminal width.

The third argument specifies the tabstop periodicity. Any tabs found in the specified lines is expanded according to this value before truncation and printing.

boldface: (boldface)

normal: (normal)

fg_black:

fg_red:

fg_green:

fg_yellow:

fg_blue:

fg_magenta:

fg_cyan:

fg_white:

bg_black:

bg_red:

bg_green:

bg_yellow:

bg_blue:

bg_magenta:

bg_cyan:

bg_white:

hide: (hide)

show: (show)

pause: (pause expr1)

scrollup: (scrollup)

scrolldn: (scrolldn)

insertln: (insertln)

printer: (printer)

noprinter: (noprinter)

shexec: (shexec expr)

exec: (exec expr ...)

truncate: (truncate expr)

> (with_output_file_appending "HOW_TO_EXTEND_IT"
>> (when (writelock)
>>> (truncate 100)))
1
> (with_input_file "HOW_TO_EXTEND_IT"
>> (setq line (getchars 1000)))
"ADDING INTRINSICS TO THE INTERPRETER
------------------------------------

Under the hood, Munger is"
> (length line)
100

dynamic_let: (dynamic_let (symbol expr) expr1 [expr2...])

> (defun f () a)
<CLOSURE#57>

> (dynamic_let (a 10)
>> (f))
10

> (f)
evaluate: symbol a not bound.
f: error evaluating body expression 1.

> (defun a (x) 'foobar)
<CLOSURE#58>

> (defun g (x) (a x))
<CLOSURE#59>

> (dynamic_let (a (lambda (x) x))
>> (g 23))
23

> (g 23)
foobar

; Exterior "let" is shadowing interior "dynamic_let":

> (let ((a 12))
>> (dynamic_let (a 10)
>>> (print a)
>>> (newline)))
12
1 ; return value of "newline"

basename: (basename expr)

(basename "/usr/local/bin/munger")
"munger"

dirname: (dirname expr)

(dirname "/usr/local/bin/munger")
"/usr/local/bin"

chmod: (chmod expr1 expr2)

chown: (chown expr1 expr2 expr3)

crypt: (crypt expr)

checkpass: (checkpass expr1 expr2)

setuid: (setuid expr)

seteuid: (seteuid expr)

getuid: (getuid)

setgid: (setgid expr)

setegid: (setgid expr)

geteuid: (geteuid)

getgid: (getgid)

seek: (seek expr1 expr2 expr3)

getchars: (getchars expr [expr])

Mixing calls to "getline" and "getchars" results in unexpected results, as "getline" performs its own input buffering. You can mix calls to "getchars" with calls to "getline_ub".

The presence of a timeout value causes "getchars" to operate as follows. The function calls the read() system call to read a character a time until the desired number of characters or EOF has been read. If any invocation of read() takes longer than the number of seconds specified by the timeout value, read() is interrupted, and "getchars" returns all the characters read so far. If no characters have been read, "getchars" returns the empty string. When invoked without a timeout value but with a positive first argument, "getchar" blocks indefinitely until it can read at least one character or EOF. "getchars" then returns a non-empty string or 0 on EOF.

When reading from a terminal device in canonical mode, when a timeout value has been specified, the empty string can be returned even though the user has typed some characters, because the terminal driver does not return any character data to the interpreter in canonical mode until a carriage return or a newline is input.

readlock: (readlock)

writelock: (writelock)

unlock: (unlock expr)

hostname: (hostname)

symlink: (symlink expr1 expr2)

gecos: (gecos expr)

record: (record expr)

getfield: (getfield expr1 expr2)

setfield: (setfield expr1 expr2 expr3)

extend: (extend expr1 expr2)

> (defun fact (n)
>> (extend 'a 1)
>> (while (> n 1)
>>>   (setq a (* n a))
>>>   (dec n))
>> a)
<CLOSURE#23>
> (fact 10)
3628800

gc: (gc)

dynamic_extent: (dynamic_extent ...)

> (let ((a 10))
>> (extend 'b (* a a))

>> (dynamic_extent
>>> (extend 'c (* b b))
>>> (print c)
>>> (newline))

>> (print (boundp 'c))
>> (newline))
10000 ; first "print"
0     ; second "print"

gc_freq: (gc_freq expr)

getpid: (getpid)

getppid: (getppid)

getpgrp: (getpgrp)

tcgetpgrp: (tcgetpgrp)

"tcgetpgrp" returns 0 if the interpreter is not associated with a terminal device. On error, "tcgetpgrp" returns a string describing the error.

setpgid: (setpgid expr1 expr2)

If the first argument is zero, the pid of the interpreter process is used as the first argument. If the second argument is zero, the first argument is used for the second argument. New process groups are created by setting both arguments to the same value. If the affected process is not already a process group leader, the process becomes the process group leader of a new process group, and the process group id is the same as the process id.

tcsetpgrp: (tcsetpgrp expr)

kill: (kill expr1 expr2)

killpg: (killpg expr1 expr2)

fork: (fork)

forkpipe: (forkpipe expr)

The interpreter reaps any child processes that exit unless the "zombies" intrinsic has been invoked.

wait: (wait expr1 [expr2])

"wait" accepts 1 or 2 arguments. The first argument must evaluate to a fixnum specifying a process id, 0, -1, or a process group id negated. This argument is passed as the first argument to the waitpid() system call. If the argument is a process id, "wait" reaps that process. If the argument is -1, "wait" reaps any zombie process. If the argument is 0, "wait" reaps any zombie process that belongs to the interpreter's process group. If the argument is a process group id negated, then "wait" reaps any zombie child whose process group id is equal to the absolute value of the argument.

If the second argument is present, it can evaluate to any value. It is a boolean flag that determines if "wait" blocks. If the second argument is not present or if it evaluates to a boolean "false" value, AND there are no stopped or zombie processes that satisfy the "wait" request, BUT there is at least one running process that satisfies the "wait" request in the future, THEN "wait" blocks until it can reap a process. Otherwise "wait" returns immediately.

"wait" returns a 2 or 3 element list.

If "wait" cannot reap a process, "wait" returns a list containing 0 or -1 and the symbol ECHILD. If no second argument was supplied to "wait" or if the second argument evaluated to a boolean "false" value, the first element of the list is -1. This means there is no running or zombie process that can satisfy the "wait" now or in the future. If a "true" second argument is supplied to "wait", the first element of the returned list can be either -1 or 0. A value of 0 indicates that there are processes that can satisfy the "wait" that are still running.

Otherwise, "wait" returns a list containing a fixnum representing the process id of the reaped process followed by a symbol describing how the process exited: EXITED, KILLED, or STOPPED. If the second element is EXITED, the process terminated by calling the "exit" or "_exit" system calls, and a third element is present in the list that is a fixnum representing the child's exit status. If the second element is KILLED, the process was terminated by a signal, and a third element is present that is a fixnum representing the signal number of the signal that terminated the process. If the second element is STOPPED, the process was stopped by a signal and can be started again, and a third element is present that is a fixnum representing the signal number that stopped the process.

To ensure that all zombies are reaped, invoke "wait" with an argument of -1, until it returns (-1 ECHILD).

> (until (eq -1 (car (wait -1)))

zombies: (zombies)

nozombies: (nozombies)

zombiesp: (zombiesp)

glob: (glob)

command_lookup: (command_lookup expr)

> (command_lookup "munger")
"/usr/local/bin/munger"

getstring: (getstring expr)

If the interpreter cannot "forkpipe", "getstring" returns -1. If the "forkpipe" is successful but the "shexec" is not, then "getstring" returns the empty string.

dec2hex: (dec2hex expr)

> (dec2hex 65535)
"FFFF"

hex2dec: (hex2dec expr)

> (hex2dec "FfFf")
65535

listen: (listen expr [expr])

On success, "listen" returns the port number of the listening socket. On error, "listen" returns a string describing the error. Only one listening socket can be active at any time. The listening socket is closed with the "stop_listening" intrinsic.

listen_unix: (listen_unix expr)

stop_listening: (stop_listening)

accept: (accept)

When "accept" returns, the stdin and stdout of the interpreter are redirected onto the incoming connection. Any of the intrinsics that read and write from those descriptors ("print", "println", "newline", "getchar", getchars", and "getline") can be used to communicate with the client. Keep in mind that "accept" works like "pipe" or "redirect" in that the new streams connected to the affected descriptors "shadow" the previously connected streams, but the previously-connected streams are still open in the interpreter. This means you must invoke both (resume 0) and (resume 1) before calling "accept" again, unless you intend to come back to the previously-accepted connection in the future.

(fatal)
; Echo Server 1

(daemonize "echo1.munger")

(defun service_client ()
   (while (setq line (getline))
      (print line)
      (flush_stdout)))

(when (fixnump (setq err (listen 7)))
   (setuid "nobody")

   (while (fixnump (setq err (accept)))

      (if (not (fork))
         (progn
            (stop_listening)
            (service_client)
            (exit 0))

         (resume 0)
         (resume 1))))

(syslog 'CRITICAL err)
(exit 1)

; Echo Server 2

(fatal)
(daemonize "echo2.munger")

(defun service_client ()
   (while (setq line (getline))
      (print line)
      (flush_stdout)))

(defun process_clients ()
   (while (fixnump (setq err (accept)))
      (service_client)
      (resume 0)
      (resume 1)))

(when (fixnump (setq err (listen 7)))
   (setuid "nobody")

   (catch
      (iterate 9
         (unless (fork)
            (throw 0)))))

(process_clients)
(syslog 'CRITICAL err)
(exit 1)

get_scgi_header: (get_scgi_header)

send_descriptors: (send_descriptors);

receive_descriptors: (receive_descriptors)

busymap: (busymap expr)

See the httpd.munger example web server for usage.

Master server processes request that their children exit by sending them a SIGTERM with the "kill" intrinsic. If this signal is received by an interpreter, the next invocation of "accept" causes the interpreter to exit. If the interpreter is blocked in "accept" at the time of the arrival of the signal, the interpreter exits immediately. This allows the slave server to continue processing any established client connection to completion before exiting.

nobusymap: (nobusymap)

busy: (busy expr)

notbusy: (notbusy expr)

busyp: (busyp expr)

chroot: (chroot expr)

daemonize: (daemonize expr)

syslog: (syslog expr expr)

flush_stdout: (flush_stdout)

getpeername: (getpeername)

base64_encode (base64_encode expr)

> (with_input_file "binary.file"
>> (with_output_file "binary.file.base64"

>>>  (println "begin-base64 644 binary.file")

>>>  (while (setq line (getchars 57))
>>>>   (println (base64_encode line)))

>>>  (println "====")))

produces the same output as the b64encode system utility invoked as:

b64encode -o binary.file.base64 binary.file binary.file

Base 64 encoding represents 3 bytes of data as 4 printable characters, so using a line size of 57 causes those lines to expand to 76 characters after encoding, which is less than the once-customary 80 character limit on line lengths in an email message.

A more efficient method is to read a larger amount of text and cut up the lines with "substring":

> (with_input_file "binary.file"
>> (with_output_file "binary.file.base64"

>>> (println "begin-base64 644 binary.file")
>>> (setq line "")

>>> (while (setq segment (getchars 100000))
>>>> (setq line (concat line segment))

>>>> (while (> (length line) 57)
>>>>> (println (base64_encode (substring line 0 57)))
>>>>> (setq line (substring line 57 0))))

>>> (when line (println (base64_encode line)))

>>> (println "====")))

base64_decode (base64_decode expr)

sleep: (sleep expr)

unsigned: (unsigned expr)

form_encode: (form_encode expr)

form_decode: (form_decode expr)