The clith Reference Manual

This is the clith Reference Manual, generated automatically by Declt version 4.0 beta 2 "William Riker" on Tue Jul 15 04:39:55 2025 GMT+0.

Table of Contents


1 Introduction


2 Systems

The main system appears first, followed by any subsystem dependency.


2.1 clith

Common Lisp wITH macro. A general WITH macro.

Author

Héctor Galbis Sanchis

License

MIT

Dependencies
  • alexandria (system).
  • expanders (system).
Source

clith.asd.

Child Component

src (module).


3 Modules

Modules are listed depth-first from the system components tree.


3.1 clith/src

Source

clith.asd.

Parent Component

clith (system).

Child Components

4 Files

Files are sorted by type and then listed depth-first from the systems components trees.


4.1 Lisp


4.1.1 clith/clith.asd

Source

clith.asd.

Parent Component

clith (system).

ASDF Systems

clith.


4.1.2 clith/src/package.lisp

Source

clith.asd.

Parent Component

src (module).

Packages

clith.


4.1.3 clith/src/clith.lisp

Dependency

package.lisp (file).

Source

clith.asd.

Parent Component

src (module).

Public Interface
Internals

4.1.4 clith/src/definitions.lisp

Dependency

clith.lisp (file).

Source

clith.asd.

Parent Component

src (module).


5 Packages

Packages are listed by definition order.


5.1 clith

Source

package.lisp.

Use List
  • alexandria.
  • common-lisp.
Public Interface
Internals

6 Definitions

Definitions are sorted by export status, category, package, and then by lexicographic order.


6.1 Public Interface


6.1.1 Macros

Macro: defwith (name (vars args with-body) &body body)

Define a WITH expansion. A WITH expansion controls how the macro WITH is expanded. This macro has
the following syntax:

(DEFWITH name (vars args with-body) declaration* body*)

name ::= symbol
vars ::= symbol | (var-with-options*)
var-with-options ::= symbol | (symbol option*)
option ::= destructuring-lambda-argument
args ::= destructuring-lambda-list
with-body ::= symbol
declaration ::= declaration-form | docstring
body ::= form

When using (NAME ARGS*) inside the macro WITH, it will expand to the value returned by DEFWITH.
The variables to be bound are passed through VARS (VARS will always be a list) and the arguments passed to NAME are bound to ARGS. Finally, WITH-BODY is bound to the body of the WITH macro. Keep in mind that WITH-BODY can contain declarations.

As an example, let’s define the with expansion MY-FILE. We will make WITH to be expanded to WITH-OPEN-FILE.

(defwith my-file (vars (filespec &rest options) body)
"Open a file."
(with-gensyms (stream)
‘(with-open-file (,stream ,filespec ,@options)
(multiple-value-bind ,vars ,stream
,@body))))

As VARS is always a list, we can use MULTIPLE-VALUE-BIND in case additional variables are passed.
Also, we are assuming here that no additional options are passed with the variables to be bound.

Now, using WITH:

(with ((file (my-file "~/file.txt" :direction :output)))
(print "Hey!" file))

Finally, note that we put a docstring when we defined MY-FILE. We can retrieve it with DOCUMENTATION:

(documentation ’my-file ’with) ;; –> "Open a file."

Package

clith.

Source

clith.lisp.

Macro: with (bindings &body body)

This macro has the following systax:

(WITH (binding*) declaration* form*)

binding ::= symbol | ([vars] form)
vars ::= symbol | (var-with-options*)
var-with-options ::= symbol | (symbol var-option*)
var-option ::= form

WITH accepts a list of binding clauses. Each binding clause can be a symbol or a list. Depending on this, the behaeviour of WITH is slightly different:

- A symbol: The symbol is bound to NIL.

(with (x) ; X is bound to NIL
...)

- A list with one element. That element can be a WITH expansion or not:

* A WITH expansion: The form is expanded according to DEFWITH. In this case,
the WITH expansion will receive NIL as the list of variables to be bound.

(with (((init-video-system))) ; Possible expansion that should finalize the video system at the end ;; Doing video stuff
)

* Otherwise: The form is placed untouched. It will be evaluated normally.

(with (((print 3))) ; Just prints 3
...)

- A list with two elements: The first element must be a symbol or a list of symbols with
or without options. The second element is a form that can be a WITH expansion:

* A WITH expansion: The form is expanded according to DEFWITH.

(with ((my-file (open "~/my-file.txt"))) ; Expanded to WITH-OPEN-FILE
...)

* Otherwise: The form is placed into a MULTIPLE-VALUE-BIND expression.

(with ((x 3)
((y z) (floor 4 5))) ; Forms placed into MULTIPLE-VALUE-BIND
...)

Binding clauses that uses a WITH expansion accepts an extended syntax. Each variable can have options. These options should be used inside DEFWITH to control the expansion with better precision:

(defwith slots (vars (object) body)
‘(with-slots ,vars ,object
,@body))

(defstruct 3d-vector x y z)

(with ((v (make-3d-vector :x 1 :y 2 :z 3))
((x (up y) z) (slots v)))
(+ x up z))

Macros and symbol-macros are treated specially. If a macro or symbol-macro is used, they
will be expanded with MACROEXPAND-1 and its result is the form, or WITH expansion, this macro uses.

Package

clith.

Source

clith.lisp.


6.1.2 Ordinary functions

Function: withp (sym)

Checks wether a symbol denotes a WITH expansion.

Package

clith.

Source

clith.lisp.


6.2 Internals


6.2.1 Ordinary functions

Function: canonize-binding (binding env)

Transforms BINDING to a form that is more apropiate to process.
In particular, turns BINDING into a list of two elements.
The former element is a list of the binding symbols written by user.
The latter is the form that returns the values which variables will be bound to.

Package

clith.

Source

clith.lisp.

Function: check-binding (binding env)

Checks the syntax of a binding clause.

Package

clith.

Source

clith.lisp.

Function: check-bindings (bindings env)

Checks the syntax of binding clauses.

Package

clith.

Source

clith.lisp.

Function: check-defwith (name vars with-body)
Package

clith.

Source

clith.lisp.

Function: check-vars (vars extendedp)

Checks the syntax of variables.
If extendedp, it is accepted to have options after a variable.
I.e. if extendedp, a variable can be a list with a symbol followed by other forms.

Package

clith.

Source

clith.lisp.

Function: expand-binding-expression (expression env)

Returns the actual expression to be used inside a binding clause.

Package

clith.

Source

clith.lisp.

Function: expand-with-expansion (macro-name vars args body)

Expands a WITH expansion.

Package

clith.

Source

clith.lisp.

Function: extract-declaration-single-var (var declarations)

Splits DECLARATIONS into two lists of declarations. The former is a list of declarations that applies to VAR. The latter are the rest of declarations.

Package

clith.

Source

clith.lisp.

Function: extract-declarations (body)

Extracts the declarations of BODY.

Package

clith.

Source

clith.lisp.

Function: extract-var-declarations (vars declarations)

Splits DECLARATIONS into two lists of declarations.
The former is a list of declarations that applies to one variable in VARS. The latter are the rest of declarations.

Package

clith.

Source

clith.lisp.

Function: make-with-form (bindings body binding-declarations body-declarations env)

Returns the WITH macro expansion.

Package

clith.

Source

clith.lisp.

Function: make-with-macro-form (binding body declaration env)

Expands a WITH expansion given its BINDING, its BODY and its DECLARATION.

Package

clith.

Source

clith.lisp.

Function: split-declarations (canonized-bindings declarations)

Splits DECLARATIONS into two lists.
The former is a list of declarations that applies to one of the variables used in CANONIZED-BINDINGS. The latter are the rest of declarations.

Package

clith.

Source

clith.lisp.

Function: var-declaration-p (id)

Checks if ID is an identifier of a variable declaration.

Package

clith.

Source

clith.lisp.

Function: with-expansion-p (expression env)

Checks if a expression is a with expansion.

Package

clith.

Source

clith.lisp.

Function: with-macro-binding-p (canonized-binding env)

Checks if a binding has a custom expansion.

Package

clith.

Source

clith.lisp.


Appendix A Indexes


A.1 Concepts


A.2 Functions

Jump to:   C   D   E   F   M   S   V   W  
Index Entry  Section

C
canonize-binding: Private ordinary functions
check-binding: Private ordinary functions
check-bindings: Private ordinary functions
check-defwith: Private ordinary functions
check-vars: Private ordinary functions

D
defwith: Public macros

E
expand-binding-expression: Private ordinary functions
expand-with-expansion: Private ordinary functions
extract-declaration-single-var: Private ordinary functions
extract-declarations: Private ordinary functions
extract-var-declarations: Private ordinary functions

F
Function, canonize-binding: Private ordinary functions
Function, check-binding: Private ordinary functions
Function, check-bindings: Private ordinary functions
Function, check-defwith: Private ordinary functions
Function, check-vars: Private ordinary functions
Function, expand-binding-expression: Private ordinary functions
Function, expand-with-expansion: Private ordinary functions
Function, extract-declaration-single-var: Private ordinary functions
Function, extract-declarations: Private ordinary functions
Function, extract-var-declarations: Private ordinary functions
Function, make-with-form: Private ordinary functions
Function, make-with-macro-form: Private ordinary functions
Function, split-declarations: Private ordinary functions
Function, var-declaration-p: Private ordinary functions
Function, with-expansion-p: Private ordinary functions
Function, with-macro-binding-p: Private ordinary functions
Function, withp: Public ordinary functions

M
Macro, defwith: Public macros
Macro, with: Public macros
make-with-form: Private ordinary functions
make-with-macro-form: Private ordinary functions

S
split-declarations: Private ordinary functions

V
var-declaration-p: Private ordinary functions

W
with: Public macros
with-expansion-p: Private ordinary functions
with-macro-binding-p: Private ordinary functions
withp: Public ordinary functions


A.3 Variables