Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Browse files

Merge pull request #1 from vityok/master

README
  • Loading branch information...
commit dea7b5a713b5180e7b26d48580b4699fbbc19100 2 parents 5221b51 + 71ffc83
@deadtrickster authored
Showing with 95 additions and 103 deletions.
  1. +95 −103 README → README.md
View
198 README → README.md
@@ -1,107 +1,96 @@
-
-======== --------------------
- CL-EMB Embedded Common Lisp
-======== --------------------
+CL-EMB: Embedded Common Lisp
+==============================
A mixture of features from eRuby and HTML::Template. You could name
it "Yet Another LSP" (LispServer Pages) but it's a bit more than that
and not limited to a certain server or text format.
LICENSE
-=======
+-------
+
LLGPL
INSTALL
-=======
+-------
CL-EMB can be installed with ASDF-INSTALL.
See http://weitz.de/asdf-install/ for further information.
USAGE
-=====
+-----
-[generic function]
-EXECUTE-EMB name &key env generator-maker => string
+* *generic function* `EXECUTE-EMB name &key env generator-maker` => `string`
- NAME can be a registered (with REGISTER-EMB) emb code or a pathname
- (type PATHNAME) of a file containing the code. Returns a string.
- Keyword parameter ENV to pass objects to the code. ENV must be a
- plist. ENV can be accessed within your emb code.
- The GENERATOR-MAKER is a function which gets called with a key and value
- from the given ENV and should return a generator function like described on
- http://www.cs.northwestern.edu/academics/courses/325/readings/graham/generators.html
+ `NAME` can be a registered (with `REGISTER-EMB`) emb code or a pathname
+ (type `PATHNAME`) of a file containing the code. Returns a string.
+ Keyword parameter `ENV` to pass objects to the code. `ENV` must be a
+ plist. `ENV` can be accessed within your emb code.
+ The `GENERATOR-MAKER` is a function which gets called with a key and value
+ from the given `ENV` and should return a generator function like described on
+ http://www.cs.northwestern.edu/academics/courses/325/readings/graham/generators.html
-[generic function]
-REGISTER-EMB name code => emb-function
+* *generic function* `REGISTER-EMB name code` => `emb-function`
- Internally registeres given CODE with NAME to be called with
- EXECUTE-EMB. CODE can be a string or a pathname (type PATHNAME) of
- a file containing the code.
+ Internally registeres given `CODE` with `NAME` to be called with
+ `EXECUTE-EMB`. `CODE` can be a string or a pathname (type `PATHNAME`) of
+ a file containing the code.
-[function]
-PPRINT-EMB-FUNCTION name
+* *function* `PPRINT-EMB-FUNCTION name`
- DEBUG function. Pretty prints function form, if *DEBUG* was T
- when the function was registered.
+ DEBUG function. Pretty prints function form, if `*DEBUG*` was `T`
+ when the function was registered.
-[function]
-CLEAR-EMB name
- Remove named emb code.
+* *function* `CLEAR-EMB name`
+ Remove named emb code.
-[function]
-CLEAR-EMB-ALL
- Remove all registered emb code.
+* *function* `CLEAR-EMB-ALL`
+ Remove all registered emb code.
-[function]
-CLEAR-EMB-ALL-FILES
- Remove all registered file emb code (registered/executed by a pathname).
+* *function* `CLEAR-EMB-ALL-FILES`
+ Remove all registered file emb code (registered/executed by a pathname).
-[special variable]
-*EMB-START-MARKER* (default "<%")
+* *special variable* `*EMB-START-MARKER* (default "<%")`
- Start of scriptlet or expression. Remember that a following #\=
- indicates an expression.
+ Start of scriptlet or expression. Remember that a following #\=
+ indicates an expression.
-[special variable]
-*EMB-END-MARKER* (default "%>")
- End of scriptlet or expression.
+* *special variable* `*EMB-END-MARKER* (default "%>")`
+ End of scriptlet or expression.
-[special variable]
-*ESCAPE-TYPE*
+* *special variable* `*ESCAPE-TYPE*`
- Default value for escaping @var output is :RAW
- Can be changed to :XML, :HTML, :URI, :URL, :URL-ENCODE
+ Default value for escaping `@var` output is `:RAW`
+ Can be changed to `:XML`, `:HTML`, `:URI`, `:URL`, `:URL-ENCODE`
-[special variable]
-*FUNCTION-PACKAGE*
+* *special variable* `*FUNCTION-PACKAGE*`
- Package the emb function body gets interned to.
- Default: (find-package :cl-emb-intern)
+ Package the emb function body gets interned to.
+ Default: `(find-package :cl-emb-intern)`
-[special variable]
-*DEBUG*
+* *special variable* `*DEBUG*`
- Debugging mode if T. Default: NIL
+ Debugging mode if `T`. Default: `NIL`
-[special variable]
-*LOCKING-FUNCTION*
+* *special variable* `*LOCKING-FUNCTION*`
- Function to call to lock access to an internal hash table.
- Must accept a function designator which must be called with
- the lock hold.
- IMPORTANT: The locking function must return the value of
- the function it calls!
+ Function to call to lock access to an internal hash table.
+ Must accept a function designator which must be called with
+ the lock hold.
+
+ IMPORTANT: The locking function must return the value of
+ the function it calls!
- Example:
+Example:
+```lisp
(defvar *emb-lock* (kmrcl::make-lock "emb-lock")
"Lock for CL-EMB.")
@@ -111,7 +100,7 @@ CLEAR-EMB-ALL-FILES
(funcall func)))
(setf emb:*locking-function* 'emb-lock-function)
-
+```
Files get cached and reread when they change.
@@ -120,18 +109,18 @@ format) and special tags you know from eRuby or JSP (JavaServer Pages)
which can hold Common Lisp or CL-EMB's template tags, perhaps
comparable to JSP's taglib.
-<% ... %> is a scriptlet tag, and wraps
- Common Lisp code.
+`<% ... %>` is a scriptlet tag, and wraps Common Lisp code.
-<%= ... %> is an expression tag. Its content gets evaluated and fed as
- a parameter to (FORMAT T "~A" ...).
+`<%= ... %>` is an expression tag. Its content gets evaluated and fed as
+ a parameter to `(FORMAT T "~A" ...)`.
-<%# ... #%> is a comment. Everything within will be removed/ignored.
+`<%# ... #%>` is a comment. Everything within will be removed/ignored.
Can't be nested!
Examples:
---------
+```lisp
CL-USER> (asdf:oos 'asdf:load-op :cl-emb)
CL-USER> (cl-emb:register-emb "test1"
"10 stars: <% (dotimes (i 10) %>*<% ) %>")
@@ -151,87 +140,88 @@ CL-USER> (let ((emb:*emb-start-marker* "<?emb")
#<CL-EMB::EMB-FUNCTION {97BEFD9}>
CL-USER> (emb:execute-emb "marker-test")
"42 + 42 = 84"
-
+```
Template Tags
-------------
You can use special template tags instead of Common Lisp code between
-<% and %>. This will be translated to Common Lisp and serves as a
+`<%` and `%>`. This will be translated to Common Lisp and serves as a
simple shortcut for you.
And more important: It's easier to use for non-programmers. A designer
can work on HTML code and insert these simple template tags.
-Template tags start with @.
+Template tags start with `@`.
Currently supported:
-@if, @else, @endif, @unless, @endunless, @var, @repeat, @endrepeat,
-@loop, @endloop, @include, @call, @with, @endwith, @set, @genloop,
-@endgenloop, @insert
+`@if`, `@else`, `@endif`, `@unless`, `@endunless`, `@var`, `@repeat`, `@endrepeat`,
+`@loop`, `@endloop`, `@include`, `@call`, `@with`, `@endwith`, `@set`, `@genloop`,
+`@endgenloop`, `@insert`
-@if and @unless check if the given parameter is set in the
-supplied environment (parameter ENV of EXECUTE-EMB). The
+`@if` and `@unless` check if the given parameter is set in the
+supplied environment (parameter `ENV` of `EXECUTE-EMB`). The
environment is a plist with keyword + value pairs. Must be terminated
-with @endif or @endunless.
+with `@endif` or `@endunless`.
-@var emits the corresponding value from the environment. Uses the
+`@var` emits the corresponding value from the environment. Uses the
escape type defined in *ESCAPE-TYPE* (Default :raw, no escaping) or
-with -escape modifier. E. g. <% @var foo -escape xml %>
-or without modifier <% @var foo %>
+with -escape modifier. E. g. `<% @var foo -escape xml %>`
+or without modifier `<% @var foo %>`
Supported escaping: raw, xml (aka html), uri (aka url or url-encode)
-@insert inserts a given (text) file. Parameter from the environment.
-E. g. <% @insert textfile %>
+`@insert` inserts a given (text) file. Parameter from the environment.
+E. g. `<% @insert textfile %>`
-@repeat repeats everything between it and @endrepeat the given times.
+`@repeat` repeats everything between it and `@endrepeat` the given times.
Parameter can be a number or a name. The name will be used to lookup
the corresponding value from the environment.
-@loop loops over a named list in the environment. Environment
+`@loop` loops over a named list in the environment. Environment
gets set to current plist inside this list. Must be terminated with
-@endloop.
+`@endloop`.
-@include includes a given file. Relative to current template.
+`@include` includes a given file. Relative to current template.
-@call calls a given emb-function, which was registered with REGISTER-EMB
+`@call` calls a given emb-function, which was registered with REGISTER-EMB
-@with is similar to @loop as it sets the current environment to the named
-plist. @loop needs a list of plists and @with just a plist associated to
-the given name. Block ends in @endwith.
+`@with` is similar to @loop as it sets the current environment to the named
+plist. `@loop` needs a list of plists and @with just a plist associated to
+the given name. Block ends in `@endwith`.
-@set is used to set special variables like *ESCAPE-TYPE* from within a
+`@set` is used to set special variables like `*ESCAPE-TYPE*` from within a
emb code. This way a default for a file can be specified in the file
itself. The variables are changed for the current and called/included code.
Changes to the variables in called/included code don't effect the caller/
-includer. E. g. <% @set escape=uri %>
+includer. E. g. `<% @set escape=uri %>`
Currently supported: escape (raw, xml, html, url, uri, url-encode)
-@genloop starts a special kind of loop: a generator loop. It must be
-terminated by @endgenloop and operates on a generator returned by the
-given GENERATOR-MAKER (see EXECUTE-EMB). The GENERATOR-MAKER gets called
-with two parameters: the key (which is the argument to @genloop) and the
+`@genloop` starts a special kind of loop: a generator loop. It must be
+terminated by `@endgenloop` and operates on a generator returned by the
+given `GENERATOR-MAKER` (see `EXECUTE-EMB`). The `GENERATOR-MAKER` gets called
+with two parameters: the key (which is the argument to `@genloop`) and the
corresponding value in the plist. Each time in the loop the generator is
-called first with the parameter :TEST to see if there's data left.
-The generator must return a plist on :NEXT, which will be the current
-ENV (like @with or within a normal @loop).
+called first with the parameter `:TEST` to see if there's data left.
+The generator must return a plist on `:NEXT`, which will be the current
+`ENV` (like `@with` or within a normal `@loop`).
The parameters which access the environment can just be the name of a
-keyword symbol in the plist. foo -> :FOO in (:FOO "bar")
+keyword symbol in the plist. foo -> `:FOO` in `(:FOO "bar")`
Or you can provide a path within a nested plist structure by dividing the
-parts of the path with a slash. foo/bar -> Value of :BAR inside the
-plist at :FOO. (:FOO (:BAR "yeah")) -> "yeah"
+parts of the path with a slash. foo/bar -> Value of `:BAR` inside the
+plist at `:FOO`. `(:FOO (:BAR "yeah"))` -> "`yeah`"
Starting the parameter with a slash lets it traverse the nested plists
from the top. That way you can access top values inside loops.
-Writing "<% @var foo/bar/quux %>" can be translated to
-(GETF (GETF (GETF ENV :FOO) :BAR) :QUUX)
+Writing "`<% @var foo/bar/quux %>`" can be translated to
+`(GETF (GETF (GETF ENV :FOO) :BAR) :QUUX)`
Examples:
---------
+```lisp
CL-USER> (cl-emb:register-emb "test1"
"Foo: <% @if foo %>Yes!<% @else %>No!<% @endif %>")
#<CL-EMB::EMB-FUNCTION {9C0F2D1}>
@@ -327,10 +317,11 @@ CL-USER> (emb:register-emb "test13" "The file:<pre><% @insert textfile %></pre>"
CL-USER> (emb:execute-emb "test13" :env '(:textfile "/etc/gentoo-release"))
"The file:<pre>Gentoo Base System version 1.6.14
</pre>"
-
+```
CREDITS
=======
+
Uses code from John Wiseman. See http://lemonodor.com/archives/000128.html
and lsp-LICENSE.txt
Thanks to Edi Weitz for letting me use his code for ESCAPE-FOR-XML.
@@ -338,4 +329,5 @@ Thanks to Edi Weitz for letting me use his code for ESCAPE-FOR-XML.
AUTHOR
======
+
Stefan Scholl <stesch@no-spoon.de>
Please sign in to comment.
Something went wrong with that request. Please try again.