The clod Reference Manual

Table of Contents

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

The clod Reference Manual

This is the clod Reference Manual, version 1.0.0, generated automatically by Declt version 2.4 "Will Decker" on Wed Jun 20 11:34:37 2018 GMT+0.


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

1 Systems

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


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

1.1 clod

Author

Paul Sexton

Description

Common Lisp Autodoc generator

Version

1.0.0

Dependencies
Source

clod.asd (file)

Component

clod.lisp (file)


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

2 Files

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


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

2.1 Lisp


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

2.1.1 clod.asd

Location

clod.asd

Systems

clod (system)


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

2.1.2 clod/clod.lisp

Parent

clod (system)

Location

clod.lisp

Packages

clod

Exported Definitions
Internal Definitions

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

3 Packages

Packages are listed by definition order.


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

3.1 clod

* Description

CLOD is a tool for creating documentation for Common Lisp programs.
CLOD examines a loaded package and writes information about all the
symbols defined within that package, to a file.

The output file is in /Org/ format. Org is a simple but powerful ’wiki-like’ markup language that is understood by *Org-mode*, a powerful outliner, personal wiki and organiser that runs as a major mode within the /Emacs/ text
editor. Org-mode can export org-format files to numerous other formats, including HTML, LaTeX, PDF, DocBook, and plain text.

More information:
- Emacs :: [[http://www.gnu.org/software/emacs]] (if you program CL, you won’t need to be told what Emacs is)
- Org mode :: [[http://orgmode.org/]]

* Why use CLOD?

- You can use org markup within docstrings (easy for humans to read) to create subsections, bulleted lists, hyperlinks within the document or
to external URLs, etc.
- Easy export to multiple file formats: text, HTML, DocBook, LaTeX -> PDF... - You can edit the output within Emacs, which is already the IDE of most Commn Lisp programmers.
- If GraphViz is installed, automatically create a diagram illustrating the package’s class hierarchy – see http://www.graphviz.org/
- Org markup has many cool tricks. Some examples of useful things you can put in docstrings:
- Include an entire file and format as plain text:
: #+INCLUDE: "filename" quote
- Include an entire file with common lisp syntax highlighting
: #+INCLUDE: "filename.lisp" src lisp
- Timestamps and datestamps:
: {{{ modification-time(%r) }}}
{{{modification-time(%r)}}}
: {{{ date(%Y-%m-%d) }}}
{{{date(%Y-%m-%d)}}}
- Define text macros, use with ={{{macro(arg1,arg2)}}}=
: #+MACRO: foo Replacement text $1 $2
- Embed any LaTeX code directly (no special markup needed)
- Embed any HTML code (special markup needed)
- Automatic syntax highlighting of source code examples in exported documents, eg:
;;; (defun hello (a &key b)
;;; (print "Hello, world!"))
- Because CLOD works by introspection rather than parsing files,
it copes effortlessly with unusual toplevel forms. Documentation generators that parse files usually won’t be able to tell that your toplevel macro ‘=(defclass-easy ...)=’ (or whatever) actually
expands to a class definition.
- For the same reason, CLOD avoids the problems with dependencies that
can trouble other documentation generators (i.e. difficulties
generating correct documentation unless you manually move things
around in the source so that the doc generator finds things in
the ‘right’ order).
- Easily change the global appearance of the document by specifying a cascading style sheet (/note: only affects HTML export from Org mode/)

* Dependencies

- ASDF: [[http://common-lisp.net/project/asdf/]]
- Closer-MOP: [[http://common-lisp.net/project/closer/]]
- Iterate: [[http://common-lisp.net/project/iterate/]]
- CL-PPCRE: [[http://weitz.de/cl-ppcre/]]

* How to use

1. Install CLOD somewhere ASDF can find it.
2. Load CLOD with =(asdf:oos ’asdf:load-op :clod)=
3. Load the package or packages for which you wish to produce documentation, eg: =(asdf:oos ’asdf:load-op :mypkg)=
4. Run =(clod:document-package :mypkg nil)= and you will see the documentation as a string, returned by [[document-package]].
5. Run =(clod:document-package :mypkg "filename.org")= and the same documentation will be written to ’filename.org’.
6. Load filename.org into Emacs. Export to HTML with =M-x org-export=, or press C-c C-e to be presented with a menu of export options.

* Writing the documentation

All documentation produced by CLOD is obtained by /introspection/, i.e. by the running CL process examining itself. If a symbol has an associated docstring, it will be used by CLOD to produce the documentation for that symbol.

Within documentation strings, you can use org mode markup. This is a simple, human-readable markup language similar to the type of markup used for wiki editing and forum posting. See the Org [[http://orgmode.org/manual/Markup.html][manual]] for more information. Also see the docstrings in the CLOD source code, which use org markup.

Some special points to note:
- Outline headings are used to structure org documents. These headings
begin with one or more asterisks at the start of the line. Thus, if you want a large docstring to be divided into subsections, the heading for each subsection should be a line that starts with one or more asterisks (*), then a space, then the title of the heading.
- These headings will automatically be correctly ’indented’ for their location in the structure of the final document. The whole document is one outline, and any given docstring will usually be appearing 2 or 3 levels deep within that outline. However, CLOD finds all heading lines within docstrings and increases the number of asterisks appropriately.
- An extra blank line is also automatically inserted after headings within docstrings, allowing you to save screen space in the docstring itself.
- By default, many docstrings are inserted within a subsection titled ’Description’. However, if you don’t want this to happen, but rather want the docstring to define its own heading names, make sure that the very first thing in the docstring is a heading (straight after the opening quote). (Note for mmm-mode users (see below): if the docstring starts with ’###’ to signal that it is in fact a docstring, CLOD will skip the hashes before looking to see if the string starts with a heading.)
So ="###* Arguments ..."= will work in that case.
- Some symbol names used by common lisp can conflict with the markup used
by org mode. For example, =*global-variable*=: asterisks are interpreted by org mode as signifying bold text. CLOD catches these in headings and auto-generated documentation, but not within doc strings, where you will need to surround the offending symbol with =equals signs=.
- *Hyperlinks* are created using
: [[double square brackets]]
Any text surrounded by these brackets will link to the same text (case insensitive) surrounded by =<<double angle brackets>>=. CLOD uses this to define hyperlinks for all symbols in the package. Every symbol MYSYMBOL has: 1. A hyperlink =<<function MYSYMBOL>>= if MYSYMBOL is a function, =<<variable MYSYMBOL>>= if it is a global variable, etc.
2. A hyperlink =<<MYSYMBOL>>= which will either link to MYSYMBOL’s documentation, or to a ’disambiguation section’ if the same symbol has multiple meanings (eg there is both a function and a variable called MYSYMBOL).
- Org mode has the ability to use Emacs’ font-lock mode to produce source code snippets that are correctly syntax highlighted for any major mode. To use this normally requires surrounding the code with =#+BEGIN_SRC ... #+END_SRC=. CLOD provides a shortcut: Any lines within docstrings that begin with three semicolons =;;;= are assumed to be example lisp source code. The first 3 semicolons are removed and the rest of the line is syntax highlighted.

* Combining org mode and common lisp mode in a single Emacs buffer

You can use org mode markup within docstrings, but you can’t see the effects of the markup until you export the documentation to org using CLOD. You also don’t get access to org’s support for automatic formatting of bulleted lists as you write, or the fantastic support for writing tables, or hyperlinks that you can click with the mouse, or ....

What if you could use all the goodness of Org, while editing docstrings in your lisp source code? You can. This section explains how.

1. Download and install nXhtml, an emacs package that contains code allowing multiple major modes to be active in a single buffer. http://ourcomments.org/cgi-bin/emacsw32-dl-latest.pl
2. Add the code in ‘mmm-clod.el’ to your .emacs file. Make sure you change the mmm-mode directory to the directory where you installed mmm-mode.
3. Restart emacs. Load a lisp source file. All documentation strings should appear with a coloured background, and when you move the cursor inside them, you will see ’Lisp[Org]’ on the modeline.
4. If not everything is highlighting correctly, or if you write a new docstring and org does not activate within it, press control-‘ to ’refresh’ mmm-mode.

Not everything works: expanding and collapsing headings fails, and
clicking the mouse elsewhere within the doc string often causes problems. But overall the two modes work together surprisingly well.

MMM-mode recognises the following things as doc strings:
1. Any string that emacs fontifies using ’font-lock-doc-face’. (in other words, font-lock mode must be active.)
2. Any string inside the form ’=(:documentation STRING)=’.
3. Finally, any string whose first three characters are ’###’. Since lines beginning with a hash are interpreted as comments by org mode, these characters will disappear when you export your document to HTML or other formats.

* Example docstring

Here is the docstring for [[document-package]]. It illustrates the use of headings, bulleted lists, definition lists, =code=, *bold* and /italic/ markup, hyperlinks to other definitions, and syntax highlighting of lisp source code examples.

: "* Arguments
: - PKG :: A package name or package object.
: - FILE/STREAM :: A string (filename), stream object, or =NIL=.
: - AUTO-LINKS :: Boolean.
: - LINES-BETWEEN-SECTIONS :: Boolean.
: - BRIEF-METHODS :: Boolean.
: - STYLE-SHEET :: A string.
: - TITLE :: A string.
: - AUTHOR :: A string.
: - EMAIL :: A string.
: * Returns
: A string, or nil.
: * Description
: Produce documentation for the package =PKG=.
:
: The documentation’s destination depends on the value of =FILE/STREAM=:
: - =STRING=: documentation is written to the file named by the string.
: - =STREAM=: documentation is written to the already existing stream.
: - =NIL=: documentation is written to a string, which is then returned by
: this function.
:
: Explanation of optional arguments:
: - =TITLE=, =AUTHOR= and =EMAIL= specify the document title, the name of
: the author, and the email address of the author.
: - If =AUTO-LINKS= is non-nil, *all* occurrences of symbol names within the : text of docstrings will be interpreted as hyperlinks, regardless of
: whether they are marked up as hyperlinks.
: - If LINES-BETWEEN-SECTIONS is nil, do not output a horizontal line before : each new section of documentation.
: - If BRIEF-METHODS is nil, document individual methods with their own
: sections, just like functions and generic functions. Most people put
: ’method’ documentation in the docstrings of their generic functions, but : if you set docstrings for individual methods then set this to nil.
: - =STYLE-SHEET= specifies the name of a /Cascading Style Sheet/ (.CSS) file : which will be used as the style for the document if you export it
: to HTML from org mode."
:
: * Example
: ;;; (clod:document-package :mypkg "mypkg-doc.org"
: ;;; :style-sheet "swiss.css" :title "My Package"
: ;;; :author "F. B. Quux" :email "quux@gmail.com")
:
: * See also
: - [[document-packages]]

Source

clod.lisp (file)

Use List
Exported Definitions
Internal Definitions

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

4 Definitions

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


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

4.1 Exported definitions


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

4.1.1 Functions

Function: document-package PKG FILE/STREAM &key AUTO-LINKS LINES-BETWEEN-SECTIONS BRIEF-METHODS INTERNAL-SYMBOLS? CLASS-DIAGRAM STYLE-SHEET TITLE AUTHOR EMAIL

* Arguments
- PKG :: A package name or package object.
- FILE/STREAM :: A string (filename), stream object, or =NIL=.
- AUTO-LINKS :: Boolean.
- LINES-BETWEEN-SECTIONS :: Boolean.
- BRIEF-METHODS :: Boolean.
- INTERNAL-SYMBOLS :: Boolean.
- CLASS-DIAGRAM :: Boolean.
- STYLE-SHEET :: A string.
- TITLE :: A string.
- AUTHOR :: A string.
- EMAIL :: A string.
* Returns
A string, or nil.
* Description
Produce documentation for the package =PKG=.

The documentation’s destination depends on the value of =FILE/STREAM=:
- =STRING=: documentation is written to the file named by the string.
- =STREAM=: documentation is written to the already existing stream.
- =NIL=: documentation is written to a string, which is then returned by this function.

Explanation of optional arguments:
- =TITLE=, =AUTHOR= and =EMAIL= specify the document title, the name of the author, and the email address of the author.
- =STYLE-SHEET= specifies the name of a Cascading Style Sheet (.CSS) file which will be used as the style for the document if you export it
to HTML from org mode.
- If =AUTO-LINKS= is non-nil, *all* occurrences of symbol names within the text of docstrings will be interpreted as hyperlinks, regardless of whether they are marked up as hyperlinks.
- If =LINES-BETWEEN-SECTIONS= is nil, do not output a horizontal line before each new section of documentation.
- If =BRIEF-METHODS= is nil, document individual methods with their own sections, just like functions and generic functions. Most people put ’method’ documentation in the docstrings of their generic functions, but if you set docstrings for individual methods then set this to nil.
- If =INTERNAL-SYMBOLS?= is non-nil, document both internal and external (exported) symbols. If nil, only document external symbols.
- If =CLASS-DIAGRAM= is non-nil, create a section after the toplevel package description, containing a description of the package hierarchy
in the form of a GraphViz ’dot’ diagram (see http://www.graphviz.org/).

* Example
;;; (clod:document-package :mypkg "mypkg-doc.org"
;;; :style-sheet "swiss.css" :title "My Package"
;;; :author "F. B. Quux" :email "quux@gmail.com")

* See also
- [[document-packages]]

Package

clod

Source

clod.lisp (file)

Function: document-packages PACKAGES FILE/STREAM &key AUTO-LINKS LINES-BETWEEN-SECTIONS BRIEF-METHODS INTERNAL-SYMBOLS? CLASS-DIAGRAM STYLE-SHEET TITLE AUTHOR EMAIL

* Arguments
- PACKAGES :: A list of package objects, or symbols naming packages. - FILE/STREAM :: A string (filename), stream object, or =NIL=. Other arguments are the same as for [[document-package]].
* Returns
A string, or nil.
* Description
Produces documentation for all the packages in =PACKAGES=, within a single file.

See [[document-package]] for more details.

Package

clod

Source

clod.lisp (file)


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

4.2 Internal definitions


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

4.2.1 Special variables

Special Variable: *accessibilities*

List of one or both of the keywords =:EXTERNAL= and =:INTERNAL=. Only symbols whose accessibility matches one of the keywords in the list will be documented.

Package

clod

Source

clod.lisp (file)

Special Variable: *alphabet*

List of uppercase letters (characters) from A to Z.

Package

clod

Source

clod.lisp (file)

Special Variable: *ambiguities*

Hash table created during package documentation. Stores all symbols which have multiple ’meanings’ within the package.

Package

clod

Source

clod.lisp (file)

Special Variable: *auto-links*

If true, all occurrences of package symbols anywhere in the documentation will be turned into hyperlinks, even if they are not marked up as such.

Package

clod

Source

clod.lisp (file)

Special Variable: *brief-methods*

If true, most documentation for methods is assumed to be found in the docstring for their generic function. A generic function’s methods are therefore described in a very brief format (bulleted list).

If false, each method receives its own section, just like other functions.

Package

clod

Source

clod.lisp (file)

Special Variable: *class-diagram*

If true, creates a section describing the package class hierarchy as a ’dot’ diagram, which can be fed to the GraphViz program (if installed) to create a visual representation of the hierarchy.

Package

clod

Source

clod.lisp (file)

Special Variable: *class-diagram-counter*

Counter that is incremented by one each time a class diagram is created. Used to construct the name of the class diagram PNG file that is produced by ‘dot’.

Package

clod

Source

clod.lisp (file)

Special Variable: *clod-version-string*

String containing CLOD’s version number.

Package

clod

Source

clod.lisp (file)

Special Variable: *document-author*

The author of the document. A string.

Package

clod

Source

clod.lisp (file)

Special Variable: *document-email*

The email address of the document’s author. A string.

Package

clod

Source

clod.lisp (file)

Special Variable: *document-style-sheet*

Filename of the Cascading Style Sheet (.css) file to use if the document produced by CLOD is exported to HTML.

Package

clod

Source

clod.lisp (file)

Special Variable: *document-title*

The title of the document. A string.

Package

clod

Source

clod.lisp (file)

Special Variable: *heading-char*

Character used at the beginning of lines to signify headings and subheadings. Should not be changed.

Package

clod

Source

clod.lisp (file)

Special Variable: *heading-level*

Number of levels ’deep’ within the outline. Used when creating headings for sections and subsections.

Package

clod

Source

clod.lisp (file)

Special Variable: *hyperspec-root*

URL or directory where the Hyperspec is found. Not currently implemented.

Package

clod

Source

clod.lisp (file)

Special Variable: *left-margin*

Width of the current ’left margin’, in spaces.

Package

clod

Source

clod.lisp (file)

Special Variable: *line-width*

Width to which paragraphs are wrapped, in characters.

Package

clod

Source

clod.lisp (file)

Special Variable: *lines-between-sections*

If true, sections of the document will be separated by horizontal lines.

Package

clod

Source

clod.lisp (file)

Special Variable: *out*

Global variable that is bound to the output stream used by CLOD while writing documentation.

Package

clod

Source

clod.lisp (file)

Special Variable: *unsafe-html-chars*

List of characters which are unsafe within HTML links and anchors, and which need to be converted to a safe representation.

See also: [[html-safe-string]].

Package

clod

Source

clod.lisp (file)


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

4.2.2 Macros

Macro: do-own-symbols (VAR PKG) &body BODY

* Arguments
- VAR :: symbol naming a variable that will be bound to each symbol in turn. - PKG :: a package.
* Description
Iterate through all the non-imported symbols in the package =PKG=. =BODY= is executed once for each such symbol, with =VAR= bound to each symbol in turn.

Package

clod

Source

clod.lisp (file)

Macro: write-indented (INDENT) &body BODY

* Arguments
- INDENT :: An integer.
* Return Value
Ignored.
* Description
All text that is written within the body of the form will be indented a further =INDENT= spaces from the left margin.

Package

clod

Source

clod.lisp (file)

Macro: writing-bulleted-list &body BODY

All output within the body of a form is assumed to be within a bulleted list.

Package

clod

Source

clod.lisp (file)

Macro: writing-section (TITLE) &body BODY

Wraps all output within the body of the form in its own section.

Package

clod

Source

clod.lisp (file)

Macro: writing-section-for-symbol (ENTITY SYM) &body BODY

Wraps all output within the body of the form in its own section. The title of the section describes the entity of type =ENTITY= that is bound to the symbol =SYM=.

Package

clod

Source

clod.lisp (file)


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

4.2.3 Functions

Function: accessible-symbols SYMS ACCESS PKG

* Arguments
- SYMS :: A list of symbols.
- ACCESS :: One of the keywords =:INTERNAL= or =:EXTERNAL=. - PKG :: A package object.
* Returns
A list of symbols.
* Description
Given a list of symbols, SYMS, returns the subset of SYMS whose accessibility in PKG matches ACCESS.

Package

clod

Source

clod.lisp (file)

Function: ampersand-symbol? SYM

Does the symbol SYM begin with an ampersand, such as &ANY, &REST and so on?

Package

clod

Source

clod.lisp (file)

Function: declared-special-p SYMBOL

Returns true if SYMBOL is declared special.

Package

clod

Source

clod.lisp (file)

Function: docpkg &rest PACKAGES
Package

clod

Source

clod.lisp (file)

Function: document-package-contents PKG &optional ACCESSIBILITIES

* Arguments
- PKG :: A package name or package object.
- ACCESSIBILITIES :: A list containing zero or more of the symbols =:external= or =:internal=.
* Return Value
Ignored.
* Description
Writes documentation for all symbols contained within the package =PKG=. Does not write documentation for the actual package object.

Package

clod

Source

clod.lisp (file)

Function: entity->string ENTITY

* Arguments
- ENTITY :: An [[=entity=]].
* Returns
A string.
* Description
Given an entity, returns a string that can be used to describe that entity type in human-readable form, in headings, etc.

Package

clod

Source

clod.lisp (file)

Function: entity->tag ENTITY

* Arguments
- ENTITY :: An [[=entity=]].
* Returns
A string.
* Description
Given an entity, returns a string that can be used as a *tag* denoting that entity type in org mode. See [[http://orgmode.org/manual/Tags.html]] for information on tags.

Package

clod

Source

clod.lisp (file)

Function: find-pkg PKG
Package

clod

Source

clod.lisp (file)

Function: find-sym SYM &optional PKG
Package

clod

Source

clod.lisp (file)

Function: function-lambda-list FUNC

* Arguments
- FUNC :: A function object, macro object, generic function object,
or a symbol bound to a function or macro.
* Returns
Two values:
- The lambda list of the function name or function object, FUNC; or nil if the function takes no arguments or the lambda list cannot be retrieved. - A boolean value – T if a lambda list (even an empty one) was found, NIL otherwise.
* Description
Returns the lambda list associated with the definition of the function or macro =FUNC=. For example, the lambda list for the common lisp function =FIND= is the list:
: (ITEM SEQUENCE &KEY :FROM-END :TEST :TEST-NOT :START :END :KEY)

Package

clod

Source

clod.lisp (file)

Function: function-name FN

* Arguments
- FN :: A function, generic function or macro object.
* Returns
The name of a function or macro, or nil.
* Description
Returns the official ’name’ bound to the function, macro, or generic function object FN. Returns =NIL= if no name can be found or if the function is anonymous (=lambda=).

Package

clod

Source

clod.lisp (file)

Function: html-safe-string STR

* Arguments
- STR :: A string.
* Returns
A string.
* Description

Given a string which is intended as a link target, return a copy in which we remove or alter any unsafe characters that will stop the link working properly when the document is exported to HTML.
* See Also
- [[*unsafe-html-chars*]]

Package

clod

Source

clod.lisp (file)

Function: list->string-with-commas LS

* Arguments
- LS :: A list of values.
* Returns
A string.
* Description
Given a list of arbitrary values, returns a string consisting of the printed representations of those values, separated by commas and spaces. * Example
;;; (list->string-with-commas ’(a b 123))
;;;
;;; => "A, B, 123"

Package

clod

Source

clod.lisp (file)

Function: list-all-direct-slots CLASSES

* Arguments
- CLASSES :: A list of class objects.
* Return Value
A list of SLOT-DEFINITION instances.
* Description
Return a list of all the direct SLOT-DEFINITION instances defined for all the classes in CLASSES.

Package

clod

Source

clod.lisp (file)

Function: list-all-indirect-slots CLASSES

* Arguments
- CLASSES :: A list of class objects.
* Return Value
A list of SLOT-DEFINITION instances.
* Description
Return a list of all the indirect SLOT-DEFINITION instances defined for all the classes in CLASSES.

Package

clod

Source

clod.lisp (file)

Function: list-all-slot-accessors CLASSES

* Arguments
- CLASSES :: A list of class objects.
* Return Value
A list of generic functions.
* Description
Return a list of all the reader and writer generic functions associated with all the slots of the classes in CLASSES.

Package

clod

Source

clod.lisp (file)

Function: make-class-link X &key TEXT

Synonym for ([[make-link]] =X :class=).

Package

clod

Source

clod.lisp (file)

Function: make-package-link SYM

Synonym for ([[make-link]] =X :package=).

Package

clod

Source

clod.lisp (file)

Function: make-specialised-lambda-list TERMS SPECS

* Arguments
- TERMS :: Unspecialised version of the lambda list (a list of symbols). - SPECS :: List of class names on which a particular method is specialised.
* Returns
A list.
* Description
Given an unspecialised lambda list and a list of specialisers, reconstruct the specialised lambda list and return it.

Package

clod

Source

clod.lisp (file)

Function: make-target SYM &optional ENTITY

Returns a string that will be interpreted by org as a destination for hyperlinks to =SYM=.

Package

clod

Source

clod.lisp (file)

Function: map-list FUNCTION LIST

Map over proper and not proper lists.

Package

clod

Source

clod.lisp (file)

Function: org-safe-symbol SYM

* Arguments
- SYM :: A symbol.
* Return Value
A string.
* Description
Given the symbol SYM, return a string that represents SYM in a form that is human-readable and where org will not be confused by any characters that might represent markup instructions.

Package

clod

Source

clod.lisp (file)

Function: replace-strings-with-symbols TREE
Package

clod

Source

clod.lisp (file)

Function: simple-type? SYM

* Arguments
- SYM :: A symbol.
* Return Value
Boolean.
* Description
Returns =T= if =SYM= names a non-class type, such as can be defined by [[deftype]].

Package

clod

Source

clod.lisp (file)

Function: str+ &rest STRINGS

* Arguments
- STRINGS :: One or more strings.
* Returns
A string.
* Description
Returns the concatenation of all supplied strings. Shorthand for =(concatenate ’string . STRINGS)=.

Package

clod

Source

clod.lisp (file)

Function: string-starts-with? STR START

* Arguments
- STR :: A string.
- START :: A smaller string.
* Returns
Boolean.
* Description
Predicate. Does the string =STR= start with the string =START=?

Package

clod

Source

clod.lisp (file)

Function: symbol-accessibility SYM &optional PKG

* Arguments
- SYM :: A symbol.
- PKG :: A package.
* Returns
One of =:inherited, :internal, :external= or =nil=.
* Description
Returns a symbol describing how the symbol =SYM= is accessible within the package =PKG=. If =SYM= is exported by =PKG= then the function returns =:external=, and so on.

Package

clod

Source

clod.lisp (file)

Function: type->string TYP

Returns a simple string representation of the type specifier =TYP=.

Package

clod

Source

clod.lisp (file)

Function: uses-for-symbol SYM

* Arguments
- SYM :: A symbol.
* Return Value
A list of [[=entity=]] values.
* Description
Given a symbol =SYM=, return a list of entity values, describing the different meanings/bindings of =SYM= within its home package.

Package

clod

Source

clod.lisp (file)

Function: word-wrap TEXT &key WIDTH RESPECT-NEWLINES RESPECT-HYPHENS EXCLUDE-START-CHAR EXCLUDE-END-CHAR

* Arguments
- TEXT :: A string.
- WIDTH :: An integer. The maximum length of lines once TEXT is wrapped. Default is 80.
- RESPECT-NEWLINES :: Boolean. Should newline characters within the string be treated as unbreakable? (=NIL=)
- RESPECT-HYPHENS :: Boolean. Should we refrain from breaking hyphenated words? (=NIL=)
- EXCLUDE-START-CHAR :: A character, or nil.
- EXCLUDE-END-CHAR :: A character, or nil.

* Return Value
A list of strings.

* Description
Given a string =TEXT=, breaks the string into a series of
smaller strings, none of which is longer than =WIDTH=. Returns the list of strings.

If =EXCLUDE-START-CHAR= and =EXCLUDE-END-CHAR= are supplied, those characters will be treated as demarcating sections of the string whose length is to be ignored (treated as zero).

Package

clod

Source

clod.lisp (file)

Function: wrap-and-write FMT &rest ARGS

Wraps the result of =(FORMAT NIL FMT . ARGS)=, then writes the resulting paragraph to output.

Package

clod

Source

clod.lisp (file)

Function: wrap-and-write-code FMT &rest ARGS

Wraps the result of =(FORMAT NIL FMT . ARGS)=, then writes the resulting paragraph with ’literal’ or ’source code block’ markup.

Package

clod

Source

clod.lisp (file)

Function: write-bullet-point FMT &rest ARGS

Writes a the result of =(FORMAT NIL FMT . ARGS)= as a point within an active bulleted list.

Package

clod

Source

clod.lisp (file)

Function: write-chapter SYMLIST ENTITY TITLE

* Arguments
- SYMLIST :: A list of symbols.
- ENTITY :: An [[=entity=]].
- TITLE :: A string.
* Return Value
Ignored.
* Description
Writes the section of the document which describes all entities of type =ENTITY=. =SYMLIST= should be a list of all the symbols that name such entities.

Package

clod

Source

clod.lisp (file)

Function: write-class-hierarchy CLASSES

* Arguments
- CLASSES :: A list of CLASS objects.
* Returns
Ignored.
* Description
Writes the inheritance tree of CLASSES as a GraphViz diagram, using the DOT language. External parent classes are also included.

See http://www.graphviz.org/ for details of the GraphViz language.

Package

clod

Source

clod.lisp (file)

Function: write-colophon ()
Package

clod

Source

clod.lisp (file)

Function: write-disambiguation SYM USES

Writes a section providing disambiguating links for the symbol SYM, which is bound in multiple namespaces.

Package

clod

Source

clod.lisp (file)

Function: write-docstring STR &key LEVELS DEFAULT

* Arguments
- STR :: A docstring.
- LEVELS :: How many levels deep in the outline is
this docstring?
- DEFAULT :: A string. Default text, used if =STR= is =NIL=.
* Return Value
Ignored.
* Description
Writes the docstring STR to the document. Before doing this, processes the docstring to:
- Demote headings
- Make all hyperlinks safe for org mode and HTML export
- Convert lines beginning with ’;;;’ to syntax-highlighting markup.

Package

clod

Source

clod.lisp (file)

Function: write-docstring-section TITLE DOCSTR

Writes the documentation string DOCSTR within its own subsection.

Package

clod

Source

clod.lisp (file)

Function: write-heading TITLE

Writes a section heading entitled =TITLE=.

Package

clod

Source

clod.lisp (file)

Function: write-index PKG &optional ACCESSIBILITIES

Writes a section containing an alphabetical index of all the symbols in the package PKG.

Package

clod

Source

clod.lisp (file)

Function: write-lambda-list-section SYM

Writes a section describing the lambda list of the function or macro SYM.

Package

clod

Source

clod.lisp (file)

Function: write-lines &rest LINES
Package

clod

Source

clod.lisp (file)

Function: write-list-as-paragraph LS

LS is a list of items. Writes all the items in LS to output as a single wrapped paragraph. Individual items are separated by commas.

Package

clod

Source

clod.lisp (file)

Function: write-out FMT &rest ARGS

Writes the result of =(FORMAT NIL FMT . ARGS)= to output.

Package

clod

Source

clod.lisp (file)

Function: write-preamble ()

* Arguments
None.
* Return Value
Ignored.
* Description
Writes some org instructions, intended to be placed at the start of the document. These specify the document’s author, title, and set some export options.

Package

clod

Source

clod.lisp (file)


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

4.2.4 Generic functions

Generic Function: document SYM DOCTYPE

* Arguments
- SYM :: a symbol.
- DOCTYPE :: an [[=entity=]].
* Returns:
Ignored.
* Description
Writes a section documenting the [[=entity=]] named =SYM= which is of entity type =DOCTYPE=.

Package

clod

Source

clod.lisp (file)

Methods
Method: document (SLOT direct-slot-definition) (DOCTYPE (eql slot))
Method: document (SLOT effective-slot-definition) (DOCTYPE (eql slot))
Method: document (SLOT slot-definition) (DOCTYPE (eql slot)) around
Method: document (SYM symbol) (DOCTYPE (eql structure))
Method: document (SYM symbol) (DOCTYPE (eql class))
Method: document (M standard-method) (DOCTYPE (eql method))
Method: document (SYM symbol) (DOCTYPE (eql slot-accessor))
Method: document (SYM symbol) (DOCTYPE (eql slot-writer))
Method: document (SYM symbol) (DOCTYPE (eql slot-reader))
Method: document (SYM symbol) (DOCTYPE (eql generic))
Method: document (SYM symbol) (DOCTYPE (eql constant))
Method: document (SYM symbol) (DOCTYPE (eql variable))
Method: document (SYM symbol) (DOCTYPE (eql type))
Method: document (SYM symbol) (DOCTYPE (eql macro))
Method: document (SYM symbol) (DOCTYPE (eql function))
Method: document (SYM symbol) DOCTYPE before
Method: document (SYM symbol) DOCTYPE after
Generic Function: make-link TARGET ENTITY &key TEXT

* Arguments
- TARGET :: A symbol, string, or other value that constitutes the target of the link.
- ENTITY :: An [[=entity=]].
- TEXT :: An optional string, used for the appearance of the link. The default is a direct textual representation of =TARGET=.
* Returns
A string.
* Description
Given a target and text, return a string that will be interpreted by org mode as a hyperlink leading to the documentation for =TARGET=.

Package

clod

Source

clod.lisp (file)

Methods
Method: make-link (C eql-specializer) (ENTITY (eql class)) &key TEXT
Method: make-link (O standard-object) (ENTITY (eql class)) &key TEXT
Method: make-link (C class) (ENTITY (eql class)) &key TEXT
Method: make-link (SYM symbol) ENTITY &key TEXT
Method: make-link (STR string) (ENTITY symbol) &key TEXT
Method: make-link (STR string) (ENTITY null) &key TEXT

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

4.2.5 Classes

Class: animal ()

dummy class, created to illustrate CLOD’s ability to produce class diagrams using GraphViz.

Package

clod

Source

clod.lisp (file)

Direct superclasses

standard-object (class)

Direct subclasses
Class: bird ()

dummy class, created to illustrate CLOD’s ability to produce class diagrams using GraphViz.

Package

clod

Source

clod.lisp (file)

Direct superclasses

animal (class)

Direct subclasses

hawk (class)

Class: cat ()

dummy class, created to illustrate CLOD’s ability to produce class diagrams using GraphViz.

Package

clod

Source

clod.lisp (file)

Direct superclasses

mammal (class)

Class: dog ()

dummy class, created to illustrate CLOD’s ability to produce class diagrams using GraphViz.

Package

clod

Source

clod.lisp (file)

Direct superclasses

mammal (class)

Class: hawk ()

dummy class, created to illustrate CLOD’s ability to produce class diagrams using GraphViz.

Package

clod

Source

clod.lisp (file)

Direct superclasses

bird (class)

Class: mammal ()

dummy class, created to illustrate CLOD’s ability to produce class diagrams using GraphViz.

Package

clod

Source

clod.lisp (file)

Direct superclasses

animal (class)

Direct subclasses

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

4.2.6 Types

Type: =entity= ()

The type ’entity’ can have any of several different symbols as its value. Each value is a different kind of ’meaning’ which a symbol can have within a package. For example, =:function= is a function, =:class= is a class, and so on.

Package

clod

Source

clod.lisp (file)


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
clod.asd: The clod<dot>asd file
clod/clod.lisp: The clod/clod<dot>lisp file

F
File, Lisp, clod.asd: The clod<dot>asd file
File, Lisp, clod/clod.lisp: The clod/clod<dot>lisp file

L
Lisp File, clod.asd: The clod<dot>asd file
Lisp File, clod/clod.lisp: The clod/clod<dot>lisp file

Jump to:   C   F   L  

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

A.2 Functions

Jump to:   A   D   E   F   G   H   L   M   O   R   S   T   U   W  
Index Entry  Section

A
accessible-symbols: Internal functions
ampersand-symbol?: Internal functions

D
declared-special-p: Internal functions
do-own-symbols: Internal macros
docpkg: Internal functions
document: Internal generic functions
document: Internal generic functions
document: Internal generic functions
document: Internal generic functions
document: Internal generic functions
document: Internal generic functions
document: Internal generic functions
document: Internal generic functions
document: Internal generic functions
document: Internal generic functions
document: Internal generic functions
document: Internal generic functions
document: Internal generic functions
document: Internal generic functions
document: Internal generic functions
document: Internal generic functions
document: Internal generic functions
document: Internal generic functions
document-package: Exported functions
document-package-contents: Internal functions
document-packages: Exported functions

E
entity->string: Internal functions
entity->tag: Internal functions

F
find-pkg: Internal functions
find-sym: Internal functions
Function, accessible-symbols: Internal functions
Function, ampersand-symbol?: Internal functions
Function, declared-special-p: Internal functions
Function, docpkg: Internal functions
Function, document-package: Exported functions
Function, document-package-contents: Internal functions
Function, document-packages: Exported functions
Function, entity->string: Internal functions
Function, entity->tag: Internal functions
Function, find-pkg: Internal functions
Function, find-sym: Internal functions
Function, function-lambda-list: Internal functions
Function, function-name: Internal functions
Function, html-safe-string: Internal functions
Function, list->string-with-commas: Internal functions
Function, list-all-direct-slots: Internal functions
Function, list-all-indirect-slots: Internal functions
Function, list-all-slot-accessors: Internal functions
Function, make-class-link: Internal functions
Function, make-package-link: Internal functions
Function, make-specialised-lambda-list: Internal functions
Function, make-target: Internal functions
Function, map-list: Internal functions
Function, org-safe-symbol: Internal functions
Function, replace-strings-with-symbols: Internal functions
Function, simple-type?: Internal functions
Function, str+: Internal functions
Function, string-starts-with?: Internal functions
Function, symbol-accessibility: Internal functions
Function, type->string: Internal functions
Function, uses-for-symbol: Internal functions
Function, word-wrap: Internal functions
Function, wrap-and-write: Internal functions
Function, wrap-and-write-code: Internal functions
Function, write-bullet-point: Internal functions
Function, write-chapter: Internal functions
Function, write-class-hierarchy: Internal functions
Function, write-colophon: Internal functions
Function, write-disambiguation: Internal functions
Function, write-docstring: Internal functions
Function, write-docstring-section: Internal functions
Function, write-heading: Internal functions
Function, write-index: Internal functions
Function, write-lambda-list-section: Internal functions
Function, write-lines: Internal functions
Function, write-list-as-paragraph: Internal functions
Function, write-out: Internal functions
Function, write-preamble: Internal functions
function-lambda-list: Internal functions
function-name: Internal functions

G
Generic Function, document: Internal generic functions
Generic Function, make-link: Internal generic functions

H
html-safe-string: Internal functions

L
list->string-with-commas: Internal functions
list-all-direct-slots: Internal functions
list-all-indirect-slots: Internal functions
list-all-slot-accessors: Internal functions

M
Macro, do-own-symbols: Internal macros
Macro, write-indented: Internal macros
Macro, writing-bulleted-list: Internal macros
Macro, writing-section: Internal macros
Macro, writing-section-for-symbol: Internal macros
make-class-link: Internal functions
make-link: Internal generic functions
make-link: Internal generic functions
make-link: Internal generic functions
make-link: Internal generic functions
make-link: Internal generic functions
make-link: Internal generic functions
make-link: Internal generic functions
make-package-link: Internal functions
make-specialised-lambda-list: Internal functions
make-target: Internal functions
map-list: Internal functions
Method, document: Internal generic functions
Method, document: Internal generic functions
Method, document: Internal generic functions
Method, document: Internal generic functions
Method, document: Internal generic functions
Method, document: Internal generic functions
Method, document: Internal generic functions
Method, document: Internal generic functions
Method, document: Internal generic functions
Method, document: Internal generic functions
Method, document: Internal generic functions
Method, document: Internal generic functions
Method, document: Internal generic functions
Method, document: Internal generic functions
Method, document: Internal generic functions
Method, document: Internal generic functions
Method, document: Internal generic functions
Method, make-link: Internal generic functions
Method, make-link: Internal generic functions
Method, make-link: Internal generic functions
Method, make-link: Internal generic functions
Method, make-link: Internal generic functions
Method, make-link: Internal generic functions

O
org-safe-symbol: Internal functions

R
replace-strings-with-symbols: Internal functions

S
simple-type?: Internal functions
str+: Internal functions
string-starts-with?: Internal functions
symbol-accessibility: Internal functions

T
type->string: Internal functions

U
uses-for-symbol: Internal functions

W
word-wrap: Internal functions
wrap-and-write: Internal functions
wrap-and-write-code: Internal functions
write-bullet-point: Internal functions
write-chapter: Internal functions
write-class-hierarchy: Internal functions
write-colophon: Internal functions
write-disambiguation: Internal functions
write-docstring: Internal functions
write-docstring-section: Internal functions
write-heading: Internal functions
write-indented: Internal macros
write-index: Internal functions
write-lambda-list-section: Internal functions
write-lines: Internal functions
write-list-as-paragraph: Internal functions
write-out: Internal functions
write-preamble: Internal functions
writing-bulleted-list: Internal macros
writing-section: Internal macros
writing-section-for-symbol: Internal macros

Jump to:   A   D   E   F   G   H   L   M   O   R   S   T   U   W  

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

A.3 Variables

Jump to:   *  
S  
Index Entry  Section

*
*accessibilities*: Internal special variables
*alphabet*: Internal special variables
*ambiguities*: Internal special variables
*auto-links*: Internal special variables
*brief-methods*: Internal special variables
*class-diagram*: Internal special variables
*class-diagram-counter*: Internal special variables
*clod-version-string*: Internal special variables
*document-author*: Internal special variables
*document-email*: Internal special variables
*document-style-sheet*: Internal special variables
*document-title*: Internal special variables
*heading-char*: Internal special variables
*heading-level*: Internal special variables
*hyperspec-root*: Internal special variables
*left-margin*: Internal special variables
*line-width*: Internal special variables
*lines-between-sections*: Internal special variables
*out*: Internal special variables
*unsafe-html-chars*: Internal special variables

S
Special Variable, *accessibilities*: Internal special variables
Special Variable, *alphabet*: Internal special variables
Special Variable, *ambiguities*: Internal special variables
Special Variable, *auto-links*: Internal special variables
Special Variable, *brief-methods*: Internal special variables
Special Variable, *class-diagram*: Internal special variables
Special Variable, *class-diagram-counter*: Internal special variables
Special Variable, *clod-version-string*: Internal special variables
Special Variable, *document-author*: Internal special variables
Special Variable, *document-email*: Internal special variables
Special Variable, *document-style-sheet*: Internal special variables
Special Variable, *document-title*: Internal special variables
Special Variable, *heading-char*: Internal special variables
Special Variable, *heading-level*: Internal special variables
Special Variable, *hyperspec-root*: Internal special variables
Special Variable, *left-margin*: Internal special variables
Special Variable, *line-width*: Internal special variables
Special Variable, *lines-between-sections*: Internal special variables
Special Variable, *out*: Internal special variables
Special Variable, *unsafe-html-chars*: Internal special variables

Jump to:   *  
S  

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

A.4 Data types

Jump to:   =  
A   B   C   D   H   M   P   S   T  
Index Entry  Section

=
=entity=: Internal types

A
animal: Internal classes

B
bird: Internal classes

C
cat: Internal classes
Class, animal: Internal classes
Class, bird: Internal classes
Class, cat: Internal classes
Class, dog: Internal classes
Class, hawk: Internal classes
Class, mammal: Internal classes
clod: The clod system
clod: The clod package

D
dog: Internal classes

H
hawk: Internal classes

M
mammal: Internal classes

P
Package, clod: The clod package

S
System, clod: The clod system

T
Type, =entity=: Internal types

Jump to:   =  
A   B   C   D   H   M   P   S   T