Next: Introduction, Previous: (dir), Up: (dir) [Contents][Index]
This is the cl-annot Reference Manual, version 0.1, generated automatically by Declt version 3.0 "Montgomery Scott" on Mon Apr 19 14:29:59 2021 GMT+0.
• Introduction | What cl-annot is all about | |
• Systems | The systems documentation | |
• Modules | The modules documentation | |
• Files | The files documentation | |
• Packages | The packages documentation | |
• Definitions | The symbols documentation | |
• Indexes | Concepts, functions, variables and data types |
cl-annot is an general annotation library for Common Lisp.
cl-annot is tested under the following implementations:
Annotations is a special syntax for annotating and transforming forms. Annotations look like Python's decorator:
@annot
(defun foobar ()
...)
Any functions and macros can be annotations which takes one argument by default. For example, if you define the following function,
(defun trace (object)
(print object)
object)
you can use the function as an annotation like:
@trace (+ 1 2)
This expression prints 3
and returns 3
. Internally, this
expression will be regarded as (trace (+ 1 2))
.
Standard annotation export
exports the symbol of the given
definition. For example,
@export
(defun foobar ()
...)
defines a function foobar
and exports the symbol foobar
. This
equivalents to:
(progn
(export 'foobar)
(defun foobar ()
...))
Annotations help you to write the simple and declarative codes.
Just write the following code at the header of each files:
(annot:enable-annot-syntax)
After this code, @...
syntax can be used.
If you use Emacs, it is recommended to install misc/slime-annot.el
which contains some features of annotations. After locating
misc/slime-annot.el
into your loadpath, write the following code
into your .emacs
.
(require 'slime-annot)
annot.std
This package contains very basic and useful annotations. You don't
need to use-package
this package.
export
@export DEFINITION-FORM
export
is a macro which adds an export
form of the definition
form. For example,
@export (defun f () ...)
is equivalent to
(progn
(export 'f)
(defun f () ...))
ignore
@ignore VARIABLES
ignore
is a macro which is equivalent to (declare (ignore ...))
form. For example,
@ignore v
is equivalent to
(declare (ignore v))
ignore
can take a list of variables like:
@ignore (a b c)
ignorable
@ignorable VARIABLES
Same as ignore
annotation except that this is equivalent to
(declare (ignorable v))
type
@type TYPESPEC NAME
type
is a macro which is equivalent to (declare (type ...))
form. For example,
@type integer v
is equivalent to
(declare (type integer v))
optimize
@optimize QUALITY
optimize
is a macro which is equivalent to (declare (optimize ...))
form. For example,
@optimize (speed 3)
is equivalent to
(declare (optimize (speed 3)))
inline
@inline NAME
inline
is a macro which is equivalent to (proclaim (inline ...))
or (declare (inline ...))
form. If NAME is just a symbol,
declaration will be used. If NAME is a definition form, proclamation
will be used. For example,
@inline f
is equivalent to
(declare (inline f))
And
@inline
(defun f () ...)
is equivalent to
(proclam (inline f))
(defun f () ...)
annot.eval-when
This package contains annotations eval-when
special form.
eval-when-compile
@eval-when-compile FORM
eval-when-compile
is a macro which is equivalent to (eval-when (:compile-toplevel) ...)
. For example,
@eval-when-compile
(defun macro-util () ...)
is equivalent to
(eval-when-compile (:compile-toplevel)
(defun macro-util () ...))
eval-when-load
@eval-when-load FORM
Same as eval-when-compile
except that this is equivalent to
(eval-when (:load-toplevel) ...)
.
eval-when-execute
@eval-when-execute FORM
Same as eval-when-compile
except that this is equivalent to
(eval-when (:execute) ...)
.
eval-always
@eval-always FORM
eval-always
is a macro which is equivalent to (eval-when (:compile-toplevel :load-toplevel :execute) ...)
.
annot.doc
This package contains documentation annotations.
doc
@doc DOCSTRING DEFINITION-FORM
doc
is a macro which inserts documentation string into the
definition form. For example,
@doc "docstring"
(defun f () ...)
is equivalent to
(defun f ()
"docstring"
...)
Mixture of export
annotation and doc
annotation is allowed, means
@export
@doc "docstring"
(defun f () ...)
works as you expected.
annot.class
This package contains annotations about classes.
metaclass
@metaclass METACLASS CLASS-DEFINITION-FORM
metaclass
embeds (:metaclsas METACLASS)
into class-options of
CLASS-DEFINITION-FORM
. For example,
@metaclass persistent-class
(defclass foo ()
())
is equivalent to
(defclass foo ()
()
(:metaclass persistent-class))
export-slots
@export-slots CLASS-DEFINITION-FORM
export-slots
adds (export ...)
form for slots of
CLASS-DEFINITION-FORM
. For example,
@export-slots
(defclass foo ()
(bar baz))
is equivalent to
(progn
(export '(bar baz))
(defclass foo ()
(bar baz)))
It can also be used with defstruct
as of the commit
9043a74815a028a7db664f2fd77a8b009c736df9
(8/31,2013).
export-accessors
@export-accessors CLASS-DEFINITION-FORM
export-accessors
adds (export ...)
form for accessors
(i.e. readers, writers and accessors) of CLASS-DEFINITION-FORM
. For
example,
@export-accessors
(defclass foo ()
((bar :reader bar-of)
(bax :writer bax-of)
(baz :accessor baz-of)))
is equivalent to
(progn
(export '(bar-of bax-of baz-of))
(defclass foo ()
((bar :reader bar-of)
(bax :writer bax-of)
(baz :accessor baz-of))))
It can also be used with defstruct
as of the commit
9043a74815a028a7db664f2fd77a8b009c736df9
(8/31,2013).
export-constructors
It can be used as of the commit
9043a74815a028a7db664f2fd77a8b009c736df9
(8/31,2013).
According to the {CLHS: Macro
DEFSTRUCT}[http://www.lispworks.com/documentation/HyperSpec/Body/m_defstr.htm],
defstruct
can define more than one constructor, for example:
@export-constructors
(defstruct (s (:constructor abya a c)
(:constructor abya2 a b c))
a b c)
is equivalent to
(progn
(export '(abya abya2))
(defstruct (s (:constructor abya a c)
(:constructor abya2 a b c)) a b c))
and it might have no constructor like this.
(defstruct (s (:constructor nil)) a b c)
export-class
and export-structure
export-class
combines export
, export-slots
and
export-accessors
. export-structure
also combines
export-constructors
in addition.
annot.slot
This package contains annotations about slots.
optional
@optional INITFORM SLOT-SPECIFIER
optional
embeds :initarg SLOT-NAME
and :initform INITFORM
into
SLOT-SPECIFIER
. For example,
(defclass c ()
(@optional nil
foo))
is equivalent to
(defclass c ()
((foo :initarg :foo
:initform nil)))
required
@required SLOT-SPECIFIER
required
embeds :initarg SLOT-NAME
and :initform (annot.slot:required-argument SLOT-NAME)
into SLOT-SPECIFIER
so
that MAKE-INSTANCE
will raise errors when no argument for the slot
given. For example,
(defclass c ()
(@required
foo))
is equivalent to
(defclass c ()
((foo :initarg :foo
:initform (annot.slot:required-argument :foo))))
As I mentioned, any functions and macros can be
annotations. Basically, if you have a function or a macro named
annot
, the following code
@annot (+ 1 2)
will be expanded like
(annot (+ 1 2))
You may use an alias for specifying annotations. This is useful when
you want to use more general names as annotation names. Actually,
annot.std
uses this technique to overriding the meanings of symbols
in common-lisp
package. Here is how to alias:
(setf (annotation-real 'do) 'long-long-name)
Now you can use do
as meaning long-long-name
at annotations like:
@do ...
By default, annotations can take only one argument. If you want to write an annotation taking two or more arguments, you need to specify a number of arguments into the annotation symbol like:
(use-package :annot.core)
(defun my-annot (x y) (+ x y))
(setf (annotation-arity 'my-annot) 2)
Now you can use this annotation like:
@my-annot 2 3
;; => 5
In some cases, you want annotations to be expanded at read-time. You can do it by:
(setf (annotation-inline-p 'annot) t)
Be caseful to use feature.
defannotation
defannotation NAME LAMBDA-LIST (:alias ALIAS :arity ARITY :inline INLINE) &body BODY
defannotation
is an utility macro for creating annotations. Here is an example:
(defannotation my-annot (x y)
(:arity 2 :inline t)
`(+ ,x ,y))
annotation
annotation (:alias ALIAS :arity ARITY :inline INLINE) FUNCTION-DEFINITION-FORM
annotation
is an annotation for creating annotations in a way of
defannotation
. Here is an example:
@annotation (:arity 2 :inline t)
(defmacro my-annot (x y)
`(+ ,x ,y))
Copyright (C) 2011 Tomohiro Matsuyama <tomo@cx4a.org>
Next: Modules, Previous: Introduction, Up: Top [Contents][Index]
The main system appears first, followed by any subsystem dependency.
• The cl-annot system |
Tomohiro Matsuyama
LLGPL
Python-like Annotation Syntax for Common Lisp
0.1
alexandria
cl-annot.asd (file)
src (module)
Modules are listed depth-first from the system components tree.
• The cl-annot/src module | ||
• The cl-annot/src/main module | ||
• The cl-annot/src/lib module |
Next: The cl-annot/src/main module, Previous: Modules, Up: Modules [Contents][Index]
Next: The cl-annot/src/lib module, Previous: The cl-annot/src module, Up: Modules [Contents][Index]
src (module)
src/main/
Previous: The cl-annot/src/main module, Up: Modules [Contents][Index]
main (module)
src (module)
src/lib/
Files are sorted by type and then listed depth-first from the systems components trees.
• Lisp files |
Next: The cl-annot/src/main/utils․lisp file, Previous: Lisp files, Up: Lisp files [Contents][Index]
cl-annot.asd
cl-annot (system)
Next: The cl-annot/src/main/core․lisp file, Previous: The cl-annot․asd file, Up: Lisp files [Contents][Index]
main (module)
src/main/utils.lisp
Next: The cl-annot/src/main/expand․lisp file, Previous: The cl-annot/src/main/utils․lisp file, Up: Lisp files [Contents][Index]
utils.lisp (file)
main (module)
src/main/core.lisp
Next: The cl-annot/src/main/syntax․lisp file, Previous: The cl-annot/src/main/core․lisp file, Up: Lisp files [Contents][Index]
core.lisp (file)
main (module)
src/main/expand.lisp
expand-annotation-form (function)
Next: The cl-annot/src/main/helper․lisp file, Previous: The cl-annot/src/main/expand․lisp file, Up: Lisp files [Contents][Index]
expand.lisp (file)
main (module)
src/main/syntax.lisp
Next: The cl-annot/src/main/annot․lisp file, Previous: The cl-annot/src/main/syntax․lisp file, Up: Lisp files [Contents][Index]
syntax.lisp (file)
main (module)
src/main/helper.lisp
set-annotation-options (function)
Next: The cl-annot/src/lib/std․lisp file, Previous: The cl-annot/src/main/helper․lisp file, Up: Lisp files [Contents][Index]
helper.lisp (file)
main (module)
src/main/annot.lisp
Next: The cl-annot/src/lib/eval-when․lisp file, Previous: The cl-annot/src/main/annot․lisp file, Up: Lisp files [Contents][Index]
lib (module)
src/lib/std.lisp
%declare-list-or-symbol (function)
Next: The cl-annot/src/lib/doc․lisp file, Previous: The cl-annot/src/lib/std․lisp file, Up: Lisp files [Contents][Index]
std.lisp (file)
lib (module)
src/lib/eval-when.lisp
Next: The cl-annot/src/lib/class․lisp file, Previous: The cl-annot/src/lib/eval-when․lisp file, Up: Lisp files [Contents][Index]
eval-when.lisp (file)
lib (module)
src/lib/doc.lisp
doc (macro)
Next: The cl-annot/src/lib/slot․lisp file, Previous: The cl-annot/src/lib/doc․lisp file, Up: Lisp files [Contents][Index]
doc.lisp (file)
lib (module)
src/lib/class.lisp
Previous: The cl-annot/src/lib/class․lisp file, Up: Lisp files [Contents][Index]
class.lisp (file)
lib (module)
src/lib/slot.lisp
Next: Definitions, Previous: Files, Up: Top [Contents][Index]
Packages are listed by definition order.
Next: The cl-annot․util package, Previous: Packages, Up: Packages [Contents][Index]
cl-annot.asd
Next: The cl-annot․core package, Previous: The cl-annot-asd package, Up: Packages [Contents][Index]
utils.lisp (file)
annot.util
common-lisp
Next: The cl-annot․expand package, Previous: The cl-annot․util package, Up: Packages [Contents][Index]
core.lisp (file)
annot.core
common-lisp
Next: The cl-annot․syntax package, Previous: The cl-annot․core package, Up: Packages [Contents][Index]
expand.lisp (file)
annot.expand
expand-annotation (function)
expand-annotation-form (function)
Next: The cl-annot․helper package, Previous: The cl-annot․expand package, Up: Packages [Contents][Index]
syntax.lisp (file)
annot.syntax
Next: The cl-annot package, Previous: The cl-annot․syntax package, Up: Packages [Contents][Index]
helper.lisp (file)
annot.helper
set-annotation-options (function)
Next: The cl-annot․std package, Previous: The cl-annot․helper package, Up: Packages [Contents][Index]
annot.lisp (file)
annot
common-lisp
Next: The cl-annot․eval-when package, Previous: The cl-annot package, Up: Packages [Contents][Index]
std.lisp (file)
annot.std
%declare-list-or-symbol (function)
Next: The cl-annot․doc package, Previous: The cl-annot․std package, Up: Packages [Contents][Index]
eval-when.lisp (file)
annot.eval-when
common-lisp
Next: The cl-annot․class package, Previous: The cl-annot․eval-when package, Up: Packages [Contents][Index]
doc.lisp (file)
annot.doc
doc (macro)
Next: The cl-annot․slot package, Previous: The cl-annot․doc package, Up: Packages [Contents][Index]
class.lisp (file)
annot.class
Previous: The cl-annot․class package, Up: Packages [Contents][Index]
slot.lisp (file)
annot.slot
Definitions are sorted by export status, category, package, and then by lexicographic order.
• Exported definitions | ||
• Internal definitions |
Next: Internal definitions, Previous: Definitions, Up: Definitions [Contents][Index]
• Exported macros | ||
• Exported functions |
Next: Exported functions, Previous: Exported definitions, Up: Exported definitions [Contents][Index]
Annotation Expansion Engine.
expand.lisp (file)
helper.lisp (file)
Shorthand for (DECLARE (DECLARATION ...)).
std.lisp (file)
helper.lisp (file)
Add DOCSTRING documentation for DEFINITION-FORM.
doc.lisp (file)
Shorthand for (DECLARE (DYNAMIC-EXTENT ...)).
std.lisp (file)
syntax.lisp (file)
eval-when.lisp (file)
eval-when.lisp (file)
eval-when.lisp (file)
eval-when.lisp (file)
Export the definition symbol of DEFINITION-FORM.
std.lisp (file)
class.lisp (file)
class.lisp (file)
class.lisp (file)
class.lisp (file)
class.lisp (file)
Shorthand for (DECLARE (FTYPE ...)).
std.lisp (file)
Shorthand for (DECLARE (IGNORABLE ...)).
std.lisp (file)
Shorthand for (DECLARE (IGNORE ...)).
std.lisp (file)
Shorthand for (DECLARE (INLINE ...)).
std.lisp (file)
class.lisp (file)
Shorthand for (DECLARE (NOTINLINE ...)).
std.lisp (file)
Shorthand for (DECLARE (OPTIMIZE ...)).
std.lisp (file)
slot.lisp (file)
slot.lisp (file)
Shorthand for (DECLARE (SPECIAL ...)).
std.lisp (file)
Shorthand for (DECLARE (TYPE ...)).
std.lisp (file)
Previous: Exported macros, Up: Exported definitions [Contents][Index]
Return the number of arguments of ANNOT.
core.lisp (file)
(setf annotation-arity) (function)
core.lisp (file)
annotation-arity (function)
Make an annotation-form with ANNOT and ARGS.
core.lisp (file)
Return non-nil if FORM is an annotation-form.
core.lisp (file)
Return non-nil if ANNOT should be expanded on read-time.
core.lisp (file)
(setf annotation-inline-p) (function)
core.lisp (file)
annotation-inline-p (function)
Return the real annotation of ANNOT.
core.lisp (file)
(setf annotation-real) (function)
core.lisp (file)
annotation-real (function)
syntax.lisp (file)
Return class-options of CLASS-DEFINITION-FORM.
utils.lisp (file)
Return the symbol of DEFINITION-FORM.
utils.lisp (file)
Return the type of DEFINITION-FORM.
utils.lisp (file)
Expand ANNOT. ARGS will be expanded prior to this form (call-by-value).
expand.lisp (file)
Return a value of NAME class-option of CLASS-DEFINITION-FORM.
utils.lisp (file)
Expand FORM once. The result form won’t be nil.
utils.lisp (file)
Expand FORM until it brecomes normal-form.
utils.lisp (file)
Return non-nil if SYMBOL is a macro.
utils.lisp (file)
Return all values in PLIST named PROP.
utils.lisp (file)
Return t if PLIST contains PROP as a property.
utils.lisp (file)
Return the last form of PROGN-FORM which should be evaluated at last. If macro forms seen, the macro forms will be expanded using MACROEXPAND-UNTIL-NORMAL-FORM.
utils.lisp (file)
Replace the last form of PROGN-FORM with LAST. If LAST is a function, the function will be called with the last form and used for replacing. If macro forms seen, the macro forms will be expanded using MACROEXPAND-UNTIL-NORMAL-FORM.
utils.lisp (file)
Replace the body of FUNCTION-DEFINITION-FORM by calling FUNCTION with name, lambda-list and the body as arguments.
utils.lisp (file)
Replace slot-specifiers of CLASS-DEFINITION-FORM with FUNCTION. The result value will be a class definition form also.
utils.lisp (file)
Return class-specifiers of CLASS-DEFINITION-FORM.
utils.lisp (file)
Previous: Exported definitions, Up: Definitions [Contents][Index]
• Internal macros | ||
• Internal functions |
Next: Internal functions, Previous: Internal definitions, Up: Internal definitions [Contents][Index]
slot.lisp (file)
Previous: Internal macros, Up: Internal definitions [Contents][Index]
std.lisp (file)
syntax.lisp (file)
Expand annotation FORM if possible.
expand.lisp (file)
class.lisp (file)
class.lisp (file)
class.lisp (file)
syntax.lisp (file)
syntax.lisp (file)
slot.lisp (file)
helper.lisp (file)
Previous: Definitions, Up: Top [Contents][Index]
• Concept index | ||
• Function index | ||
• Variable index | ||
• Data type index |
Next: Function index, Previous: Indexes, Up: Indexes [Contents][Index]
Jump to: | C F L M |
---|
Jump to: | C F L M |
---|
Next: Variable index, Previous: Concept index, Up: Indexes [Contents][Index]
Jump to: | %
(
A C D E F G I M N O P R S T |
---|
Jump to: | %
(
A C D E F G I M N O P R S T |
---|
Next: Data type index, Previous: Function index, Up: Indexes [Contents][Index]
Previous: Variable index, Up: Indexes [Contents][Index]
Jump to: | C P S |
---|
Jump to: | C P S |
---|