The linewise-template Reference Manual

This is the linewise-template Reference Manual, generated automatically by Declt version 4.0 beta 2 "William Riker" on Wed May 15 05:46:00 2024 GMT+0.

Table of Contents


1 Introduction


2 Systems

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


2.1 linewise-template

Linewise file/stream processor for code generation etc.

Maintainer

Boris Smilga <>

Author

Boris Smilga <>

License

BSD-3-Clause

Dependencies
  • cl-ppcre (system).
  • cl-fad (system).
Source

linewise-template.asd.

Child Component

src (module).


3 Modules

Modules are listed depth-first from the system components tree.


3.1 linewise-template/src

Source

linewise-template.asd.

Parent Component

linewise-template (system).

Child Component

linewise-template.lisp (file).


4 Files

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


4.1 Lisp


4.1.1 linewise-template/linewise-template.asd

Source

linewise-template.asd.

Parent Component

linewise-template (system).

ASDF Systems

linewise-template.

Packages

linewise-template-system.


4.1.2 linewise-template/src/linewise-template.lisp

Source

linewise-template.asd.

Parent Component

src (module).

Packages

linewise-template.

Public Interface
Internals

5 Packages

Packages are listed by definition order.


5.1 linewise-template

Source

linewise-template.lisp.

Use List
  • cl-fad.
  • cl-ppcre.
  • common-lisp.
Public Interface
Internals

5.2 linewise-template-system

Source

linewise-template.asd.

Use List
  • asdf/interface.
  • common-lisp.

6 Definitions

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


6.1 Public Interface


6.1.1 Special variables

Special Variable: *backup-pathname-suffix*

String added to file path in order to obtain the name of the backup file.

Package

linewise-template.

Source

linewise-template.lisp.

Special Variable: *directive-base-packages*

List of packages which are to be used by the temporary package established for reading symbols in directives

Package

linewise-template.

Source

linewise-template.lisp.

Special Variable: *directive-circumfix*

Prefix or circumfix of directive lines (when in comments etc.): a list of 0, 1 or 2 ppcre strings.

Package

linewise-template.

Source

linewise-template.lisp.

Special Variable: *directive-escape*

String to introduce a directive

Package

linewise-template.

Source

linewise-template.lisp.

Special Variable: *source-line-count*

Reference to an integer incremented for each line read, and reset for each subsequent source stream.

Package

linewise-template.

Source

linewise-template.lisp.

Special Variable: *source-stream*

Reference to the current source stream (the one from which a line most recently has been read).

Package

linewise-template.

Source

linewise-template.lisp.


6.1.2 Macros

Macro: process-template (spec)

Process the template specified by SPEC, which must have the following syntax:

<SPEC> ::= (<SOURCE-SPEC> <ACTION-AND-OPTIONS>
[ <SUBSPEC>* ])

<SOURCE-SPEC> ::= ([[ {<SOURCE-STREAM-SPEC>}1 | <SOURCE-OPTS>* ]])
<SOURCE-STREAM-SPEC> ::= :FILE <PATH> [[ <UPDATE-OPTS>* ]] |
:FILES <PATHS> |
:STRING <STRING> | :STRINGS <STRINGS> | :STREAM <STREAM> | :STREAMS <STREAMS>

<UPDATE-OPTS> ::= :UPDATE <BOOLEAN> | :BACKUP <BOOLEAN>

<SOURCE-OPTS> ::= :CIRCUMFIX <REGEXP-PARTS> | :ESCAPE <STRING> | :BASE-PACKAGES <PACKAGES>

<ACTION-AND-OPTIONS> ::= :COPY [[ <COPY-OPTS>* ]] |
:TRANSFORM [[ <TRANSFORM-OPTS>* ]] | :REPLACE [[ <REPLACE-OPTS>* ]] |
:DISCARD [[ <DISCARD-OPTS>* ]]

<COPY-OPTS> ::= :TO <DESTINATION> | <COMMON-OPTS>

<TRANSFORM-OPTS> ::= :BY <FUNCTION> | :TO <DESTINATION> | <COMMON-OPTS>

<REPLACE-OPTS> ::= :WITH <STRING-OR-NIL> | <COMMON-OPTS>

<DISCARD-OPTS> ::= <COMMON-OPTS>

<COMMON-OPTS> ::= :DO <EXPRESSION> |
:PRESERVE-DIRECTIVES <BOOLEAN>

<SUBSPEC> ::= (<SELECTOR> <ACTION-AND-OPTIONS>
[ <SUBSPEC>* ])

<SELECTOR> ::= <NAME> |
(:ATOMIC <NAME> [ <ARGS> [ <TRAILER-ARG> ]]) | (:BLOCK <NAME> [ <ARGS> [ <TRAILER-ARG> ]]) | (:AFTER <NAME> [ <ARGS> [ <TRAILER-ARG> ]])

<DESTINATION> ::= NIL | <STREAM> |
(:VAR <VAR>) | (:FN <FUNCTION>)

<NAME> ::= <string designator>

<ARGS> ::= <destructuring lambda list>

<TRAILER-ARG> ::= &TRAILER <VAR> ; &TRAILER is matched by name

<VAR> ::= <symbol>

<PATH> | <STRING> | <STRING-OR-NIL> | ; Evaluated to produce a single <STREAM> | <BOOLEAN> | <FUNCTION> ; value of the specified type ::= <expression>

<PATHS> | <STRINGS> | <STREAMS> | ; Evaluated to produce a list of <PACKAGES> ::= <expression> ; values of the specified type

<REGEXP-PARTS> :: <expression> ; Evaluated to produce a list of ; 0, 1 or 2 strings, conjoined ; to form a ppcre

The sources specified in <SOURCE-SPEC> are read from by READ-LINE and the resulting lines processed in a dynamic environment where *DIRECTIVE-CIRCUMFIX*, *DIRECTIVE-ESCAPE* and *DIRECTIVE-BASE-PACKAGES* are bound to the values of the corresponding <SOURCE-OPTS> (when provided), *SOURCE-STREAM* is bound to the current source stream, and *SOURCE-LINE-COUNT* to the number of lines read from that stream.

Lines are processed according to <ACTION-AND-OPTIONS> applying either to the whole source (those outside of any <SUBSPEC>), or to some part of the source delimited by “directives”. A directive is a line that has a prefix and suffix matching respectively the first and second element of *DIRECTIVE-CIRCUMFIX* (unless null), and a middle portion beginning with the string *DIRECTIVE-ESCAPE* (unless null), followed by keywords given by <SELECTOR>s of applicable <SUBSPEC>s, followed by zero or more whitespace-separated Lisp expressions, followed by zero or more trailer characters. In the following, we give examples of directives for *DIRECTIVE-ESCAPE* = "@" and *DIRECTIVE-CIRCUMFIX* = NIL; X stays for arbitrary names.

A <SUBSPEC> with a (:BLOCK X ...) selector applies to any part of the source starting with a @BEGIN X directive and an ending with an @END X directive.

A <SUBSPEC> with an (:AFTER X ...) selector applies to any part of the source starting with an @X directive and ending immediately before the start of any sibling <SUBSPEC>, or before the end of its parent <SUBSPEC>, whichever comes first.

A <SUBSPEC> with an (:ATOMIC X ...) selector applies to just the directive line. A plain X selector is shorthand for (:ATOMIC X).

Nested subspecs take precedence over their parent specs. Nested subspecs are not allowed inside atomic subspecs. :ATOMIC selectors are incompatible with :COPY and :TRANSFORM actions.

If the <ACTION> is :COPY, affected lines are copied verbatim to <DESTINATION>. If the applicable (sub)spec specifies a non-stream destination, an output string-stream is used. If the destination
is (:VAR X), the string associated with the stream is assigned to the variable X once all affected lines have been copied. If the destination is (:FN X), the function to which X evaluates is called on the associated string for side effects once all affected lines have been copied.

If the (sub)spec does not specify any <DESTINATION>, it is inherited from the parent spec; for the topmost <SPEC> without an explicit destination, and for a <SPEC> that specifies :TO NIL, an output string-stream is used. However, if <SOURCE-STREAM-SPEC> includes the option :UPDATE T, the destination shall instead be a stream writing to a new version of the input file; additionally, the option :BACKUP T causes the prior version of the file to be backed up as if by (OPEN ... :IF-EXISTS :RENAME).

If the <ACTION> is :TRANSFORM, affected lines are copied to a temporary string, the string is passed to the specified function, and the value returned by the function is written to the destination as if by :COPY. Subspecs of this spec shall inherit as destination an output stream writing to the temporary string.

If the <ACTION> is :REPLACE, affected lines are not copied. Instead, the specified value (unless null) is written to the destination inherited from the parent spec. :DISCARD is a shorthand for :REPLACE :WITH NIL.

If <SELECTOR> includes some <ARGS>, they are expected to form a destructuring lambda list. In this case, Lisp expressions are read from the directive line after the directive name: until the end of the line if <ARGS> contains a &REST and no &KEY keywords, or until the maximum possible number of arguments needed to satisfy the lambda list is obtained. The list of expressions is matched against <ARGS> as if by DESTRUCTURING-BIND. Lisp expressions inside the selector’s <SUBSPEC> are then evaluated in a lexcial environment where variables from <ARGS> are bound to the data read, and the variable from <TRAILER-ARG> (if specified) is bound to a substring of the directive line after the end of the last expression read. Symbols occuring in the data are interned in a temporary package which inherits all external symbols from *DIRECTIVE-BASE-PACKAGES*.

The option :DO X causes the expression X to be executed for side-effects after all affected lines have been processed.

The option :PRESERVE-DIRECTIVES T causes the directive(s) delimiting the affected lines to be copied to the specified or inherited destination, except when both the applicable selector and its parent have :REPLACE or :DISCARD actions.

The value returned by executing PROCESS-TEMPLATE is the string associated with the destination stream, if the action in <SPEC> is :COPY or :TRANSFORM, the <DESTINATION> is NIL or unspecified, and <SOURCE-STREAM-SPEC> does not specify :UPDATE T. Otherwise, the value is NIL.

Package

linewise-template.

Source

linewise-template.lisp.


6.2 Internals


6.2.1 Special variables

Special Variable: $dest$
Package

linewise-template.

Source

linewise-template.lisp.

Special Variable: $file$
Package

linewise-template.

Source

linewise-template.lisp.

Special Variable: $input$
Package

linewise-template.

Source

linewise-template.lisp.

Special Variable: $line$
Package

linewise-template.

Source

linewise-template.lisp.

Special Variable: $residual-line$
Package

linewise-template.

Source

linewise-template.lisp.

Special Variable: $state$
Package

linewise-template.

Source

linewise-template.lisp.

Special Variable: $tmp-file$
Package

linewise-template.

Source

linewise-template.lisp.

Special Variable: *destination*
Package

linewise-template.

Source

linewise-template.lisp.


6.2.2 Macros

Macro: bind-keys-and-suffix (spec form &body body)
Package

linewise-template.

Source

linewise-template.lisp.

Macro: cond/bind (clause &rest more-clauses)
Package

linewise-template.

Source

linewise-template.lisp.

Macro: def-compiler-var (var)
Package

linewise-template.

Source

linewise-template.lisp.

Macro: if/bind ((vars cond) seq &optional alt)
Package

linewise-template.

Source

linewise-template.lisp.

Macro: with-input ((input-streams &key file files string strings stream streams update backup circumfix escape base-packages) &body body)
Package

linewise-template.

Source

linewise-template.lisp.

Macro: with-temp-package (&body body)
Package

linewise-template.

Source

linewise-template.lisp.

Macro: with-temporary-output ((destination file) &body body)
Package

linewise-template.

Source

linewise-template.lisp.


6.2.3 Ordinary functions

Function: after-selector (selector)
Package

linewise-template.

Source

linewise-template.lisp.

Function: atomic-selector (selector)
Package

linewise-template.

Source

linewise-template.lisp.

Function: backup-pathname (file)
Package

linewise-template.

Source

linewise-template.lisp.

Function: block-selector (selector)
Package

linewise-template.

Source

linewise-template.lisp.

Function: compile-check-end (selector sibling-selectors)
Package

linewise-template.

Source

linewise-template.lisp.

Function: compile-check-end-directive (selector sibling-selectors)
Package

linewise-template.

Source

linewise-template.lisp.

Function: compile-check-eot (selector)
Package

linewise-template.

Source

linewise-template.lisp.

Function: compile-copy-directive (selector preserve)
Package

linewise-template.

Source

linewise-template.lisp.

Function: compile-directive-handler (subs selector cousin-selectors)
Package

linewise-template.

Source

linewise-template.lisp.

Function: compile-pop-state (&optional inner)
Package

linewise-template.

Source

linewise-template.lisp.

Function: compile-push-state (selector destination default-destination)
Package

linewise-template.

Source

linewise-template.lisp.

Function: compile-write-value (value)
Package

linewise-template.

Source

linewise-template.lisp.

Function: compile-yield-dest (place fn)
Package

linewise-template.

Source

linewise-template.lisp.

Function: count-registers (tree)
Package

linewise-template.

Source

linewise-template.lisp.

Function: directive (re line nargs)
Package

linewise-template.

Source

linewise-template.lisp.

Function: directive-regex (begin/end names)
Package

linewise-template.

Source

linewise-template.lisp.

Function: disallow-atomic (selector action)
Package

linewise-template.

Source

linewise-template.lisp.

Function: get-destination (state)
Package

linewise-template.

Source

linewise-template.lisp.

Function: lambda-list-keyword-p (thing &rest additional)
Package

linewise-template.

Source

linewise-template.lisp.

Function: mapcar-to-streams (fn sequence)
Package

linewise-template.

Source

linewise-template.lisp.

Function: name+nargs (selector)
Package

linewise-template.

Source

linewise-template.lisp.

Function: process-atomic (input residual-line state &key begin end &allow-other-keys)
Package

linewise-template.

Source

linewise-template.lisp.

Function: process-lines (input prev-residual-line state &key begin end directive plain)
Package

linewise-template.

Source

linewise-template.lisp.

Function: read-line* (streams)
Package

linewise-template.

Source

linewise-template.lisp.

Function: sans-circumfix (line)
Package

linewise-template.

Source

linewise-template.lisp.

Function: selector-lambda-list (selector $trailer)
Package

linewise-template.

Source

linewise-template.lisp.

Function: symbol= (x y)
Package

linewise-template.

Source

linewise-template.lisp.

Function: update-scanner ()
Package

linewise-template.

Source

linewise-template.lisp.

Function: validate-destination (destination)
Package

linewise-template.

Source

linewise-template.lisp.

Function: validate-selector (selector)
Package

linewise-template.

Source

linewise-template.lisp.


6.2.4 Generic functions

Generic Function: compile-spec (selector sibling-selectors action detail)
Package

linewise-template.

Source

linewise-template.lisp.

Methods
Method: compile-spec :around (selector sibling-selectors action detail)
Method: compile-spec (selector sibling-selectors (action (eql :discard)) detail)
Method: compile-spec (selector sibling-selectors (action (eql :transform)) detail)
Method: compile-spec (selector sibling-selectors (action (eql :replace)) detail)
Method: compile-spec (selector sibling-selectors (action (eql :copy)) detail)

Appendix A Indexes


A.1 Concepts


A.2 Functions

Jump to:   A   B   C   D   F   G   I   L   M   N   P   R   S   U   V   W  
Index Entry  Section

A
after-selector: Private ordinary functions
atomic-selector: Private ordinary functions

B
backup-pathname: Private ordinary functions
bind-keys-and-suffix: Private macros
block-selector: Private ordinary functions

C
compile-check-end: Private ordinary functions
compile-check-end-directive: Private ordinary functions
compile-check-eot: Private ordinary functions
compile-copy-directive: Private ordinary functions
compile-directive-handler: Private ordinary functions
compile-pop-state: Private ordinary functions
compile-push-state: Private ordinary functions
compile-spec: Private generic functions
compile-spec: Private generic functions
compile-spec: Private generic functions
compile-spec: Private generic functions
compile-spec: Private generic functions
compile-spec: Private generic functions
compile-write-value: Private ordinary functions
compile-yield-dest: Private ordinary functions
cond/bind: Private macros
count-registers: Private ordinary functions

D
def-compiler-var: Private macros
directive: Private ordinary functions
directive-regex: Private ordinary functions
disallow-atomic: Private ordinary functions

F
Function, after-selector: Private ordinary functions
Function, atomic-selector: Private ordinary functions
Function, backup-pathname: Private ordinary functions
Function, block-selector: Private ordinary functions
Function, compile-check-end: Private ordinary functions
Function, compile-check-end-directive: Private ordinary functions
Function, compile-check-eot: Private ordinary functions
Function, compile-copy-directive: Private ordinary functions
Function, compile-directive-handler: Private ordinary functions
Function, compile-pop-state: Private ordinary functions
Function, compile-push-state: Private ordinary functions
Function, compile-write-value: Private ordinary functions
Function, compile-yield-dest: Private ordinary functions
Function, count-registers: Private ordinary functions
Function, directive: Private ordinary functions
Function, directive-regex: Private ordinary functions
Function, disallow-atomic: Private ordinary functions
Function, get-destination: Private ordinary functions
Function, lambda-list-keyword-p: Private ordinary functions
Function, mapcar-to-streams: Private ordinary functions
Function, name+nargs: Private ordinary functions
Function, process-atomic: Private ordinary functions
Function, process-lines: Private ordinary functions
Function, read-line*: Private ordinary functions
Function, sans-circumfix: Private ordinary functions
Function, selector-lambda-list: Private ordinary functions
Function, symbol=: Private ordinary functions
Function, update-scanner: Private ordinary functions
Function, validate-destination: Private ordinary functions
Function, validate-selector: Private ordinary functions

G
Generic Function, compile-spec: Private generic functions
get-destination: Private ordinary functions

I
if/bind: Private macros

L
lambda-list-keyword-p: Private ordinary functions

M
Macro, bind-keys-and-suffix: Private macros
Macro, cond/bind: Private macros
Macro, def-compiler-var: Private macros
Macro, if/bind: Private macros
Macro, process-template: Public macros
Macro, with-input: Private macros
Macro, with-temp-package: Private macros
Macro, with-temporary-output: Private macros
mapcar-to-streams: Private ordinary functions
Method, compile-spec: Private generic functions
Method, compile-spec: Private generic functions
Method, compile-spec: Private generic functions
Method, compile-spec: Private generic functions
Method, compile-spec: Private generic functions

N
name+nargs: Private ordinary functions

P
process-atomic: Private ordinary functions
process-lines: Private ordinary functions
process-template: Public macros

R
read-line*: Private ordinary functions

S
sans-circumfix: Private ordinary functions
selector-lambda-list: Private ordinary functions
symbol=: Private ordinary functions

U
update-scanner: Private ordinary functions

V
validate-destination: Private ordinary functions
validate-selector: Private ordinary functions

W
with-input: Private macros
with-temp-package: Private macros
with-temporary-output: Private macros


A.3 Variables

Jump to:   $   *  
S  
Index Entry  Section

$
$dest$: Private special variables
$file$: Private special variables
$input$: Private special variables
$line$: Private special variables
$residual-line$: Private special variables
$state$: Private special variables
$tmp-file$: Private special variables

*
*backup-pathname-suffix*: Public special variables
*destination*: Private special variables
*directive-base-packages*: Public special variables
*directive-circumfix*: Public special variables
*directive-escape*: Public special variables
*source-line-count*: Public special variables
*source-stream*: Public special variables

S
Special Variable, $dest$: Private special variables
Special Variable, $file$: Private special variables
Special Variable, $input$: Private special variables
Special Variable, $line$: Private special variables
Special Variable, $residual-line$: Private special variables
Special Variable, $state$: Private special variables
Special Variable, $tmp-file$: Private special variables
Special Variable, *backup-pathname-suffix*: Public special variables
Special Variable, *destination*: Private special variables
Special Variable, *directive-base-packages*: Public special variables
Special Variable, *directive-circumfix*: Public special variables
Special Variable, *directive-escape*: Public special variables
Special Variable, *source-line-count*: Public special variables
Special Variable, *source-stream*: Public special variables