# Symbol Definition

## Variables

### defparameter name value [doc-string] ⇒ name

Unconditionally assign value to a global dynamic variable. The convention for naming a (global) special variable is `*name*`.

``(defparameter *x* 1) ;⇒ *X*``

### defvar name [value doc-string] ⇒ name

Unless bound already, assign value to a global dynamic variable.

``````(defvar *x* 'a) ;⇒ *X*
(defvar *x* 'b)
*x*             ;⇒ A``````

### defconstant name value [doc-string] ⇒ name

Assign value to a global constant variable. A constant can be redefined by defconstant. The convention for naming a constant is `+name+`.

``````(defconstant +x+ 'a) ;⇒ +X+
(setf +x+ 'b)        ;⇒ [error]``````

### setf {place value}* ⇒ result

Sets the value of place to value. Multiple pairs are set sequentially, use `psetf` to set in parallel. `setf` works with symbols and forms, and is preferred, while setq and psetq can only set symbols.

### let ({var | (var [value])}*) forms* ⇒ result*

Evaluate forms with vars lexically bound (or NIL) to values, assigned in parallel. Use let* to assign sequentially.

``````(let ((x 1))
(list x))       ;⇒ (1)

(let* ((x 1)
(y (+1 x)))
(list x y))      ;⇒ (1 2)``````

### multiple-value-bind (vars*) values-form body-forms* ⇒ result*

Evaluate body-forms with vars lexically bound to the return values of values-form. Return values of body-forms.

``````(multiple-value-bind (q r) (floor 7.5)
(list q r))                          ;⇒ (7 0.5)``````

### destructuring-bind lambda-list expression forms* ⇒ result*

Evaluate forms with variables from tree lambda-list bound to corresponding elements of tree expression, and return their values.

``````(destructuring-bind (a b c) (list 1 (list 2 20) 3)
(list a b c))       ;⇒ (1 (2 20) 3)

(destructuring-bind (a (b &optional c) d) (list 1 (list 2) 3)
(list a b c d))     ;⇒ (1 2 NIL 3)

(destructuring-bind (&whole whole &key a b c) (list :c 3 :b 2 :a 1)
(list a b c whole)) ;⇒ (1 2 3 (:C 3 :B 2 :A 1))``````

### shiftf place* newvalue ⇒ first-value

Store newvalue in rightmost place, shifting values of places left, returning first place.

``````(setf a :a b :b)
(shiftf a b :c)  ;⇒ :A
(list a b)       ;⇒ (:B :C)``````

### rotatef places* ⇒ nil

Rotate values of places left, the first becoming new last place’s value.

``````(setf a :a b :b c :c)
(rotatef a b c)       ;⇒ NIL
(list a b c)          ;⇒ (:B :C :A)``````

### makunbound symbol ⇒ symbol

Makes symbol unbound, regardless of whether it was previously bound.

``````(setf a 1)
(boundp 'a)     ;⇒ T
(makunbound 'a) ;⇒ A
(boundp 'a)     ;⇒ NIL``````

### multiple-value-setq (vars) form ⇒ result

Assign multiple values returned by form to vars.

``(multiple-value-setq (a b) (values 1 2))``

### progv symbols values forms* ⇒ result*

Evaluate forms with locally established dynamic bindings of symbols to values.

``````(setf *a* 1)
(progv '(*a*) '(2)
(print *a*))     ;⇒ [prints 2]``````

## Functions

### defun name lambda-list [[declare* | doc]] form* ⇒ name

Define a function with a given name, which acts as an implicit block when evaluating forms. Optionally declare type information about the function parameters.

``````(defun adder (a b)
(declare (number a b))
"Sum numbers and return the result."
(+ a b))

### lambda lambda-list [[declare* | doc]] form* ⇒ function

Return an anonymous function.

``(funcall #'(lambda (x) (* x x)) 3) ;⇒ 9``

### labels ((name lambda-list [[local-declare | local-doc]] local-forms*)*) [declare*] forms* ⇒ result*

Evaluate forms with a locally defined function. Functions defined by labels are visible within local-forms, functions defined by flet are not.

``````(labels ((adder (a b)
(+ a b))

(+ a b)))

### function name ⇒ function

The shorthand notation is `#'`. Return the function for name.

``(funcall #'list 'a 'b) ;⇒ (A B)``

### funcall function args* ⇒ result

Apply values as arguments to function.

``(funcall #'+ 1 2 3) ;⇒ 6``

### apply function [args*] arg-list ⇒ result

Apply values as arguments to function, the final one a list.

``````(apply #'+ '(1 2 3))   ;⇒ 6
(apply #'+ 1 2 '(3 4)) ;⇒ 10``````

### multiple-value-call function forms* ⇒ result

Apply all values returned from forms as arguments to function.

``(multiple-value-call #'+ (floor 5.5) (floor 4.3)) ;= (+ 5 0.5 4 0.3) ⇒ 9.8``

### values objects* ⇒ objects*

Return objects as multiple values. `setf`able.

``````(values 'a 'b)        ;⇒ A, B
(list (values 'a 'b)) ;⇒ (A)

(setf (values a b) (floor 7.5))
(list a b)                             ;⇒ (7 0.5)``````

### values-list list ⇒ objects*

Return list elements as multiple values.

``````(values-list '(A B)) ;⇒ A, B

(multiple-value-bind (a b) (values-list '(1 2))
(list a b))  ;⇒ (1 2)``````

### multiple-value-list form ⇒ list

Evaluates form returning multiple values and returns a list containing them.

``(multiple-value-list (floor 7.5)) ;⇒ (7 0.5)``

### fmakunbound name ⇒ name

Removes the function or macro definition.

``````(defun add-some (x) (+ x 19))   ;⇒ ADD-SOME
(flet ((add-some (x) (+ x 37)))

### nth-value n form ⇒ object

Return the nth value yielded by form, zero-indexed.

``````(nth-value 0 (values 'a 'b)) ;⇒ A
(nth-value 1 (values 'a 'b)) ;⇒ B``````

### function-lambda-expression function ⇒ lambda-expression, closure-p, name

If available, return lambda expression of function, `nil if function was defined in an environment without bindings, and name of function.

``(function-lambda-expression (funcall #'(lambda (x) #'(lambda () x)) nil)) ;⇒ NIL, T, NIL``

### fdefinition name ⇒ definition

Definition of global function foo; `setf`able.

``(fdefinition 'list) ;⇒ #<Compiled-function LIST>``

## Macros

The Common Lisp macro facility allows the user to define arbitrary functions that convert certain Lisp forms into different forms before evaluating or compiling them. This is done at the expression level, not at the character-string level as in most other languages. Macros are important in the writing of good code: they make it possible to write code that is clear and elegant at the user level but that is converted to a more complex or more efficient internal form for execution.

### defmacro name lambda-list [[declare* | doc]] forms* ⇒ name

Define a macro with a given name, which acts as an implicit block when evaluating forms. `define-compiler-macro` is similar with a few differences.

``````(defmacro adder (a b)
"Sums two numbers and returns the result"
`(+ ,a ,b))

### macrolet ((name lambda-list [[local-declare | local-doc]] local-forms*)*) [declare*] forms* ⇒ result*

Defines local macro definitions, using the same format used by defmacro.

``````(macrolet ((adder (a b) `(+ ,a ,b)))

### define-symbol-macro symbol expansion ⇒ symbol

Defines a macro expansion for symbol. `setf`able.

``````(setf a '(1 2 3))
(define-symbol-macro b (car a)) ;⇒ B
b                               ;⇒ 1
(setf b 5)
a                               ;⇒ (5 2 3)
b                               ;⇒ 5``````

### symbol-macrolet ((symbol expansion)*) declare* forms* ⇒ result*

Evaluate forms with locally defined symbol macros.

``````(symbol-macrolet ((x 'foo))
(list x (let ((x 'bar)) x))) ;⇒ (FOO BAR)``````

### define-modify-macro name lambda-list function [doc] ⇒ name

Defines a macro to read and write a place.

``````(define-modify-macro new-incf (&optional (delta 1)) +)
(setf a 1)
(new-incf a) ;⇒ 2``````

### defsetf access-fn update-fn [doc] ⇒ access-fn

Specify how to `setf` a place accessed by function. There is a “short form” and “long form” of defsetf as distinguished by the type of arguments.

``````(defun middle (x)
(nth (truncate (* (list-length x) 0.5)) x))
(defun set-middle (x val)
(let ((idx (truncate (* (list-length x) 0.5))))
(setf (nth idx x) val)))
(defsetf middle set-middle)

(setf a '(a b c))   ;⇒ (A B C)
(middle a)          ;⇒ B
(setf (middle a) 2)
a                   ;⇒ (A 2 C)``````

### get-setf-expansion place &optional env ⇒ vars, vals, store-vars, writer-form, reader-form

Returns lists of temporary variables, values, and get and set forms for setf to read place.

``````(defvar x)
(get-setf-expansion 'x) ;⇒ NIL, NIL, (#:G6725), (SETQ X #:G6725), X``````

### define-setf-expander access-fn lambda-list [[declaration* | doc]] form* ⇒ access-fn

Specifies the means by which setf updates a place that is referenced by access-fn.

``````(defun last-element (x) (car (last x)))
(define-setf-expander last-element (x &environment env)
"Set the last element in a list to the given value."
(multiple-value-bind (dummies vals newval setter getter) (get-setf-expansion x env)
(let ((store (gensym)))
(values dummies
vals
`(,store)
`(progn (rplaca (last ,getter) ,store) ,store)
`(lastguy ,getter)))))

(setf l '(a b c d))       ;⇒ (A B C D)
(last-element l)          ;⇒ D
(setf (last-element l) 4)
l                         ;⇒ (A B C 4)``````