This is Info file librep.info, produced by Makeinfo version 1.68 from the input file librep.texi. START-INFO-DIR-ENTRY * librep: (librep). A LISP extension language END-INFO-DIR-ENTRY This is Edition 1.2, last updated 8 September 2000, of `The librep Manual', for librep, Version 0.13. Copyright 1999-2000 John Harper. Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies. Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one.  File: librep.info, Node: Local Variables, Next: Setting Variables, Up: Variables Local Variables --------------- A "local variable" is a variable which has a temporary value. For example, when a function is called the variables which are the names of its arguments are temporarily bound to the values of the arguments passed to the function. When the function call exits its arguments are unbound and the previous definitions of the variables come back into view. A "binding" is a particular instance of a local variable. Even if a variable has more than one binding currently in place, only the most recent is available--there is no way the previous binding can be accessed until the previous binding is removed. One way of visualising variable binding is to think of each variable as a stack. When the variable is bound to, a new value is pushed onto the stack, when it is unbound the top of the stack is popped. Similarly when the stack is empty the value of the variable is void (*note Void Variables::.). Assigning a value to the variable (*note Setting Variables::.) overwrites the top value on the stack with a new value. When the value of the variable is required it is simply read from the top of the stack. Apart from function applications there are two special forms which perform variable binding (i.e. creating local variables), `let' and `let*'. - Macro: let BINDINGS BODY-FORMS... `let' creates new variable bindings as specified by the BINDINGS argument, then evaluates the BODY-FORMS in order. The bindings are then removed, returning all variables to their state before the `let' statement was entered. The value of the statement is the value of the implicit `progn'. The BINDINGS argument is a list of the bindings to perform. Each binding is either a symbol, in which case that variable is bound to `()', or a list whose car is a symbol. The cdr of this list is a list of forms which, when evaluated as a `progn', gives the value to bind to that variable. (setq foo 42) => 42 (let ((foo (+ 1 2)) bar) ;; Body forms (setq foo (1+ foo)) ;This sets the new binding (cons foo bar)) => (4 . ()) foo => 42 ;The original values is back No bindings are made until all new values have been computed. For example: (setq foo 42) => 42 (let ((foo 100) (bar foo)) (cons foo bar)) => (100 . 42) Although `foo' is given a new binding this is not actually done until all the new values have been computed, hence `bar' is bound to the *old* value of `foo'. - Macro: let* BINDINGS BODY-FORMS... This special form is exactly the same as `let' except for one important difference: the new bindings are installed *as they are computed*. You can see the difference by comparing the following example with the last example in the `let' documentation (above), (setq foo 42) => 42 (let* ;Using `let*' this time ((foo 100) (bar foo)) (cons foo bar)) => (100 . 100) By the time the new value of `bar' is computed the new binding of `foo' is already active. - Macro: letrec BINDINGS BODY-FORMS... `letrec' is similar to `let' and `let*', with the differerence being that the values of bindings are evaluated with all other bindings in scope. This means that recursive functions may be defined with `letrec'. For example, a local factorial function (from SICP): (letrec ((fact (lambda (n) (if (= n 1) 1 (* n (fact (1- n))))))) (fact 10)) Note also that letrec allows groups of mutually recursive functions to be defined, as in the following example (also from SICP): (defun f (x) (letrec ((evenp (lambda (n) (if (= n 0) t (oddp (1- n))))) (oddp (lambda (n) (if (= n 0) nil (evenp (1- n)))))) ...  File: librep.info, Node: Setting Variables, Next: Scope and Extent, Prev: Local Variables, Up: Variables Setting Variables ----------------- "Setting" a variable means to overwrite its current value (that is, the value of its most recent active binding) with a new one. In the variable-as-stack analogy, this is analogous to overwriting the top of the stack. The old value is irretrievably lost (unlike when a new value is bound to a variable, *note Local Variables::.). The `setq' special form is the usual method of altering the value of a variable. - Special Form: setq VARIABLE FORM ... Each VARIABLE is set to the result of evaluating its corresponding FORM. The last value assigned becomes the value of the `setq' form. (setq x 20 y (+ 2 3)) => 5 In the above example the variable `x' is set to `20' and `y' is set to the value of the form `(+ 2 3)' (5). - Function: set VARIABLE NEW-VALUE The value of the variable VARIABLE (a symbol) is set to NEW-VALUE and the NEW-VALUE is returned. This function is used when the VARIABLE is unknown until run-time, and therefore has to be computed from a form. (set 'foo 20) == (setq foo 20) ;`setq' means `set-quoted' => 20 *Note:* currently the `set' function may be used to set any type of variable (i.e. lexical or special). However this likely to change in the future, such that only special variables will be allowed to be modified using the `set' function. It is strongly advised to avoid using this function on lexical bindings! (Moreover the compiler may generate incorrect code in certain circumstances.)  File: librep.info, Node: Scope and Extent, Next: Void Variables, Prev: Setting Variables, Up: Variables Scope and Extent ---------------- In the `librep' dialect of Lisp by default variables have "lexical scope". This means that bindings are associated with textual regions of programs, and may be accessed by any forms within this associated textual region. Moreover, the bindings are persistent, even when the flow of control is currently outside the associated region. Consider the following example: (let ((counter 0)) (defun count () (setq counter (1+ counter)) counter)) the value of the `counter' variable persists, and is incremented each time the `count' function is called. The `counter' variable is accessible from nowhere but the forms written inside the `let' statement declaring it. (count) => 1 (count) => 2 An alternative method of scoping variables is also available. Any variables declared using the `defvar' special form are said to be "special" variables, they have "indefinite scope" and "dynamic extent", often simplified to "dynamic scope". What this means is that references to these variables may occur anywhere in a program (i.e. bindings established in one function are visible within functions called from the original function) and that references may occur at any point in time between the binding being created and it being unbound. Dynamic scoping is easy to abuse, making programs hard to understand and debug. A quick example of the use of dynamic scope, (defvar *foo-var* nil) (defun foo (x) (let ;; a dynamically-scoped binding ((*foo-var* (* x 20))) (bar x) ... (defun bar (y) ;; Since this function is called from ;; the function `foo' it can refer ;; to `*foo-var*' (setq y (+ y *foo-var*)) ... As shown in the previous example, a common convention is to mark special variables by enclosing their names within asterisks.  File: librep.info, Node: Void Variables, Next: Defining Variables, Prev: Scope and Extent, Up: Variables Void Variables -------------- A variable which has no value is said to be "void", attempting to reference the value of such a symbol will result in an error. It is possible for the most recent binding of a variable to be void even though the inactive bindings may have values. - Function: boundp VARIABLE Returns true if the symbol VARIABLE has a value. - Function: makunbound VARIABLE This function makes the current binding of the symbol VARIABLE be void, then returns VARIABLE. (setq foo 42) => 42 foo => 42 (boundp 'foo) => t (makunbound 'foo) => foo (boundp 'foo) => () foo error--> Value as variable is void: foo  File: librep.info, Node: Defining Variables, Next: Fluid Variables, Prev: Void Variables, Up: Variables Defining Variables ------------------ The special forms `define', `defvar' and `defconst' allow you to define the global variables that will be used by a program. - Macro: define VARIABLE FORM Defines a lexically scoped global variable called VARIABLE. It will have the result of evaluating FORM assigned to it. Note that the `define' special form may also be used to declare block-structured functions, *Note Definitions::. - Special Form: defvar VARIABLE FORM [DOC-STRING] This special form defines a special (i.e. dynamically scoped) variable, the symbol VARIABLE. If the value of VARIABLE is void the FORM is evaluated and its value is stored as the value of VARIABLE (note that only the default value is modified, never a buffer-local value). If the DOC-STRING argument is defined it is a string documenting VARIABLE. This string is then stored as the symbol's `variable-documentation' property and can be accessed by the `describe-variable' function. (defvar *my-variable* '(x y) "This variable is an example showing the usage of the `defvar' special form.") => *my-variable* - Macro: defconst CONSTANT FORM [DOC-STRING] `defconst' defines a global constant, the symbol CONSTANT. Its value is set to the result of evaluating FORM. Note that unlike `defvar' the value of the symbol is *always* set, even if it already has a value. The DOC-STRING argument, if defined, is the documentation string for the constant. (defconst the-answer 42 "An example constant.") => the-answer  File: librep.info, Node: Fluid Variables, Prev: Defining Variables, Up: Variables Fluid Variables --------------- Special variables have a number of drawbacks, especially when used in conjunction with the module system (*note Modules and Special Variables::.). As a consequence of these drawbacks, `rep' provides a second method of implementing dynamically scoped variables, known as "fluid variables", or just "fluids". A fluid is a first class Lisp object that may be passed around as any other Lisp object. It's sole function is to provide a location from which dynamic bindings may be created. Fluids are anonymous objects, they are usually named by being stored in lexically scoped variables. - Function: make-fluid #!OPTIONAL VALUE Create and return a new fluid, it will have an initial binding of VALUE (or false if VALUE is undefined). - Function: fluid FLUID Return the value of the most recently created binding of the fluid variable object FLUID. - Function: fluid-set FLUID VALUE Set the value of the most recently created binding of the fluid variable object FLUID to VALUE. - Function: with-fluids FLUIDS VALUES THUNK Call the zero parameter function THUNK (and return the value that it returns) with new bindings created for each of the fluid variables specified in the list FLUIDS. For each member of FLUIDS the corresponding member of the VALUES list provides the initial value of the new binding. If the lists FLUIDS and VALUES are not of the same length, an error is signalled. - Macro: let-fluids BINDINGS BODY ... A convenient wrapper around `with-fluids', similar to the `let' syntax. The list BINDINGS associates the names of lexical variables containing fluid objects, with the values to bind to those fluid objects. Once the bindings have been installed, the BODY ... forms are evaluated, and the bindings removed. The value of the last of the BODY ... forms is returned. Here is an example code fragment using fluid variables and `let-fluids': (define a (make-fluid)) (define b (make-fluid)) (let-fluids ((a 1) (b 2)) (+ (fluid a) (fluid b))) => 3  File: librep.info, Node: Functions, Next: Macros, Prev: Variables, Up: The language Functions ========= A "function" is a Lisp object which, when applied to a sequence of argument values, produces another value--the function's "result". It may also induce side-effects (e.g. changing the environment of the calling function). All Lisp functions return results -- there is nothing like a procedure in Pascal. Note that special forms (*note Special Forms::.) and macros (*note Macros::.) are *not* functions since they do not guarantee to evaluate all of their arguments. Functions are the main building-block in Lisp programs, each program is usually a system of interrelated functions. There are two types of function: "primitive functions" are functions written in the C language, these are sometimes called built-in functions, the object containing the C code itself is called a "subr". All other functions are defined in Lisp. - Function: functionp OBJECT Returns true if OBJECT is a function (i.e. it can be used as the function argument of `funcall'. (functionp set) => t (functionp setq) => () (functionp (lambda (x) (+ x 2))) => t - Function: subrp ARG Returns true is ARG is a primitive subroutine object. - Function: subr-name SUBR Returns a string naming the primitive subroutine SUBR. * Menu: * Lambda Expressions:: Structure of a function object * Defining Functions:: How to write a function definition * Anonymous Functions:: Or they can be un-named * Predicate Functions:: Functions which return boolean values * Local Functions:: Binding functions temporarily * Calling Functions:: Functions can be called by hand * Mapping Functions:: Map a function to the elements of a list  File: librep.info, Node: Lambda Expressions, Next: Defining Functions, Up: Functions Lambda Expressions ------------------ "Lambda expressions" are used to create functions from other Lisp objects. A lambda expression is a list whose first element is the symbol `lambda'. All functions written in Lisp (as opposed to the primitive functions in C) are defined using lambda expressions. The general format of a lambda expression is: (lambda LAMBDA-LIST [DOC] [INTERACTIVE-DECLARATION] BODY-FORMS... ) Where LAMBDA-LIST is a list defining the formal parameters of the function, DOC is an optional documentation string, INTERACTIVE-DECLARATION is only required by interactive commands (1) and BODY-FORMS is the sequence of forms making up the function body, evaluated using an implicit `progn'. The LAMBDA-LIST is a list, it defines how the values applied to the function are bound to local variables which represent the parameters of the function. At its simplest it is simply a list of symbols, each symbol will have the corresponding argument value bound to it. For example, the lambda list `(x y)' defines two parameters, `x' and `y'. When called with two arguments the first will be bound to the variable `x', the second to `y'. When used in a full lambda expression this looks like: (lambda (x y) (+ x y)) this evaluates to an anonymous function with two parameters, `x' and `y', which when called evaluates to their sum. Note that a lambda expression itself is *not* a function, it must be associated with a lexical environment, this conjunction is usually called a closure; it is the closure that may be called as a function. However, to confuse matters, a lambda expression *evaluates* to the closure of itself and the current environment. Consider the following example: (lambda (x) (1+ x)) => # (functionp (lambda (x) (1+ x))) => t (functionp '(lambda (x) (1+ x))) => () There are several "lambda-list keywords" which modify the meaning of symbols in the lambda-list. The syntax of the lambda list is: ([REQUIRED-PARAMETERS...] [#!optional OPTIONAL-PARAMETERS...] [#!key KEYWORD-PARAMETERS...] [#!rest REST-PARAMETER | . REST-PARAMETER]) Each lambda list keyword is a symbol whose name begins `#!', they are interpreted as follows: `#!optional' All variables following this keyword are considered "optional" (all variables before the first keyword are "required": an error will be signalled if a required argument is undefined in a function call). OPTIONAL-PARAMETERS may either be of the form `SYMBOL' or of the form `(SYMBOL DEFAULT)'. If no argument is supplied for this parameter the DEFAULT form is evaluated to give the bound value(2). If no DEFAULT form is given, then the variable is bound to a false value. Note that optional parameters must be specified if a later parameter is also specified. ((lambda (#!optional a b) (list a b))) => (() ()) ((lambda (#!optional a b) (list a b)) 1) => (1 ()) ((lambda (#!optional a b) (list a b)) nil 1) => (() 1) ((lambda (#!optional (a 1)) (list a))) => (1) ((lambda (#!optional (a 1)) (list a)) 2) => (2) `#!key' This object marks that the parameters up to the next lambda list keyword are keyword parameters. The values bound to these parameters when the function is called are determined not by position (as with normal parameters), but by being marked by a preceding keyword symbol. Keyword symbols have the syntax `#:SYMBOL'. As with optional parameters, default values may be supplied through the use of the `(SYMBOL DEFAULT)' syntax. If no default value is given and no keyword argument of the specified kind is available, the variable is bound to a false value. For example, the lambda list `(a #!key b c)' accepts one required argument, and two optional keyword arguments. The variable `a' would be bound to the first supplied argument; the variable `b' would be bound to the argument preceded by the keyword `#:b', or `()' if no such argument exists. (After extracting required and optional arguments, each remaining pair of values is checked for associating a value with each keyword.) ((lambda (a #!key b c) (list a b c)) 1 2 3) => (1 () ()) ((lambda (a #!key b c) (list a b c)) 1 #:b 2 3) => (1 2 ()) ((lambda (a #!key b c) (list a b c)) 1 #:b 2 #:c 3) => (1 2 3) ((lambda (a #!key b c) (list a b c)) 1 #:c 3 #:b 2) => (1 2 3) `#!rest' The `#!rest' keyword allows a variable number of arguments to be applied to a function, all the argument values which have not been bound to argument variables (or used to mark keyword arguments) are made into a list and bound to the variable following the `#!rest' keyword. For example, in (lambda (x #!rest y) ...) the first argument, `x', is required. Any other arguments applied to this function are made into a list and this list is bound to the variable `y'. Variable argument functions may also be defined through the Scheme method of using an improper lambda-list. The previous example is exactly equivalent to: (lambda (x . y) ...) When a function represented by a lambda-list is called the first action is to bind the argument values to the formal parameters. The LAMBDA-LIST and the list of argument values applied to the function are worked through in parallel. Any required arguments which are left undefined when the end of the argument values has been reached causes an error. After the arguments have been processed the BODY-FORMS are evaluated by an implicit progn, the value of which becomes the value of the function call. Finally, all parameters are unbound and control passes back to the caller. ---------- Footnotes ---------- (1) Only used when `librep' is embedded within another application. (2) The DEFAULT form is evaluated in the environment of the closure being called, but without any of the bindings created by the lambda expression.  File: librep.info, Node: Defining Functions, Next: Anonymous Functions, Prev: Lambda Expressions, Up: Functions Defining Functions ------------------ Globally accessible functions are usually defined by the `defun' special form. - Macro: defun NAME LAMBDA-LIST BODY-FORMS... `defun' initialises the function definition of the symbol NAME to the lambda expression resulting from the concatenation of the symbol `lambda', LAMBDA-LIST and the BODY-FORMS. The BODY-FORMS may contain a documentation string for the function as its first form and an interactive calling specification as its first (if there is no doc-string) or second form if the function may be called interactively by the user (*note Lambda Expressions::.). An example function definition taken from the `librep' source code is: (defun load-all (file) "Try to load files called FILE (or FILE.jl, etc) from all directories in the Lisp load path." (mapc (lambda (dir) (let ((full-name (expand-file-name file dir))) (when (or (file-exists-p full-name) (file-exists-p (concat full-name ".jl")) (file-exists-p (concat full-name ".jlc"))) (load full-name nil t)))) load-path))  File: librep.info, Node: Anonymous Functions, Next: Predicate Functions, Prev: Defining Functions, Up: Functions Anonymous Functions ------------------- When supplying functions as arguments to other functions it is often useful to give an actual function *definition* (i.e. an enclosed lambda expression) instead of the name of a function. In Lisp, unlike most other programming languages, functions have no inherent name. As seen in the last section named-functions are created by storing a function object in a variable, if you want, a function can have many different names: simply store the function in many different variables! So, when you want to pass a function as an argument there is the option of just writing down its definition. This is especially useful with functions like `mapc' and `delete-if'. For example, the following form removes all elements from the LIST which are even and greater than 20. (setq LIST (delete-if (lambda (x) (and (zerop (% x 2)) (> x 20))) LIST)) The above lambda expression combines two predicates applied to its argument. In certain cases it may be necessary to create a non-constant function, for example by using backquoting (*note Backquoting::.). In these cases the `make-closure' function may be used to create a function object from a lambda expression. - Function: make-closure ARG Return the closure of ARG and the current lexical environment. - Function: closurep ARG Returns true if ARG is a closure. - Function: closure-function CLOSURE Returns the function object associated with the lexical closure CLOSURE.  File: librep.info, Node: Predicate Functions, Next: Local Functions, Prev: Anonymous Functions, Up: Functions Predicate Functions ------------------- In Lisp, a function which returns a boolean `true' or boolean `false' value is called a "predicate". As is the convention in Lisp a value of `()' means false, anything else means true. The symbols `nil' and `t' are often used to represent constant false and true values (*note nil and t::.). Another Lisp convention is that the names of predicate functions should name the quality that the predicate is testing followed by either a `p' or `-p' string. The `p' variant is used when the first string does not contain any hyphens. For example, the predicate to test for the quality "const-variable" (a variable which has a constant value, *note Defining Variables::.) is called `const-variable-p'. On the other hand the predicate to test for the quality "cons" (a Cons cell) is called `consp'.  File: librep.info, Node: Local Functions, Next: Calling Functions, Prev: Predicate Functions, Up: Functions Local Functions --------------- The `defun' special form allows globally-accessible functions to be defined. It is often desirable to declare functions local to the current lexical environment. The `let' and `let*' special form that were introduced earlier allow this since named functions are simply functional values stored in variables. For example, (let ((temporary-function (lambda (x) (+ x 42)))) ... (temporary-function 20) ...  File: librep.info, Node: Calling Functions, Next: Mapping Functions, Prev: Local Functions, Up: Functions Calling Functions ----------------- Most of the time function applications are made by the evaluator when it finds a functional value after evaluating the first element of a list form. However two functions are available for manually calling functions. - Function: funcall FUNCTION #!REST ARGS Applies the argument values ARGS to the function FUNCTION, then returns its result. - Function: apply FUNCTION #!REST ARGS Similar to `funcall' except that the last of its arguments is a *list* of arguments which are appended to the other members of ARGS to form the list of argument values to apply to the function FUNCTION. (apply + 1 '(2 3)) => 6 (apply + (make-list 1000000 1)) => 1000000  File: librep.info, Node: Mapping Functions, Prev: Calling Functions, Up: Functions Mapping Functions ----------------- A "mapping function" applies a function to each of a collection of objects. `librep' currently has two mapping functions, `mapcar' and `mapc'. - Function: mapcar FUNCTION LIST Each element of LIST is individually applied to the function FUNCTION. The values returned are made into a new list which is returned. The FUNCTION must accept a single argument value. (mapcar 1+ '(1 2 3 4 5)) => (2 3 4 5 6) - Function: mapc FUNCTION LIST Similar to `mapcar' except that the values returned when each element is applied to the function FUNCTION are discarded. The value returned is undefined. This function is generally used where the side effects of calling the function are the important thing, not the results. It is often the most efficient way of traversing all items in a list, for example: (mapc (lambda (x) (print x standard-error)) list) The two following functions are also mapping functions of a sort. They are variants of the `delete' function (*note Modifying Lists::.) and use predicate functions to classify the elements of the list which are to be deleted. - Function: delete-if PREDICATE LIST This function is a variant of the `delete' function. Instead of comparing each element of LIST with a specified object, each element of LIST is applied to the predicate function PREDICATE. If it returns true then the element is destructively removed from LIST. (delete-if stringp '(1 "foo" 2 "bar" 3 "baz")) => (1 2 3) - Function: delete-if-not PREDICATE LIST This function does the inverse of `delete-if'. It applies PREDICATE to each element of LIST, if it returns false then the element is destructively removed from the list. (delete-if-not stringp '(1 "foo" 2 "bar" 3 "baz")) => ("foo" "bar" "baz") The `filter' function is similar to `delete-if-not', except that the original list isn't modified, a new list is created. - Function: filter PREDICATE LIST Return a new list, consisting of the elements in LIST which the function PREDICATE returns true when applied to. This function is equivalent to: (mapcar nconc (mapcar (lambda (x) (and (PREDICATE x) (list x))) LIST))  File: librep.info, Node: Macros, Next: Definitions, Prev: Functions, Up: The language Macros ====== "Macros" are used to extend the Lisp language. They consist of a function which instead of returning a computed value, transform their unevaluated arguments into a new form that, when evaluated, produces the actual value of the original form. For example, the `when' macro (*note Conditional Structures::.) implements a new conditional operation by transforming its arguments into a `cond' statement. That is, (when CONDITION FORM ...) ==> (cond (CONDITION FORM ...)) Since macros do not evaluate their arguments, instead just transforming them, they may be expanded at *compile-time*. The resulting form is then compiled as usual. - Function: macrop ARG Returns true if ARG is a macro object. * Menu: * Defining Macros:: Macros are defined like functions * Backquoting:: Creating macros from templates * Macro Expansion:: How macros are used by the evaluator * Compiling Macros:: The compiler expands macros at compile- time.  File: librep.info, Node: Defining Macros, Next: Backquoting, Up: Macros Defining Macros --------------- Macros are defined in the same style as functions, the only difference is the name of the special form used to define them. A macro object is a list whose car is the symbol `macro', its cdr is the function which creates the expansion of the macro when applied to the macro calls unevaluated arguments. - Macro: defmacro NAME LAMBDA-LIST BODY-FORMS... Defines the macro stored in the function cell of the symbol NAME. LAMBDA-LIST is the lambda-list specifying the arguments to the macro (*note Lambda Expressions::.) and BODY-FORMS are the forms evaluated when the macro is expanded. The first of BODY-FORMS may be a documentation string describing the macro's use. Here is a simple macro definition, it is the definition of the `when' macro shown in the previous section. (defmacro when (condition #!rest body) "Evaluates CONDITION, if it's true evaluates the BODY forms." (list 'cond (list* condition body))) When a form of the type `(when C B ...)' is evaluated the macro definition of `when' expands to the form `(cond (C (progn B ...)))' which is then evaluated to perform the `when'-construct. When you define a macro ensure that the forms which produce the expansion have no side effects; otherwise undefined effects will occur when programs using the macro are compiled.  File: librep.info, Node: Backquoting, Next: Macro Expansion, Prev: Defining Macros, Up: Macros Backquoting ----------- As seen in the previous sections, macros are a very powerful mechanism of defining new control structures. However due to the need to create the expansion, i.e. the form that will be actually evaluated, they can often be complex to write and understand. We have already seen that constants may be produced through the use of the quote-mark (*note Quoting::.), here another form of quoting is described, where only some of the quoted object is actually constant. This is known as "backquoting", since it is introduced by the backquote character ``', a shortcut for the `backquote' macro. - Macro: backquote ARG Constructs a new version of ARG (a list). All parts of LIST are preserved except for expressions introduced by comma (`,') characters, which are evaluated and spliced into the list. For example: `(1 2 ,(+ 1 2)) => (1 2 3) Also, the `,@' prefix will splice the following *list* into the output list, at the same level: `(1 2 ,@(list 3)) => (1 2 3) Backquoting allows macros expansions to be created from static templates. For example the `when' macro shown in the previous sections can be rewritten as: (defmacro when (condition #!rest body) `(cond (,condition ,@body))) which is easier to read, since it is a lot closer to the actual expansion.  File: librep.info, Node: Macro Expansion, Next: Compiling Macros, Prev: Backquoting, Up: Macros Macro Expansion --------------- When a macro call is detected (*note List Forms::.) the function which is the cdr of the macro's definition (*note Defining Macros::.) is applied to the macro call's arguments. Unlike in a function call, the arguments are *not evaluated*, the actual forms are the arguments to the macro's expansion function. This is to allow these forms to be rearranged by the macro's expansion function, creating the form that will finally be evaluated. There is a function which performs macro expansion, its main use is to let the Lisp compiler expand macro calls at compile time. - Function: macroexpand FORM #!OPTIONAL ENVIRONMENT If FORM is a macro call `macroexpand' will expand that call by calling the macro's expansion function (the cdr of the macro definition). If this expansion is another macro call the process is repeated until an expansion is obtained which is not a macro call, this form is then returned. The optional ENVIRONMENT argument is a function to call to do the actual expansion. (defmacro when (condition #!rest body) "Evaluates CONDITION, if it's true evaluates the BODY forms." (list 'if condition (cons 'progn body))) => when (macroexpand '(when x (setq foo bar))) => (cond (x (progn (setq foo bar)))) While a macro is being expanded, the special variable `macro-environment' is bound to value of the ENVIRONMENT parameter in the containing call to `macroexpand'. This allows macros to expand inner macros correctly. - Function: macroexpand-1 FORM #!OPTIONAL ENVIRONMENT Similar to `macroexpand', but only a single macro expansion is ever performed, i.e. if FORM is a macro call the result of expanding that call will be returned, otherwise FORM is returned. (macroexpand-1 '(when x (setq foo bar))) => (if x (progn (setq foo bar)))  File: librep.info, Node: Compiling Macros, Prev: Macro Expansion, Up: Macros Compiling Macros ---------------- Although it may seem odd that macros return a form to produce a result and not simply the result itself, this is actually their most important feature. It allows the expansion and the evaluation of the expansion to occur at different times. The Lisp compiler makes use of this; when it comes across a macro call in a form it is compiling it uses the `macroexpand' function to produce the expansion of that form. This expansion is then compiled straight into the object code. Obviously this is good for performance (why evaluate the expansion every time it is needed when once will do?). Some rules do need to be observed to make this work properly: * The macro expansion function (i.e. the definition of the macro) should not have any side effects or evaluate its arguments (the value of a symbol at compile-time probably won't be the same as its value at run-time). * Macros which are defined by another file must be loaded so they can be recognised. Use the `require' function, the compiler will evaluate any `require' forms it sees loading any macro definitions used. Note however, that the `librep' compiler does allow macros to be used before they are defined (two passes are made through the source file).  File: librep.info, Node: Definitions, Next: Modules, Prev: Macros, Up: The language Block-Structured Definitions ============================ Previous sections of this document have described several special forms and macros for defining top-level functions and variables. `librep' also provides a higher-level method of creating these definitions, the `define' statement. `define' originates in the Scheme dialect of Lisp, it allows block-structured programs to be defined intuitively. The most basic use of `define' is very similar to `defun', e.g. the two following forms have exactly the same effect: (defun foo (x) (1+ x)) (define (foo x) (1+ x)) But note the changed position of the parentheses. This is because `define' may also be used to define (lexical) variables. Hence the following is also equivalent: (define foo (lambda (x) (1+ x))) However this is the most uninteresting aspect of `define'. More interesting is that it allows "internal definitions". Within a `define' form, any inner calls to `define' (that occur in a contiguous block at the start of the body of a `let', `let*', `letrec', `lambda', or `define' form) are also used to create definitions, but definitions that are local to the containing scope. For example: (define (foo x) (define (bar) (* x 42)) (1+ (bar))) This defines a top-level function called `foo'; but this also contains an inner function named `bar', that is only accessible within `foo'. Since `bar' is defined inside `foo', and librep uses lexical scope by default, the variable `x' defined by `foo' may also be accessed by `bar'. - Macro: define NAME FORM - Macro: define (NAME . ARGS) BODY-FORMS... Define a global lexical variable called NAME, whose value will be set to FORM. If the first argument to the macro is a list, then a function is defined whose name is NAME and whose formal parameters are specified by ARGS. The body of the function is defined by the BODY-FORMS. The body forms have any macros expanded, and are scanned for internal definitions (at the start of the body of `let', `let*', `lambda' special forms) - Macro: define-macro NAME FORM - Macro: define-macro (NAME . ARGS) BODY-FORMS... Similar to `define', except that it creates a macro definition (*note Macros::.). - Macro: with-internal-definitions BODY-FORMS Recursively expand macros in BODY-FORMS, while scanning out any internal definitions into `letrec' statements.  File: librep.info, Node: Modules, Next: Control Structures, Prev: Definitions, Up: The language Modules ======= When creating large programs from many separate components, it is important to be able to encapsulate these components, such that the interfaces they present to other components are well defined, and the implementations of these interfaces may be modified without affecting any other components. To this end `rep' provides a "module system" for managing the scope of global definitions. This module system was inspired by the Scheme48, Xerox Scheme and Standard ML module systems. Modules are known as "structures" and may be anonymous or named. Each structure specifies and implements an "interface", essentially a list of names listing the definitions within the module that may be referenced by other modules. Each structure is a separate global namespace, with a number of variable bindings. Each closure contains a reference to the structure it was instantiated in, providing the source for referencing any unbound variables. As well as specifying its name and interface, each module also lists the other modules whose bindings it may reference. Structures may either "open" or "access" other structures; when opening a structure all its exported bindings are immediately referenceable from the importing module. Exported bindings from accessed structures are referenced using the `structure-ref' form. * Menu: * Module Interfaces:: * Module Definition:: * Module Loading:: * Modules and Special Variables::  File: librep.info, Node: Module Interfaces, Next: Module Definition, Up: Modules Module Interfaces ----------------- Each module implements an interface--the set of bindings (i.e. functions, macros or variables) that it exports to other modules. Interfaces may either be defined and then referenced by name, written literally, or combined from a number of sources. The syntax of interface definitions is as follows: INTERFACE -> (export ID ...) | NAME | (compound-interface INTERFACE ...) | (structure-interface MODULE-NAME) where each ID is the name of a binding to export, and each NAME is the name of an interface previously defined using `define-interface'. - Macro: define-interface NAME INTERFACE Associate the symbol NAME with the module interface INTERFACE (using one of the forms listed above. Here is an example defining an interface called `foo': (define-interface foo (compound-interface bar (export baz quux))) It includes the interface called `bar' and adds two extra exported symbols: `baz' and `quux'.  File: librep.info, Node: Module Definition, Next: Module Loading, Prev: Module Interfaces, Up: Modules Module Definition ----------------- Two special forms are used to define modules, one for anonymous modules, one for named modules. When storing modules in files, each file often contains a single instance of one of these forms. - Macro: structure INTERFACE CONFIG BODY... - Macro: define-structure NAME INTERFACE CONFIG BODY... These special forms each create a new module with interface INTERFACE (using the syntax described in the previous section), and configuration CONFIG. After configuring the module as specified, the sequence of forms BODY... is evaluated; it should include the definitions required to fulfil the interface that the module has promised to exhibit. The CONFIG form is either a list of configuration clauses, or a single configuration clause. Each such clause must be of the following syntax: CLAUSE -> (open NAME ...) | (access NAME ...) Each NAME specifies the name of a module, in the case of `open' clauses, the named module(s) will be loaded such that their exported bindings may be referenced from within the current module with no qualification (i.e. as if they had been defined within the module itself). Alternatively, if an `access' clause was used, the named module(s) will be loaded, but their exported bindings will only be accessible from within the current module using the `structure-ref' form. E.g. if a module `foo' has been accessed and it exports a binding named `bar', then the following form could be used to access its value: (structure-ref foo bar) Since this form is used so often, the reader allows the abbreviation `foo#bar' to be used instead, it is expanded to the form above when read. Note that no whitespace is allowed between the three tokens. Note that to access the standard features of the `rep' language described in this manual, modules need to import the `rep' module. Alternatively, they may import the `scheme' module to load a minimal R4RS Scheme environment. Here is an example module definition, defining a module named `test' that exports two functions `foo' and `bar'. (define-structure test (export foo bar) (open rep) (define (foo x) (* x 42)) (define (bar x y) (+ (foo x) (1+ y)))) It is also possible to export multiple views of a single underlying set of bindings, by using the `define-structures' form to create a number of modules. - Macro: define-structures ((NAME INTERFACE) ...) CONFIG BODY... Create a module for each `(NAME INTERFACE)' pair. The module is called NAME and exports the interface defined by INTERFACE. The CONFIG and BODY... forms are as in `define-structure'. Here is a trivial example: (define-structures ((foo (export foo both)) (bar (export bar both))) (open rep) (define both 1) (define foo 2) (define bar 3)) the underlying environment has three bindings. Each created module exports two of these.  File: librep.info, Node: Module Loading, Next: Modules and Special Variables, Prev: Module Definition, Up: Modules Module Loading -------------- As described above, the common way of loading modules is to use the `open' and `access' clauses of the configuration language. If the modules named by these clauses are not currently loaded into the interpreter, then the system will attempt to load them from the filing system, using the standard `load-path' variable to define the directories to search. To allow modules names to be hierarchical, any dot characters in a module's name are replaced by the operating system's directory separator string (i.e. on unix, all `.' characters are simply replaced by `/' characters). When searching for files to load, the standard filename suffixes are used to differentiate Lisp files from other types of files (*note Load Function::.). This file should contain a `define-structure' form (as described in the previous section) as the last top-level form in the file. For backwards compatibility, the `require' function can also be used to import modules. If a module of the same name as the requested feature has already been loaded, then it is imported into the current module. Otherwise if a file is loaded that contains a module definition as its last top-level form, this module is imported into the current module. *Note Features::.  File: librep.info, Node: Modules and Special Variables, Prev: Module Loading, Up: Modules Modules and Special Variables ----------------------------- As described earlier, the `defvar' special form may be used to create variables that are scoped dynamically, known as special variables, see *Note Defining Variables::. Due to their dynamic scope, special variables do not fit well with the lexically scoped module system described here. As a result of this mismatch, special variables are stored in a separate namespace. This means that modules defining special variables must take the necessary steps to avoid the names of these variables clashing with those declared in other modules(1). In fact, it is often advisable to avoid using special variables as much as possible, especially when writing modules of Lisp code. An alternative method of creating dynamically scoped variables is to use fluid variable objects. These use first class Lisp objects to represent anonymous dynamically scoped variables. Since they are just Lisp objects, they may be stored in lexically scoped variables--this gives the benefits of both lexical (i.e. encapsulation) and dynamic scoping. *Note Fluid Variables::. ---------- Footnotes ---------- (1) The usual convention is to prefix the variable name with a unique string derived from the module name.  File: librep.info, Node: Control Structures, Next: Threads, Prev: Modules, Up: The language Control Structures ================== Control structures are special forms or macros that control *which* forms get evaluated, *when* they get evaluated and the *number* of times to evaluate them. This includes conditional structures, loops, etc... The simplest control structures are the sequencing structures; they are used to evaluate a list of forms in left to right order. * Menu: * Sequencing Structures:: Evaluating several forms in sequence * Conditional Structures:: Making decisions based on truth values * Looping Structures:: `while' loops * Non-Local Exits:: Exiting from several levels of evaluation * Continuations:: Capturing the call stack