The cl-why Reference Manual

Table of Contents

Next: , Previous: , Up: (dir)   [Contents][Index]

The cl-why Reference Manual

This is the cl-why Reference Manual, version 1.1.4, generated automatically by Declt version 2.4 "Will Decker" on Wed Jun 20 11:27:50 2018 GMT+0.


Next: , Previous: , Up: Top   [Contents][Index]

1 Introduction

cl-why

(X)HTML generation macros, fork of CL-WHO

Reason behind CL-WHY

This project is intended as an improvement over CL-WHO, a Common Lisp library for HTML generation.

I develop this fork because while a tree DSL is an elegant way to construct HTML documents, I disagree with some ideas of the original specification.

One particular problem with CL-WHO is about escaping: values are not escaped unless it is explicitly demanded. On the contrary, the values should be written escaped by default and raw by exception; it reduces the probability of making mistakes and helps to ensure creating well-formed documents.

Installing

Download CL-WHY in a path recognized by Quicklisp and execute the following command.

(ql:quickload '#:cl-why)

Differences

The usage of CL-WHY is largely similar to CL-WHO whose documentation is located here.

Instead of a complete documentation I make a list of differences between these two libraries.


Next: , Previous: , Up: Top   [Contents][Index]

2 Systems

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


Previous: , Up: Systems   [Contents][Index]

2.1 cl-why

Author

JP Cimalando

License

BSD

Description

(X)HTML generation macros

Version

1.1.4

Source

cl-why.asd (file)

Components

Next: , Previous: , Up: Top   [Contents][Index]

3 Files

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


Previous: , Up: Files   [Contents][Index]

3.1 Lisp


Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.1 cl-why.asd

Location

cl-why.asd

Systems

cl-why (system)


Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.2 cl-why/packages.lisp

Parent

cl-why (system)

Location

packages.lisp

Packages

cl-why


Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.3 cl-why/specials.lisp

Dependency

packages.lisp (file)

Parent

cl-why (system)

Location

specials.lisp

Exported Definitions
Internal Definitions

Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.4 cl-why/util.lisp

Dependency

specials.lisp (file)

Parent

cl-why (system)

Location

util.lisp

Exported Definitions
Internal Definitions

Previous: , Up: Lisp files   [Contents][Index]

3.1.5 cl-why/why.lisp

Dependency

util.lisp (file)

Parent

cl-why (system)

Location

why.lisp

Exported Definitions
Internal Definitions

Next: , Previous: , Up: Top   [Contents][Index]

4 Packages

Packages are listed by definition order.


Previous: , Up: Packages   [Contents][Index]

4.1 cl-why

Source

packages.lisp (file)

Nickname

why

Use List

common-lisp

Exported Definitions
Internal Definitions

Next: , Previous: , Up: Top   [Contents][Index]

5 Definitions

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


Next: , Previous: , Up: Definitions   [Contents][Index]

5.1 Exported definitions


Next: , Previous: , Up: Exported definitions   [Contents][Index]

5.1.1 Special variables

Special Variable: *attribute-quote-char*

Quote character for attributes.

Package

cl-why

Source

specials.lisp (file)

Special Variable: *downcase-tokens-p*

If NIL, a keyword symbol representing a tag or attribute name will not be automatically converted to lowercase. This is useful when one needs to output case sensitive XML.

Package

cl-why

Source

specials.lisp (file)

Special Variable: *escape-char-p*

Used by ESCAPE-STRING to test whether a character should be escaped.

Package

cl-why

Source

specials.lisp (file)

Special Variable: *html-empty-tag-aware-p*

Set this to NIL to if you want to use CL-WHY as a strict XML generator. Otherwise, CL-WHY will only write empty tags listed in *HTML-EMPTY-TAGS* as <tag/> (XHTML mode) or <tag> (SGML mode and HTML5 mode). For all other tags, it will always generate <tag></tag>.

Package

cl-why

Source

specials.lisp (file)

Special Variable: *html-empty-tags*

The list of HTML tags that should be output as empty tags. See *HTML-EMPTY-TAG-AWARE-P*.

Package

cl-why

Source

specials.lisp (file)

Special Variable: *html-no-indent-tags*

The list of HTML tags that should disable indentation inside them. The initial value is a list containing only :PRE and :TEXTAREA.

Package

cl-why

Source

specials.lisp (file)

Special Variable: *prologue*

This is the first line that’ll be printed if the :PROLOGUE keyword argument is T

Package

cl-why

Source

specials.lisp (file)


Next: , Previous: , Up: Exported definitions   [Contents][Index]

5.1.2 Macros

Macro: with-html-output (VAR &optional STREAM &rest REST &key PROLOGUE INDENT) &body BODY

Transform the enclosed BODY consisting of HTML as s-expressions into Lisp code to write the corresponding HTML as strings to VAR - which should either hold a stream or which’ll be bound to STREAM if supplied.

Package

cl-why

Source

why.lisp (file)

Macro: with-html-output-to-string (VAR &optional STRING-FORM &key ELEMENT-TYPE PROLOGUE INDENT) &body BODY

Transform the enclosed BODY consisting of HTML as s-expressions into Lisp code which creates the corresponding HTML as a string.

Package

cl-why

Source

why.lisp (file)


Next: , Previous: , Up: Exported definitions   [Contents][Index]

5.1.3 Functions

Function: conc &rest LIST

Concatenates all arguments into one string.

Package

cl-why

Source

why.lisp (file)

Function: convert-attributes ATTR-LIST

Helper function for CONVERT-TAG-TO-STRING-LIST which converts the alist ATTR-LIST of attributes into a list of strings and/or Lisp forms.

Package

cl-why

Source

why.lisp (file)

Function: escape-char CHAR &key TEST

Returns an escaped version of the character CHAR if CHAR satisfies the predicate TEST. Always returns a string.

Package

cl-why

Source

util.lisp (file)

Function: escape-char-all CHAR

Escapes characters which aren’t in the 7-bit ASCII character set.

Package

cl-why

Source

util.lisp (file)

Function: escape-char-iso-8859-1 CHAR

Escapes characters that aren’t defined in ISO-8859-9.

Package

cl-why

Source

util.lisp (file)

Function: escape-char-minimal CHAR

Escapes only #<, #>, and #& characters.

Package

cl-why

Source

util.lisp (file)

Function: escape-char-minimal-plus-quotes CHAR

Like ESCAPE-CHAR-MINIMAL but also escapes quotes.

Package

cl-why

Source

util.lisp (file)

Function: escape-string STRING &key TEST

Escape all characters in STRING which pass TEST. This function is not guaranteed to return a fresh string. Note that you can pass NIL for STRING which’ll just be returned.

Package

cl-why

Source

util.lisp (file)

Function: escape-string-all STRING

Escapes all characters in STRING which aren’t in the 7-bit ASCII character set.

Package

cl-why

Source

util.lisp (file)

Function: escape-string-iso-8859-1 STRING

Escapes all characters in STRING which aren’t defined in ISO-8859-1.

Package

cl-why

Source

util.lisp (file)

Function: escape-string-minimal STRING

Escapes only #<, #>, and #& in STRING.

Package

cl-why

Source

util.lisp (file)

Function: escape-string-minimal-plus-quotes STRING

Like ESCAPE-STRING-MINIMAL but also escapes quotes.

Package

cl-why

Source

util.lisp (file)

Function: html-mode ()

Returns the current HTML mode. :SGML for (SGML-)HTML, :XML for XHTML and :HTML5 for HTML5 (HTML syntax).

Package

cl-why

Source

why.lisp (file)

Writer

(setf html-mode) (function)

Function: (setf html-mode) MODE

Sets the output mode to XHTML or (SGML-)HTML. MODE can be :SGML for HTML, :XML for XHTML or :HTML5 for HTML5 (HTML syntax).

Package

cl-why

Source

why.lisp (file)

Reader

html-mode (function)


Previous: , Up: Exported definitions   [Contents][Index]

5.1.4 Generic functions

Generic Function: convert-tag-to-string-list TAG ATTR-LIST BODY BODY-FN

Used by PROCESS-TAG to convert ‘HTML’ into a list
of strings. TAG is a keyword symbol naming the outer tag, ATTR-LIST is an alist of its attributes (the car is the attribute’s name as a keyword, the cdr is its value), BODY is the tag’s body, and BODY-FN is a function which should be applied to BODY. The function must return a list of strings or Lisp forms.

Package

cl-why

Source

why.lisp (file)

Methods
Method: convert-tag-to-string-list TAG ATTR-LIST BODY BODY-FN

The standard method which is not specialized. The idea is that you can use EQL specializers on the first argument.


Previous: , Up: Definitions   [Contents][Index]

5.2 Internal definitions


Next: , Previous: , Up: Internal definitions   [Contents][Index]

5.2.1 Constants

Constant: +newline+

Used for indentation.

Package

cl-why

Source

specials.lisp (file)

Constant: +spaces+

Used for indentation.

Package

cl-why

Source

specials.lisp (file)


Next: , Previous: , Up: Internal definitions   [Contents][Index]

5.2.2 Special variables

Special Variable: *empty-tag-end*

End of an empty tag. Default is XML style.

Package

cl-why

Source

specials.lisp (file)

Special Variable: *html-mode*

:SGML for (SGML-)HTML, :XML (default) for XHTML, :HTML5 for HTML5.

Package

cl-why

Source

specials.lisp (file)

Special Variable: *indent*

Whether to insert line breaks and indent. Also controls amount of indentation dynamically.

Package

cl-why

Source

specials.lisp (file)


Next: , Previous: , Up: Internal definitions   [Contents][Index]

5.2.3 Macros

Macro: defconstant NAME VALUE &optional DOC

Make sure VALUE is evaluated only once (to appease SBCL).

Package

cl-why

Source

specials.lisp (file)

Macro: n-spaces N

A string with N spaces - used by indentation.

Package

cl-why

Source

util.lisp (file)

Macro: with-rebinding BINDINGS &body BODY

WITH-REBINDING ( { var | (var prefix) }* ) form*

Evaluates a series of forms in the lexical environment that is formed by adding the binding of each VAR to a fresh, uninterned symbol, and the binding of that fresh, uninterned symbol to VAR’s original value, i.e., its value in the current lexical environment.

The uninterned symbol is created as if by a call to GENSYM with the string denoted by PREFIX - or, if PREFIX is not supplied, the string denoted by VAR - as argument.

The forms are evaluated in order, and the values of all but the last are discarded (that is, the body is an implicit PROGN).

Package

cl-why

Source

util.lisp (file)

Macro: with-unique-names (&rest BINDINGS) &body BODY

Syntax: WITH-UNIQUE-NAMES ( { var | (var x) }* ) declaration* form*

Executes a series of forms with each VAR bound to a fresh, uninterned symbol. The uninterned symbol is as if returned by a call to GENSYM with the string denoted by X - or, if X is not supplied, the string denoted by VAR - as argument.

The variable bindings created are lexical unless special declarations are specified. The scopes of the name bindings and declarations do not include the Xs.

The forms are evaluated in order, and the values of all but the last are discarded (that is, the body is an implicit PROGN).

Package

cl-why

Source

util.lisp (file)


Next: , Previous: , Up: Internal definitions   [Contents][Index]

5.2.4 Functions

Function: -esc- DATA

Create a wrapper of type <ESC> for DATA if it is non-null, otherwise return NIL.

Package

cl-why

Source

specials.lisp (file)

Function: -raw- DATA

Create a wrapper of type <RAW> for DATA if it is non-null, otherwise return NIL.

Package

cl-why

Source

specials.lisp (file)

Function: <esc>-data INSTANCE
Package

cl-why

Source

specials.lisp (file)

Function: <esc>-p OBJECT
Package

cl-why

Source

specials.lisp (file)

Function: <raw>-data INSTANCE
Package

cl-why

Source

specials.lisp (file)

Function: <raw>-p OBJECT
Package

cl-why

Source

specials.lisp (file)

Function: copy-<esc> INSTANCE
Package

cl-why

Source

specials.lisp (file)

Function: copy-<raw> INSTANCE
Package

cl-why

Source

specials.lisp (file)

Function: extract-declarations FORMS

Given a FORM, the declarations - if any - will be extracted
from the head of the FORM, and will return two values the declarations, and the remaining of FORM

Package

cl-why

Source

util.lisp (file)

Function: iso-8859-1-escape-char-p CHAR

Helper function for the ESCAPE-FOO-ISO-8859-1 functions to determine whether CHAR must be escaped.

Package

cl-why

Source

util.lisp (file)

Function: list-to-string LIST

Concatenates a list of objects into one string.

Package

cl-why

Source

why.lisp (file)

Function: make-<esc> &key (DATA DATA)
Package

cl-why

Source

specials.lisp (file)

Function: make-<raw> &key (DATA DATA)
Package

cl-why

Source

specials.lisp (file)

Function: minimal-escape-char-p CHAR

Helper function for the ESCAPE-FOO-MINIMAL functions to determine whether CHAR must be escaped.

Package

cl-why

Source

util.lisp (file)

Function: minimal-plus-quotes-escape-char-p CHAR

Helper function for the ESCAPE-FOO-MINIMAL-PLUS-QUOTES functions to determine whether CHAR must be escaped.

Package

cl-why

Source

util.lisp (file)

Function: non-7bit-ascii-escape-char-p CHAR

Helper function for the ESCAPE-FOO-ISO-8859-1 functions to determine whether CHAR must be escaped.

Package

cl-why

Source

util.lisp (file)

Function: process-tag SEXP BODY-FN

Returns a string list corresponding to the ‘HTML’ (in CL-WHY syntax) in SEXP. Uses the generic function CONVERT-TO-STRING-LIST internally. Utility function used by TREE-TO-TEMPLATE.

Package

cl-why

Source

why.lisp (file)

Function: tree-to-commands TREE STREAM &key PROLOGUE (INDENT *INDENT*)
Package

cl-why

Source

why.lisp (file)

Function: tree-to-template TREE

Transforms an HTML tree into an intermediate format - mainly a flattened list of strings. Utility function used by TREE-TO-COMMANDS-AUX.

Package

cl-why

Source

why.lisp (file)

Function: wrapper-p OBJECT

Returns whether object is a wrapper of either type <RAW> or <ESC>.

Package

cl-why

Source

specials.lisp (file)


Previous: , Up: Internal definitions   [Contents][Index]

5.2.5 Structures

Structure: <esc> ()

A wrapper for objects to print with HTML escapes.

Package

cl-why

Source

specials.lisp (file)

Direct superclasses

structure-object (structure)

Direct methods

print-object (method)

Direct slots
Slot: data
Readers

<esc>-data (function)

Writers

(setf <esc>-data) (function)

Structure: <raw> ()

A wrapper for objects to print without HTML escapes.

Package

cl-why

Source

specials.lisp (file)

Direct superclasses

structure-object (structure)

Direct methods

print-object (method)

Direct slots
Slot: data
Readers

<raw>-data (function)

Writers

(setf <raw>-data) (function)


Previous: , Up: Top   [Contents][Index]

Appendix A Indexes


Next: , Previous: , Up: Indexes   [Contents][Index]

A.1 Concepts

Jump to:   C   F   L  
Index Entry  Section

C
cl-why.asd: The cl-why<dot>asd file
cl-why/packages.lisp: The cl-why/packages<dot>lisp file
cl-why/specials.lisp: The cl-why/specials<dot>lisp file
cl-why/util.lisp: The cl-why/util<dot>lisp file
cl-why/why.lisp: The cl-why/why<dot>lisp file

F
File, Lisp, cl-why.asd: The cl-why<dot>asd file
File, Lisp, cl-why/packages.lisp: The cl-why/packages<dot>lisp file
File, Lisp, cl-why/specials.lisp: The cl-why/specials<dot>lisp file
File, Lisp, cl-why/util.lisp: The cl-why/util<dot>lisp file
File, Lisp, cl-why/why.lisp: The cl-why/why<dot>lisp file

L
Lisp File, cl-why.asd: The cl-why<dot>asd file
Lisp File, cl-why/packages.lisp: The cl-why/packages<dot>lisp file
Lisp File, cl-why/specials.lisp: The cl-why/specials<dot>lisp file
Lisp File, cl-why/util.lisp: The cl-why/util<dot>lisp file
Lisp File, cl-why/why.lisp: The cl-why/why<dot>lisp file

Jump to:   C   F   L  

Next: , Previous: , Up: Indexes   [Contents][Index]

A.2 Functions

Jump to:   (   -   <  
C   D   E   F   G   H   I   L   M   N   P   T   W  
Index Entry  Section

(
(setf html-mode): Exported functions

-
-esc-: Internal functions
-raw-: Internal functions

<
<esc>-data: Internal functions
<esc>-p: Internal functions
<raw>-data: Internal functions
<raw>-p: Internal functions

C
conc: Exported functions
convert-attributes: Exported functions
convert-tag-to-string-list: Exported generic functions
convert-tag-to-string-list: Exported generic functions
copy-<esc>: Internal functions
copy-<raw>: Internal functions

D
defconstant: Internal macros

E
escape-char: Exported functions
escape-char-all: Exported functions
escape-char-iso-8859-1: Exported functions
escape-char-minimal: Exported functions
escape-char-minimal-plus-quotes: Exported functions
escape-string: Exported functions
escape-string-all: Exported functions
escape-string-iso-8859-1: Exported functions
escape-string-minimal: Exported functions
escape-string-minimal-plus-quotes: Exported functions
extract-declarations: Internal functions

F
Function, (setf html-mode): Exported functions
Function, -esc-: Internal functions
Function, -raw-: Internal functions
Function, <esc>-data: Internal functions
Function, <esc>-p: Internal functions
Function, <raw>-data: Internal functions
Function, <raw>-p: Internal functions
Function, conc: Exported functions
Function, convert-attributes: Exported functions
Function, copy-<esc>: Internal functions
Function, copy-<raw>: Internal functions
Function, escape-char: Exported functions
Function, escape-char-all: Exported functions
Function, escape-char-iso-8859-1: Exported functions
Function, escape-char-minimal: Exported functions
Function, escape-char-minimal-plus-quotes: Exported functions
Function, escape-string: Exported functions
Function, escape-string-all: Exported functions
Function, escape-string-iso-8859-1: Exported functions
Function, escape-string-minimal: Exported functions
Function, escape-string-minimal-plus-quotes: Exported functions
Function, extract-declarations: Internal functions
Function, html-mode: Exported functions
Function, iso-8859-1-escape-char-p: Internal functions
Function, list-to-string: Internal functions
Function, make-<esc>: Internal functions
Function, make-<raw>: Internal functions
Function, minimal-escape-char-p: Internal functions
Function, minimal-plus-quotes-escape-char-p: Internal functions
Function, non-7bit-ascii-escape-char-p: Internal functions
Function, process-tag: Internal functions
Function, tree-to-commands: Internal functions
Function, tree-to-template: Internal functions
Function, wrapper-p: Internal functions

G
Generic Function, convert-tag-to-string-list: Exported generic functions

H
html-mode: Exported functions

I
iso-8859-1-escape-char-p: Internal functions

L
list-to-string: Internal functions

M
Macro, defconstant: Internal macros
Macro, n-spaces: Internal macros
Macro, with-html-output: Exported macros
Macro, with-html-output-to-string: Exported macros
Macro, with-rebinding: Internal macros
Macro, with-unique-names: Internal macros
make-<esc>: Internal functions
make-<raw>: Internal functions
Method, convert-tag-to-string-list: Exported generic functions
minimal-escape-char-p: Internal functions
minimal-plus-quotes-escape-char-p: Internal functions

N
n-spaces: Internal macros
non-7bit-ascii-escape-char-p: Internal functions

P
process-tag: Internal functions

T
tree-to-commands: Internal functions
tree-to-template: Internal functions

W
with-html-output: Exported macros
with-html-output-to-string: Exported macros
with-rebinding: Internal macros
with-unique-names: Internal macros
wrapper-p: Internal functions

Jump to:   (   -   <  
C   D   E   F   G   H   I   L   M   N   P   T   W  

Next: , Previous: , Up: Indexes   [Contents][Index]

A.3 Variables

Jump to:   *   +  
C   D   S  
Index Entry  Section

*
*attribute-quote-char*: Exported special variables
*downcase-tokens-p*: Exported special variables
*empty-tag-end*: Internal special variables
*escape-char-p*: Exported special variables
*html-empty-tag-aware-p*: Exported special variables
*html-empty-tags*: Exported special variables
*html-mode*: Internal special variables
*html-no-indent-tags*: Exported special variables
*indent*: Internal special variables
*prologue*: Exported special variables

+
+newline+: Internal constants
+spaces+: Internal constants

C
Constant, +newline+: Internal constants
Constant, +spaces+: Internal constants

D
data: Internal structures
data: Internal structures

S
Slot, data: Internal structures
Slot, data: Internal structures
Special Variable, *attribute-quote-char*: Exported special variables
Special Variable, *downcase-tokens-p*: Exported special variables
Special Variable, *empty-tag-end*: Internal special variables
Special Variable, *escape-char-p*: Exported special variables
Special Variable, *html-empty-tag-aware-p*: Exported special variables
Special Variable, *html-empty-tags*: Exported special variables
Special Variable, *html-mode*: Internal special variables
Special Variable, *html-no-indent-tags*: Exported special variables
Special Variable, *indent*: Internal special variables
Special Variable, *prologue*: Exported special variables

Jump to:   *   +  
C   D   S  

Previous: , Up: Indexes   [Contents][Index]

A.4 Data types

Jump to:   <  
C   P   S  
Index Entry  Section

<
<esc>: Internal structures
<raw>: Internal structures

C
cl-why: The cl-why system
cl-why: The cl-why package

P
Package, cl-why: The cl-why package

S
Structure, <esc>: Internal structures
Structure, <raw>: Internal structures
System, cl-why: The cl-why system

Jump to:   <  
C   P   S