24.3. Functions

Sets SYMBOL to VALUE. SYMBOL is not evaluated, while VALUE is. Example

(set! a 3)
(set! pi 3.14)
(set! fruit '(apples pears bananas))
(set! fruit2 fruit)

define a function called FUNCNAME with specified arguments and body.

(define (myadd a b) (+ a b))
(define (factorial a)
 (cond
  ((< a 2) 1)
  (t (* a (factorial (- a 1))))))

If the value of TEST is non-nil, evaluate TRUECASE and return value else if present evaluate FALSECASE if present and return value, else return nil.

(if (string-equal v "apples")
   (format t "It's an apple\n")
   (format t "It's not an apple\n"))
(if (member v '(apples pears bananas))
   (begin
       (format t "It's a fruit (%s)\n" v)
       'fruit)
   'notfruit)

A multiple if statement. Evaluates each TEST until a non-nil test is found then evalues each of the expressions in that BODY return the value of the last one.

(cond
  ((string-equal v "apple")
   'ringo)
  ((string-equal v "plum")
   'ume)
  ((string-equal v "peach")
   'momo)
  (t
   'kudamono)

This evaluates each s-expression in BODY and returns the value of the last s-expression in the list. This is useful for case where only one s-expression is expected but you need to call a number of functions, notably the if function.

(if (string-equal v "pear")
    (begin
       (format t "assuming it's a asian pear\n")
       'nashi)
    'kudamono)

evalutate each disjunct until one is non-nil and return that value.

(or (string-equal v "tortoise")
    (string-equal v "turtle"))
(or (string-equal v "pear")
    (string-equal v "apple")
    (< num_fruits 6))

evalutate each conjunct until one is nil and return that value or return the value of the last conjunct.

(and (< num_fruits 10)
     (> num_fruits 3))
(and (string-equal v "pear")
     (< num_fruits 6)
     (or (string-equal day "Tuesday")
         (string-equal day "Wednesday")))

returns the "car" of EXPR, for a list this is the first item, for an atom or the empty list this is defined to be nil.

(car '(a b)) => a
(car '((a b) c d)) => (a b)
(car '(a (b c) d)) => a
(car nil) => nil
(car 'a) => nil

returns the "cdr" of EXPR, for a list this is the rest of the list, for an atom or the empty list this is defined to be nil.

(cdr '(a b)) => (b)
(cdr '((a b) c d)) => (c d)
(cdr '(a)) => nil
(cdr '(a (b c))) => ((b c))
(cdr nil) => nil
(cdr 'a) => nil

build a new list whose "car" is EXPR0 and whose "cdr" is EXPR1.

(cons 'a '(b c)) => (a b c)
(cons 'a ()) => (a)
(cons '(a b) '(c d) => '((a b) c d))
(cons () '(a) => '(nil a))
(cons 'a 'b => (a . b))
(cons nil nil) => (nil)

Form a list from each of the arguments

(list 'a 'b 'c) => (a b c)
(list '(a b) 'c 'd) => ((a b) c d)
(list nil '(a b) '(a b)) => (nil (a b) (a b))

Join each of the arguments (lists) into a single list

(append '(a b) '(c d)) => (a b c d)
(append '(a b) '((c d)) '(e f)) => (a b (c d) e f)
(append nil nil) => nil
(append '(a b)) => (a b))
(append 'a 'b) => error

Return Nth member of list, the first item is the 0th member.

(nth 0 '(a b c)) => a
(nth 2 '(a b c)) => c
(nth 3 '(a b c)) => nil

Return Nth cdr list, the first cdr is the 0th member, which is the list itself.

(nth 0 '(a b c)) => (a b c)
(nth 2 '(a b c)) => (c)
(nth 1 '(a b c)) => (b c)
(nth 3 '(a b c)) => nil

The last cdr of a list, traditionally this function has always been called last rather last_cdr

(last '(a b c)) => (c)
(last '(a b (c d))) => ((c d))

Return the list in reverse order

(reverse '(a b c)) => (c b a)
(reverse '(a)) => (a)
(reverse '(a b (c d))) => ((c d) b a)

Returns the cdr in LIST whose car is ITEM or nil if it found

(member 'b '(a b c)) => (b c)
(member 'c '(a b c)) => (c)
(member 'd '(a b c)) => nil
(member 'b '(a b c b)) => (b c b)

a-list are a standard list format for representing feature value pairs. An a-list is basically a list of pairs of name and value, although the name may be any lisp item it is usually an symbol. A typlical a-list is

((name AH)
 (duration 0.095)
 (vowel +)
 (occurs ("file01" "file04" "file07" "file24"))
)

(assoc 'name '((name AH) (duration 0.95))) => (name AH)
(assoc 'duration '((name AH) (duration 0.95))) => (duration 0.95)
(assoc 'vowel '((name AH) (duration 0.95))) => nil

The format function is a little unusually in Lisp. It basically follows the printf command in C, or more closely follows the format function in Emacs lisp. It is desgined to print out infomation that is not necessarily to be read in by Lisp (unlike pprint, print and printfp). FD is a file descriptor as created by fopen, and the result is printed to that. Also two special values are allows there. t causes the output to be sent to standard out (which is usually the terminal). nil causes the output to be written to a string and returned by the function. Also the variable stderr is set to a file descriptor for standard error output.

The format string closely follows the format used in C's printf functions. It is actually interpreted by those functions in its implementation. format supports the following directives

The %s directive will try to convert the corresponding lisp argument to a string before passing it to the low level print function. Thus list will be printed to strings, and numbers also coverted. This form will loose the distinction between lisp symbols and lisp strings as the quote will not be present in the %s form. In general %s should be used for getting nice human output and not for machine readable output as it is a lossy print form.

In contrast %l is designed to reserve the Lisp forms so they can be more easily read, quotes will appear and escapes for embedded quote will be treated properly.

(format t "duration %0.3f\n" 0.12345) => duration 0.123
(format t "num %d\n" 23) => num 23
(format t "num %04d\n" 23) => num 0023

Pretty print give expression to standard out (or FD if specified). Pretty printing is a technique that inserts newlines in the printout and indentation to make the lisp expression easier to read.

This creates a file description, which can be used in the various I/O functions. It closely follows C stdio fopen function. The mode may be

Close a file descriptor as created by fopen.

Read next s-expression from standard in

Read next s-expression from given file descriptor FD. On end of file it returns an sexpression eq to the value returned by the function (eof_val). A typical example use of these functions is

(let ((ifd (fopen infile "r"))
      (ofd (fopen outfile "w"))
      (word))
   (while (not (equal? (set! word (readfp ifd)) (eof-val)))
      (format ofd "%l\n" (lex.lookup word nil)))
   (fclose ifd)
   (fclose ofd)))

Load in the s-expressions in FILENAME. If NOEVAL is unspecified the s-expressions are evaluated as they are read. If NOEVAL is specified and non-nil, load will return all s-expressions in the file un-evaluated in a single list.

Finds the string of STR1 and STR2 and returns t if these are equal, and nil otherwise. Symbol names and numbers are mapped to string, though you should be aware that the mapping of a number to a string may not always produce what you hope for. A number 0 may or may not be mapped to "0" or maybe to "0.0" such that you should not dependent on the mapping. You can use format to map a number ot a string in an explicit manner. It is however safe to pass symbol names to string-equal. In most cases string-equal is the right function to use rather than equal? which is must stricter about its definition of equality.

(string-equal "hello" "hello") => t
(string-equal "hello" "Hello") => false
(string-equal "hello" 'hello) => t

For each argument coerce it to a string, and return the concatenation of all arguments.

(string-append "abc" "def") => "abcdef"
(string-append "/usr/local/" "bin/" "festival") => "/usr/local/bin/festival"
(string-append "/usr/local/" t 'hello) => "/usr/local/thello"
(string-append "abc") => "abc"
(string-append ) => ""

returns nil if no member of LIST is string-equal to STR, otherwise it returns t. Again, this is often the safe way to check membership of a list as this will work properly if STR or the members of LIST are symbols or strings.

(member_string "a" '("b" "a" "c")) => t
(member_string "d" '("b" "a" "c")) => nil
(member_string "d" '(a b c d)) => t
(member_string 'a '("b" "a" "c")) => t

Returns the initial prefix of STR up to the first occurrence of SUBSTR in STR. If SUBSTR doesn't exist within STR the empty string is returned.

(string-before "abcd" "c") => "ab"
(string-before "bin/make_labs" "/") => "bin"
(string-before "usr/local/bin/make_labs" "/") => "usr"
(string-before "make_labs" "/") => ""

Returns the longest suffix of STR after the first occurrence of SUBSTR in STR. If SUBSTR doesn't exist within STR the empty string is returned.

(string-after "abcd" "c") => "d"
(string-after "bin/make_labs" "/") => "make_labs"
(string-after "usr/bin/make_labs" "/") => "bin/make_labs"
(string-after "make_labs" "/") => ""

Returns the lengh of given string (or list). Length does not coerce its argument into a string, hence given a symbol as argument is an error.

(length "") => 0
(length "abc") => 3
(length 'abc) -> SIOD ERROR
(length '(a b c)) -> 3

returns a list of single character strings for each character in SYMBOL}' print name. This will also work on strings.

(symbolexplode 'abc) => ("a" "b" "c")
(symbolexplode 'hello) => ("h" "e" "l" "l" "o")

Convert a string into a symbol with the same print name.

Returns t if STR matches REGEX regular expression. Regular expressions are described more fully below.

(string-matches "abc" "a.*") => t
(string-matches "hello" "[Hh]ello") => t

Evaluates the command with the Unix shell (or equivalent). Its not clear how this should (or does0 work on other operating systems so it should be used sparingly if the code is to be portable.

(system "ls") => lists files in current directory.
(system (format nil "cat %s" filename))

Copies contents of URL into OFILE. It support file: and http: prefixes, but current does not support the ftp: protocol.

(get_url "http://www.festvox.org/index.html" "festvox.html")

Set environment variable NAME to VALUE which should be strings

(setenv "DISPLAY" "nara.mt.cs.cmu.edu:0.0")

Get value of environment variable NAME.

(getenv "DISPLAY")

The process id, as a number. This is useful when creating files that need to be unique for the festival instance.

(set! bbbfile (format nil "/tmp/stuff.%05d" (getpid)))

Change directory.

(cd "/tmp")

return a string which is a pathname to the current working directory.