This is the linewise-template Reference Manual, generated automatically by Declt version 4.0 beta 2 "William Riker" on Mon Feb 26 16:54:33 2024 GMT+0.
The main system appears first, followed by any subsystem dependency.
linewise-templateLinewise file/stream processor for code generation etc.
Boris Smilga <boris.smilga@gmail.com>
Boris Smilga <boris.smilga@gmail.com>
BSD-3-Clause
cl-ppcre (system).
cl-fad (system).
src (module).
Modules are listed depth-first from the system components tree.
linewise-template/srclinewise-template (system).
linewise-template.lisp (file).
Files are sorted by type and then listed depth-first from the systems components trees.
linewise-template/linewise-template.asdlinewise-template (system).
linewise-template/src/linewise-template.lispsrc (module).
*backup-pathname-suffix* (special variable).
*directive-base-packages* (special variable).
*directive-circumfix* (special variable).
*directive-escape* (special variable).
*source-line-count* (special variable).
*source-stream* (special variable).
process-template (macro).
$dest$ (special variable).
$file$ (special variable).
$input$ (special variable).
$line$ (special variable).
$residual-line$ (special variable).
$state$ (special variable).
$tmp-file$ (special variable).
*destination* (special variable).
after-selector (function).
atomic-selector (function).
backup-pathname (function).
bind-keys-and-suffix (macro).
block-selector (function).
compile-check-end (function).
compile-check-end-directive (function).
compile-check-eot (function).
compile-copy-directive (function).
compile-directive-handler (function).
compile-pop-state (function).
compile-push-state (function).
compile-spec (generic function).
compile-write-value (function).
compile-yield-dest (function).
cond/bind (macro).
count-registers (function).
def-compiler-var (macro).
directive (function).
directive-regex (function).
disallow-atomic (function).
get-destination (function).
if/bind (macro).
lambda-list-keyword-p (function).
mapcar-to-streams (function).
name+nargs (function).
process-atomic (function).
process-lines (function).
read-line* (function).
sans-circumfix (function).
selector-lambda-list (function).
symbol= (function).
update-scanner (function).
validate-destination (function).
validate-selector (function).
with-input (macro).
with-temp-package (macro).
with-temporary-output (macro).
Packages are listed by definition order.
linewise-templatecl-fad.
cl-ppcre.
common-lisp.
*backup-pathname-suffix* (special variable).
*directive-base-packages* (special variable).
*directive-circumfix* (special variable).
*directive-escape* (special variable).
*source-line-count* (special variable).
*source-stream* (special variable).
process-template (macro).
$dest$ (special variable).
$file$ (special variable).
$input$ (special variable).
$line$ (special variable).
$residual-line$ (special variable).
$state$ (special variable).
$tmp-file$ (special variable).
*destination* (special variable).
after-selector (function).
atomic-selector (function).
backup-pathname (function).
bind-keys-and-suffix (macro).
block-selector (function).
compile-check-end (function).
compile-check-end-directive (function).
compile-check-eot (function).
compile-copy-directive (function).
compile-directive-handler (function).
compile-pop-state (function).
compile-push-state (function).
compile-spec (generic function).
compile-write-value (function).
compile-yield-dest (function).
cond/bind (macro).
count-registers (function).
def-compiler-var (macro).
directive (function).
directive-regex (function).
disallow-atomic (function).
get-destination (function).
if/bind (macro).
lambda-list-keyword-p (function).
mapcar-to-streams (function).
name+nargs (function).
process-atomic (function).
process-lines (function).
read-line* (function).
sans-circumfix (function).
selector-lambda-list (function).
symbol= (function).
update-scanner (function).
validate-destination (function).
validate-selector (function).
with-input (macro).
with-temp-package (macro).
with-temporary-output (macro).
Definitions are sorted by export status, category, package, and then by lexicographic order.
String added to file path in order to obtain the name of the backup file.
List of packages which are to be used by the temporary package established for reading symbols in directives
Prefix or circumfix of directive lines (when in comments etc.): a list of 0, 1 or 2 ppcre strings.
String to introduce a directive
Reference to an integer incremented for each line read, and reset for each subsequent source stream.
Reference to the current source stream (the one from which a line most recently has been read).
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.
(eql :discard)) detail) ¶(eql :transform)) detail) ¶(eql :replace)) detail) ¶(eql :copy)) detail) ¶| Jump to: | A B C D F G I L M N P R S U V W |
|---|
| Jump to: | A B C D F G I L M N P R S U V W |
|---|
| Jump to: | $
*
S |
|---|
| Jump to: | $
*
S |
|---|
| Jump to: | F L M P S |
|---|
| Jump to: | F L M P S |
|---|