3.3. Symbols

Symbols are the only named objects. Symbol names may be up to 40 characters long.

The evaluation of a symbol returns the ``value'' of the symbol. Function setq changes the value of a symbol. The value of a new symbol is always the empty list.

During a call to a Lush function, or during the execution of certain special functions (e.g. function let ) predefined symbols take a temporary value. The previous values are then restored when the function exits.

For instance, assume that we define a function (de sqr(x) (* x x)) . Evaluating list (sqr 4) will perform the following actions:

save the old values of symbol x which is the name of a function argument,
set the value of symbol x to 4 ,
execute the function body (* x x) and save the result,
restore the previous value of symbol x ,
and return the saved result.

This dynamical binding makes the interpreter getting faster, but somewhat precludes the development of efficient compilers.

The textual representation of a symbol is composed by the characters of its name. The reader usually converts symbol names to lowercase and replaces underscores by dashes. This can be prevented by quoting the symbol name with vertical bars. Such vertical bars are useful for defining symbols whose name contains any character usually forbidden: parenthesis, spaces, semi-colon, macro-characters, upper-case characters etc....

Examples :

  gasp GasP         ; are the same symbol named "gasp"
  |GasP|            ; is different symbol named "GasP"
  |);( '|           ; is a symbol named ");( '"
  "gasp"            ; is a string
  12                ; is a number
  |12|              ; is a symbol named "12"

Unlike several dialect of lisp, Lush does not provide other fields in a symbol for storing a specific functional value or a property list. The value of a symbol is the only storage provided by symbols.

3.3.0. (defvar name [val])

[DM] (sysenv.lsh)

Defines a new global variable name . Argument name must be an unquoted symbol.

If there was already an existing global variable name , function defvar does nothing. Argument val is not even evaluated.
If there was no existing global variable name , function defvar defines such a global variable, and initializes it with the result of the evaluation of argument val .

Traditionally function setq was used for that purpose in SN/TLisp because there was no notion of undefined global variables. All undefined global variables were assumed to contain an empty list. This behavior was the source of many bugs. The lush kernel now prints a warning when using setq to define a new global variable.

3.3.1. (defparameter name [val])

[DM] (sysenv.lsh)

See: (defvar name [ val ])

Defines a new global variable name initialized with value val . Argument name must be an unquoted symbol. Unlike defvar , this function unconditionally evaluates val and sets the variable value.

3.3.2. (setq v1 a1 ... [vn an])

[DX]

Sets the value of symbols v1 ... vn to a1 ... an . It is good practice to create the symbol being setq'ed beforehand using defvar , let , let* or other constructs that create global or local variables.

The setq function has a special behavior when the vi are not symbols. This behavior is documented later, with the scope function.

Example:

? (setq a 3)
= 3
? (setq b 6)
= 6
? a b
= 3
= 6
? (setq a b b a)
= 3
? a b
= 6
= 3

3.3.3. (set v a)

[DX]

Sets the value of the symbol v to a . set is different from setq because v is evaluated first.

Example:

? (setq s 'a)
= a
? (set s 3)
= 3
? s
= a
? a
= 3

3.3.4. (incr v [n])

[DX]

Increments v by n (default 1). v is not evaluated, and must be a symbol whose value is a number. Number n may be a positive or negative.

Example:

? (setq s 0)
= 0
? (incr s)
= 1
? s
= 1

3.3.5. (named s)

[DX]

Returns a new symbol whose name is the string s .

Example:

? (named "a")
= a

? (named "A")
= |A|

3.3.6. (nameof s)

[DX]

Returns a string containing the name of symbol s . This is the converse of named .

Example:

? (nameof 'a)
= "a"

? (nameof '|A|)
= "A"

3.3.7. (namedclean s)

[DX]

Returns a new symbol whose name is computed by normalizing the string s using the same algorithm as the Lisp reader. This is the converse of function pname .

Example:

? (namedclean "a")
= a

? (namedclean "A")
= a

? (namedclean "|A|")
= |A|

3.3.8. (lock-symbol s1 ... sn)

[DX]

Locks symbols s1 to sn . Symbols may be locked. You can no longer change the value of locked symbols, but you may still modify them temporarily by using the let function. Some Lush functions and all C functions are stored in locked symbols. This avoids the accidental loss of a C function.

3.3.9. (unlock-symbol s1 ... sn)

[DX]

Unlocks symbols s1 to sn .

3.3.10. (symblist)

[DX]

Returns the list of all the symbol names: i. e. a list of strings.

Example:

? (length (symblist))
= 3006

3.3.11. (oblist)

[DX]

Returns the list of all the symbols: i. e. a list of symbols.

Example:

? (length (oblist))
= 3006

3.3.12. (macrochp s)

[DX]

Returns t if s symbol defines a macro-character.

Example:

? (macrochp '|'|)
= t

3.3.13. (putp anything name value)

[DE] (sysenv.lsh)

Every Lush object (atoms, cons, etc.) may be enriched by defining properties identified by a symbolic name. Function putp is used to define such properties. Its first argument is an arbitrary Lush object anything . Function putp sets the property named by symbol name to value value . Properties can be later retrieved using getp .

3.3.14. (getp anything name)

[DE] (sysenv.lsh)

Retrieves the property name for the Lush object anything .

3.4. Namespaces and Packages

3.4.0. (private ..symbols..)

[DM] (sysenv.lsh)

This function must be used inside a package definition. It indicates that the symbols ..symbols.. must be considered private to the package.
See: (package name ..expressions.. )

3.4.1. (package name ..expressions..)

[DM] (sysenv.lsh)

Author(s): Leon Bottou

This construct provides a simple way to make symbols "semi-private" to a group of functions so as to avoid name clashes. It basically has the effect of prepending the package name to all the symbols defined within its scope and marked as private (using the private construct).

Example:

   (package foobar
      (private foo)   
      (de foo(x) (print x)) 
      (de bar(x) (foo x)) )

defines a global symbol bar . Symbol foo however is renamed foobar.foo in all expressions occuring after (private foo) . Hence the above expression would be equivalent to:

  (de bar (x)
    (toto.foo x) )
  (de toto.foo (x)
    (print x) )

Internals: Symbol name is used to identify the group of functions. Function package maintains a list of hidden symbols declared with function private . Each expression is first transformed to replace all occurences of a hidden symbol by a new symbol whose name is composed by prepending the package name name , then evaluated as usual.