The cl-interpol Reference Manual

Table of Contents

The cl-interpol Reference Manual

This is the cl-interpol Reference Manual, version 0.2.7, generated automatically by Declt version 3.0 "Montgomery Scott" on Sun May 15 03:52:43 2022 GMT+0.

1 Introduction

CL-INTERPOL - String interpolation for Common Lisp

CL-INTERPOL is a library for Common Lisp which modifies the reader so that you can have interpolation within strings similar to Perl or Unix Shell scripts. It also provides various ways to insert arbitrary characters into literal strings even if your editor/IDE doesn't support them. Here's an example:

(named-readtables:in-readtable :interpol-syntax)


(let ((a 42))
    #?"foo: \xC4\N{Latin capital letter U with diaeresis}\nbar: ${a}")
"foo: ÄÜ
bar: 42"

CL-INTERPOL comes with a BSD-style license so you can basically do with it whatever you want.

Complete documentation for CL-INTERPOL can be found in the docs directory or at the project documentation site

2 Systems

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

2.1 cl-interpol

License

BSD-2-Clause

Version

0.2.7

Dependencies

• cl-unicode
• named-readtables

Source

cl-interpol.asd (file)

Components

• packages.lisp (file)
• specials.lisp (file)
• util.lisp (file)
• alias.lisp (file)
• read.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 cl-interpol.asd

Location

cl-interpol.asd

Systems

cl-interpol (system)

Packages

cl-interpol-asd

3.1.2 cl-interpol/packages.lisp

Parent

cl-interpol (system)

Location

packages.lisp

Packages

cl-interpol

3.1.3 cl-interpol/specials.lisp

Dependency

packages.lisp (file)

Parent

cl-interpol (system)

Location

specials.lisp

Exported Definitions

• *inner-delimiters* (special variable)
• *interpolate-format-directives* (special variable)
• *list-delimiter* (special variable)
• *optional-delimiters-p* (special variable)
• *outer-delimiters* (special variable)

Internal Definitions

• *hyperdoc-base-uri* (special variable)
• *pair-level* (special variable)
• *previous-readtables* (special variable)
• *readtable-copy* (special variable)
• *regex-delimiters* (special variable)
• *saw-backslash* (special variable)
• *start-char* (special variable)
• *stream* (special variable)
• *term-char* (special variable)
• *unicode-aliases* (special variable)
• defvar-unbound (macro)
• hyperdoc-lookup (function)

3.1.4 cl-interpol/util.lisp

Dependency

specials.lisp (file)

Parent

cl-interpol (system)

Location

util.lisp

Internal Definitions

• copy-readtable* (function)
• get-end-delimiter (function)
• lower-case-p* (function)
• make-char-from-code (function)
• make-collector (function)
• nsubvec (function)
• peek-char* (macro)
• read-char* (macro)
• signal-reader-error (macro)
• simple-reader-error (condition)
• string-list-to-string (function)

3.1.5 cl-interpol/alias.lisp

Dependency

util.lisp (file)

Parent

cl-interpol (system)

Location

alias.lisp

3.1.6 cl-interpol/read.lisp

Dependency

alias.lisp (file)

Parent

cl-interpol (system)

Location

read.lisp

Exported Definitions

• disable-interpol-syntax (macro)
• enable-interpol-syntax (macro)
• interpol-reader (function)

Internal Definitions

• %disable-interpol-syntax (function)
• %enable-interpol-syntax (function)
• get-char-from-unicode-name (function)
• get-number (function)
• inner-reader (function)
• never-name-char-p (function)
• normal-name-char-p (function)
• quell-warnings-form (special variable)
• read-form (function)
• read-format-directive (function)
• read-longest-name (function)
• read-optional-delimited (function)
• read-while (function)
• resolve-unicode-name (function)
• unescape-char (function)

4 Packages

Packages are listed by definition order.

4.1 cl-interpol-asd

Source

cl-interpol.asd

Use List

• asdf/interface
• common-lisp

4.2 cl-interpol

Source

packages.lisp (file)

Nickname

interpol

Use List

• cl-ppcre
• cl-unicode
• common-lisp

Exported Definitions

• *inner-delimiters* (special variable)
• *interpolate-format-directives* (special variable)
• *list-delimiter* (special variable)
• *optional-delimiters-p* (special variable)
• *outer-delimiters* (special variable)
• disable-interpol-syntax (macro)
• enable-interpol-syntax (macro)
• interpol-reader (function)

Internal Definitions

• %disable-interpol-syntax (function)
• %enable-interpol-syntax (function)
• *hyperdoc-base-uri* (special variable)
• *pair-level* (special variable)
• *previous-readtables* (special variable)
• *readtable-copy* (special variable)
• *regex-delimiters* (special variable)
• *saw-backslash* (special variable)
• *start-char* (special variable)
• *stream* (special variable)
• *term-char* (special variable)
• *unicode-aliases* (special variable)
• copy-readtable* (function)
• defvar-unbound (macro)
• get-char-from-unicode-name (function)
• get-end-delimiter (function)
• get-number (function)
• hyperdoc-lookup (function)
• inner-reader (function)
• lower-case-p* (function)
• make-char-from-code (function)
• make-collector (function)
• never-name-char-p (function)
• normal-name-char-p (function)
• nsubvec (function)
• peek-char* (macro)
• quell-warnings-form (special variable)
• read-char* (macro)
• read-form (function)
• read-format-directive (function)
• read-longest-name (function)
• read-optional-delimited (function)
• read-while (function)
• resolve-unicode-name (function)
• signal-reader-error (macro)
• simple-reader-error (condition)
• string-list-to-string (function)
• unescape-char (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: *inner-delimiters*

Legal delimiters for interpolation with #$ and #@.

Package

cl-interpol

Source

specials.lisp (file)

Special Variable: *interpolate-format-directives*

Whether to allow ~X(...) as format control directives in interpolated strings.

Package

cl-interpol

Source

specials.lisp (file)

Special Variable: *list-delimiter*

What is inserted between the elements of a list which is interpolated by #@.

Package

cl-interpol

Source

specials.lisp (file)

Special Variable: *optional-delimiters-p*

Whether text following $ or @ should interpolate even without a following delimiter. Lexical variables are handled correctly, but the rules are somewhat complex – see the docs for details.

Package

cl-interpol

Source

specials.lisp (file)

Special Variable: *outer-delimiters*

Legal outer delimiters for CL-INTERPOL strings.

Package

cl-interpol

Source

specials.lisp (file)

5.1.2 Macros

Macro: disable-interpol-syntax ()

Restore readtable which was active before last call to ENABLE-INTERPOL-SYNTAX. If there was no such call, the standard readtable is used.

Package

cl-interpol

Source

read.lisp (file)

Macro: enable-interpol-syntax &rest %ENABLE-INTERPOL-SYNTAX-ARGS

Enable CL-INTERPOL reader syntax.

Package

cl-interpol

Source

read.lisp (file)

5.1.3 Functions

Function: interpol-reader *STREAM* CHAR ARG &key RECURSIVE-P

The actual reader function for the ’sub-character’ #?.

This function can be used directly outside of a read table by passing ‘recursive-p‘ as NIL.

Package

cl-interpol

Source

read.lisp (file)

5.2 Internal definitions

5.2.1 Special variables

Special Variable: *hyperdoc-base-uri*

Package

cl-interpol

Source

specials.lisp (file)

Special Variable: *pair-level*

Package

cl-interpol

Source

specials.lisp (file)

Special Variable: *previous-readtables*

A stack which holds the previous readtables that have been pushed here by ENABLE-INTERPOL-SYNTAX.

Package

cl-interpol

Source

specials.lisp (file)

Special Variable: *readtable-copy*

Bound to the current readtable if it has to be temporarily modified.

Package

cl-interpol

Source

specials.lisp (file)

Special Variable: *regex-delimiters*

Outer delimiters which automatically enable regex mode.

Package

cl-interpol

Source

specials.lisp (file)

Special Variable: *saw-backslash*

Whether we have to re-process an L or U because it closes several scopes.

Package

cl-interpol

Source

specials.lisp (file)

Special Variable: *start-char*

Bound to the opening outer delimiter while parsing a string.

Package

cl-interpol

Source

specials.lisp (file)

Special Variable: *stream*

Bound to the stream which is read from while parsing a string.

Package

cl-interpol

Source

specials.lisp (file)

Special Variable: *term-char*

Bound to the closing outer delimiter while parsing a string.

Package

cl-interpol

Source

specials.lisp (file)

Special Variable: *unicode-aliases*

A hash table which maps Unicode aliases to their real names.

Package

cl-interpol

Source

specials.lisp (file)

Special Variable: quell-warnings-form

A declaration form to quiet warnings about unbound variables within a lexical environment.

Package

cl-interpol

Source

read.lisp (file)

5.2.2 Macros

Macro: defvar-unbound VARIABLE-NAME DOCUMENTATION

Like DEFVAR, but the variable will be unbound rather than getting an initial value. This is useful for variables which should have no global value but might have a dynamically bound value.

Package

cl-interpol

Source

specials.lisp (file)

Macro: peek-char* ()

Convenience macro because we always peek at the same string with the same arguments.

Package

cl-interpol

Source

util.lisp (file)

Macro: read-char* ()

Convenience macro because we always read from the same string with the same arguments.

Package

cl-interpol

Source

util.lisp (file)

Macro: signal-reader-error FORMAT-CONTROL &rest FORMAT-ARGUMENTS

Like ERROR but signals a SIMPLE-READER-ERROR for the stream *STREAM*.

Package

cl-interpol

Source

util.lisp (file)

5.2.3 Functions

Function: %disable-interpol-syntax ()

Internal function used to restore previous readtable.

Package

cl-interpol

Source

read.lisp (file)

Function: %enable-interpol-syntax &key MODIFY-*READTABLE*

Internal function used to enable reader syntax and store current readtable on stack.

Package

cl-interpol

Source

read.lisp (file)

Function: copy-readtable* ()

Returns a copy of the readtable which was current when INTERPOL-READER was invoked. Memoizes its result.

Package

cl-interpol

Source

util.lisp (file)

Function: get-char-from-unicode-name ()

Parses and returns a named character after "\N" has already been read. This function reads from *STREAM*.

Package

cl-interpol

Source

read.lisp (file)

Function: get-end-delimiter START-DELIMITER DELIMITERS &key ERRORP

Find the closing delimiter corresponding to the opening delimiter START-DELIMITER in a list DELIMITERS which is formatted like *OUTER-DELIMITERS*. If ERRORP is true, signal an error if none was found, otherwise return NIL.

Package

cl-interpol

Source

util.lisp (file)

Function: get-number &key RADIX MAX

Reads and consumes the number *STREAM* is currently looking at and returns it. Returns NIL if no number could be identified. RADIX is used as in PARSE-INTEGER. If MAX is not NIL we’ll read at most the next MAX characters.

Package

cl-interpol

Source

read.lisp (file)

Function: hyperdoc-lookup SYMBOL TYPE

Package

cl-interpol

Source

specials.lisp (file)

Function: inner-reader REGEX-MODE EXTENDED-MODE QUOTE-MODE CASE-MODE &key RECURSIVE-P

Helper function for INTERPOL-READER which does all the work. May call itself recursively.

Package

cl-interpol

Source

read.lisp (file)

Function: lower-case-p* CHAR

Whether CHAR is a character which has case and is lowercase.

Package

cl-interpol

Source

util.lisp (file)

Function: make-char-from-code NUMBER

Create character from char-code NUMBER. NUMBER can be NIL which is interpreted as 0.

Package

cl-interpol

Source

util.lisp (file)

Function: make-collector ()

Create an empty string which can be extended by VECTOR-PUSH-EXTEND.

Package

cl-interpol

Source

util.lisp (file)

Function: never-name-char-p C

Package

cl-interpol

Source

read.lisp (file)

Function: normal-name-char-p C

Package

cl-interpol

Source

read.lisp (file)

Function: nsubvec SEQUENCE START &optional END

Return a subvector by pointing to location in original vector.

Package

cl-interpol

Source

util.lisp (file)

Function: read-form &key RECURSIVE-P

Reads and returns one or more Lisp forms from *STREAM* if the character we’re looking at is a valid inner delimiter. Otherwise returns NIL.

Package

cl-interpol

Source

read.lisp (file)

Function: read-format-directive ()

Reads and returns a format directive (as a string) along with one or more lisp forms (as per read-form).

Package

cl-interpol

Source

read.lisp (file)

Function: read-longest-name ()

Package

cl-interpol

Source

read.lisp (file)

Function: read-optional-delimited ()

Read the stuff following an optional delimiter, returning a form that tries to deal correctly with lexical variables.

Package

cl-interpol

Source

read.lisp (file)

Function: read-while PREDICATE &key MAX

Reads characters from *STREAM* while PREDICATE returns a true value for each character. Returns at most MAX characters if MAX is true.

Package

cl-interpol

Source

read.lisp (file)

Function: resolve-unicode-name NAME

Tries to return a character which was encoded as \N<NAME>.

Package

cl-interpol

Source

read.lisp (file)

Function: string-list-to-string STRING-LIST

Concatenates a list of strings to one string.

Package

cl-interpol

Source

util.lisp (file)

Function: unescape-char REGEX-MODE

Convert the characters(s) on *STREAM* following a backslash into a character which is returned. This function is to be called when the backslash has already been consumed.

Package

cl-interpol

Source

read.lisp (file)

5.2.4 Conditions

Condition: simple-reader-error ()

A reader error which can be signalled by ERROR.

Package

cl-interpol

Source

util.lisp (file)

Direct superclasses

• reader-error (condition)
• simple-condition (condition)

Appendix A Indexes

A.1 Concepts

A.2 Functions

A.3 Variables

A.4 Data types