expand-string.lsp

Module index

source download

Module: expand-string.lsp

Author: Ralph Ronnquist, Real Thing Entertainment Pty. Ltd.
Location: http://www.realthing.com.au/files/newlisp/expand-string.lsp
Version: 1.1

Inclusion module providing string templating using expansion.

This is an inclusion module that provides an expand-string function to process a string template and replace key tokens as declared in a rules list of token-to-replacement associations with their associated values. It offers a similar function to expand but for strings, but uses string pattern match (without tokenization) to determine the replacement points, and evaluates the value parts to make the replacements.



§

expand-string

syntax: (expand-string text rules)
Processes the given text for the occurrences of the rule keys, and replaces these with the values obtained by evaluating the associated value expressions. The result is the new string with replacements. Note that a value expression may affect variable txt, which is the rest of the input following the expanding key, to optionally consume additional text in the replacement. See function .expand-map for an example.



§

expand-file

syntax: (expand-file file rules)
Reads the file and expand it using expand-string with the given rules.



§

.expand-eval

syntax: (.expand-eval ctx end)
This function is intended as expansion value function for an expand-string rule, to implement template expression evaluation. The ctx parameter tells the context for symbol creations. The optional end parameter tells the end of the replacement fragment. This function extracts the text fragment until the nearest end text, then evaluates this with eval-string, makes the result a string, and uses that as value to replace the whole block. See default-expand-rules below how a rule using this function may look.



§

.expand-map

syntax: (.expand-map ctx end)
This function is intended as expansion value function for an expand-string rule, to implement template fragment repetition. The optional ctx parameter tells the context for symbol creations. The optional end parameter tells the end of the fragment portion, which is "</MAP>" by default. The function pulls two s-expression from the template using read-expr. The first is a list of keys, and the second a list of binding lists for those keys. The rest of the fragment is then expanded recursively, repeatedly, with the keys having their subsequent bindings, and the block is replaced by the concatenation of these results. See default-expand-rules below how a rule using this function may look.



§

default-expand-rules

syntax: default-expand-rules
This constant holds a few default rules for using repetition end expression evaluation. Currently set to the following:

 (constant 'default-expand-rules
           '(("<MAP1>" (.expand-map MAIN "</MAP1>"))
             ("<MAP2>" (.expand-map MAIN "</MAP2>"))
             ("<MAP3>" (.expand-map MAIN "</MAP3>"))
             ("<MAP>" (.expand-map MAIN "</MAP>"))
             ("<EVAL>" (.expand-eval MAIN "</EVAL>"))))
 

These default rules obviously favours HTML templates. §
Example: The following is an illustration of expand-string using .expand-map:

(expand-string
          "<MAP>(A B) '((1 2) (3 4)) A B B A</MAP>"
          '(("<MAP>" (.expand-map)) ))
 

The example results in the string " 1 2 2 1 3 4 4 3".

Note that the binding lists expression is evaluated in the given context, or MAIN, if nil is given. Thus, the rule above is equivalent with the following: (.expand-map MAIN "</MAP>")

Note also that the fragment blocks cannot be nested. To achieve nested repetition, use several tag pairs, as in the following rule set:

 '(("<MAP1>" (.expand-map nil "</MAP1>"))
   ("<MAP2>" (.expand-map nil "</MAP2>"))
   ("<MAP3>" (.expand-map nil "</MAP3>")) )

In that case, the outer expansion keys may be used in the inner repetition although they are not actually bound to the values.

Example:

(expand-string
          {<EVAL>(first (exec "uname -mrs"))</EVAL>}
          default-expand-rules )

This example results in the machine details as reported by the uname program with the -mrs command line argument.

Example: This example illustrates HTML rendering, with a template file that includes certain keys for expansion. In this case I have a list if paragraps as value of variable texts, and want them inserted nicely into an HTML page. Note that the spaces following the two s-expressions in the MAP../MAP construct are compulsory, and they get consumed by the read-expr function.

 @PAGEDOCTYPE@
 <html><head><title>@TITLE@</title></head>
 <body><h1>@TITLE@</h1>
 <MAP>(text) texts <p>text</p></MAP>
 </body></html>

This template would be used in a context that provides suitable expansion rules for the "@PAGEDOCTYPE@" and "@TITLE@" keys, as well as the default "<MAP>" expansion rule.

- ∂ -
generated with newLISP  and newLISPdoc