How to read the documentation

If you want some information about a command, say 'foo', if suffices to find the symbol on the page that contains all commands starting with the letter F, or to click on a symbol like this foo if it is underlined. If command does not start with a letter, click on the page symbols.

There are different types of objects; they can be classified as Lisp objects, and symbolic objects. See the tutorial for how to create, manipulate, or print them. Some objects have a name. If `foo' is such an object, you can assign a value to it, and later on, retrieve the value via the name. Assume for instance that the value is a+b. Then there is no difference between foo^2 and (a+b)^2. However, there are two instances of the sum a+b, which is an unnamed object. If you replace a by c in one sum, the other sum does not change. On the other hand, there is a single object named `foo'.

In fact, on the Lisp level, each symbol is in a package, for instance foo is in the default package, #:feval:foo is in the feval package, #:a:b:c:d:foo is in the package #:a:b:c:d. In some cases, the package is not fully printed (for instance, in verbose mode, the compiler does not print the feval package). In symbolic mode, if you say a+b, the expression is read, as a sequence of three symbols, in the same way as (+ a b) in read in Lisp mode. The Lisp evaluator evaluates the argumemts, and applies the operator. The symbolic compiler is a preprocessor. In the case where the symbol a is undefined, it replaces it by a fsymbol with the same name (a fsymbol is a named object; it has no value, but can have some properties). There is a simplifier that knows how to deal with fexpressions and fsymbols (the + symbol understands only numbers). One of the jobs of the compiler is to notice the existence of the function #:feval:+, and use it instead of +. You can use #cons(a,b) if you do not want the compiler to use #:feval:cons. You can also say lisp("+")(a,b); here quotes are needed to make the reader happy.

We start with a simple example. The command a==b returns true if both objects are similar, while #eq(a,b) is true if both objects are the same (have the same memory adress).

(1) [#eq(a,a), a==a , #eq("cons", "cons"), "cons"=="cons" ];

(1)                       [TRUE, TRUE, FALSE, TRUE]

(2) x:=a+b?; y:= b+a?;

(4) [#eq(x,x), #eq(x,y), x==x, x==y];

(4)                       [TRUE, FALSE, TRUE, TRUE]

(5) #eq+3;
eval : undefined variable : eq
(6) cons+3;
+ : Cannot compute : +(3, cons)

This example shows some interesting features. User input is in red, errors are in blue; input expressions are terminated by a semi-colon; when preceded by a question mark, the result of the evaluation is not printed. In example 2, the compiler has replaced a by a fsymbol (if the simplifier has re-ordered the sum), but in case 5, it has left #eq unchanged, so that the Lisp evaluator, in charge of evalution, provokes an error. In case 6, the compiler has replaced cons by #:feval:cons (in reality, by something that the Lisp evaluator understands as being this function). The trouble is that the simplifier wants a fsymbol, or a fexpression, not a Lisp function.

Note: It is possible, in a future version, that (f+3)(x) and f(x)+3 are the same if f is a function; in this case f+3 would be a function. This mechanism will work only in the case of a flambda (a symbolic function), so that the sum cons+3 will remain an error.

We show now an example in Lisp mode; the color of the frame is different, in order to make it easier to distinguish. Notice that the prompt is a constant character string; expressions are not remembered in a big table. The Lisp printer is also less sophisticated than the symbolic printer.

[Endymion] (list 1 2 'foo "foo" #:foo:bar:#[a b c])
(1 2 foo foo #:foo:bar:#[a b c])
[Endymion] (rebverse (list 1 2 'foo "foo" #:foo:bar:#[a b c]))
eval : undefined function : rebverse
[Endymion] (reverse (list 1 2 'foo "foo" #:foo:bar:#[a b c]))
(#:foo:bar:#[a b c] foo foo 2 1)
[Endymion] (cons 1 2 3)
cons : wrong number of arguments : 3 this should be 2

Most objects explained in the documentation are Lisp functions. In some cases, we give a definition, that is functionnally the same as the C code; in general argument checking is missing. Here is an example of a function.

(my-function x y) (Lisp function)

The my-function function takes two arguments and creates a cons, like function, but in a different ordrer. The function could be defined as

(defun my-function (x y)
   ;; sample definition
   (let ((res (function y x)))
        ; (print "my function gives: " res) 
        res))

Here is an example of a symbolic function.

my_function(x,y) (Symbolic function)

The my_function function is like my-function, but unevaluated. Example:

(5) my_function(x^2, 1/y);

                                         / 2  1\
(5)                           my-function|x , -|
                                         \    y/


Valid XHTML 1.0 Strict back to home page © INRIA 2005, 2006 Last modified $Date: 2006/06/30 13:32:07 $