Next: Introduction, Previous: (dir), Up: (dir) [Contents][Index]
This is the clip Reference Manual, version 0.7.0, generated automatically by Declt version 3.0 "Montgomery Scott" on Tue Dec 22 13:04:13 2020 GMT+0.
• Introduction | What clip is all about | |
• Systems | The systems documentation | |
• Files | The files documentation | |
• Packages | The packages documentation | |
• Definitions | The symbols documentation | |
• Indexes | Concepts, functions, variables and data types |
Clip is an attempt at a templating library that allows you to write templates in a way that is both accessible to direct webdesign and flexible. The main idea is to incorporate transformation commands into an HTML file through tags and attributes. Clip is heavily dependant on Plump and lQuery.
Load Clip through ASDF or Quicklisp.
(ql:quickload :clip)
To process a template, simply call PROCESS
:
(clip:process #p"my-template.ctml")
You may also pass in pure strings or plump nodes. Most likely you will want to include some kind of data in your template. Data in Clip is managed through a central CLIPBOARD
. The additional arguments you pass to PROCESS
are entered into the initial clipboard like a plist (key and value alternating).
Depending on the current tag environment and how the template is processed at the time these values can come into play. Most of the time, entering the name as passed into PROCESS
in the template as an attribute value will then evaluate to the according value using RESOLVE-VALUE
. In the case of a symbol this then delegates to CLIP
, which returns the value stored in the clipboard.
The value returned by PROCESS
is the node you passed into it. You can parse this back into a string using PLUMP:SERIALIZE
or lQuery's WRITE-TO-FILE
.
C:EXPAND
This tag expands its attributes and then calls PROCESS-NODE
on itself again. This is useful to generate attributes to be expanded.C:IF
Looks for either a TEST
attribute or a C:TEST
tag as one of its direct children. If the test as by RESOLVE-VALUE
is non-NIL, all children of the C:THEN
tag are spliced in place of the C:IF
block. Otherwise it looks for C:ELSEIF
blocks and checks their TEST
attributes in turn. The contents of the first block whose TEST
passes is spliced. If none pass, the C:ELSE
child block, if any, is spliced.C:ITERATE
Looks for one attribute called OVER
and then works like the ITERATE
attribute processor using the value of the OVER
attribute.C:LET
Creates a new clipboard environment with all the tag attributes bound in the following manner: The attribute key is put into the clipboard directly and associated with the value of RESOLVE-VALUE
of the attribute value. Acts like SPLICE
.C:NOOP
This tag only processes its attributes, but none of its children.C:SPLICE
Splices all nodes within it into the parent's child list at the position of itself (essentially replacing it with its children).C:UNLESS
Same as WHEN, but inverted.C:USING
Binds the clipboard to the resolved-value of its VALUE
attribute. Acts like SPLICE
.C:WHEN
Looks for a TEST
attribute and if the value of it as by RESOLVE-VALUE
is non-NIL, acts like SPLICE
. Otherwise it removes itself including its children from the DOM.If you specify attributes that are not known on a standard tag, a warning of type UNKNOWN-ATTRIBUTE
is signalled. If you do not specify a required attribute on a standard tag, an error of type MISSING-ATTRIBUTE
is signalled.
AS
Simply changes that node's tag-name to the value of this attribute.COUNT
Inserts the value of *TARGET-COUNT*
as the attribute value. This is useful to follow processing order during debugging.EVAL
Simply calls EVAL
on the value of READ-FROM-STRING
of the attribute value.ITERATE
The value (as by RESOLVE-VALUE
) is used as an iteration list or vector. The first node within the node this attribute belongs to is copied once for each item in the iteration list and processed with that item used as the clipboard.LQUERY
Calls lQuery functions on the node as if by ($ node ..)
. Note that only lQuery functions are available, not its macros.FILL
The attribute value is read as a plist, the keys of which designate other attribute names and the values are resolved to the objects to use. For each named attribute, its value is modified by replacing {thing}
by the result of clip
on the respective object's field thing
.You can define new tag and attribute processors with the macros DEFINE-TAG-PROCESSOR
and DEFINE-ATTRIBUTE-PROCESSOR
. For tag processors you will usually want to make sure to call PROCESS-ATTRIBUTES
and PROCESS-CHILDREN
to ensure that tags and attributes within are properly processed. To retrieve values most of the time you need to use RESOLVE-VALUE
(or its shorthand RESOLVE-ATTRIBUTE
) unless you want to whip up your own system for one reason or another. All tags that you define will automatically be prefixed with C:
in order to help highlighting template tags and ensure that there are no collisions with existing tags.
The Emacs extension Web-Mode(version 9.0.77+) provides syntax highlighting for Clip templates. In order for it to recognise the templates, use the .ctml
file extension. A huge thanks goes to Bois Francois-Xavier for adding the support.
These are short tutorials to help explaining the effects of each tag and to illustrate some basic templating techniques. The examples will only work with Clip>=0.5.1 and lQuery>=3.1.1 .
###Updating a node with values
(clip:process-to-string
"<span lquery=\"(text text) (add-class class)\" />"
:text "Hi!" :class "clip-text")
Explanation: The LQUERY
attribute allows you to perform lQuery operations on the node it is an attribute of. In this case, the TEXT
function sets the text of the node to the value of TEXT
, which we told Clip to be "Hi!"
. Similarly for ADD-CLASS
. Any non-keyword symbol within the template is automatically resolved to a field on the current clipboard. You may think of the clipboard as a form of lexical environment for the template, which we currently set to have the variables TEXT
and CLASS
bound. The default CLIPBOARD
object is special in the sense that it does not differentiate between accessing it with keywords, symbols or strings and is case-insensitive. This makes it easier to access in templates.
Please see the lQuery documentation for all possible node manipulation functions.
(clip:process-to-string
"<ol iterate=\"todo-list\"><li lquery=\"(text *)\"></li></ol>"
:todo-list '("Write tutorials" "Make tiramisu" "Visit grandma"))
The ITERATE
attribute goes over the list or vector of elements its attribute-value resolves to and uses each item as the current clipboard for the iteration element. Since in this case these values themselves are direct strings we cannot retrieve further values from them and instead need to use *
to refer to the entire clipboard.
(clip:process-to-string
"<ul iterate=\"users\">
<li><c:if test=\"anonymous\"><c:then>Username Hidden</c:then><c:else lquery=\"(text username)\"/></c:if></li>
</ul>"
:users '((:username "Some Guy" :anonymous T) (:username "Some Other Guy" :anonymous NIL) (:username "You" :anonymous NIL)))
Clip offers a couple of constructs to perform conditionals. These constructs are C:WHEN
C:UNLESS
and C:IF
, after their CL equivalents. Each take an attribute called TEST
that has to resolve to a non-NIL value to be taken as true. In the case of C:IF
, three special local child tags are used: C:THEN
, C:ELSE
and C:TEST
. The C:TEST
tag can be used as an alternative to the test attribute. The other two should be self-explanatory. Note that none of the child-tags or attributes of an unchosen branch are processed.
(clip:process-to-string
"<c:using value=\"num\">
<c:let orig=\"*\" double=\"(* * 2)\" square=\"(expt * 2)\" root=\"(sqrt *)\">
<span lquery=\"(text (list orig double square root))\" />
</c:let>
</c:using>"
:num 2)
In order to manipulate the clipboard bindings you can use the C:USING
and C:LET
special tags. C:USING
replaces the clipboard environment with what the value of its VALUE
attribute resolves to. C:LET
on the other hand creates a new CLIPBOARD
object, setting the specified symbol/value pairs from its attributes.
(clip:process-to-string
"<ul iterate=\"articles\">
<li><article>
<header><div class=\"author\" lquery=\"(text (** :author))\">AUTHOR</div></header>
<section class=\"content\" lquery=\"(text *)\">CONTENT</section>
</article></li>
</ul>"
:author "Max Mastermind" :articles '("Whoa I am blogging!!" "I don't know what to write, sadface."))
Sometimes you need to refer to values in clipboards outside of the current binding. No worries, this is easy to do as the clipboards are organised using a stack. You can reach clipboards higher up in the stack using the asterisk symbols. Each asterisk more is one clipboard higher. Using the asterisk symbol as a variable returns the clipboard directly, using it as a function call is akin to doing (CLIP ** 'thing)
. In order to avoid clashing with the *
multiplication function, the asterisk function shorthand is only active for two or more asterisks.
(defun seconds () (decode-universal-time (get-universal-time)))
(clip:process-to-string
"<time lquery=\"(text (seconds))\">TIME</time>")
Whenever you require to use functions within clip documents, you need to be aware of the current value of *package*
. As values that are resolved are first parsed using read
, they are influenced by *package*
. You can of course use fully qualified symbol names, but often times it is useful to bind the variable to the package you need to reduce verbosity.
You must also be aware of the special resolving for symbols used as function calls within standard resolvings. As mentioned in the previous section, symbols only consisting of asterisks are specially handled. Additionally, the symbols cl:quote
, cl:function
, cl:or
, cl:and
, cl:if
, cl:when
, and cl:unless
are handled to work like their usual macro/special equivalents. Any other symbol is treated as follows: If a function's symbol with the same symbol-name is externalised from the clip
package, the clip
function is used. If not, the function named by the symbol in the symbol's package is used. This is done so that, no matter your package, you will always have access to functions like clip
and clipboard
. As an unfortunate side-effect of a symbol not knowing whether it was fully qualified or not, this means that even if you use the full symbol name with package in your template, as long as the name is external in clip
, the clip
function is used instead. You will have to use a combination of funcall
and #'
to circumvent this limitation..
Next: Files, Previous: Introduction, Up: Top [Contents][Index]
The main system appears first, followed by any subsystem dependency.
• The clip system |
Nicolas Hafner <shinmera@tymoon.eu>
Nicolas Hafner <shinmera@tymoon.eu>
(:git "https://github.com/shinmera/clip.git")
zlib
An HTML templating engine using Plump.
0.7.0
clip.asd (file)
Files are sorted by type and then listed depth-first from the systems components trees.
• Lisp files |
Next: The clip/package․lisp file, Previous: Lisp files, Up: Lisp files [Contents][Index]
clip.asd
clip (system)
Next: The clip/toolkit․lisp file, Previous: The clip․asd file, Up: Lisp files [Contents][Index]
Next: The clip/conditions․lisp file, Previous: The clip/package․lisp file, Up: Lisp files [Contents][Index]
package.lisp (file)
clip (system)
toolkit.lisp
Next: The clip/clipboard․lisp file, Previous: The clip/toolkit․lisp file, Up: Lisp files [Contents][Index]
toolkit.lisp (file)
clip (system)
conditions.lisp
Next: The clip/attr-processors․lisp file, Previous: The clip/conditions․lisp file, Up: Lisp files [Contents][Index]
conditions.lisp (file)
clip (system)
clipboard.lisp
Next: The clip/tag-processors․lisp file, Previous: The clip/clipboard․lisp file, Up: Lisp files [Contents][Index]
clipboard.lisp (file)
clip (system)
attr-processors.lisp
Next: The clip/processor․lisp file, Previous: The clip/attr-processors․lisp file, Up: Lisp files [Contents][Index]
attr-processors.lisp (file)
clip (system)
tag-processors.lisp
splice-into (function)
Previous: The clip/tag-processors․lisp file, Up: Lisp files [Contents][Index]
tag-processors.lisp (file)
clip (system)
processor.lisp
Next: Definitions, Previous: Files, Up: Top [Contents][Index]
Packages are listed by definition order.
• The clip package |
package.lisp (file)
org.tymoonnext.clip
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 special variables | ||
• Exported macros | ||
• Exported functions | ||
• Exported generic functions | ||
• Exported conditions | ||
• Exported classes |
Next: Exported macros, Previous: Exported definitions, Up: Exported definitions [Contents][Index]
Global registry of attribute processors.
This has to be an EQUALP hash-table with the attribute name as keys and functions that accept two arguments (node attribute-value) as values. Binding this variable can be useful to establish local attributes.
attr-processors.lisp (file)
Template storage stack. When new clipboards are bound, they are pushed onto the stack. Once the binding is left, they are popped off the stack again.
clipboard.lisp (file)
Global registry of tag processors.
This has to be an EQUALP hash-table with the tag name as keys and functions that accept one argument (the node) as values. Binding this variable can be useful to establish local tags.
tag-processors.lisp (file)
This variable is bound to whatever node is currently being processed.
attr-processors.lisp (file)
Next: Exported functions, Previous: Exported special variables, Up: Exported definitions [Contents][Index]
Defines a new attribute processor.
ATTRIBTUE — A symbol or string that matches the attribute to process (case-insensitive)
NODE — The current node is bound to this symbol.
VALUE — The value of the attribute is bound to this symbol.
BODY ::= form*
attr-processors.lisp (file)
Defines a new attribute processor.
TAG — A symbol or string that matches the tag name to process (case-insensitive)
NODE — The node to process is bound to this symbol
BODY ::= form*
tag-processors.lisp (file)
Executes the body with the new clipboard on the *CLIPBOARD-STACK*.
If fields are provided, they are set on the NEW-CLIPBOARD in plist fashion as per consecutive SETF. This means that side-effects of an early field set affect later fields. The fields are evaluated before the NEW-CLIPBOARD is pushed onto the *CLIPBOARD-STACK*.
clipboard.lisp (file)
Next: Exported generic functions, Previous: Exported macros, Up: Exported definitions [Contents][Index]
Returns the processor function for the requested attribute if one is registered. Otherwise returns NIL. See *ATTRIBUTE-PROCESSORS*.
attr-processors.lisp (file)
(setf attribute-processor) (function)
Sets the attribute-processor bound to the given attribute to the specified function. See *ATTRIBUTE-PROCESSORS*.
attr-processors.lisp (file)
attribute-processor (function)
Checks whether the given attribute is present on the node.
If it is, the attribute’s value is returned.
Otherwise, an error of type MISSING-ATTRIBUTE is signalled.
See MISSING-ATTRIBUTE
conditions.lisp (file)
Checks whether there are any unknown attributes present on the node.
If an unknown attribute is present, a warning of type
UNKNOWN-ATTRIBUTE is signalled. Otherwise, NIL is returned.
See UNKNOWN-ATTRIBUTE
conditions.lisp (file)
Checks whether the given attribute is the only attribute on the node.
If it is not present, or not the only one, an error is signalled.
Otherwise, the attribute’s value is returned.
See CHECK-NO-UNKNOWN-ATTRIBUTES
See CHECK-ATTRIBUTE
conditions.lisp (file)
Shorthand for (CLIP (FIRST *CLIPBOARD-STACK*) FIELD)
clipboard.lisp (file)
(setf clipboard) (function)
Shorthand for (SETF (CLIP (FIRST *CLIPBOARD-STACK*) FIELD) VALUE)
clipboard.lisp (file)
clipboard (function)
Creates a new clipboard using the specified fields (like a plist).
clipboard.lisp (file)
If the passed value is a STRING it is parsed using READ-FROM-STRING and subsequently passed to RESOLVE-VALUE. If it is not a string, the value itself is returned.
clipboard.lisp (file)
Processes all clip markup on the target with the given FIELDS used to initialise the clipboard.
processor.lisp (file)
Processes the specified attribute using the given value. If no attribute processor can be found, nothing is done. See *ATTRIBUTE-PROCESSORS*.
attr-processors.lisp (file)
Processes all attributes on the node. See PROCESS-ATTRIBUTE.
attr-processors.lisp (file)
Calls PROCESS-NODE on all childrens of the passed node.
This takes some care to make sure that splicing into the childrens array of the node is possible. However, note that inserting children before the node that is currently being processed will most likely lead to horrors. If such functionality is indeed ever needed (I hope not), this system needs to be rewritten to somehow be able to cope with such scenarios.
tag-processors.lisp (file)
Processes the passed node.
Depending on type the following is done:
PLUMP:ELEMENT PROCESS-TAG is called.
PLUMP:NESTING-NODE PROCESS-CHILDREN is called.
PLUMP:NODE Nothing is done.
T An error is signalled.
Any call to this also increases the *TARGET-COUNTER* regardless of what
is done.
tag-processors.lisp (file)
Processes the specified node as the given tag.
If no tag processor can be found, PROCESS-ATTRIBUTES and PROCESS-CHILDREN is called.
See *TAG-PROCESSORS*.
tag-processors.lisp (file)
Same as PROCESS, but automatically performs PLUMP:SERIALIZE on the result to a string.
processor.lisp (file)
Shorthand to resolve the value of an attibute. See RESOLVE-VALUE.
clipboard.lisp (file)
Returns the processor function for the requested tag if one is registered. Otherwise returns NIL. See *TAG-PROCESSORS*.
tag-processors.lisp (file)
(setf tag-processor) (function)
Sets the tag-processor bound to the given tag-name to the specified function. See *TAG-PROCESSORS*.
tag-processors.lisp (file)
tag-processor (function)
Next: Exported conditions, Previous: Exported functions, Up: Exported definitions [Contents][Index]
Generic object accessor.
If you want to get special treatment of objects or types, define your own methods on this.
clipboard.lisp (file)
(setf clip) (generic function)
Generic slot accessor.
Generic alist or plist accessor.
Generic hash-table accessor.
Accessor for the clipboard object.
Generic object setter.
If you want to get special treatment of objects or types, define your own methods on this.
clipboard.lisp (file)
clip (generic function)
Attempts to resolve the object to a specific value.
This is usually used in combination with READ-FROM-STRING of an attribute value.
clipboard.lisp (file)
Handler for lists, aka function calls.
The function call is decided upon the CAR of the list.
The following cases are handled:
QUOTE Returns the first argument
FUNCTION Returns the symbol-function of the first argument
OR Simulated version of the OR macro.
AND Simulated version of the AND macro.
Otherwise the symbol is looked for in the :CLIP package and then the current *PACKAGE*. If found, the function is applied with all arguments of the list (which are first all individually passed to RESOLVE-VALUE too).
Handler for symbols.
If the symbol is EQL to ’* the *CLIPBOARD* is returned,
If the symbol is a keyword the symbol itself is returned,
otherwise the value of (CLIPBOARD SYMBOL) is returned.
Default fallback for unrecognized objects; simply returns it.
Next: Exported classes, Previous: Exported generic functions, Up: Exported definitions [Contents][Index]
Superclass for all conditions related to problems with a node’s attribute.
See NODE-CONDITION
conditions.lisp (file)
node-condition (condition)
:attribute
Superclass for all conditions related to Clip.
conditions.lisp (file)
condition (condition)
node-condition (condition)
Condition signalled when a required attribute is missing.
See ATTRIBUTE-CONDITION
conditions.lisp (file)
Superclass for all conditions related to problems with a node.
See CLIP-CONDITION
conditions.lisp (file)
clip-condition (condition)
attribute-condition (condition)
:node
Condition signalled when an unknown attribute is present.
See ATTRIBUTE-CONDITION
conditions.lisp (file)
Previous: Exported conditions, Up: Exported definitions [Contents][Index]
Special class for clipboard environments. Use CLIPBOARD or CLIP to access and set values within. Field names are automatically transformed into strings as per STRING. Access is case-insensitive.
clipboard.lisp (file)
standard-object (class)
:env
(make-hash-table :test (quote equalp))
clipboard-env (generic function)
(setf clipboard-env) (generic function)
Previous: Exported definitions, Up: Definitions [Contents][Index]
• Internal special variables | ||
• Internal functions | ||
• Internal generic functions |
Next: Internal functions, Previous: Internal definitions, Up: Internal definitions [Contents][Index]
This counter is upped whenever process-node is called.
attr-processors.lisp (file)
Next: Internal generic functions, Previous: Internal special variables, Up: Internal definitions [Contents][Index]
Returns a space concatenated string of the passed list.
toolkit.lisp (file)
Returns a keyword of the passed name.
toolkit.lisp (file)
attr-processors.lisp (file)
tag-processors.lisp (file)
Previous: Internal functions, Up: Internal definitions [Contents][Index]
automatically generated reader method
clipboard.lisp (file)
automatically generated writer method
clipboard.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 |
---|
Jump to: | C F L |
---|
Next: Variable index, Previous: Concept index, Up: Indexes [Contents][Index]
Jump to: | (
A C D F G M P R S T W |
---|
Jump to: | (
A C D F G M P R S T W |
---|
Next: Data type index, Previous: Function index, Up: Indexes [Contents][Index]
Jump to: | %
*
A N S |
---|
Jump to: | %
*
A N S |
---|
Previous: Variable index, Up: Indexes [Contents][Index]
Jump to: | A C M N P S U |
---|
Jump to: | A C M N P S U |
---|