The mgl-pax Reference Manual

4.1.1 mgl-pax/mgl-pax.asd

Source

mgl-pax.asd.

Parent Component

mgl-pax (system).

ASDF Systems

mgl-pax.

---

4.1.2 mgl-pax.asdf/mgl-pax.asdf.asd

Source

mgl-pax.asdf.asd.

Parent Component

mgl-pax.asdf (system).

ASDF Systems

mgl-pax.asdf.

---

4.1.3 mgl-pax-bootstrap/mgl-pax-bootstrap.asd

Source

mgl-pax-bootstrap.asd.

Parent Component

mgl-pax-bootstrap (system).

ASDF Systems

mgl-pax-bootstrap.

---

4.1.4 autoload/autoload.asd

Source

autoload.asd.

Parent Component

autoload (system).

ASDF Systems

autoload.

---

4.1.5 dref/dref.asd

Source

dref.asd.

Parent Component

dref (system).

ASDF Systems

dref.

---

4.1.6 mgl-pax/src/base//pax.lisp

Source

mgl-pax.asd.

Parent Component

src/base/ (module).

Public Interface

• install-pax-elisp (function).
• note (macro).
• section-entries (function).
• section-link-title-to (function).

Internals

• %note (structure).
• %note-children (reader).
• (setf %note-children) (writer).
• %note-join (reader).
• (setf %note-join) (writer).
• %note-name (reader).
• (setf %note-name) (writer).
• %note-p (function).
• %note-package (reader).
• (setf %note-package) (writer).
• *pax-version* (special variable).
• @background (special variable).
• @basics (special variable).
• @emacs-functionality (special variable).
• @emacs-keys (special variable).
• @emacs-loading (special variable).
• @emacs-quicklisp (special variable).
• @emacs-setup (special variable).
• @introduction (special variable).
• @links-and-systems (special variable).
• @m-. (special variable).
• @markdown (special variable).
• @oaoo (special variable).
• @pax-manual (special variable).
• @quicklisp (special variable).
• @slime (special variable).
• @w3m (special variable).
• check-pax-elisp-version (function).
• copy-%note (function).
• ensure-list (function).
• expand-nested-note (function).
• handle-note (function).
• make-%note (function).
• mark-this-source-location (macro).
• parse-note-body (function).
• section-entry-to-xref (function).

---

4.1.7 mgl-pax/src/base//extension-api.lisp

Dependency

pax.lisp (file).

Source

mgl-pax.asd.

Parent Component

src/base/ (module).

Public Interface

document-object* (generic function).

Internals

• @adding-new-locatives (special variable).
• @extension-api (special variable).
• @glossary-terms (special variable).
• @locative-aliases (special variable).
• @sections (special variable).

---

4.1.8 mgl-pax/src/base//document-early.lisp

Dependency

extension-api.lisp (file).

Source

mgl-pax.asd.

Parent Component

src/base/ (module).

Public Interface

• *browse-html-style* (special variable).
• *document-base-url* (special variable).
• *document-downcase-uppercase-code* (special variable).
• *document-fancy-html-navigation* (special variable).
• *document-html-bottom-blocks-of-links* (special variable).
• *document-html-charset* (special variable).
• *document-html-default-style* (special variable).
• *document-html-head* (special variable).
• *document-html-lang* (special variable).
• *document-html-max-navigation-table-of-contents-level* (special variable).
• *document-html-sidebar* (special variable).
• *document-html-top-blocks-of-links* (special variable).
• *document-hyperspec-root* (special variable).
• *document-link-code* (special variable).
• *document-link-sections* (special variable).
• *document-link-to-hyperspec* (special variable).
• *document-mark-up-signatures* (special variable).
• *document-max-numbering-level* (special variable).
• *document-max-table-of-contents-level* (special variable).
• *document-min-link-hash-length* (special variable).
• *document-normalize-packages* (special variable).
• *document-pandoc-pdf-header-includes* (special variable).
• *document-pandoc-pdf-metadata-block* (special variable).
• *document-pandoc-pdf-options* (special variable).
• *document-pandoc-program* (special variable).
• *document-text-navigation* (special variable).
• *document-tight* (special variable).
• *document-uppercase-is-code* (special variable).
• *document-url-versions* (special variable).
• *format* (special variable).
• doctitle (function).
• doctitle* (generic function).
• document (function).
• document-docstring (function).
• documenting-definition (macro).
• escape-markdown (function).
• escape-tex (function).
• make-git-source-uri-fn (function).
• make-github-source-uri-fn (function).
• prin1-to-markdown (function).
• unresolvable-reflink (condition).
• update-asdf-system-html-docs (function).
• update-asdf-system-readmes (function).
• update-pax-world (function).
• with-dislocated-names (macro).
• with-heading (macro).

Internals

• *documenting-dref* (special variable).
• *git-version-for-test* (special variable).
• @extending-document (special variable).
• @github-workflow (special variable).
• asdf-system-git-root-and-version (function).
• call-with-heading (function).
• convert-source-location (function).
• downcasingp (function).
• end-of-register-doc-example (special variable).
• file-position-to-line-number (function).
• git-root (function).
• git-version (function).
• in-git-p (function).
• line-file-positions (function).
• pathname-as-directory (function).
• pax-pages (function).
• pax-sections (function).
• print-dref-bullet (function).
• with-local-references (macro).

---

4.1.9 mgl-pax/src/base//web-early.lisp

Dependency

document-early.lisp (file).

Source

mgl-pax.asd.

Parent Component

src/base/ (module).

Public Interface

ensure-web-server (function).

---

4.1.10 mgl-pax/src/base//transcribe-early.lisp

Dependency

web-early.lisp (file).

Source

mgl-pax.asd.

Parent Component

src/base/ (module).

Public Interface

• *transcribe-check-consistency* (special variable).
• *transcribe-syntaxes* (special variable).
• delete-comments (function).
• delete-trailing-whitespace (function).
• squeeze-whitespace (function).
• transcribe (function).
• transcription-consistency-error (condition).
• transcription-error (condition).

Internals

ensure-transcribe-loaded (function).

---

4.1.11 mgl-pax/src/base//locatives-early.lisp

Dependency

transcribe-early.lisp (file).

Source

mgl-pax.asd.

Parent Component

src/base/ (module).

Internals

@pax-locatives (special variable).

---

4.1.12 mgl-pax.asdf/asdf.lisp

Source

mgl-pax.asdf.asd.

Parent Component

mgl-pax.asdf (system).

Packages

mgl-pax.asdf.

Public Interface

• call-with-wrappers (function).
• compile-pax (function).
• compile-per-file (function).
• compile-with-source-info (function).
• compose-wrappers (function).

Internals

compile-without-some-warnings (function).

---

4.1.13 mgl-pax-bootstrap/src/bootstrap//package.lisp

Source

mgl-pax-bootstrap.asd.

Parent Component

src/bootstrap/ (module).

Packages

mgl-pax.

---

4.1.14 mgl-pax-bootstrap/src/bootstrap//basics.lisp

Dependency

package.lisp (file).

Source

mgl-pax-bootstrap.asd.

Parent Component

src/bootstrap/ (module).

Public Interface

• *discard-documentation-p* (special variable).
• define-glossary-term (macro).
• define-package (macro).
• defsection (macro).
• exportable-locative-type-p (generic function).
• exportable-reference-p (generic function).
• glossary-term (class).
• glossary-term-name (reader method).
• glossary-term-title (reader method).
• glossary-term-url (reader method).
• print-object (method).
• section (class).
• section-name (reader method).
• section-package (reader method).
• section-readtable (reader method).
• section-title (reader method).

Internals

• check-link-title-to (function).
• check-section-entries (function).
• export-some-symbols (function).
• exportablep (function).
• glossary-term-docstring (reader method).
• malformed-ref-list-in-section-error (function).
• prin1-to-string/fully-qualified (function).
• ref-list-p (function).
• symbol-accessible-in-package-p (function).

---

4.1.15 mgl-pax-bootstrap/src/bootstrap//pax-world.lisp

Dependency

basics.lisp (file).

Source

mgl-pax-bootstrap.asd.

Parent Component

src/bootstrap/ (module).

Public Interface

register-doc-in-pax-world (function).

Internals

• *registered-pax-world-docs* (special variable).
• @pax-world (special variable).
• list-designator (function).

---

4.1.16 autoload/package.lisp

Source

autoload.asd.

Parent Component

autoload (system).

Packages

autoload.

---

4.1.17 autoload/autoload.lisp

Dependency

package.lisp (file).

Source

autoload.asd.

Parent Component

autoload (system).

Public Interface

• autoload (macro).
• defun/autoloaded (macro).
• defvar/autoloaded (macro).

Internals

• set-symbol-global-value (function).
• special-variable-name-p (function).
• (setf symbol-global-value) (setf expander).
• symbol-global-value (function).
• symbol-globally-boundp (function).
• without-redefinition-warnings (macro).

---

4.1.18 dref/src/base//package.lisp

Source

dref.asd.

Parent Component

src/base/ (module).

Packages

• dref.
• dref-ext.

Public Interface

• exportable-reference-p (method).
• exportable-reference-p (method).

Internals

dref-std-env (function).

---

4.1.19 dref/src/base//util.lisp

Dependency

package.lisp (file).

Source

dref.asd.

Parent Component

src/base/ (module).

Internals

• ensure-list* (function).
• find-system* (function).
• load-time-value* (macro).
• macro-arg-names (function).
• member-type-specifier-p (function).
• nth-value-or* (macro).
• on-unknown-type-warning (macro).
• parse-body-declare (function).
• parse-body-docstring (function).
• satisfies-type-specifier-p (function).
• succeedsp (macro).
• type-specifier-name (function).
• valid-satisisfies-type-specifier-args-p (function).
• valid-type-specifier-p (function).

---

4.1.20 dref/src/base//dref.lisp

Dependency

util.lisp (file).

Source

dref.asd.

Parent Component

src/base/ (module).

Public Interface

• arglist (function).
• docstring (function).
• dref (function).
• dref (class).
• dref-locative (reader method).
• dref-locative-args (function).
• dref-locative-type (function).
• dref-name (reader method).
• dref-origin (reader method).
• initialize-instance (method).
• lisp-locative-types (function).
• locate (function).
• locate-error (condition).
• locative-aliases (function).
• locative-args (function).
• locative-type (function).
• locative-types (function).
• print-object (method).
• pseudo-locative-types (function).
• resolve (function).
• resolve-error (condition).
• source-location (function).
• xref (function).
• xref (class).
• xref-locative (reader method).
• xref-locative-args (function).
• xref-locative-type (function).
• xref-name (reader method).
• xref= (function).

Internals

• *lisp-locative-types* (special variable).
• *locate-error-ignored* (special variable).
• *locative-aliases* (special variable).
• *locative-types* (special variable).
• *locative-types-and-aliases* (special variable).
• *pseudo-locative-types* (special variable).
• @basic-operations (special variable).
• @definition (special variable).
• @dissecting-references (special variable).
• @dref-manual (special variable).
• @dtypes (special variable).
• @introduction (special variable).
• @links-and-systems (special variable).
• @listing-definitions (special variable).
• @locative (special variable).
• @locative-type (special variable).
• @name (special variable).
• @presentation (special variable).
• @reference (special variable).
• @references (special variable).
• @references-glossary (special variable).
• @reverse-definition-order (special variable).
• check-lisp-locative-type (function).
• check-locative-type (function).
• declare-locative-alias (function).
• declare-locative-type (function).
• declare-pseudo-locative-type (function).
• ensure-dref-loaded (function).
• invalid-lisp-locative-type (function).
• invalid-locative-type (function).
• lisp-locative-type-p (function).
• locate-error-message (reader method).
• locate-error-message-args (reader method).
• locate-error-object (reader method).
• locative-type-p (function).
• normalize-locative (function).
• nth-value-or-with-obj-or-def (macro).
• order-locative-types (function).
• removef (macro).
• reorder-locative-types (function).
• resolve-error-dref (reader method).
• resolve-error-message (reader method).
• swank-error-value-p (function).
• with-locate-error-ignored (macro).
• xref-name= (function).

---

4.1.21 dref/src/base//extension-api.lisp

Dependency

dref.lisp (file).

Source

dref.asd.

Parent Component

src/base/ (module).

Public Interface

• *check-locate* (special variable).
• arglist* (generic function).
• call-cast (macro).
• call-locator (macro).
• call-lookup (macro).
• check-locative-args (macro).
• define-cast (macro).
• define-definer-for-symbol-locative-type (macro).
• define-locative-alias (macro).
• define-locative-type (macro).
• define-locator (macro).
• define-lookup (macro).
• define-pseudo-locative-type (macro).
• define-symbol-locative-type (macro).
• definition-properties (function).
• (setf definition-property) (setf expander).
• definition-property (function).
• delete-definition-properties (function).
• delete-definition-property (function).
• docstring* (generic function).
• dref-class (function).
• locate-error (function).
• locative-type-direct-subs (function).
• locative-type-direct-supers (function).
• map-definitions-of-name (generic function).
• map-definitions-of-type (generic function).
• move-definition-properties (function).
• resolve* (generic function).
• resolve-error (function).
• source-location* (generic function).
• symbol-locative-dref (class).
• this-source-location (macro).

Internals

• %declare-locative-type (function).
• %define-locative-type (macro).
• %locate (function).
• %locative-type-class-info (function).
• %locative-type-direct-subs (function).
• %locative-type-direct-supers (function).
• *definition-properties* (special variable).
• *dref-class-to-locative-type* (special variable).
• *dummy-locate-error* (special variable).
• *locating-object* (special variable).
• *locative-type-to-class-info* (special variable).
• *resolving-dref* (special variable).
• @canonicalization (special variable).
• @cast-name-change (special variable).
• @default-downcast (special variable).
• @defining-locative-types (special variable).
• @defining-lookups-locators-and-casts (special variable).
• @definition-properties (special variable).
• @extending-dref (special variable).
• @extending-everything-else (special variable).
• @extending-locate (special variable).
• @extension-tutorial (special variable).
• @initial-definition (special variable).
• @locative-type-hierarchy (special variable).
• @symbol-locatives (special variable).
• canonicalize-dref (function).
• check-body-docstring (function).
• check-cast-name-change (function).
• check-docstring-only-body (function).
• check-lisp-and-pseudo-are-distinct (function).
• check-locative-args* (function).
• check-locator-return-values (function).
• definition-property-key (function).
• dref* (generic function).
• dref-class-superclasses (function).
• dref-class-to-locative-type (function).
• expand-define-definer-for-symbol-as-locative-definer-body (function).
• find-subclass-of (function).
• locate* (generic function).
• locate-initial-definition (function).
• locate-with-first-locator (function).
• locate-with-lookup (function).
• locative-subtype-p (function).
• map-names-for-type (function).
• maybe-default-dref-class (function).
• set-definition-property (function).
• update-class-info (function).

---

4.1.22 dref/src/base//early.lisp

Dependency

extension-api.lisp (file).

Source

dref.asd.

Parent Component

src/base/ (module).

Public Interface

• define-dtype (macro).
• define-restart (macro).
• definitions (function).
• dref-apropos (function).
• dtypep (function).
• make-source-location (function).
• restart-dref (class).
• source-location-adjusted-file-position (function).
• source-location-buffer (function).
• source-location-buffer-position (function).
• source-location-file (function).
• source-location-file-position (function).
• source-location-p (function).
• source-location-snippet (function).

Internals

• *dtype-expanders* (special variable).
• dref* (method).
• swank-source-location* (function).
• translate-sb-source-location (function).

---

6.1.1 Special variables

Special Variable: *browse-html-style* ¶

Package

mgl-pax.

Source

document-early.lisp.

Special Variable: *check-locate* ¶

Enable runtime verification of invariants during LOCATE calls. This carries a performance penalty and is intended for testing and debugging.

In particular, enforce the rule of @CAST-NAME-CHANGE and that [ check-locator-return-values function][docstring]

Package

dref-ext.

Source

extension-api.lisp.

Special Variable: *discard-documentation-p* ¶

The default value of DEFSECTION’s DISCARD-DOCUMENTATION-P argument. One may want to set *DISCARD-DOCUMENTATION-P* to true before building a binary application.

Package

mgl-pax.

Source

basics.lisp.

Special Variable: *document-base-url* ¶

Package

mgl-pax.

Source

document-early.lisp.

Special Variable: *document-downcase-uppercase-code* ¶

Package

mgl-pax.

Source

document-early.lisp.

Special Variable: *document-fancy-html-navigation* ¶

Package

mgl-pax.

Source

document-early.lisp.

Special Variable: *document-html-bottom-blocks-of-links* ¶

Package

mgl-pax.

Source

document-early.lisp.

Special Variable: *document-html-charset* ¶

Package

mgl-pax.

Source

document-early.lisp.

Special Variable: *document-html-default-style* ¶

Package

mgl-pax.

Source

document-early.lisp.

Special Variable: *document-html-head* ¶

Package

mgl-pax.

Source

document-early.lisp.

Special Variable: *document-html-lang* ¶

Package

mgl-pax.

Source

document-early.lisp.

Special Variable: *document-html-max-navigation-table-of-contents-level* ¶

Package

mgl-pax.

Source

document-early.lisp.

Special Variable: *document-html-sidebar* ¶

Package

mgl-pax.

Source

document-early.lisp.

Special Variable: *document-html-top-blocks-of-links* ¶

Package

mgl-pax.

Source

document-early.lisp.

Special Variable: *document-hyperspec-root* ¶

Package

mgl-pax.

Source

document-early.lisp.

Special Variable: *document-link-code* ¶

Package

mgl-pax.

Source

document-early.lisp.

Special Variable: *document-link-sections* ¶

Package

mgl-pax.

Source

document-early.lisp.

Special Variable: *document-link-to-hyperspec* ¶

Package

mgl-pax.

Source

document-early.lisp.

Special Variable: *document-mark-up-signatures* ¶

Package

mgl-pax.

Source

document-early.lisp.

Special Variable: *document-max-numbering-level* ¶

Package

mgl-pax.

Source

document-early.lisp.

Special Variable: *document-max-table-of-contents-level* ¶

Package

mgl-pax.

Source

document-early.lisp.

Special Variable: *document-min-link-hash-length* ¶

Package

mgl-pax.

Source

document-early.lisp.

Special Variable: *document-normalize-packages* ¶

Package

mgl-pax.

Source

document-early.lisp.

Special Variable: *document-pandoc-pdf-header-includes* ¶

Package

mgl-pax.

Source

document-early.lisp.

Special Variable: *document-pandoc-pdf-metadata-block* ¶

Package

mgl-pax.

Source

document-early.lisp.

Special Variable: *document-pandoc-pdf-options* ¶

Package

mgl-pax.

Source

document-early.lisp.

Special Variable: *document-pandoc-program* ¶

Package

mgl-pax.

Source

document-early.lisp.

Special Variable: *document-text-navigation* ¶

Package

mgl-pax.

Source

document-early.lisp.

Special Variable: *document-tight* ¶

Package

mgl-pax.

Source

document-early.lisp.

Special Variable: *document-uppercase-is-code* ¶

Package

mgl-pax.

Source

document-early.lisp.

Special Variable: *document-url-versions* ¶

Package

mgl-pax.

Source

document-early.lisp.

Special Variable: *format* ¶

Bound by DOCUMENT to its FORMAT argument, this allows Markdown output to depend on the output format.

Package

mgl-pax.

Source

document-early.lisp.

Special Variable: *transcribe-check-consistency* ¶

Package

mgl-pax.

Source

transcribe-early.lisp.

Special Variable: *transcribe-syntaxes* ¶

Package

mgl-pax.

Source

transcribe-early.lisp.

---

6.1.2 Macros

Macro: autoload (name asdf-system-name &key export macro) ¶

Package

autoload.

Source

autoload.lisp.

Macro: call-cast (locative-type dref) ¶

Call the [cast][DEFINE-CAST] to LOCATIVE-TYPE with DREF.

Package

dref-ext.

Source

extension-api.lisp.

Macro: call-locator (object locative-type) ¶

Call the [locator][DEFINE-LOCATOR] for LOCATIVE-TYPE with OBJECT.

Package

dref-ext.

Source

extension-api.lisp.

Macro: call-lookup (name locative-type locative-args) ¶

Call the [lookup][DEFINE-LOOKUP] for LOCATIVE-TYPE with NAME and LOCATIVE-ARGS.

Package

dref-ext.

Source

extension-api.lisp.

Macro: check-locative-args (locative-type locative-args) ¶

Signal a LOCATE-ERROR condition if LOCATIVE-ARGS do not match the LAMBDA-LIST argument of LOCATIVE-TYPE (not evaluated).

Package

dref-ext.

Source

extension-api.lisp.

Macro: define-cast (locative-type ((dref dref-class)) &body body) ¶

Define a method of converting a @DEFINITION to another
with LOCATIVE-TYPE. When a cast’s BODY is evaluated, DREF is bound to an instance DREF-CLASS, which denotes a valid but potentially [non-canonical][ @canonicalization] definition.

Note the @DEFAULT-DOWNCAST often suffices, and defining a cast is only necessary if the [name][ @cast-name-change] or the locative args change:

“‘
(define-cast accessor ((dref reader-dref))
(let ((name (dref-name dref))
(class (second (dref-locative dref))))
(when (ignore-errors (find-accessor-slot-definition name class)) (make-instance ’accessor-dref :name name
:locative ‘(accessor ,class)))))
“‘

- LOCATIVE-TYPE is a valid @LOCATIVE-TYPE.

- If LOCATIVE-TYPE is one of PSEUDO-LOCATIVE-TYPES, then DREF-CLASS must be of another pseudo locative type.

- DREF-CLASS is either a direct _downcast_ or an potentially non-direct _upcast_.

- _Downcast:_ In this case, LOCATIVE-TYPE is one of LOCATIVE-TYPE-DIRECT-SUBS of (DREF-CLASS-TO-LOCATIVE-TYPE DREF-CLASS).

Downcasting to non-direct subtypes is done in multiple steps. Consequently,the BODY of a downcast can rely on (CLASS-OF DREF) being CLASS, not any subclass thereof.

- _Upcast:_ LOCATIVE-TYPE is different but reachable
from (DREF-CLASS-TO-LOCATIVE-TYPE DREF-CLASS) by repeatedly choosing one of LOCATIVE-TYPE-DIRECT-SUPERS. Upcasting to non-direct supertypes is done in one step.

The above are enforced at macro-expansion time.

- BODY must follow the rules in *CHECK-LOCATE*, including those in @CAST-NAME-CHANGE.

Package

dref-ext.

Source

extension-api.lisp.

Macro: define-definer-for-symbol-locative-type (name locative-type &body docstring) ¶

Define a macro with NAME that can be used to attach a lambda list, documentation, and source location to a symbol in the context of LOCATIVE-TYPE. The defined macro’s arglist is ‘(SYMBOL LAMBDA-LIST &OPTIONAL DOCSTRING)‘. LOCATIVE-TYPE is assumed to have been defined with DEFINE-SYMBOL-LOCATIVE-TYPE.

Package

dref-ext.

Source

extension-api.lisp.

Macro: define-dtype (name lambda-list &body body) ¶

Like DEFTYPE, but it may expand into other DTYPEs.

The following example defines ‘METHOD*‘ as the locative METHOD without its direct locative subtypes.

“‘common-lisp
(define-dtype method* () ’(and method (not reader) (not writer))) “‘

See DTYPEP for the semantics and also the locative DTYPE.

Package

dref.

Source

early.lisp.

Macro: define-glossary-term (name (&key title url discard-documentation-p) &body docstring) ¶

Define a global variable with NAME, and set it to a [GLOSSARY-TERM] [class] object. TITLE, URL and DOCSTRING are Markdown strings or NIL. Glossary terms are DOCUMENTed in the lightweight bullet + locative + name/title style. See the glossary entry @NAME for an example.

When a glossary term is linked to in documentation, its TITLE will be the link text instead of the name of the symbol (as with SECTIONs).

Glossary entries with a non-NIL URL are like external links: they are linked to their URL in the generated documentation. These offer a more reliable alternative to using Markdown reference links and are usually not included in SECTIONs.

When DISCARD-DOCUMENTATION-P (defaults to *DISCARD-DOCUMENTATION-P*) is true, DOCSTRING will not be recorded to save memory.

Package

mgl-pax.

Source

basics.lisp.

Macro: define-locative-alias (alias locative-type &body docstring) ¶

Define ALIAS that can be substituted for LOCATIVE-TYPE (both SYMBOLs) for the purposes of LOCATEing. LOCATIVE-TYPE must exist (i.e. be among LOCATIVE-TYPES). For example, let’s define OBJECT as an alias of the CLASS locative:

“‘
(define-locative-alias object class)
“‘

Then, LOCATEing with OBJECT will find the CLASS:

“‘
(dref ’xref ’object)
==> #<DREF XREF CLASS>
“‘

The LOCATIVE-ARGS of OBJECT (none in the above) are passed on to CLASS.

“‘
(arglist (dref ’object ’locative))
=> (&REST ARGS)
=> :DESTRUCTURING
“‘

Note that LOCATIVE-ALIASES are not LOCATIVE-TYPES and are not valid DTYPES.

Also, see PAX::@LOCATIVE-ALIASES in PAX.

Package

dref-ext.

Source

extension-api.lisp.

Macro: define-locative-type (locative-type-and-lambda-list locative-supertypes &optional docstring dref-defclass-form) ¶

Declare [LOCATIVE-TYPE][argument] as a [LOCATIVE][locative],
which is the first step in @EXTENDING-DREF.

- _Simple example_

To define a locative type called ‘DUMMY‘ that takes no arguments and is not a locative subtype of any other locative type:

“‘
(define-locative-type dummy ()
"Dummy docstring.")
“‘

With this definition, only the locatives ‘DUMMY‘ and its equivalent form ‘(DUMMY)‘ are valid. The above defines a DREF subclass called ‘DUMMY-DREF‘ in the current package. All definitions with locative type ‘DUMMY‘ and its locatives subtypes must be instances of ‘DUMMY-DREF‘.

‘(LOCATE ’DUMMY ’LOCATIVE)‘ refers to this definition. That is, ARGLIST, [DOCSTRING][function] and SOURCE-LOCATION all work on it.

- _Complex example_

‘DUMMY‘ may have arguments ‘X‘ and ‘Y‘ and inherit from locative types ‘L1‘ and ‘L2‘:

“‘
(define-locative-type (dummy x &key y) (l1 l2)
"Dummy docstring."
(defclass dummy-dref ()
((xxx :initform nil :accessor dummy-xxx))))
“‘

One may change name of ‘DUMMY-DREF‘, specify superclasses and add slots as with DEFCLASS. Behind the scenes, the DREF classes of ‘L1‘ and ‘L2‘ are added automatically to the list of superclasses.

Arguments:

- The general form of LOCATIVE-TYPE-AND-LAMBDA-LIST
is (LOCATIVE-TYPE &REST LAMBDA-LIST), where LOCATIVE-TYPE is a SYMBOL, and LAMBDA-LIST is a [destructuring lambda list][clhs]. The LOCATIVE-ARGS of [DREF][class]s with @LOCATIVE-TYPE LOCATIVE-TYPE (the argument given to this macro) always conform to this lambda list. See CHECK-LOCATIVE-ARGS.

If LOCATIVE-TYPE-AND-LAMBDA-LIST is a single symbol, then that’s interpreted as LOCATIVE-TYPE, and LAMBDA-LIST is NIL.

- LOCATIVE-SUPERTYPES is a list of @LOCATIVE-TYPEs whose DREF-CLASSes are added to prepended to the list of superclasses this definition.

Locative types defined with DEFINE-LOCATIVE-TYPE can be listed with LISP-LOCATIVE-TYPES.

Package

dref-ext.

Source

extension-api.lisp.

Macro: define-locator (locative-type ((object class)) &body body) ¶

Define a method of finding the @DEFINITION with LOCATIVE-TYPE of instances of CLASS. When a locator’s BODY is evaluated, OBJECT is bound to such an instance.

“‘
(define-locator class ((class class))
(make-instance ’class-dref :name (class-name class) :locative ’class)) “‘

- LOCATIVE-TYPE is one of LISP-LOCATIVE-TYPES. This is because PSEUDO-LOCATIVE-TYPES never RESOLVE to first-class objects.

- OBJECT is a SYMBOL.

- CLASS names a [CLASS][class] that is not a subtype of [XREF][class]. For how to convert definitions from one locative type to another, see DEFINE-CAST.

The above are enforced at macro-expansion time.

- BODY must follow the rules in *CHECK-LOCATE*.

In contrast to when the @INITIAL-DEFINITION is created from an
XREF (see DEFINE-LOOKUP), here LOCATIVE-ARGS are determined from OBJECT.

Package

dref-ext.

Source

extension-api.lisp.

Macro: define-lookup (locative-type (name locative-args) &body body) ¶

Define a method of looking up @DEFINITIONs of LOCATIVE-TYPE
with the given LOCATIVE-ARGS. Lookups are invoked by LOCATE when its OBJECT argument is an XREF with LOCATIVE-TYPE but it is not a DREF, as in the case of ‘(DREF ’PRINT ’FUNCTION)‘. When called, the variables NAME and LOCATIVE-ARGS are bound to XREF-NAME and XREF-LOCATIVE-ARGS of the XREF. LOCATIVE-ARGS is validated with CHECK-LOCATIVE-ARGS before BODY is evaluated.

“‘
(define-lookup variable (name locative-args)
(unless (special-variable-name-p name)
(locate-error))
(make-instance ’variable-dref :name name :locative ’variable)) “‘

- LOCATIVE-TYPE is a valid @LOCATIVE-TYPE.

- NAME and LOCATIVE-ARGS are both SYMBOLs.

The above are enforced at macro-expansion time.

- BODY must follow the rules in *CHECK-LOCATE*.

Package

dref-ext.

Source

extension-api.lisp.

Macro: define-package (package &rest options) ¶

This is like CL:DEFPACKAGE but silences warnings and errors signalled when the redefined package is at variance with the current state of the package. Typically this situation occurs when symbols are exported by calling EXPORT (as is the case with DEFSECTION) as opposed to adding :EXPORT forms to the DEFPACKAGE form and the package definition is subsequently reevaluated. See the section on [package variance](http://www.sbcl.org/manual/#Package-Variance) in the SBCL manual.

The bottom line is that if you rely on DEFSECTION to do the exporting, then you’d better use DEFINE-PACKAGE.

Package

mgl-pax.

Source

basics.lisp.

Macro: define-pseudo-locative-type (locative-type-and-lambda-list locative-supertypes &optional docstring dref-defclass-form) ¶

Like DEFINE-LOCATIVE-TYPE, but declare that [LOCATIVE-TYPE][argument] does not correspond to definitions in the running Lisp. Definitions with pseudo locatives are of DTYPE PSEUDO and are not listed by default by DEFINITIONS.

Locative types defined with DEFINE-PSEUDO-LOCATIVE-TYPE can be listed with PSEUDO-LOCATIVE-TYPES.

Package

dref-ext.

Source

extension-api.lisp.

Macro: define-restart (symbol lambda-list &body docstring) ¶

Associate a definition with the name of a restart, which must be a symbol. LAMBDA-LIST should be what calls like ‘(INVOKE-RESTART ’<SYMBOL> ...)‘ must conform to, but this not enforced.

PAX "defines" standard CL restarts such as USE-VALUE with DEFINE-RESTART:

“‘cl-transcript (:dynenv dref-std-env)
(first-line (source-location-snippet
(source-location (dref ’use-value ’restart))))
=> "(define-restart use-value (value)"
“‘

Note that while there is a CL:RESTART class, its instances have no docstring or source location.

Package

dref.

Source

early.lisp.

Macro: define-symbol-locative-type (locative-type-and-lambda-list locative-supertypes &optional docstring dref-class-def) ¶

Similar to DEFINE-LOCATIVE-TYPE, but it assumes that all things LOCATEable with LOCATIVE-TYPE are going to be symbols defined with a definer defined with DEFINE-DEFINER-FOR-SYMBOL-LOCATIVE-TYPE. Symbol locatives are for attaching a definition (along with arglist, documentation and source location) to a symbol in a particular context. An example will make everything clear:

“‘
(define-symbol-locative-type direction ()
"A direction is a symbol.")

(define-definer-for-symbol-locative-type define-direction direction "With DEFINE-DIRECTION, one can document what a symbol means when interpreted as a DIRECTION.")

(define-direction up ()
"UP is equivalent to a coordinate delta of (0, -1).")
“‘

After all this, ‘(DREF ’UP ’DIRECTION)‘ refers to the ‘DEFINE-DIRECTION‘ form above.

The DREF-CLASS of the defined locative type inherits from SYMBOL-LOCATIVE-DREF, which may be used for specializing when implementing new operations.

Package

dref-ext.

Source

extension-api.lisp.

Macro: defsection (name (&key package readtable export title link-title-to discard-documentation-p) &body entries) ¶

Define a documentation section and maybe export referenced symbols. A bit behind the scenes, a global variable with NAME is defined and is bound to a [SECTION][class] object. By convention, section names start with the character ‘@‘. See @INTRODUCTION for an example.

**Entries**

ENTRIES consists of docstrings and references in any order. Docstrings are arbitrary strings in Markdown format.

References are [XREF][class]s given in the form ‘(NAME LOCATIVE)‘. For example, ‘(FOO FUNCTION)‘ refers to the function ‘FOO‘, ‘(@BAR SECTION)‘ says that ‘@BAR‘ is a subsection of this
one. ‘(BAZ (METHOD (T T T)))‘ refers to the default method of the three argument generic function ‘BAZ‘. ‘(FOO FUNCTION)‘ is equivalent to ‘(FOO (FUNCTION))‘. See the DRef DREF::@INTRODUCTION for more.

The same name may occur in multiple references, typically with different locatives, but this is not required.

The references are not LOCATEd until documentation is generated, so they may refer to things yet to be defined.

**Exporting**

If EXPORT is true (the default), NAME and the @NAMEs of references among ENTRIES which are SYMBOLs are candidates for exporting. A candidate symbol is exported if

- it is [accessible][find-symbol] in PACKAGE, and

- there is a reference to it in the section being defined which is approved by EXPORTABLE-REFERENCE-P.

See DEFINE-PACKAGE if you use the export feature. The idea with confounding documentation and exporting is to force documentation of all exported symbols.

**Misc**

TITLE is a string containing Markdown or NIL. If non-NIL, it determines the text of the heading in the generated output. LINK-TITLE-TO is a reference given as an ‘(NAME LOCATIVE)‘ pair or NIL, to which the heading will link when generating HTML. If not specified, the heading will link to its own anchor.

When DISCARD-DOCUMENTATION-P (defaults to *DISCARD-DOCUMENTATION-P*) is true, ENTRIES will not be recorded to save memory.

Package

mgl-pax.

Source

basics.lisp.

Macro: defun/autoloaded (name lambda-list &body body) ¶

Package

autoload.

Source

autoload.lisp.

Macro: defvar/autoloaded (var &optional val doc) ¶

Package

autoload.

Source

autoload.lisp.

Macro: documenting-definition ((stream &key dref package readtable arglist) &body body) ¶

Write DREF to STREAM as described in *DOCUMENT-MARK-UP-SIGNATURES*, and establish DREF as a @LOCAL-DEFINITION for the processing of BODY.

- DREF defaults to the definition for which documentation is currently being generated.

- If DREF has a DOCTITLE, then it is PRINCed after the LOCATIVE-TYPE (see @MARKDOWN-IN-TITLES). Else, ‘(DREF-NAME DREF)‘ is printed subject to *DOCUMENT-DOWNCASE-UPPERCASE-CODE* but with all Markdown and @MATHJAX markup escaped.

- *PACKAGE* and *READTABLE* are bound to PACKAGE and READTABLE for the duration of printing the ARGLIST and the processing of BODY. If either is NIL, then a default value is computed as described in @PACKAGE-AND-READTABLE.

- ARGLIST:

- If it is not provided, then it defaults to (ARGLIST DREF).

- If NIL, then it is not printed.

- If it is a list, then it is must be a [lambda list][clhs] and is printed without the outermost parens and with the package names removed from the argument names.

- If its is a string, then it must be valid Markdown.

- It is not allowed to have WITH-HEADING within the [dynamic extent][clhs] of BODY.

Package

mgl-pax.

Source

document-early.lisp.

Macro: note (&body args) ¶

Define a note with an optional [NAME][argument] and an optional [DOCSTRING][argument]. The [DOCSTRING][function] of the note is its own docstring concatenated with docstrings of other notes in the lexical scope of BODY.

ARGS has the form \[‘NAME‘\] \[‘DOCSTRING‘\] BODY, where the square brackets indicate optional arguments. See below for the details of parsing ARGS.

__NOTE is experimental and as such subject to change.__

NOTE can occur in an any evaluated position without changing its BODY’s run-time behaviour or introducing any run-time overhead. [Top level forms][clhs] remain top level when whrapped in NOTE. The names of notes live in the same global namespace regardless of nesting or whether they are [top level form][clhs]s. _These properties come at the price of NOTE being weird: it defines named notes at macro-expansion time (or load time). But the definitions are idempotent, so it’s fine to macroexpand NOTE any number of times._

Notes are similar to Lisp comments, but they can be included in the documentation. In fact, notes are auto-included: a @SPECIFIC-LINK to a note is equivalent to including it with the DOCSTRING locative.

Notes are intended to help reduce the distance between code and its documentation when there is no convenient definition docstring to use nearby.

“‘cl-transcript (:dynenv pax-std-env)
(note @xxx "We change the package."
(in-package :mgl-pax))
==> #<PACKAGE "MGL-PAX">
(values (docstring (dref ’@xxx ’note)))
=> "We change the package."
“‘

Here is an example of how to overdo things:

“‘cl-transcript
(note @1+*
"This is a seriously overdone example."
(defun 1+* (x)
"[@1+* note][docstring]"
(if (stringp x)
(note (@1+*/1 :join #\Newline)
"- If X is a STRING, then it is parsed as a REAL number." (let ((obj (read-from-string x)))
(note "It is an error if X does not contain a REAL." (unless (realp obj)
(assert nil)))
(1+ obj)))
(note "- Else, X is assumed to be REAL number, and we simply add 1 to it."
(1+ x)))))

(1+* "7")
=> 8

(values (docstring (dref ’@1+* ’note)))
=> "This is a seriously overdone example.

- If X is a STRING, then it is parsed as a REAL number.
It is an error if X does not contain a REAL.

- Else, X is assumed to be REAL number, and we simply
add 1 to it."
“‘

The parsing of ARGS:

- If the first element of ARGS is not a string, then it is a NAME (a non-NIL SYMBOL) or name with options, currently destructured as ‘(NAME &KEY JOIN)‘. As in DEFSECTION and DEFINE-GLOSSARY-TERM, the convention is that NAME starts with a ‘@‘ character.

JOIN is PRINCed before the docstring of a child note is output. Its default value is a string of two newline characters.

- The next element of ARGS is a Markdown docstring. See @MARKDOWN-IN-DOCSTRINGS.

- The rest of ARGS is the BODY. If BODY is empty, then NIL is returned.

Note that named and nameless notes can contain other named or nameless notes without restriction, but nameless notes without a lexically enclosing named note are just an [implicit progn][clhs] with BODY, and their docstring is discarded.

If NOTE occurs as a [top level form][clhs], then its SOURCE-LOCATION is reliably recorded. Else, the quality of the source location varies, but it is at least within the right top level form on all implementations. On SBCL, exact source location is supported.

Package

mgl-pax.

Source

pax.lisp.

Macro: this-source-location () ¶

The value of this macro form is a function of no arguments that returns its own SOURCE-LOCATION.

Package

dref-ext.

Source

extension-api.lisp.

Macro: with-dislocated-names (names &body body) ¶

For each name in NAMES, establish a @LOCAL-DEFINITION.

Package

mgl-pax.

Source

document-early.lisp.

Macro: with-heading ((stream &key dref link-title-to) &body body) ¶

Write a Markdown heading with the DOCTITLE of DREF to STREAM.

- DREF defaults to the definition for which documentation is currently being generated.

- Nested WITH-HEADINGs produce nested headings.

- If *DOCUMENT-LINK-SECTIONS*, generate anchors based on DREF.

- LINK-TITLE-TO behaves like the LINK-TITLE-TO argument of DEFSECTION.

Package

mgl-pax.

Source

document-early.lisp.

---

6.1.3 Setf expanders

Setf Expander: (setf definition-property) (xref indicator) ¶

Package

dref-ext.

Source

extension-api.lisp.

Reader

definition-property (function).

Writer

set-definition-property (function).

---

6.1.4 Ordinary functions

Function: arglist (object) ¶

Return the arglist of the definition of OBJECT or NIL if the arglist cannot be determined.

The second return value indicates whether the arglist has been found. As the second return value, :ORDINARY indicates an [ordinary lambda list][clhs], :MACRO a [macro lambda list][clhs], :DEFTYPE a [deftype lambda list][clhs], and :DESTRUCTURING a [destructuring lambda list][clhs]. Other non-NIL values are also allowed.

“‘cl-transcript (:dynenv dref-std-env)
(arglist #’arglist)
=> (OBJECT)
=> :ORDINARY
“‘
“‘cl-transcript (:dynenv dref-std-env)
(arglist (dref ’define-locative-type ’macro))
=> (LOCATIVE-TYPE-AND-LAMBDA-LIST LOCATIVE-SUPERTYPES &OPTIONAL DOCSTRING DREF-DEFCLASS-FORM)
=> :MACRO
“‘
“‘cl-transcript (:dynenv dref-std-env)
(arglist (dref ’method ’locative))
=> (&REST QUALIFIERS-AND-SPECIALIZERS)
=> :DESTRUCTURING
“‘

This function supports [MACROs][locative], [COMPILER-MACROs][locative], [SETF][locative] functions, [FUNCTIONs][locative], [GENERIC-FUNCTIONs][locative], [METHODs][locative], [TYPEs][locative], [LOCATIVEs][locative]. Note that ARGLIST depends on the quality of SWANK-BACKEND:ARGLIST. With the exception of SBCL, which has perfect support, all Lisp implementations have minor omissions:

- DEFTYPE lambda lists on ABCL, AllegroCL, CLISP, CCL, CMUCL, ECL; - default values in MACRO lambda lists on AllegroCL;
- various edge cases involving traced functions.

Can be extended via ARGLIST*

Package

dref.

Source

dref.lisp.

Function: call-with-wrappers (wrappers fn) ¶

Package

mgl-pax.asdf.

Source

asdf.lisp.

Function: compile-pax (continuation) ¶

Package

mgl-pax.asdf.

Source

asdf.lisp.

Function: compile-per-file (continuation) ¶

Package

mgl-pax.asdf.

Source

asdf.lisp.

Function: compile-with-source-info (continuation) ¶

Package

mgl-pax.asdf.

Source

asdf.lisp.

Function: compose-wrappers (wrappers) ¶

Package

mgl-pax.asdf.

Source

asdf.lisp.

Function: definition-properties (xref) ¶

Return the properties of XREF as an association list.

Package

dref-ext.

Source

extension-api.lisp.

Function: definition-property (xref indicator) ¶

Return the value of the property associated with XREF whose name is EQL to INDICATOR. The second return value indicates whether the property was found. SETFable.

Package

dref-ext.

Source

extension-api.lisp.

Setf expander for this function

(setf definition-property).

Function: definitions (&rest args) ¶

Autoloaded function in system [dref/full][asdf:system].

Package

dref.

Source

early.lisp.

Function: delete-comments (&rest args) ¶

Autoloaded function in system [mgl-pax/transcribe][asdf:system].

Package

mgl-pax.

Source

transcribe-early.lisp.

Function: delete-definition-properties (xref) ¶

Delete all properties associated with XREF.

Package

dref-ext.

Source

extension-api.lisp.

Function: delete-definition-property (xref indicator) ¶

Delete the property associated with XREF whose name is EQL to INDICATOR. Return true if the property was found.

Package

dref-ext.

Source

extension-api.lisp.

Function: delete-trailing-whitespace (&rest args) ¶

Autoloaded function in system [mgl-pax/transcribe][asdf:system].

Package

mgl-pax.

Source

transcribe-early.lisp.

Function: docstring (object) ¶

Return the docstring from the definition of OBJECT.
As the second value, return the *PACKAGE* that was in effect when the docstring was installed or NIL if it cannot be determined (this is used by PAX:DOCUMENT when PAX::@PARSING the docstring). This function is similar in purpose to CL:DOCUMENTATION.

Note that some locative types such as [ASDF:SYSTEMS][locative] and [DECLARATIONs][locative] have no docstrings, and some Lisp implementations do not record all docstrings. The following are known to be missing:

- [COMPILER-MACRO][locative] docstrings on ABCL, AllegroCL, CCL, ECL; - [METHOD-COMBINATION][locative] docstrings on ABCL, AllegroCL.

Can be extended via DOCSTRING*.

Package

mgl-pax.

Source

dref.lisp.

Function: doctitle (&rest args) ¶

Autoloaded function in system [mgl-pax/document][asdf:system].

Package

mgl-pax.

Source

document-early.lisp.

Function: document (&rest args) ¶

Autoloaded function in system [mgl-pax/document][asdf:system].

Package

mgl-pax.

Source

document-early.lisp.

Function: document-docstring (&rest args) ¶

Autoloaded function in system [mgl-pax/document][asdf:system].

Package

mgl-pax.

Source

document-early.lisp.

Function: dref (name locative &optional errorp) ¶

Shorthand for ‘(LOCATE (XREF NAME LOCATIVE) ERRORP)‘.

Package

dref.

Source

dref.lisp.

Function: dref-apropos (&rest args) ¶

Autoloaded function in system [dref/full][asdf:system].

Package

dref.

Source

early.lisp.

Function: dref-class (locative-type) ¶

Return the name of the CLASS used to represent @DEFINITIONs with LOCATIVE-TYPE. This is always a subclass of [DREF][class]. Returns NIL if LOCATIVE-TYPE is not a valid locative type.

Note that the actual TYPE-OF a DREF is mostly intended for @EXTENDING-DREF. Hence, it is hidden when a DREF is printed:

“‘cl-transcript (:dynenv dref-std-env)
(dref ’print ’function)
==> #<DREF PRINT FUNCTION>
(type-of *)
=> FUNCTION-DREF
“‘

Due to @CANONICALIZATION, the actual type may be a proper subtype of DREF-CLASS:

“‘cl-transcript (:dynenv dref-std-env)
(dref ’documentation ’function)
==> #<DREF DOCUMENTATION GENERIC-FUNCTION>
(type-of *)
=> GENERIC-FUNCTION-DREF
(subtypep ’generic-function-dref ’function-dref)
=> T
=> T
“‘

Package

dref-ext.

Source

extension-api.lisp.

Function: dref-locative-args (dref) ¶

Package

dref.

Source

dref.lisp.

Function: dref-locative-type (dref) ¶

Package

dref.

Source

dref.lisp.

Function: dtypep (&rest args) ¶

Autoloaded function in system [dref/full][asdf:system].

Package

dref.

Source

early.lisp.

Function: ensure-web-server (&rest args) ¶

Autoloaded function in system [mgl-pax/web][asdf:system].

Package

mgl-pax.

Source

web-early.lisp.

Function: escape-markdown (&rest args) ¶

Autoloaded function in system [mgl-pax/document][asdf:system].

Package

mgl-pax.

Source

document-early.lisp.

Function: escape-tex (&rest args) ¶

Autoloaded function in system [mgl-pax/document][asdf:system].

Package

mgl-pax.

Source

document-early.lisp.

Function: install-pax-elisp (target-dir) ¶

Install ‘mgl-pax.el‘ distributed with this package in TARGET-DIR.

Package

mgl-pax.

Source

pax.lisp.

Function: lisp-locative-types () ¶

Return the locative types that correspond to Lisp definitions, which typically have SOURCE-LOCATION. These are defined with DEFINE-LOCATIVE-TYPE and DEFINE-SYMBOL-LOCATIVE-TYPE and are the constituents of DTYPE T.

This list is in @REVERSE-DEFINITION-ORDER.

Package

dref.

Source

dref.lisp.

Function: locate (object &optional errorp) ¶

Return a [DREF][class] representing the @DEFINITION of OBJECT.

OBJECT must be a supported first-class object, a DREF, or an [XREF][class]:

“‘cl-transcript (:dynenv dref-std-env)
(locate #’print)
==> #<DREF PRINT FUNCTION>
“‘
“‘cl-transcript (:dynenv dref-std-env)
(locate (locate #’print))
==> #<DREF PRINT FUNCTION>
“‘
“‘cl-transcript (:dynenv dref-std-env)
(locate (xref ’print ’function))
==> #<DREF PRINT FUNCTION>
“‘

When OBJECT is a DREF, it is simply returned.

Else, a LOCATE-ERROR is signalled if OBJECT is an XREF with an invalid @LOCATIVE, or if no corresponding definition is found. If ERRORP is NIL, then NIL is returned instead.

“‘cl-transcript (:dynenv dref-std-env)
(locate (xref ’no-such-function ’function))
.. debugger invoked on LOCATE-ERROR:
.. Could not locate NO-SUCH-FUNCTION FUNCTION.
.. NO-SUCH-FUNCTION does not name a function.
“‘
“‘cl-transcript (:dynenv dref-std-env)
(locate (xref ’print ’(function xxx)))
.. debugger invoked on LOCATE-ERROR:
.. Could not locate PRINT #’XXX.
.. Bad arguments (XXX) for locative FUNCTION with lambda list NIL. “‘
“‘cl-transcript (:dynenv dref-std-env)
(locate "xxx")
.. debugger invoked on LOCATE-ERROR:
.. Could not locate "xxx".
“‘

Use the XREF function to construct an XREF without error checking.

See DREF-EXT::@EXTENDING-LOCATE.

Package

dref.

Source

dref.lisp.

Function: locate-error (&optional format-control &rest format-args) ¶

Call this function to signal a LOCATE-ERROR condition from the [dynamic extent][clhs] of a LOCATE call, that is, from the ‘BODY‘s of DEFINE-LOOKUP, DEFINE-LOCATOR and DEFINE-CAST. It is an error to call LOCATE-ERROR elsewhere.

FORMAT-CONTROL, if non-NIL, is a [format control][clhs] for which FORMAT-ARGS are suitable.

Package

dref-ext.

Source

extension-api.lisp.

Function: locative-aliases () ¶

Return the list of locatives aliases, defined with DEFINE-LOCATIVE-ALIAS.

This list is in @REVERSE-DEFINITION-ORDER.

Package

dref.

Source

dref.lisp.

Function: locative-args (locative) ¶

Return the REST of @LOCATIVE LOCATIVE if it’s a list. If it’s a symbol, then return NIL. See @LOCATIVE.

Package

dref-ext.

Source

dref.lisp.

Function: locative-type (locative) ¶

Return @LOCATIVE-TYPE of the @LOCATIVE LOCATIVE. This is the first element of LOCATIVE if it’s a list. If it’s a symbol, it’s that symbol itself.

Package

dref-ext.

Source

dref.lisp.

Function: locative-type-direct-subs (locative-type) ¶

List the @LOCATIVE-TYPEs whose DREF-CLASSes are direct subclasses of the DREF-CLASS of LOCATIVE-TYPE. These can be considered subtypes of LOCATIVE-TYPE in the sense of DTYPEP.

This list is in @REVERSE-DEFINITION-ORDER.

Package

dref-ext.

Source

extension-api.lisp.

Function: locative-type-direct-supers (locative-type) ¶

List the @LOCATIVE-TYPEs whose DREF-CLASSes are direct superclasses of the DREF-CLASS of LOCATIVE-TYPE. These can be considered supertypes of LOCATIVE-TYPE in the sense of DTYPEP.

This is ordered as in the corresponding definition.

Package

dref-ext.

Source

extension-api.lisp.

Function: locative-types () ¶

Return a list of non-[alias][locative-aliases] locative types. This is the UNION of LISP-LOCATIVE-TYPES and PSEUDO-LOCATIVE-TYPES, which is the set of constituents of the DTYPE TOP.

This list is in @REVERSE-DEFINITION-ORDER.

Package

dref.

Source

dref.lisp.

Function: make-git-source-uri-fn (asdf-system git-forge-uri &key git-version uri-format-string) ¶

Return an object suitable as :SOURCE-URI-FN of a page spec (see
the PAGES argument of DOCUMENT). The function looks at the source location of the object passed to it, and if the location is found, the path is made relative to the top-level directory of the git checkout containing the file of the ASDF-SYSTEM and finally an \URI pointing to your git forge (such as GitHub) is returned. A warning
is signalled whenever the source location lookup fails or if the source location points to a directory not below the directory of ASDF-SYSTEM.

If GIT-FORGE-URI is ‘"https://github.com/melisgl/mgl-pax/"‘ and GIT-VERSION is ‘"master"‘, then the returned \URI may look like this:

https://github.com/melisgl/mgl-pax/blob/master/src/pax-early.lisp#L12

If GIT-VERSION is NIL, then an attempt is made to determine to current commit id from the ‘.git‘ in the directory holding ASDF-SYSTEM. If no ‘.git‘ directory is found, then no links to
the git forge will be generated.

URI-FORMAT-STRING is a CL:FORMAT control string for four arguments:

- GIT-FORGE-URI,
- GIT-VERSION,
- the relative path to the file of the source location of the reference, - and the line number.

The default value of URI-FORMAT-STRING is for GitHub. If using a non-standard git forge, such as Sourcehut or GitLab, simply pass a suitable URI-FORMAT-STRING matching the \URI scheme of your forge.

Package

mgl-pax.

Source

document-early.lisp.

Function: make-github-source-uri-fn (asdf-system github-uri &key git-version) ¶

This function is a backward-compatibility wrapper around MAKE-GIT-SOURCE-URI-FN, which supersedes MAKE-GITHUB-SOURCE-URI-FN. All arguments are passed on to MAKE-GIT-SOURCE-URI-FN, leaving URI-FORMAT-STRING at its default, which is suitable for GitHub.

Package

mgl-pax.

Source

document-early.lisp.

Function: make-source-location (&rest args) ¶

Autoloaded function in system [dref/full][asdf:system].

Package

dref-ext.

Source

early.lisp.

Function: move-definition-properties (from-xref to-xref) ¶

Associate all properties of FROM-XREF with TO-XREF, as if readding them one-by-one with ‘(SETF DEFINITION-PROPERTY)‘, and deleting them from FROM-XREF with DELETE-DEFINITION-PROPERTY.

Package

dref-ext.

Source

extension-api.lisp.

Function: prin1-to-markdown (&rest args) ¶

Autoloaded function in system [mgl-pax/document][asdf:system].

Package

mgl-pax.

Source

document-early.lisp.

Function: pseudo-locative-types () ¶

Return the locative types that correspond to non-Lisp definitions. These are the ones defined with DEFINE-PSEUDO-LOCATIVE-TYPE and are the constituents of DTYPE PSEUDO.

This list is in @REVERSE-DEFINITION-ORDER.

Package

dref.

Source

dref.lisp.

Function: register-doc-in-pax-world (name sections page-specs) ¶

Register SECTIONS and PAGE-SPECS under NAME (a symbol) in PAX World. By default, UPDATE-PAX-WORLD generates documentation for all of these. SECTIONS and PAGE-SPECS must be lists of SECTIONs and PAGE-SPECs (SEE DOCUMENT) or designators of function of no arguments that return such lists.

Package

mgl-pax.

Source

pax-world.lisp.

Function: resolve (object &optional errorp) ¶

If OBJECT is an [XREF][class], then return the first-class object associated with its definition if any. Return OBJECT if it’s not an XREF. Thus, the value returned is never an XREF. The second return value is whether resolving succeeded.

“‘cl-transcript (:dynenv dref-std-env)
(resolve (dref ’print ’function))
==> #<FUNCTION PRINT>
=> T
“‘
“‘cl-transcript (:dynenv dref-std-env)
(resolve #’print)
==> #<FUNCTION PRINT>
=> T
“‘

If OBJECT is an XREF, and the definition for it cannot be LOCATEd, then LOCATE-ERROR is signalled.

“‘cl-transcript (:dynenv dref-std-env)
(resolve (xref ’undefined ’variable))
.. debugger invoked on LOCATE-ERROR:
.. Could not locate UNDEFINED VARIABLE.
“‘

If there is a definition, but there is no first-class object corresponding to it, then RESOLVE-ERROR is signalled or NIL is returned depending on ERRORP:

“‘cl-transcript (:dynenv dref-std-env)
(resolve (dref ’*print-length* ’variable))
.. debugger invoked on RESOLVE-ERROR:
.. Could not resolve *PRINT-LENGTH* VARIABLE.
“‘
“‘cl-transcript (:dynenv dref-std-env)
(resolve (dref ’*print-length* ’variable) nil)
=> NIL
=> NIL
“‘

RESOLVE is a partial inverse of LOCATE: if a [DREF][class] is RESOLVEable, then LOCATEing the object it resolves to recovers the DREF equivalent to the original (XREF= and of the same type but not EQ).

Can be extended via RESOLVE*.

Package

dref.

Source

dref.lisp.

Function: resolve-error (&rest format-and-args) ¶

Call this function to signal a RESOLVE-ERROR condition from the [dynamic extent][clhs] of a RESOLVE* method. It is an error to call RESOLVE-ERROR elsewhere.

FORMAT-AND-ARGS, if non-NIL, is a format string and arguments suitable for FORMAT.

Package

dref-ext.

Source

extension-api.lisp.

Function: section-entries (section) ¶

A list of Markdown docstrings and [XREF][class]s in the order they occurred in DEFSECTION.

Package

mgl-pax.

Source

pax.lisp.

Function: section-link-title-to (section) ¶

Package

mgl-pax.

Source

pax.lisp.

Function: source-location (object &key error) ¶

Return the Swank source location for the [defining form][clhs]
of OBJECT.

The returned Swank location object is to be accessed only through the DREF-EXT::@SOURCE-LOCATIONS API or to be passed to e.g Slime’s ‘slime-goto-source-location‘.

If no source location was found,

- if ERROR is NIL, then return NIL;

- if ERROR is :ERROR, then return a list of the form ‘(:ERROR <ERROR-MESSAGE>)‘ suitable for ‘slime-goto-source-location‘;

- if ERROR is T, then signal an ERROR condition with the same error message as in the previous case.

Note that the availability of source location information varies greatly across Lisp implementations.

Can be extended via SOURCE-LOCATION*.

Package

dref.

Source

dref.lisp.

Function: source-location-adjusted-file-position (&rest args) ¶

Autoloaded function in system [dref/full][asdf:system].

Package

dref-ext.

Source

early.lisp.

Function: source-location-buffer (&rest args) ¶

Autoloaded function in system [dref/full][asdf:system].

Package

dref-ext.

Source

early.lisp.

Function: source-location-buffer-position (&rest args) ¶

Autoloaded function in system [dref/full][asdf:system].

Package

dref-ext.

Source

early.lisp.

Function: source-location-file (&rest args) ¶

Autoloaded function in system [dref/full][asdf:system].

Package

dref-ext.

Source

early.lisp.

Function: source-location-file-position (&rest args) ¶

Autoloaded function in system [dref/full][asdf:system].

Package

dref-ext.

Source

early.lisp.

Function: source-location-p (&rest args) ¶

Autoloaded function in system [dref/full][asdf:system].

Package

dref-ext.

Source

early.lisp.

Function: source-location-snippet (&rest args) ¶

Autoloaded function in system [dref/full][asdf:system].

Package

dref-ext.

Source

early.lisp.

Function: squeeze-whitespace (&rest args) ¶

Autoloaded function in system [mgl-pax/transcribe][asdf:system].

Package

mgl-pax.

Source

transcribe-early.lisp.

Function: transcribe (&rest args) ¶

Autoloaded function in system [mgl-pax/transcribe][asdf:system].

Package

mgl-pax.

Source

transcribe-early.lisp.

Function: update-asdf-system-html-docs (&rest args) ¶

Autoloaded function in system [mgl-pax/document][asdf:system].

Package

mgl-pax.

Source

document-early.lisp.

Function: update-asdf-system-readmes (&rest args) ¶

Autoloaded function in system [mgl-pax/document][asdf:system].

Package

mgl-pax.

Source

document-early.lisp.

Function: update-pax-world (&rest args) ¶

Autoloaded function in system [mgl-pax/full][asdf:system].

Package

mgl-pax.

Source

document-early.lisp.

Function: xref (name locative) ¶

A shorthand for ‘(MAKE-INSTANCE ’XREF :NAME NAME :LOCATIVE LOCATIVE)‘ to create [XREF][class] objects. It does no error checking: the LOCATIVE-TYPE of LOCATIVE-TYPE need not be defined, and the LOCATIVE-ARGS need not be valid. Use LOCATE or the DREF function to create [DREF][class] objects.

Package

dref.

Source

dref.lisp.

Function: xref-locative-args (xref) ¶

Package

dref.

Source

dref.lisp.

Function: xref-locative-type (xref) ¶

Package

dref.

Source

dref.lisp.

Function: xref= (xref1 xref2) ¶

See if XREF1 and XREF2 have the same XREF-NAME and XREF-LOCATIVE under EQUAL. Comparing like this makes most sense for [DREF][class]s. However, two [XREF][class]s different under XREF= may denote the same [DREF][class]s.

Package

dref.

Source

dref.lisp.

---

6.1.5 Generic functions

Generic Function: arglist* (object) ¶

To extend ARGLIST, specialize OBJECT on a normal
Lisp type or on a subclass of [DREF][class].

ARGLIST first calls ARGLIST* with its OBJECT argument. If that doesn’t work (i.e. the second value returned is NIL), then it calls ARGLIST* with OBJECT either RESOLVEd (if it’s a DREF) or LOCATEd (if it’s not a DREF).

- The default method returns NIL, NIL.

- There is also a method specialized on [DREFs][class], that looks up the DEFINITION-PROPERTY called ARGLIST and returns its value with VALUES-LIST. Thus, an arglist and its kind can be specified with something like

“‘
(setf (definition-property xref ’arglist)
(list arglist :destructuring))
“‘

This function is for extension only. Do not call it directly.

Package

dref-ext.

Source

extension-api.lisp.

Methods

Method: arglist* (object) ¶

Method: arglist* ((dref dref)) ¶

Generic Function: docstring* (object) ¶

To extend DOCSTRING, specialize OBJECT on a normal
Lisp type or on a subclass of [DREF][class].

DOCSTRING first calls DOCSTRING* with its OBJECT argument. If that doesn’t work (i.e. NIL is returned), then it calls DOCSTRING* with OBJECT either RESOLVEd (if it’s a DREF) or LOCATEd (if it’s not a DREF).

- The default method returns NIL.

- There is also a method specialized on [DREFs][class], that looks up the DEFINITION-PROPERTY called DOCSTRING and returns its value with VALUES-LIST. Thus, a docstring and a package can be specified with something like

“‘
(setf (definition-property xref ’docstring)
(list docstring *package*))
“‘

This function is for extension only. Do not call it directly.

Package

dref-ext.

Source

extension-api.lisp.

Methods

Method: docstring* (object) ¶

Method: docstring* ((dref dref)) ¶

Generic Function: doctitle* (object) ¶

DOCTITLE* extends DOCTITLE in the same way
as DOCSTRING* extends DOCSTRING.

The default method returns NIL.

This function is for extension only. Do not call it directly.

Package

mgl-pax.

Source

document-early.lisp.

Methods

Method: doctitle* (object) ¶

Generic Function: document-object* (object stream) ¶

Write OBJECT in *FORMAT* to STREAM.
Specialize this on a subclass of [DREF][class] if that subclass is not RESOLVEable, else on the type of object it resolves to. This function is for extension only. Don’t call it directly.

Package

mgl-pax.

Source

extension-api.lisp.

Methods

Method: document-object* (object stream) ¶

Generic Reader: dref-locative (object) ¶

Package

dref.

Methods

Reader Method: dref-locative ((dref dref)) ¶

The same as XREF-LOCATIVE, but only works on [DREF][class]s. Use it as a statement of intent.

Source

dref.lisp.

Target Slot

locative.

Generic Reader: dref-name (object) ¶

Package

dref.

Methods

Reader Method: dref-name ((dref dref)) ¶

The same as XREF-NAME, but only works on [DREF][class]s. Use it as a statement of intent.

Source

dref.lisp.

Target Slot

name.

Generic Reader: dref-origin (object) ¶

Package

dref.

Methods

Reader Method: dref-origin ((dref dref)) ¶

The object from which LOCATE constructed this
[DREF][class]. DREF-ORIGIN may have @PRESENTATION arguments, which are not included in LOCATIVE-ARGS as is the case with the INITFORM argument of the VARIABLE locative:

“‘cl-transcript (:dynenv dref-std-env)
(dref ’*standard-output* ’(variable "see-below"))
==> #<DREF *STANDARD-OUTPUT* VARIABLE>
“‘

“‘cl-transcript (:dynenv dref-std-env)
(dref-origin (dref ’*standard-output* ’(variable "see-below"))) ==> #<XREF *STANDARD-OUTPUT* (VARIABLE "see-below")>
“‘

The INITFORM argument overrides the global binding of *STANDARD-OUTPUT* when it’s PAX:DOCUMENTed:

“‘cl-transcript (:dynenv dref-std-env)
(first-line
(pax:document (dref ’*standard-output* ’(variable "see-below")) :stream nil))
=> "- [variable] *STANDARD-OUTPUT* \"see-below\""
“‘

Source

dref.lisp.

Target Slot

origin.

Generic Function: exportable-locative-type-p (locative-type) ¶

Return true if symbols in references with
LOCATIVE-TYPE are to be exported by default when they occur in a DEFSECTION. The default method returns T, while the methods for locative types [SECTION][locative], [GLOSSARY-TERM][locative], [PACKAGE][locative], [ASDF:SYSTEM][locative], METHOD and [INCLUDE][locative] return NIL.

This function is called by the default method of EXPORTABLE-REFERENCE-P to decide what symbols DEFSECTION shall export when its EXPORT argument is true.

Package

mgl-pax.

Source

basics.lisp.

Methods

Method: exportable-locative-type-p ((locative-type (eql mgl-pax:include))) ¶

Method: exportable-locative-type-p ((locative-type (eql method))) ¶

Method: exportable-locative-type-p ((locative-type (eql package))) ¶

Method: exportable-locative-type-p ((locative-type (eql asdf/system:system))) ¶

Method: exportable-locative-type-p (locative-type) ¶

Generic Function: exportable-reference-p (package symbol locative-type locative-args) ¶

Return true if SYMBOL is to be exported from
PACKAGE when it occurs in a DEFSECTION in a reference with LOCATIVE-TYPE and LOCATIVE-ARGS. SYMBOL is [accessible][clhs] in PACKAGE.

The default method calls EXPORTABLE-LOCATIVE-TYPE-P with
LOCATIVE-TYPE and ignores the other arguments.

By default, SECTIONs and GLOSSARY-TERMs are not exported although
they are EXPORTABLE-LOCATIVE-TYPE-P. To export symbols naming
sections from MGL-PAX, the following method could be added:

“‘
(defmethod exportable-reference-p ((package (eql (find-package ’mgl-pax))) symbol (locative-type (eql ’section)) locative-args)
t)
“‘

Package

mgl-pax.

Source

basics.lisp.

Methods

Method: exportable-reference-p ((package (eql #<package "dref">)) symbol locative-type locative-args) ¶

Source

package.lisp.

Method: exportable-reference-p ((package (eql #<package "dref-ext">)) symbol locative-type locative-args) ¶

Source

package.lisp.

Method: exportable-reference-p (package symbol (locative-type (eql mgl-pax:note)) locative-args) ¶

Method: exportable-reference-p (package symbol (locative-type (eql mgl-pax:glossary-term)) locative-args) ¶

Method: exportable-reference-p (package symbol (locative-type (eql mgl-pax:section)) locative-args) ¶

Method: exportable-reference-p (package symbol locative-type locative-args) ¶

Generic Reader: glossary-term-name (object) ¶

Package

mgl-pax.

Methods

Reader Method: glossary-term-name ((glossary-term glossary-term)) ¶

The name of the global variable whose value is this GLOSSARY-TERM object.

Source

basics.lisp.

Target Slot

name.

Generic Reader: glossary-term-title (object) ¶

Package

mgl-pax.

Methods

Reader Method: glossary-term-title ((glossary-term glossary-term)) ¶

A @TITLE or NIL. Used in generated
documentation (see @MARKDOWN-OUTPUT) and is returned by DOCTITLE for GLOSSARY-TERM objects and GLOSSARY-TERM DREF::@DEFINITIONS..

Source

basics.lisp.

Target Slot

title.

Generic Reader: glossary-term-url (object) ¶

Package

mgl-pax.

Methods

Reader Method: glossary-term-url ((glossary-term glossary-term)) ¶

A string or NIL.

Source

basics.lisp.

Target Slot

url.

Generic Function: map-definitions-of-name (fn name locative-type) ¶

Call FN with [DREF][class]s which can be LOCATEd
with an XREF with NAME, LOCATIVE-TYPE and some LOCATIVE-ARGS. The strange wording here is because there may be multiple ways (and thus XREFs) that refer to the same definition.

For most locative types, there is at most one such definition, but for METHOD, for example, there may be many. The default method simply does ‘(DREF NAME LOCATIVE-TYPE NIL)‘ and calls FN with result if [DREF][function] succeeds.

FN must not be called with the same (under XREF=) definition multiple times.

This function is for extending DEFINITIONS and DREF-APROPOS. Do not call it directly.

Package

dref-ext.

Source

extension-api.lisp.

Methods

Method: map-definitions-of-name (fn name locative-type) ¶

Generic Function: map-definitions-of-type (fn locative-type) ¶

Call FN with [DREF][class]s which can be LOCATEd
with an XREF with LOCATIVE-TYPE with some NAME and LOCATIVE-ARGS.

The default method forms XREFs by combining each interned symbol as @NAMEs with LOCATIVE-TYPE and no LOCATIVE-ARGS and calls FN if it LOCATEs a definition.

FN may be called with DREFs that are XREF= but differ in the XREF in their DREF-ORIGIN.

This function is for extending DREF-APROPOS. Do not call it directly.

Package

dref-ext.

Source

extension-api.lisp.

Methods

Method: map-definitions-of-type (fn locative-type) ¶

Generic Function: resolve* (dref) ¶

Return the object defined by the definition DREF
refers to. Signal a RESOLVE-ERROR condition by calling the RESOLVE-ERROR function if the lookup fails.

To keep RESOLVE a partial inverse of LOCATE, DEFINE-LOCATOR may be necessary for RESOLVEable definitions. This function is for extending RESOLVE. Do not call it directly.

It is an error for methods of this generic function to return an [XREF][class].

Package

dref-ext.

Source

extension-api.lisp.

Methods

Method: resolve* :around ((dref dref)) ¶

Method: resolve* ((dref dref)) ¶

Generic Reader: section-name (object) ¶

Package

mgl-pax.

Methods

Reader Method: section-name ((section section)) ¶

The name of the global variable whose value is this SECTION object.

Source

basics.lisp.

Target Slot

name.

Generic Reader: section-package (object) ¶

Package

mgl-pax.

Methods

Reader Method: section-package ((section section)) ¶

*PACKAGE* will be bound to this package when generating documentation for this section.

Source

basics.lisp.

Target Slot

package.

Generic Reader: section-readtable (object) ¶

Package

mgl-pax.

Methods

Reader Method: section-readtable ((section section)) ¶

*READTABLE* will be bound to this when generating documentation for this section.

Source

basics.lisp.

Target Slot

readtable.

Generic Reader: section-title (object) ¶

Package

mgl-pax.

Methods

Reader Method: section-title ((section section)) ¶

A @TITLE or NIL. Used in generated
documentation (see @MARKDOWN-OUTPUT) and is returned by DOCTITLE for SECTION objects and SECTION DREF::@DEFINITIONS.

Source

basics.lisp.

Target Slot

title.

Generic Function: source-location* (object) ¶

To extend SOURCE-LOCATION, specialize OBJECT on a
normal Lisp type or on a subclass of [DREF][class].

SOURCE-LOCATION first calls SOURCE-LOCATION* with its OBJECT argument. If that doesn’t work (i.e. NIL or ‘(:ERROR <MESSAGE>)‘ is returned), then it calls SOURCE-LOCATION* with OBJECT either RESOLVEd (if it’s a DREF) or LOCATEd (if it’s not a DREF).

SOURCE-LOCATION returns the last of the ‘(:ERROR <MESSAGE>)‘s encountered or a generic error message if only NILs were returned.

- The default method returns NIL.

- There is also a method specialized on [DREFs][class], that looks up the DEFINITION-PROPERTY called SOURCE-LOCATION. If present, it must be a function of no arguments that returns a source location or NIL. Typically, this is set up in the defining macro like this:

“‘
(setf (definition-property xref ’source-location) (this-source-location))
“‘

This function is for extension only. Do not call it directly.

Package

dref-ext.

Source

extension-api.lisp.

Methods

Method: source-location* (object) ¶

Method: source-location* ((dref dref)) ¶

Generic Reader: xref-locative (object) ¶

Package

dref.

Methods

Reader Method: xref-locative ((xref xref)) ¶

The @LOCATIVE of the reference.

The locative is normalized by replacing single-element lists with their only element:

“‘cl-transcript (:dynenv dref-std-env)
(xref ’print ’function)
==> #<XREF PRINT FUNCTION>
“‘
“‘cl-transcript (:dynenv dref-std-env)
(xref ’print ’(function))
==> #<XREF PRINT FUNCTION>
“‘

Source

dref.lisp.

Target Slot

locative.

Generic Reader: xref-name (object) ¶

Package

dref.

Methods

Reader Method: xref-name ((xref xref)) ¶

The @NAME of the reference.

Source

dref.lisp.

Target Slot

name.

---