The staple Reference Manual

Table of Contents

The staple Reference Manual

This is the staple Reference Manual, version 1.1.0, generated automatically by Declt version 2.4 "Will Decker" on Wed Jun 20 12:37:10 2018 GMT+0.

1 Introduction

About Staple

Staple is yet another Common Lisp documentation generation application. It uses Clip and lQuery to do most of the work. The main features include automatic package symbol index processing, documentation gathering from related files and generation through expressive templates.

How To

Load Staple through ASDF or Quicklisp:

(ql:quickload :staple)

Generating documentation is a single command away:

(staple:generate :my-asdf-system)

This should create an about.html file within the source directory of the asdf-system you specified. By default staple uses the same name as the asdf system for the package index, but you may specify your package/s directly too if they differ using the :PACKAGES argument.

Staple automatically searches your source directory for documentation files (like README.md) to include into the finished file. You may however specify your own file or a string directly with the :DOCUMENTATION argument. Staple currently only parses Markdown files to HTML, but you may extend it with other formats by adding a parse-documentation-file method.

The template used to generate everything is a Clip document. Understanding how it works and throwing together your custom layout to use should not be hard. For a full understanding of the system however please read the Clip documentation.

Extending Staple

Staple can be extended to handle other "symbol types" and to automatically behave different for specific systems. In order to do so you should create a staple.ext.lisp file within the root source directory of the system you want to have extensions for. This file will automatically be loaded when you generate documentation for your system.

In order to add a new type of symbol, you should subclass one of the symb classes. Depending on what kind of thing your type of symbol is, different classes may be appropriate. You should then add methods that specialise on your subclass to at least symb-documentation and symb-type-order. There are other methods that give you more fine-grained control over how the symbols are represented.

Finally you'll need to tell Staple how to find your new type of symbol when it scans over packages. To do so, you should use define-converter or define-simple-converter. Converters are functions that take a symbol and a package, and return a list of symb objects that apply for the given symbol and package combination.

This is all it takes for Staple to produce new symbol types in the index.

If you want to customise the default arguments to generate, or add additional properties for usage in the template document, you can add a method to system-options that specifies these properties.

(defmethod staple:system-options append ((system (eql (asdf:find-system :my-sys))))
  (list :template (system-relative-pathname system \"my-clip-template.ctml\")
        :if-exists :supersede))

See the documentation of system-options for the default properties that Staple understands and supplies. If you need to customise which symbol objects are emitted into the documentation file for a given package and system, you can add a method to system-package-symbols to control this behaviour.

(defmethod staple:system-package-symbols ((system (eql (asdf:find-system :my-sys))) package)
  (remove-if ... (staple:package-symbol-objects package)))

Note that symbols will still get filtered out depending on the value of the exclude attribute in the do-symbols tag in the template which, by default, excludes methods, internal symbols, and inherited symbols.

In general the staple.ext.lisp should allow you to lay down all the customisation of your system so that all you'll ever need to do to actually generate the docs is

(ql:quickload '(staple my-system))
(staple:generate :my-system)

and Staple will figure out everything automatically.

Documentation Browser

Staple includes a server so that you can view the documentation and symbol index of all available ASDF systems on the fly.

(ql:quickload :staple-server)
(staple-server:start)

Depending on how many systems you have loaded, starting the server may take a while as it produces a cache of all documentation pages. Once it's done, visit the url in the message. If you change the systems and want to view the updated documentation, use staple-server:recache.

2 Systems

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

2.1 staple

Maintainer

Nicolas Hafner <shinmera@tymoon.eu>

Author

Nicolas Hafner <shinmera@tymoon.eu>

Home Page

https://github.com/Shinmera/staple

License

Artistic

Description

A tool to generate documentation about Lisp projects through an HTML template.

Version

1.1.0

Dependencies

• staple-package-recording (system)
• clip
• closer-mop
• cl-ppcre
• trivial-arguments
• 3bmd
• 3bmd-ext-code-blocks
• documentation-utils
• do-urlencode
• required module sb-cltl2 (for feature sbcl)

Source

staple.asd (file)

Components

• package.lisp (file)
• symbols.lisp (file)
• clip.lisp (file)
• fulltext.lisp (file)
• stapler.lisp (file)
• documentation.lisp (file)

2.2 staple-package-recording

Maintainer

Nicolas Hafner <shinmera@tymoon.eu>

Author

Nicolas Hafner <shinmera@tymoon.eu>

Home Page

https://github.com/Shinmera/staple

License

Artistic

Description

Collects information about packages being defined with an ASDF system.

Version

1.0.1

Source

staple-package-recording.asd (file)

Component

recording.lisp (file)

3 Files

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

3.1 Lisp

3.1.1 staple.asd

Location

staple.asd

Systems

staple (system)

3.1.2 staple-package-recording.asd

Location

staple-package-recording.asd

Systems

staple-package-recording (system)

3.1.3 staple/package.lisp

Parent

staple (system)

Location

package.lisp

Packages

staple

3.1.4 staple/symbols.lisp

Dependency

package.lisp (file)

Parent

staple (system)

Location

symbols.lisp

Exported Definitions

• converter (function)
• (setf converter) (function)
• define-converter (macro)
• define-simple-converter (macro)
• package-symbol-objects (function)
• package-symbols (function)
• remove-converter (function)
• symb-accessor (class)
• symb-arguments (generic function)
• symb-arguments (method)
• symb-arguments (method)
• symb-arguments (method)
• symb-arguments (method)
• symb-arguments (method)
• symb-class (class)
• symb-condition (class)
• symb-constant (class)
• symb-documentation (generic function)
• symb-documentation (method)
• symb-documentation (method)
• symb-documentation (method)
• symb-documentation (method)
• symb-documentation (method)
• symb-function (generic function)
• symb-function (method)
• symb-function (method)
• symb-function (class)
• symb-generic (class)
• symb-id (generic function)
• symb-id (method)
• symb-macro (class)
• symb-method (method)
• (setf symb-method) (method)
• symb-method (class)
• symb-name (generic function)
• symb-name (method)
• symb-object (class)
• symb-package (generic function)
• symb-package (method)
• (setf symb-package) (method)
• symb-qualifiers (generic function)
• symb-qualifiers (method)
• symb-qualifiers (method)
• symb-scope (generic function)
• symb-scope (method)
• symb-special (class)
• symb-structure (class)
• symb-symbol (method)
• (setf symb-symbol) (method)
• symb-true-symbol (generic function)
• symb-true-symbol (method)
• symb-type (generic function)
• symb-type (method)
• symb-type (class)
• symb-type-order (generic function)
• symb-type-order (method)
• symb-type-order (method)
• symb-type-order (method)
• symb-type-order (method)
• symb-type-order (method)
• symb-type-order (method)
• symb-type-order (method)
• symb-type-order (method)
• symb-type-order (method)
• symb-type-order (method)
• symb-type-order (method)
• symb-type-order (method)
• symb-type-order (method)
• symb-type-order (method)
• symb-type-order (method)
• symb-type< (function)
• symb-variable (class)
• symb< (generic function)
• symb< (method)
• symb< (method)
• symb< (method)
• symbol-class-p (function)
• symbol-condition-p (function)
• symbol-constant-p (function)
• symbol-function-p (function)
• symbol-generic-p (function)
• symbol-objects (function)
• symbol-setf-function-p (function)
• symbol-structure-p (function)

Internal Definitions

• *converters* (special variable)
• symb-is (generic function)
• symb-is (method)
• symb-is (method)
• symb-is (method)
• symb-is (method)
• symb-is (method)
• symb-is (method)
• symb-is (method)
• symb-is (method)
• symb-is (method)
• symb-is (method)
• symb-is (method)
• symb-is (method)
• symb-is (method)
• symb-is (method)
• symb-is (method)
• symb-is (method)
• symbol-accessor-p (function)
• symbol-macro-p (function)
• symbol-special-p (function)
• symbol-type-p (function)
• symbol-typedef-p (function)

3.1.5 staple/clip.lisp

Dependency

symbols.lisp (file)

Parent

staple (system)

Location

clip.lisp

Exported Definitions

• anchor (function)
• day (function)
• licenselink (function)
• month (function)
• render-docstring (method)
• render-docstring-markdown (function)
• render-docstring-see-also (function)
• resolve-symbol-documentation (function)
• stext (function)
• year (function)

Internal Definitions

• %is-excluded (function)
• *current-packages* (special variable)
• *system-under-construction* (special variable)
• parse-block-symbols (function)
• parse-lone-symbols (function)
• present (function)
• present-arguments (function)
• present-improper-list (function)
• present-qualifiers (function)
• string-starts-with (function)
• strip-arglist (function)

3.1.6 staple/fulltext.lisp

Dependency

clip.lisp (file)

Parent

staple (system)

Location

fulltext.lisp

Exported Definitions

• *documentation-names* (special variable)
• *documentation-types* (special variable)
• *logo-names* (special variable)
• *logo-types* (special variable)
• find-documentation-file (function)
• find-logo-file (function)
• parse-documentation-file (generic function)
• parse-documentation-file (method)
• parse-documentation-file (method)
• prepare-documentation (function)

3.1.7 staple/stapler.lisp

Dependency

fulltext.lisp (file)

Parent

staple (system)

Location

stapler.lisp

Exported Definitions

• *default-template* (special variable)
• *extension-file* (special variable)
• *legacy-template* (special variable)
• *modern-template* (special variable)
• generate (function)
• staple (function)
• system-options (generic function)
• system-options (method)
• system-package-symbols (generic function)
• system-package-symbols (method)
• to-out (function)

Internal Definitions

• *loaded-extensions* (special variable)
• *root-clipboard* (special variable)
• compact (function)
• ensure-system (function)
• load-extension (function)
• merge-plist (function)
• root (function)

3.1.8 staple/documentation.lisp

Dependency

stapler.lisp (file)

Parent

staple (system)

Location

documentation.lisp

3.1.9 staple-package-recording/recording.lisp

Parent

staple-package-recording (system)

Location

recording.lisp

Packages

staple-package-recording

Exported Definitions

• *before-load-packages* (special variable)
• *system-packages* (special variable)
• efind-package (function)
• (setf system-packages) (function)
• system-packages (method)
• system-packages (method)
• (setf system-packages) (function)

4 Packages

Packages are listed by definition order.

4.1 staple

Source

package.lisp (file)

Nickname

org.tymoonnext.staple

Use List

• staple-package-recording
• clip
• closer-mop
• lquery
• common-lisp

Exported Definitions

• *default-template* (special variable)
• *documentation-names* (special variable)
• *documentation-types* (special variable)
• *extension-file* (special variable)
• *legacy-template* (special variable)
• *logo-names* (special variable)
• *logo-types* (special variable)
• *modern-template* (special variable)
• anchor (function)
• converter (function)
• (setf converter) (function)
• day (function)
• define-converter (macro)
• define-simple-converter (macro)
• find-documentation-file (function)
• find-logo-file (function)
• generate (function)
• licenselink (function)
• month (function)
• package-symbol-objects (function)
• package-symbols (function)
• parse-documentation-file (generic function)
• parse-documentation-file (method)
• parse-documentation-file (method)
• prepare-documentation (function)
• remove-converter (function)
• render-docstring (generic function)
• render-docstring (method)
• render-docstring-markdown (function)
• render-docstring-see-also (function)
• resolve-symbol-documentation (function)
• staple (function)
• stext (function)
• symb-accessor (class)
• symb-arguments (generic function)
• symb-arguments (method)
• symb-arguments (method)
• symb-arguments (method)
• symb-arguments (method)
• symb-arguments (method)
• symb-class (class)
• symb-condition (class)
• symb-constant (class)
• symb-documentation (generic function)
• symb-documentation (method)
• symb-documentation (method)
• symb-documentation (method)
• symb-documentation (method)
• symb-documentation (method)
• symb-function (generic function)
• symb-function (method)
• symb-function (method)
• symb-function (class)
• symb-generic (class)
• symb-id (generic function)
• symb-id (method)
• symb-macro (class)
• symb-method (generic function)
• symb-method (method)
• (setf symb-method) (method)
• (setf symb-method) (generic function)
• symb-method (class)
• symb-name (generic function)
• symb-name (method)
• symb-object (class)
• symb-package (generic function)
• symb-package (method)
• (setf symb-package) (generic function)
• (setf symb-package) (method)
• symb-qualifiers (generic function)
• symb-qualifiers (method)
• symb-qualifiers (method)
• symb-scope (generic function)
• symb-scope (method)
• symb-special (class)
• symb-structure (class)
• symb-symbol (generic function)
• symb-symbol (method)
• (setf symb-symbol) (method)
• (setf symb-symbol) (generic function)
• symb-true-symbol (generic function)
• symb-true-symbol (method)
• symb-type (generic function)
• symb-type (method)
• symb-type (class)
• symb-type-order (generic function)
• symb-type-order (method)
• symb-type-order (method)
• symb-type-order (method)
• symb-type-order (method)
• symb-type-order (method)
• symb-type-order (method)
• symb-type-order (method)
• symb-type-order (method)
• symb-type-order (method)
• symb-type-order (method)
• symb-type-order (method)
• symb-type-order (method)
• symb-type-order (method)
• symb-type-order (method)
• symb-type-order (method)
• symb-type< (function)
• symb-variable (class)
• symb< (generic function)
• symb< (method)
• symb< (method)
• symb< (method)
• symbol-class-p (function)
• symbol-condition-p (function)
• symbol-constant-p (function)
• symbol-function-p (function)
• symbol-generic-p (function)
• symbol-objects (function)
• symbol-setf-function-p (function)
• symbol-structure-p (function)
• system-options (generic function)
• system-options (method)
• system-package-symbols (generic function)
• system-package-symbols (method)
• to-out (function)
• year (function)

Internal Definitions

• %is-excluded (function)
• *converters* (special variable)
• *current-packages* (special variable)
• *loaded-extensions* (special variable)
• *root-clipboard* (special variable)
• *system-under-construction* (special variable)
• compact (function)
• ensure-system (function)
• load-extension (function)
• merge-plist (function)
• parse-block-symbols (function)
• parse-lone-symbols (function)
• present (function)
• present-arguments (function)
• present-improper-list (function)
• present-qualifiers (function)
• root (function)
• string-starts-with (function)
• strip-arglist (function)
• symb-is (generic function)
• symb-is (method)
• symb-is (method)
• symb-is (method)
• symb-is (method)
• symb-is (method)
• symb-is (method)
• symb-is (method)
• symb-is (method)
• symb-is (method)
• symb-is (method)
• symb-is (method)
• symb-is (method)
• symb-is (method)
• symb-is (method)
• symb-is (method)
• symb-is (method)
• symbol-accessor-p (function)
• symbol-macro-p (function)
• symbol-special-p (function)
• symbol-type-p (function)
• symbol-typedef-p (function)

4.2 staple-package-recording

Source

recording.lisp (file)

Nickname

org.tymoonnext.staple.recording

Use List

common-lisp

Used By List

staple

Exported Definitions

• *before-load-packages* (special variable)
• *system-packages* (special variable)
• efind-package (function)
• (setf system-packages) (function)
• system-packages (generic function)
• system-packages (method)
• system-packages (method)
• (setf system-packages) (function)

5 Definitions

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

5.1 Exported definitions

5.1.1 Special variables

Special Variable: *before-load-packages*

Map associating ASDF:SYSTEM objects to the package list recorded before the first time the system was loaded.

Package

staple-package-recording

Source

recording.lisp (file)

Special Variable: *default-template*

Pathname to the default template to use in GENERATE.

Package

staple

Source

stapler.lisp (file)

Special Variable: *documentation-names*

A list of strings denoting common file names (without extension) for documentation files. If you have your own file name, push it onto this list.

See *DOCUMENTATION-TYPES*
See FIND-DOCUMENTATION-FILE

Package

staple

Source

fulltext.lisp (file)

Special Variable: *documentation-types*

A list of strings denoting common file types/extensions for documentation files. If you have your own file type, push it onto this list.

See *DOCUMENTATION-NAMES*
See FIND-DOCUMENTATION-FILE

Package

staple

Source

fulltext.lisp (file)

Special Variable: *extension-file*

Pathname describing the filename for Staple extension files.

Package

staple

Source

stapler.lisp (file)

Special Variable: *legacy-template*

Pathname to a rather plain and simple preset template that was used before the modern one.

Package

staple

Source

stapler.lisp (file)

Special Variable: *logo-names*

A list of strings denoting commong file names (without extension) for logos. If you have your own file name, push it onto this list.

See *LOGO-TYPES*
See FIND-LOGO-FILE

Package

staple

Source

fulltext.lisp (file)

Special Variable: *logo-types*

A list of strings denoting commong image types/extensions for logos. If you have your own file type, push it onto this list.

See *LOGO-NAMES*
See FIND-LOGO-FILE

Package

staple

Source

fulltext.lisp (file)

Special Variable: *modern-template*

Pathname to a simple, yet modern preset template.

Package

staple

Source

stapler.lisp (file)

Special Variable: *system-packages*

Map associating ASDF:SYSTEM objects to recorded packages for the system.

See SYSTEM-PACKAGES

Package

staple-package-recording

Source

recording.lisp (file)

5.1.2 Macros

Macro: define-converter NAME ARGS &body BODY

Shorthand to easily define a converter function.

See CONVERTER

Package

staple

Source

symbols.lisp (file)

Macro: define-simple-converter OBJECT-CLASS TEST

Shorthand for the most common definitions.
If TEST function passes, a single symbol object constructed from OBJECT-CLASS is returned as a list.

Package

staple

Source

symbols.lisp (file)

5.1.3 Functions

Function: anchor OBJECT

Returns a href-anchor.

Package

staple

Source

clip.lisp (file)

Function: converter NAME

Accessor to the converter function associated with the name. Each converter function takes two arguments, a symbol and a package, and must return a list of symb-object instances.

Package

staple

Source

symbols.lisp (file)

Writer

(setf converter) (function)

Function: (setf converter) FUNCTION NAME

Package

staple

Source

symbols.lisp (file)

Reader

converter (function)

Function: day ()

Return the current day of the month

Package

staple

Source

clip.lisp (file)

Function: efind-package NAME

Attempts to find a package of the given name.

Unlike FIND-PACKAGE, this also tries the name in all uppercase, and if both attempts with the regular name and uppercased name fail, it signals an error.

Package

staple-package-recording

Source

recording.lisp (file)

Function: find-documentation-file ASDF

Attempts to find a documentation file in the given asdf system’s source directory.
This relies on *DOCUMENTATION-NAMES* and *DOCUMENTATION-TYPES* to find an appropriate file.

See *DOCUMENTATION-NAMES*
See *DOCUMENTATION-TYPES*

Package

staple

Source

fulltext.lisp (file)

Function: find-logo-file ASDF

Attempts to find a logo file in the given asdf system’s source directory. See *LOGO-NAMES* and *LOGO-TYPES*. The system will also try to find files by prepending or appending the system name to the logo names.

See *LOGO-NAMES*
See *LOGO-TYPES*

Package

staple

Source

fulltext.lisp (file)

Function: generate ASDF-SYSTEM &rest ARGS &key COMPACT DOCUMENTATION EXTENSION LOGO NAME OUT PACKAGES TEMPLATE IF-EXISTS &allow-other-keys

Generates documentation for the given asdf-system.

If the system is not already loaded, it is loaded.
If there is an extension file within the system’s root directory, that file is also loaded. The extension files of the transitive dependencies of the system are loaded as well, before that of your specified system. This ensures that potential symbol classes they may provide are also available to your system. For this to work however, the transitive systems must use the default location for their extension files.

The system may specify default arguments in its options. The arguments specified for GENERATE will always override those, however. The arguments’ effects are explained in SYSTEM-OPTIONS.

See SYSTEM-OPTIONS
See *EXTENSION-FILE*

Package

staple

Source

stapler.lisp (file)

Function: licenselink LICENSE

Returns an A tag linked to a TLDRLegal.com search on the license name.

Package

staple

Source

clip.lisp (file)

Function: month ()

Return the current month

Package

staple

Source

clip.lisp (file)

Function: package-symbol-objects PACKAGE

Gathers all possible symbol-objects of the given package.

See SYMB-OBJECT

Package

staple

Source

symbols.lisp (file)

Function: package-symbols PACKAGE

Gets all symbols within a package.

Package

staple

Source

symbols.lisp (file)

Function: prepare-documentation SYSTEM DOC

Attempts to prepare the documentation for the given system.
In the case of a pathname, PARSE-DOCUMENTATION-FILE is called.
If the doc is NIL, a matching documentation file is attempted to be found through FIND-DOCUMENTATION-FILE. If nothing is foudn for that as well, an empty string is returned instead.

Package

staple

Source

fulltext.lisp (file)

Function: remove-converter NAME

Remove the named converter.

See CONVERTER

Package

staple

Source

symbols.lisp (file)

Function: render-docstring-markdown STRING

Renders the docstring as a markdown highlighted string.

Package

staple

Source

clip.lisp (file)

Function: render-docstring-see-also STRING

Renders the docstring plainly, turning ’See X’ lines into links.

Package

staple

Source

clip.lisp (file)

Function: resolve-symbol-documentation SYMBOL

Attempts to resolve the (string) symbol to either an URL or an anchor. This works by first testing against the package. If it is known (such as the sb-*, mop, cl and *current-packages*) a link/anchor is returned. If nothing can be found, NIL is returned instead. If no package designator is given, the symbol is attempted to be automatically found in either the *current-packages* or in CL.

Package

staple

Source

clip.lisp (file)

Function: staple IN &key OUT IF-EXISTS CLIP-ARGS COMPACT

Performs stapling actions/clip processing on the IN document.

IN is parsed by PLUMP:PARSE and the results are written to OUT. Through CLIP-ARGS additional arguments can be passed to CLIP:GENERATE. These will also appear in the *ROOT-CLIPBOARD*.

Package

staple

Source

stapler.lisp (file)

Function: stext NODE OBJECT

Same as lQuery’s TEXT, but calls PRINC-TO-STRING on the object or uses an empty string on NIL.

Package

staple

Source

clip.lisp (file)

Function: symb-type< A B

Used to sort symbols alphabetically, grouped by their type.

See SYMB-OBJECT

Package

staple

Source

symbols.lisp (file)

Function: symbol-class-p SYMBOL

Returns T if the symbol is a class.

Package

staple

Source

symbols.lisp (file)

Function: symbol-condition-p SYMBOL

Returns T if the symbol is a condition.

Package

staple

Source

symbols.lisp (file)

Function: symbol-constant-p SYMBOL

Returns T if the symbol is a constant.

Package

staple

Source

symbols.lisp (file)

Function: symbol-function-p SYMBOL

Returns T if the symbol is a pure function.

Package

staple

Source

symbols.lisp (file)

Function: symbol-generic-p SYMBOL

Returns T if the symbol is a generic function.

Package

staple

Source

symbols.lisp (file)

Function: symbol-objects SYMBOLS &optional PACKAGE

Gathers all possible symbol-objects out of the list of passed symbols.

See SYMB-OBJECT

Package

staple

Source

symbols.lisp (file)

Function: symbol-setf-function-p SYMBOL

Returns T if the symbol is a setf function.

Package

staple

Source

symbols.lisp (file)

Function: symbol-structure-p SYMBOL

Returns T if the symbol is a structure.

Package

staple

Source

symbols.lisp (file)

Function: (setf system-packages) PACKAGES SYSTEM

Package

staple-package-recording

Source

recording.lisp (file)

Reader

system-packages (generic function)

Function: to-out PATHNAME

Returns a pathname whose file-name (not extension) is postfixed by .out .

Package

staple

Source

stapler.lisp (file)

Function: year ()

Return the current year

Package

staple

Source

clip.lisp (file)

5.1.4 Generic functions

Generic Function: parse-documentation-file TYPE STREAM

Used to perform special parsing on certain documentation files (such as Markdown).
The type should be an EQL-specializer to a keyword of the file-type/extension.

By default only .md files are specially handled, everything else is simply read as a string.

Package

staple

Source

fulltext.lisp (file)

Methods

Method: parse-documentation-file (TYPE (eql md)) STREAM

Method: parse-documentation-file TYPE STREAM

Generic Function: render-docstring STRING SYSTEM

Render the docstring appropriately for the given system.

See RENDER-DOCSTRING-SEE-ALSO
See RENDER-DOCSTRING-MARKDOWN

Package

staple

Methods

Method: render-docstring STRING (SYSTEM system)

Source

clip.lisp (file)

Generic Function: symb-arguments SYMB-OBJECT

Returns the arguments of the function or NIL.

See SYMB-FUNCTION

Package

staple

Source

symbols.lisp (file)

Methods

Method: symb-arguments (SYMB symb-object)

Method: symb-arguments (SYMB symb-function)

Method: symb-arguments (SYMB symb-generic)

Method: symb-arguments (SYMB symb-type)

Method: symb-arguments (SYMB symb-method)

Generic Function: symb-documentation SYMB-OBJECT

Returns the documentation-string.

See SYMB-OBJECT

Package

staple

Source

symbols.lisp (file)

Methods

Method: symb-documentation (SYMB symb-function)

Method: symb-documentation (SYMB symb-method)

Method: symb-documentation (SYMB symb-variable)

Method: symb-documentation (SYMB symb-type)

Method: symb-documentation (SYMB symb-structure)

Generic Function: symb-function SYMB-OBJECT

Returns the symbol-function of the symbol.

See SYMB-FUNCTION

Package

staple

Source

symbols.lisp (file)

Methods

Method: symb-function (SYMB symb-object)

Method: symb-function (SYMB symb-macro)

Generic Function: symb-id SYMB-OBJECT

Returns a string representing the symbol uniquely.

See SYMB-OBJECT

Package

staple

Source

symbols.lisp (file)

Methods

Method: symb-id (SYMB symb-object)

Generic Function: symb-method OBJECT

Accesses the method object that this symb-method represents.

See SYMB-QUALIFIERS
See SYMB-METHOD

Package

staple

Writer

(setf symb-method) (generic function)

Methods

Method: symb-method (SYMB-METHOD symb-method)

automatically generated reader method

Source

symbols.lisp (file)

Generic Function: (setf symb-method) NEW-VALUE OBJECT

Package

staple

Reader

symb-method (generic function)

Methods

Method: (setf symb-method) NEW-VALUE (SYMB-METHOD symb-method)

automatically generated writer method

Source

symbols.lisp (file)

Generic Function: symb-name SYMB-OBJECT

Returns the symbol-name of the symbol.

See SYMB-OBJECT

Package

staple

Source

symbols.lisp (file)

Methods

Method: symb-name (SYMB symb-object)

Generic Function: symb-package SYMB-OBJECT

Returns the symbol-package of the symbol.

Package

staple

Source

symbols.lisp (file)

Writer

(setf symb-package) (generic function)

Methods

Method: symb-package (SYMB-OBJECT symb-object)

automatically generated reader method

Generic Function: (setf symb-package) NEW-VALUE OBJECT

Package

staple

Reader

symb-package (generic function)

Methods

Method: (setf symb-package) NEW-VALUE (SYMB-OBJECT symb-object)

automatically generated writer method

Source

symbols.lisp (file)

Generic Function: symb-qualifiers SYMB-OBJECT

Returns the qualifiers of the method or NIL.

See SYMB-METHOD

Package

staple

Source

symbols.lisp (file)

Methods

Method: symb-qualifiers (SYMB symb-method)

Method: symb-qualifiers (SYMB symb-object)

Generic Function: symb-scope SYMB-OBJECT

Returns whether the symbol is :INHERITED, :EXTERNAL or :INTERNAL.

See SYMB-OBJECT

Package

staple

Source

symbols.lisp (file)

Methods

Method: symb-scope (SYMB symb-object)

Generic Function: symb-symbol OBJECT

Returns the actual symbol backed by the symbol object.

Package

staple

Writer

(setf symb-symbol) (generic function)

Methods

Method: symb-symbol (SYMB-OBJECT symb-object)

automatically generated reader method

Source

symbols.lisp (file)

Generic Function: (setf symb-symbol) NEW-VALUE OBJECT

Package

staple

Reader

symb-symbol (generic function)

Methods

Method: (setf symb-symbol) NEW-VALUE (SYMB-OBJECT symb-object)

automatically generated writer method

Source

symbols.lisp (file)

Generic Function: symb-true-symbol SYMB-OBJECT

Returns the the true symbol of the symbol.
Preferable over SYMB-SYMBOL as it takes SETF-function names into account.

See SYMB-OBJECT

Package

staple

Source

symbols.lisp (file)

Methods

Method: symb-true-symbol (SYMB symb-object)

Generic Function: symb-type SYMB-OBJECT

Returns the string-name of the kind of object it represents.

See SYMB-OBJECT

Package

staple

Source

symbols.lisp (file)

Methods

Method: symb-type (SYMB symb-object)

Generic Function: symb-type-order SYMB

For a given symbol type name, returns an integer representing the priority of the type in an ordering.

See SYMB-OBJECT

Package

staple

Source

symbols.lisp (file)

Methods

Method: symb-type-order SYMB

Method: symb-type-order (SYMB symb-object)

Method: symb-type-order (SYMB (eql symb-constant))

Method: symb-type-order (SYMB (eql symb-special))

Method: symb-type-order (SYMB (eql symb-variable))

Method: symb-type-order (SYMB (eql symb-class))

Method: symb-type-order (SYMB (eql symb-condition))

Method: symb-type-order (SYMB (eql symb-structure))

Method: symb-type-order (SYMB (eql symb-type))

Method: symb-type-order (SYMB (eql symb-accessor))

Method: symb-type-order (SYMB (eql symb-function))

Method: symb-type-order (SYMB (eql symb-generic))

Method: symb-type-order (SYMB (eql symb-method))

Method: symb-type-order (SYMB (eql symb-macro))

Method: symb-type-order (SYMB (eql symb-object))

Generic Function: symb< A B

Used to sort symbols alphabetically.
Special treatment is done so that generic functions should always appear before their methods.

See SYMB-OBJECT

Package

staple

Source

symbols.lisp (file)

Methods

Method: symb< (A symb-method) (B symb-generic)

Method: symb< (A symb-generic) (B symb-method)

Method: symb< (A symb-object) (B symb-object)

Generic Function: system-options SYSTEM

Returns options to use when stapling the given system.

The following options are accepted:

:asdf — The ASDF System object to generate. If this differs
from the argument to SYSTEM-OPTIONS, GENERATE is
called anew with the same arguments, but the system
being updated to the one in the options.
Defaults to the input system.
:compact — Whether to compact (remove whitespace) from the
resulting documentation file.
Defaults to T.
:documentation — The pathname to the primary documentation file to
output into the generated file’s documentation section.
Defaults to FIND-DOCUMENTATION-FILE
:logo — The relative path to a logo to include in the
generated file’s header.
Defaults to FIND-LOGO-FILE relative to the source
directory of the system.
:name — The name to use for the system.
Defaults to ASDF:COMPONENT-NAME
:out — The pathname for the generated file.
Defaults to "about.html" relative to the source
directory of the system.
:packages — The list of packages to output to the symbol index
in the generated file.
Defaults to SYSTEM-PACKAGES
:template — The Clip template file to use to generate the
documentation file with.
Defaults to *DEFAULT-TEMPLATE*
:if-exists — What to do if the generated file already exists on
the file system.
Defaults to :ERROR

These options may be overridden by the arguments that are passed to
GENERATE.

The methods are combined by APPEND, with the most specific method coming
first. This means that you can override certain options by creating a
method for your system and outputting a plist with the option you want
to override.

For example, the following method would specify an alternate template
file to use, and a different exists behaviour.

(defmethod staple:system-options append ((system (eql (asdf:find-system :my-sys)))) (list :template (system-relative-pathname system "my-clip-template.ctml") :if-exists :supersede))

You may specify additional arguments that are not shown above. They will
all be passed to Clip’s template generation, and may thus be accessed
from within the template.

See GENERATE
See FIND-DOCUMENTATION-FILE
See FIND-LOGO-FILE
See ASDF:COMPONENT-NAME
See ASDF:SYSTEM-SOURCE-DIRECTORY
See SYSTEM-PACKAGES
See *DEFAULT-TEMPLATE*
See CL:OPEN

Package

staple

Source

stapler.lisp (file)

Method Combination

append (short method combination)

Options: :most-specific-first

Methods

Method: system-options (SYSTEM system) append

Generic Function: system-package-symbols SYSTEM PACKAGE

Returns the applicable set of symb objects for the package under the given system.

This allows customising which symbs should be emitted for a given package
and system under construction. By default this simply includes all of the
symb objects for the package, produced by PACKAGE-SYMBOL-OBJECTS.

Note that the emitted symbols in the document may be filtered further still
by the use of the exclude attribute.

See SYMB-OBJECT
See PACKAGE-SYMBOL-OBJECTS
See DO-SYMBOLS

Package

staple

Source

stapler.lisp (file)

Methods

Method: system-package-symbols (SYSTEM system) PACKAGE

Generic Function: system-packages SYSTEM

Accessor to the list of packages associated to the system.

If the loading process of the system happened before staple was loaded, a heuristic is used where a package name is returned that corresponds to the system’s name. If the system was loaded after staple, this should return the precise list of packages that the system defined.

If no corresponding package name could be found, an error is signalled.

See *SYSTEM-PACKAGES*

Package

staple-package-recording

Writer

(setf system-packages) (function)

Methods

Method: system-packages (SYSTEM symbol)

Source

recording.lisp (file)

Method: system-packages (SYSTEM system)

Source

recording.lisp (file)

5.1.5 Classes

Class: symb-accessor ()

Object representing an accessor.

See SYMB-FUNCTION

Package

staple

Source

symbols.lisp (file)

Direct superclasses

symb-function (class)

Direct methods

symb-is (method)

Class: symb-class ()

Object representing a class.

See SYMB-TYPE

Package

staple

Source

symbols.lisp (file)

Direct superclasses

symb-type (class)

Direct subclasses

symb-structure (class)

Direct methods

symb-is (method)

Class: symb-condition ()

Object representing a condition.

See SYMB-TYPE

Package

staple

Source

symbols.lisp (file)

Direct superclasses

symb-type (class)

Direct methods

symb-is (method)

Class: symb-constant ()

Object representing a constant.

See SYMB-VARIABLE

Package

staple

Source

symbols.lisp (file)

Direct superclasses

symb-variable (class)

Direct methods

symb-is (method)

Class: symb-function ()

Object representing a function.

See SYMB-FUNCTION
See SYMB-ARGUMENTS
See SYMB-OBJECT

Package

staple

Source

symbols.lisp (file)

Direct superclasses

symb-object (class)

Direct subclasses

• symb-accessor (class)
• symb-macro (class)
• symb-generic (class)
• symb-method (class)

Direct methods

• symb-is (method)
• symb-documentation (method)
• symb-arguments (method)

Class: symb-generic ()

Object representing a generic function.

See SYMB-FUNCTION

Package

staple

Source

symbols.lisp (file)

Direct superclasses

symb-function (class)

Direct methods

• symb< (method)
• symb< (method)
• symb-is (method)
• symb-arguments (method)

Class: symb-macro ()

Object representing a macro.

See SYMB-FUNCTION

Package

staple

Source

symbols.lisp (file)

Direct superclasses

symb-function (class)

Direct methods

• symb-is (method)
• symb-function (method)

Class: symb-method ()

Object representing a generic function method.

See SYMB-FUNCTION

Package

staple

Source

symbols.lisp (file)

Direct superclasses

symb-function (class)

Direct methods

• symb< (method)
• symb< (method)
• symb-is (method)
• symb-documentation (method)
• symb-arguments (method)
• symb-qualifiers (method)
• print-object (method)
• symb-method (method)
• symb-method (method)

Direct slots

Slot: method

Initargs

:method

Initform

(error "method required")

Readers

symb-method (generic function)

Writers

(setf symb-method) (generic function)

Class: symb-object ()

Base class for symbol representation.

See SYMB-SYMBOL
See SYMB-PACKAGE
See SYMB-NAME
See SYMB-TYPE
See SYMB-ID
See SYMB-SCOPE
See SYMB-DOCUMENTATION
See SYMB-IS
See SYMB<
See SYMB-TYPE-ORDER
See SYMB-TYPE<

Package

staple

Source

symbols.lisp (file)

Direct superclasses

standard-object (class)

Direct subclasses

• symb-type (class)
• symb-variable (class)
• symb-function (class)

Direct methods

• clip (method)
• symb-type-order (method)
• symb< (method)
• symb-is (method)
• symb-is (method)
• symb-is (method)
• symb-arguments (method)
• symb-qualifiers (method)
• symb-scope (method)
• symb-id (method)
• symb-type (method)
• symb-function (method)
• symb-name (method)
• symb-true-symbol (method)
• print-object (method)
• initialize-instance (method)
• (setf symb-package) (method)
• symb-package (method)
• symb-symbol (method)
• symb-symbol (method)

Direct slots

Slot: symbol

Initargs

:symbol

Initform

(error "symbol required")

Readers

symb-symbol (generic function)

Writers

(setf symb-symbol) (generic function)

Slot: package

Initargs

:package

Readers

symb-package (generic function)

Writers

(setf symb-package) (generic function)

Class: symb-special ()

Object representing a special variable.

See SYMB-VARIABLE

Package

staple

Source

symbols.lisp (file)

Direct superclasses

symb-variable (class)

Direct methods

symb-is (method)

Class: symb-structure ()

Object representing a structure.

See SYMB-TYPE

Package

staple

Source

symbols.lisp (file)

Direct superclasses

symb-class (class)

Direct methods

• symb-is (method)
• symb-documentation (method)

Class: symb-type ()

Object representing a type.

See SYMB-OBJECT

Package

staple

Source

symbols.lisp (file)

Direct superclasses

symb-object (class)

Direct subclasses

• symb-condition (class)
• symb-class (class)

Direct methods

• symb-is (method)
• symb-documentation (method)
• symb-arguments (method)

Class: symb-variable ()

Object representing a variable.

See SYMB-OBJECT

Package

staple

Source

symbols.lisp (file)

Direct superclasses

symb-object (class)

Direct subclasses

• symb-special (class)
• symb-constant (class)

Direct methods

• symb-is (method)
• symb-documentation (method)

5.2 Internal definitions

5.2.1 Special variables

Special Variable: *converters*

Hash table to contain the converter functions.

Package

staple

Source

symbols.lisp (file)

Special Variable: *current-packages*

List of packages being processed by the template.
This is to used to figure out whether a symbol can be found on the documentation page when referring to it through RESOLVE-SYMBOL-DOCUMENTATION.

Package

staple

Source

clip.lisp (file)

Special Variable: *loaded-extensions*

Package

staple

Source

stapler.lisp (file)

Special Variable: *root-clipboard*

Side-storage in order to allow accessing of the lower-level clipboard from within different clipboard environments.

See ROOT

Package

staple

Source

stapler.lisp (file)

Special Variable: *system-under-construction*

Package

staple

Source

clip.lisp (file)

5.2.2 Functions

Function: %is-excluded SYMB EXCLUDE

Return T if the given symb is included in the list of excluded symbol types.

See SYMB-IS

Package

staple

Source

clip.lisp (file)

Function: compact NODE

Compact the given plump node by stripping away as much potentially useless whitespace in inner text nodes as possible.

Package

staple

Source

stapler.lisp (file)

Function: ensure-system SYSTEM

Package

staple

Source

stapler.lisp (file)

Function: load-extension SYSTEM &optional EXTENSION

Package

staple

Source

stapler.lisp (file)

Function: merge-plist OVERRIDE BASE

Package

staple

Source

stapler.lisp (file)

Function: parse-block-symbols HTML

Attempt to find all relevant function call symbols in the HTML block and replace them with links to the corresponding documentation anchor.

Package

staple

Source

clip.lisp (file)

Function: parse-lone-symbols HTML

Attempt to find all symbols that refer to a documented symbol and replace them with links to the corresponding documentation anchor.

Package

staple

Source

clip.lisp (file)

Function: present THING

Return a string representation of the thing that is appropriate for use in the documentation output.

Package

staple

Source

clip.lisp (file)

Function: present-arguments THING &optional LAMBDA-LIST-PARENS

Present the list of arguments in an appropriate way.

See PRESENT

Package

staple

Source

clip.lisp (file)

Function: present-improper-list LIST

Present a list, even an improper one.

See PRESENT

Package

staple

Source

clip.lisp (file)

Function: present-qualifiers THING

Present the list of qualifiers in an appropriate way.

See PRESENT

Package

staple

Source

clip.lisp (file)

Function: root FIELD

Shorthand for (CLIP *ROOT-CLIPBOARD* FIELD)

See CLIP:CLIP
See *ROOT-CLIPBOARD*

Package

staple

Source

stapler.lisp (file)

Function: string-starts-with STRING SUB

Returns T if the string starts with sub, NIL otherwise.

Package

staple

Source

clip.lisp (file)

Function: strip-arglist ARGLIST

Package

staple

Source

clip.lisp (file)

Function: symbol-accessor-p SYMBOL

Returns T if the symbol is a function and setter.

Package

staple

Source

symbols.lisp (file)

Function: symbol-macro-p SYMBOL

Returns T if the symbol is a macro.

Package

staple

Source

symbols.lisp (file)

Function: symbol-special-p SYMBOL

REturns T if the symbol is a special variable.

Package

staple

Source

symbols.lisp (file)

Function: symbol-type-p SYMBOL

Package

staple

Source

symbols.lisp (file)

Function: symbol-typedef-p SYMBOL

Package

staple

Source

symbols.lisp (file)

5.2.3 Generic functions

Generic Function: symb-is SYMB-OBJECT MASK

Checks if the symbol matches the mask.
The mask should be a keyword of either :INHERITED, :INTERNAL, :EXTERNAL or one of the symb-object types.

See SYMB-OBJECT

Package

staple

Source

symbols.lisp (file)

Methods

Method: symb-is SYMB MASK

Method: symb-is (SYMB symb-object) (MASK (eql inherited))

Method: symb-is (SYMB symb-object) (MASK (eql internal))

Method: symb-is (SYMB symb-object) (MASK (eql external))

Method: symb-is (SYMB symb-type) (MASK (eql type))

Method: symb-is (SYMB symb-variable) (MASK (eql variable))

Method: symb-is (SYMB symb-function) (MASK (eql function))

Method: symb-is (SYMB symb-accessor) (MASK (eql accessor))

Method: symb-is (SYMB symb-macro) (MASK (eql macro))

Method: symb-is (SYMB symb-generic) (MASK (eql generic))

Method: symb-is (SYMB symb-method) (MASK (eql method))

Method: symb-is (SYMB symb-structure) (MASK (eql structure))

Method: symb-is (SYMB symb-condition) (MASK (eql condition))

Method: symb-is (SYMB symb-class) (MASK (eql class))

Method: symb-is (SYMB symb-special) (MASK (eql special))

Method: symb-is (SYMB symb-constant) (MASK (eql constant))

Appendix A Indexes

A.1 Concepts

A.2 Functions