This is the architecture.builder-protocol Reference Manual, version 0.11.0, generated automatically by Declt version 4.0 beta 2 "William Riker" on Sun Dec 15 04:16:51 2024 GMT+0.
architecture.builder-protocol/architecture.builder-protocol.asdarchitecture.builder-protocol/code/package.lisparchitecture.builder-protocol/code/util.lisparchitecture.builder-protocol/code/variables.lisparchitecture.builder-protocol/code/protocol.lisparchitecture.builder-protocol/code/macros.lisparchitecture.builder-protocol/code/mixins.lisparchitecture.builder-protocol/code/list-builder.lisparchitecture.builder-protocol/code/top-down-forcing-builder.lispThe main system appears first, followed by any subsystem dependency.
architecture.builder-protocolProtocol and framework for building parse results and other object graphs.
Jan Moringen <jmoringe@techfak.uni-bielefeld.de>
Jan Moringen <jmoringe@techfak.uni-bielefeld.de>
LGPLv3
0.11.0
alexandria (system).
code (module).
Modules are listed depth-first from the system components tree.
architecture.builder-protocol/codearchitecture.builder-protocol (system).
package.lisp (file).
util.lisp (file).
variables.lisp (file).
protocol.lisp (file).
macros.lisp (file).
mixins.lisp (file).
list-builder.lisp (file).
top-down-forcing-builder.lisp (file).
Files are sorted by type and then listed depth-first from the systems components trees.
architecture.builder-protocol/architecture.builder-protocol.asdarchitecture.builder-protocol/code/package.lisparchitecture.builder-protocol/code/util.lisparchitecture.builder-protocol/code/variables.lisparchitecture.builder-protocol/code/protocol.lisparchitecture.builder-protocol/code/macros.lisparchitecture.builder-protocol/code/mixins.lisparchitecture.builder-protocol/code/list-builder.lisparchitecture.builder-protocol/code/top-down-forcing-builder.lisparchitecture.builder-protocol/architecture.builder-protocol.asdarchitecture.builder-protocol (system).
architecture.builder-protocol/code/package.lispcode (module).
architecture.builder-protocol/code/util.lisppackage.lisp (file).
code (module).
cardinality-case (macro).
cardinality-ecase (macro).
normalize-relation (function).
%map-pattern (type).
expand-cardinality-case (function).
architecture.builder-protocol/code/variables.lisputil.lisp (file).
code (module).
*builder* (special variable).
architecture.builder-protocol/code/protocol.lispvariables.lisp (file).
code (module).
add-relations (function).
add-relations* (function).
builder-visit-function (generic function).
finish (generic function).
finish* (function).
finish-node (generic function).
finish-node* (function).
make+finish-node (function).
make+finish-node* (function).
make+finish-node+relations (function).
make+finish-node+relations* (function).
make-node (generic function).
make-node* (function).
node-initargs (generic function).
node-initargs* (function).
node-kind (generic function).
node-kind* (function).
node-relation (generic function).
node-relation* (function).
node-relations (generic function).
node-relations* (function).
peeking (function).
peeking (structure).
prepare (generic function).
prepare* (function).
relate (generic function).
relate* (function).
relation-cardinality (type).
target (generic reader).
walk-nodes (generic function).
walk-nodes* (function).
wrap (generic function).
wrap* (function).
%walk-nodes (function).
make-keyword-arguments (function).
peeking-peeking-function (reader).
peeking-walk-function (reader).
architecture.builder-protocol/code/macros.lispprotocol.lisp (file).
code (module).
call-with-builder (function).
call-with-unbuilder (function).
node (macro).
node* (macro).
with-builder (macro).
with-unbuilder (macro).
%expand-with-builder (function).
%install-with-builder-docstring (function).
architecture.builder-protocol/code/mixins.lispmacros.lisp (file).
code (module).
delaying-mixin (class).
delegating-mixin (class).
finish (method).
finish (method).
finish-node (method).
forwarding-mixin (class).
make-node (method).
make-node (method).
node-initargs (method).
node-kind (method).
node-relation (method).
node-relations (method).
order-forcing-mixin (class).
prepare (method).
relate (method).
relate (method).
target (reader method).
walk-nodes (method).
wrap (method).
%target (reader method).
(setf %target) (writer method).
argumented (structure).
argumented-arguments (reader).
delayed-node (structure).
delayed-node-arguments (function).
delayed-node-kind (reader).
delayed-node-p (function).
delayed-node-relations (reader).
(setf delayed-node-relations) (writer).
delayed-relation (structure).
delayed-relation-arguments (function).
delayed-relation-kind (reader).
delayed-relation-node (reader).
delayed-relation-p (function).
make-delayed-node (function).
make-delayed-relation (function).
architecture.builder-protocol/code/list-builder.lispmixins.lisp (file).
code (module).
finish-node (method).
make-node (method).
node-initargs (method).
node-kind (method).
node-relation (method).
node-relations (method).
relate (method).
relate (method).
architecture.builder-protocol/code/top-down-forcing-builder.lisplist-builder.lisp (file).
code (module).
builder-visit-function (method).
top-down-forcing-builder (class).
Packages are listed by definition order.
architecture.builder-protocolThis package contains the build and "un-build" protocols.
The build protocol consists of two groups of generic functions
1. ‘prepare’, ‘finish’ and ‘wrap’
2. ‘make-node’, ‘finish-node’ and ‘relate’
and the special variable ‘*builder*’.
All of the above functions take an explicit builder argument which
is usually the value of ‘*builder*’ .The convenience functions
‘prepare*’, ‘finish*’, ‘wrap*’, ‘make-node*’, ‘finish-node*’ and
‘relate*’ lack the builder argument and use the value of
‘*builder*’ automatically.
Further convenience functions ‘make+finish-node[*]’,
‘make+finish-node+relation[*]’ and macros ‘node[*]’ combine common
idioms involving the above functions into a single function or
macro respectively.
For construction of an object graph, a client binds
‘*builder*’ (for example via ‘with-builder’) to an object of the
client’s choice for which methods on the above protocol generic
functions exist and calls the object graph constructing
code (e.g. a parser). This way, the client can obtain different
representations by supplying different builders and the object
graph construction code does not have to know the concrete
representation of the result it constructs.
This package also contains a builder for constructing list-based
representations which are useful for debugging and unit
tests. This builder can be selected by binding ‘*builder*’ to the
symbol ‘cl:list’.
alexandria.
common-lisp.
*builder* (special variable).
add-relations (function).
add-relations* (function).
builder-visit-function (generic function).
call-with-builder (function).
call-with-unbuilder (function).
cardinality-case (macro).
cardinality-ecase (macro).
delaying-mixin (class).
delegating-mixin (class).
finish (generic function).
finish* (function).
finish-node (generic function).
finish-node* (function).
forwarding-mixin (class).
make+finish-node (function).
make+finish-node* (function).
make+finish-node+relations (function).
make+finish-node+relations* (function).
make-node (generic function).
make-node* (function).
node (macro).
node* (macro).
node-initargs (generic function).
node-initargs* (function).
node-kind (generic function).
node-kind* (function).
node-relation (generic function).
node-relation* (function).
node-relations (generic function).
node-relations* (function).
normalize-relation (function).
order-forcing-mixin (class).
peeking (function).
peeking (structure).
prepare (generic function).
prepare* (function).
relate (generic function).
relate* (function).
relation-cardinality (type).
target (generic reader).
top-down-forcing-builder (class).
walk-nodes (generic function).
walk-nodes* (function).
with-builder (macro).
with-unbuilder (macro).
wrap (generic function).
wrap* (function).
%expand-with-builder (function).
%install-with-builder-docstring (function).
%map-pattern (type).
%target (generic reader).
(setf %target) (generic writer).
%walk-nodes (function).
argumented (structure).
argumented-arguments (reader).
delayed-node (structure).
delayed-node-arguments (function).
delayed-node-kind (reader).
delayed-node-p (function).
delayed-node-relations (reader).
(setf delayed-node-relations) (writer).
delayed-relation (structure).
delayed-relation-arguments (function).
delayed-relation-kind (reader).
delayed-relation-node (reader).
delayed-relation-p (function).
expand-cardinality-case (function).
make-delayed-node (function).
make-delayed-relation (function).
make-keyword-arguments (function).
peeking-peeking-function (reader).
peeking-walk-function (reader).
Definitions are sorted by export status, category, package, and then by lexicographic order.
Stores the builder object which should be used for constructing the result.
Execute the clause in CLAUSES which corresponds to the value of
CARDINALITY.
CARDINALITY is evaluated and the resulting value is used to select
a clause.
Elements of CLAUSES are of the form
(CARDINALITY-DESIGNATOR-OR-LIST &body BODY)
where CARDINALITY-DESIGNATOR-OR-LIST is either
1. One of the cardinality designators 1, ?, *, ‘:map’
A clause of this form matches if CARDINALITY evaluates to the specified cardinality designator or if CARDINALITY evaluates to (:map SOME-KEY) and CARDINALITY-DESIGNATOR-OR-LIST is ‘:map’.
2. A list of some of the cardinality designators mentioned above
A clause of this form matches if CARDINALITY evaluates to any of
the cardinality designators mentioned in
CARDINALITY-DESIGNATOR-OR-LIST or if CARDINALITY evaluates
to (:map SOME-KEY) and ‘:map’ is an element of
CARDINALITY-DESIGNATOR-OR-LIST.
3. An expression of the form (:map . KEY-VAR)
A clause of this form matches if the value of CARDINALITY is of the form (:map . SOME-KEY). During the evaluation of the BODY of the clause, KEY-VAR will be bound to SOME-KEY.
Like ‘cardinality-case’ but signal a compile-time error if CLAUSES does not handle all cardinalities.
Use BUILDER to create a KIND, INITARGS node, relate it via RELATIONS.
BUILDER, KIND and INITARGS are evaluated and passed to ‘make-node’.
RELATIONS is a list of relation specifications of the form accepted
by ‘make+finish-node+relations’.
‘finish-node’ is called on the created node. The created node is
returned.
Example:
(node (:operator :which ’+)
(* :operand (list left right)))
Like ‘node’ but uses ‘*builder*’ instead of accepting a builder parameter.
Execute BODY with a builder binding according to SPEC.
SPEC is either
(BUILDER-VAR BUILDER-FORM)
During the evaluation of BODY, BUILDER-VAR is bound to
the result of evaluating BUILDER-FORM.
(BUILDER-FORM)
Before the evaluation of BODY, BUILDER-FORM is evaluated, but
the constructed builder is only accessible through the
‘*builder*’ special variable.
Note that during the evaluation of BODY the special variable ‘*builder*’ is usually bound to the builder constructed by BUILDER-FORM (depending on methods on ‘prepare’ and ‘wrap’).
Execute BODY with a builder binding according to SPEC.
SPEC is either
(BUILDER-VAR BUILDER-FORM)
During the evaluation of BODY, BUILDER-VAR is bound to
the result of evaluating BUILDER-FORM.
(BUILDER-FORM)
Before the evaluation of BODY, BUILDER-FORM is evaluated, but the constructed builder is only accessible through the ‘*builder*’ special variable.
Use BUILDER to add relations according to RELATIONS to NODE.
RELATIONS is a list of relation specifications of the form
(CARDINALITY RELATION-NAME RIGHT &rest ARGS)
which are translated into ‘relate’ calls in which NODE is the
"left" argument to ‘relate’. CARDINALITY has to be of type
‘relation-cardinality’ and is interpreted as follows:
? RIGHT is a single node or ‘nil’. If RIGHT is ‘nil’,
‘relate’ is not called.
1 RIGHT is a single node.
* RIGHT is a (possibly empty) sequence of nodes. ARGS
must be of the form
:KEY₁ (VALUE₁₁ VALUE₁₂ …) :KEY₂ (VALUE₂₁ VALUE₂₂ …) …
. The ‘relate’ call for the k-th element of RIGHT will
receive the keyword arguments
:KEY₁ VALUEₖ₁ :KEY₂ VALUEₖ₂ …. If the value list for a
given key would be a repetition of a particular value
VALUE, the circular list #1=(VALUE . #1#) may be used
as a replacement for that value list.
(:map . KEY) RIGHT is a (possible empty) sequence of nodes that
should be "zipped" with a sequence of keys (see
below) to form a set of key-values pair and thus a
map. The sequence of keys is the value of the property
whose indicator is KEY in the ARGS plist. The two
sequences must be of the same length. Elements at
corresponding positions will be paired in a
"zipping" operation as described above.
RELATION-NAME does not have to be unique across the elements of
RELATIONS. This allows multiple "right" nodes to be related to
NODE via a given RELATION-NAME with CARDINALITY * in multiple
RELATIONS entries, potentially with different ARGS.
The modified NODE or a new node is returned.
Like ‘add-relations’ but uses ‘*builder*’ instead of accepting a builder parameter.
Like ‘finish’ but uses ‘*builder*’ instead of accepting a builder parameter.
Like ‘finish-node’ but uses ‘*builder*’ instead of accepting a builder parameter.
Convenience function for constructing and immediately finishing a node.
Like ‘make+finish-node’ but uses ‘*builder*’ instead of accepting a builder parameter.
Use BUILDER to create a KIND, INITARGS node, relate it via RELATIONS.
RELATIONS is processed as described for ‘add-relations’.
‘finish-node’ is called on the created node. The created node is returned.
Like ‘make+finish-node+relations’ but uses ‘*builder*’ instead of accepting a builder parameter.
Like ‘make-node’ but uses ‘*builder*’ instead of accepting a builder parameter.
Like ‘node-initargs’ but uses ‘*builder*’ instead of accepting a builder parameter.
Like ‘node-kind’ but uses ‘*builder*’ instead of accepting a builder parameter.
Like ‘node-relation’ but uses ‘*builder*’ instead of accepting a builder parameter.
Like ‘node-relations’ but uses ‘*builder*’ instead of accepting a builder parameter.
Return two values: 1) the relation kind of RELATION 2) the
cardinality of RELATION.
RELATION can be of the form RELATION-KIND or (RELATION-KIND . CARDINALITY) where CARDINALITY is of type ‘relation-cardinality’.
Like ‘prepare’ but uses ‘*builder*’ instead of accepting a builder parameter.
Like ‘relate’ but uses ‘*builder*’ instead of accepting a builder parameter.
Like ‘walk-nodes’ but uses ‘*builder*’ instead of accepting a builder parameter.
Like ‘wrap’ but uses ‘*builder*’ instead of accepting a builder parameter.
Return a function to apply to the delayed nodes constructed by BUILDER.
The function is called with the root of the tree of ‘delayed-node’s.
top-down-forcing-builder)) ¶Finalize and return VALUES produced by BUILDER as multiple values.
VALUES is a list of objects that should be returned as multiple
values and constitute the overall result of an object tree
construction with BUILDER. The first element of VALUES which
becomes the first return value is the constructed tree
itself (which often coincides with the root node). Additional
values are optional and their presence and meaning depend on
BUILDER.
The default method just returns VALUES.
order-forcing-mixin) (result cons)) ¶forwarding-mixin) result) ¶cons)) ¶Use BUILDER to perform finalization for NODE.
Return the modified NODE or an appropriate newly created object.
(eql list)) kind node) ¶forwarding-mixin) kind node) ¶Use BUILDER to make a result tree node of kind KIND and return it.
As a convention, when supplied, the value of the :bounds keyword argument is of the form (START . END) and can be used to indicate the input range for which the tree is constructed.
(eql list)) kind &rest initargs &key) ¶delaying-mixin) kind &rest initargs &key) ¶forwarding-mixin) kind &rest initargs &key &allow-other-keys) ¶Return a plist of initargs for NODE w.r.t. BUILDER.
The returned list is EQUAL to the list of keyword arguments pass to the MAKE-NODE call that, using BUILDER, constructed NODE.
(eql list)) (node cons)) ¶forwarding-mixin) node) ¶Return the kind of NODE w.r.t. BUILDER.
The return value is EQ to the KIND argument used to create NODE with BUILDER.
(eql list)) (node cons)) ¶forwarding-mixin) node) ¶Return two values: 1) a single node or a sequence of nodes related to
NODE via RELATION w.r.t. BUILDER 2) ‘nil’ or a same-length
sequence of arguments of the relations.
RELATION must be of one of the forms
RELATION-NAME
(RELATION-NAME . CARDINALITY)
where RELATION-NAME names the relation and CARDINALITY is of type
‘relation-cardinality’. The second form is accepted for
convenience so that, for example, relation descriptions returned
by ‘node-relations’ can be used as arguments to this
function. CARDINALITY is not processed by this function except
that a ‘type-error’ may be signaled if CARDINALITY is not of type
‘relation-cardinality’.
If the cardinality of RELATION is 1 or ‘?’, the first return value
is a single node. Otherwise the first return value is a sequence
of nodes. Again, note that the cardinality of RELATION here refers
to the actual cardinality as known by BUILDER, not information
encoded in RELATION by the caller supplying RELATION
as (RELATION-NAME . CARDINALITY).
Each element in the sequence of relation arguments is EQUAL to the list of arguments passed to the RELATE call that, using BUILDER, established the relation between NODE and the related node.
(eql list)) relation (node cons)) ¶forwarding-mixin) relation node) ¶cons) node) ¶Return a list of relations of NODE w.r.t. BUILDER.
Each relation is of one of the forms
RELATION-NAME
(RELATION-NAME . CARDINALITY)
where RELATION-NAME names the relation and CARDINALITY is of type
‘relation-cardinality’. When the first form is used,
i.e. CARDINALITY is not present, it is assumed to be
‘*’. CARDINALITY values are interpreted as follows:
? The relation designated by RELATION-NAME with NODE
as the "left" node has zero or one "right"
nodes.
1 The relation designated by RELATION-NAME with NODE
as the "left" node has exactly one "right"
node.
* The relation designated by RELATION-NAME with NODE
as the "left" node has zero or more "right"
nodes.
(:map . KEY) The relation designated by RELATION-NAME with NODE
as the "left" node has zero or more "right"
nodes with the additional constraint that the
relation parameters for each such node must contain
a unique value for the key KEY.
. This cardinality information is reflected by the return values of (node-relation BUILDER RELATION-NAME NODE).
(eql list)) (node cons)) ¶forwarding-mixin) node) ¶Prepare BUILDER for result construction, return a builder.
The default method just returns BUILDER.
forwarding-mixin)) ¶Establish RELATION between nodes LEFT and RIGHT and return the
resulting modified LEFT node (or an appropriate newly created
object).
ARGS can be used to supply additional information about the
relation that is available from neither LEFT nor RIGHT.
In a typical case, RELATION could be :child, LEFT being the parent node and RIGHT being the child node.
(eql list)) relation left (right null) &key) ¶(eql list)) relation left right &rest args &key) ¶delaying-mixin) relation left right &rest args &key) ¶forwarding-mixin) relation left right &rest args &key &allow-other-keys) ¶null) &key) ¶cons) left right &key) ¶Return the builder to which BUILDER delegates.
delegating-mixin)) ¶Stores the builder to which ‘make-node’, ‘relate’, etc. calls should be delegated.
Call FUNCTION on nodes of the tree ROOT constructed by BUILDER.
Return whatever FUNCTION returns when called for ROOT.
The lambda-list of FUNCTION must be compatible to
(recurse relation relation-args node kind relations
&rest initargs)
where RELATION and RELATION-ARGS are the relation and its
arguments connecting NODE to the previously visited node,
NODE is the node currently being visited,
KIND is the kind returned by ‘node-kind’ for BUILDER and NODE.
RELATIONS are the relations returned by ‘node-relations’ for
BUILDER and NODE.
INITARGS are the initargs returned by ‘node-initargs’ for BUILDER
and NODE.
RECURSE is a function with the lambda-list
(&key relations function)
that can be called, optionally with a list of relations, to
traverse the nodes related to NODE by that relation. If a list of
relations is not supplied via the :relations keyword parameter,
all relations are traversed. The :function keyword parameter
allows performing the traversal with a different function instead
of FUNCTION. Calls of this function return a list of elements each
of which is the result for the corresponding element of
RELATIONS. The result for a relation is either the return value of
FUNCTION if the cardinality of the relation is 1 or ? or a list of
such return values if the cardinality is * or :map.
If FUNCTION is an instance of ‘peeking’, call the "peeking"
function stored in FUNCTION before the ordinary walk
function (also stored in FUNCTION) is called. The lambda-list of
the "peeking" function must be compatible to
(builder relation relation-args node)
(i.e. it does not receive kind, initargs or relations). This
function can control whether NODE should be processed normally,
replaced with something else, processed with a different builder
or ignored: Its return values are interpreted as follows:
NIL
Forego processing of NODE, in particular do not call
‘node-kind’, ‘node-relations’, ‘node-initargs’ or the walk
function for NODE.
T [* * * BUILDER]
Continue processing as if there was no "peeking" function.
If non-NIL, BUILDER specifies a builder that should be used
instead of the current builder to process the NODE and its
ancestors.
INSTEAD KIND INITARGS RELATIONS [BUILDER]
Continue processing as if NODE had been replaced by INSTEAD and
builder had returned KIND, INITARGS and RELATIONS. In particular
do not call ‘node-kind’, ‘node-relations’, ‘node-initargs’ for
NODE.
If non-NIL, BUILDER specifies a builder that should be used
instead of the current builder to process INSTEAD and its
ancestors.
Depending on FUNCTION, potentially return a list-of-lists of the same shape as the traversed tree containing return values of FUNCTION.
forwarding-mixin) function root) ¶function) root) ¶Call THUNK with an appropriate dynamic environment for BUILDER.
A method on this generic function could, for example, bind special
variables around the construction of a result object tree.
The existing default methods do not specialize the BUILDER parameter and specialize the THUNK parameter to ‘cl:function’ and ‘cl:symbol’. These default methods just call THUNK.
forwarding-mixin) function) ¶symbol)) ¶function)) ¶Allows specifying a peeking function in conjunction with the walk function.
This class is intended to be mixed into builder classes that have to construct a tree of delayed nodes before doing their respective actual processing.
Intended to be mixed into builder classes that delegate certain operations to a "target" builder.
| Initarg | Value |
|---|---|
:target | (error ~@<missing required initarg for class ~s: ~s.~@:> (quote delegating-mixin) target) |
Stores the builder to which ‘make-node’, ‘relate’, etc. calls should be delegated.
:target
Intended to be mixed into builder classes that delegate all operations to a "target" builder.
This class is intended to be mixed into builder classes that have
to process nodes in a particular order.
In combination with ‘delaying-mixin’, this makes the builder independent of the order of the original ‘make-node’ and ‘relate’ calls.
This builder can act as a proxy for other builders which require nodes to be created from the root downward.
Cardinality of a relation between nodes.
? Zero or one "right" nodes can be related to the
"left" node.
1 Exactly one "right" node is related to the "left"
node.
* Zero or more "right" nodes can be related to the
"left" node.
(:map . KEY) Zero or more "right" nodes can be related to the
left node with the additional constraint that the
relation parameters for each such node must contain a
unique value for the key KEY.
See ‘relate’ for "left" and "right" node roles.
delegating-mixin)) ¶delegating-mixin)) ¶Stores the builder to which ‘make-node’, ‘relate’, etc. calls should be delegated.
structure-object.
list
This slot is read-only.
| Jump to: | %
(
A B C D E F G M N P R T W |
|---|
| Jump to: | %
(
A B C D E F G M N P R T W |
|---|
| Jump to: | *
A K N P R S T W |
|---|
| Jump to: | *
A K N P R S T W |
|---|
| Jump to: | %
A C D F L M O P R S T U V |
|---|
| Jump to: | %
A C D F L M O P R S T U V |
|---|