Debian Codegraph @

docs/index.html

raw
1 <html>
2
3 <head>
4 <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
5 <title>CL-INTERPOL - String interpolation for Common Lisp</title>
6 <style type="text/css">
7 pre { padding:5px; background-color:#e0e0e0 }
8 h3, h4 { text-decoration: underline; }
9 a { text-decoration: none; padding: 1px 2px 1px 2px; }
10 a:visited { text-decoration: none; padding: 1px 2px 1px 2px; }
11 a:hover { text-decoration: none; padding: 1px 1px 1px 1px; border: 1px solid #000000; }
12 a:focus { text-decoration: none; padding: 1px 2px 1px 2px; border: none; }
13 a.none { text-decoration: none; padding: 0; }
14 a.none:visited { text-decoration: none; padding: 0; }
15 a.none:hover { text-decoration: none; border: none; padding: 0; }
16 a.none:focus { text-decoration: none; border: none; padding: 0; }
17 a.noborder { text-decoration: none; padding: 0; }
18 a.noborder:visited { text-decoration: none; padding: 0; }
19 a.noborder:hover { text-decoration: none; border: none; padding: 0; }
20 a.noborder:focus { text-decoration: none; border: none; padding: 0; }
21 pre.none { padding:5px; background-color:#ffffff }
22 code.yellow { background-color:#ffff00; }
23 </style>
24 <meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=yes">
25 </head>
26
27 <body bgcolor=white>
28
29 <h2>CL-INTERPOL - String interpolation for Common Lisp</h2>
30
31 <br>&nbsp;<br>
32 <em>&quot;<a href="http://www.arf.ru/Notes/Apostro/stfoot.html">The crux of the biscuit is the apostrophe.</a>&quot;</em> (<a href="http://zappa.com/">Frank Zappa</a>)
33
34 <blockquote>
35 <br>&nbsp;<br><h3>Abstract</h3>
36
37 CL-INTERPOL is a library for Common Lisp which modifies the reader so
38 that you can have interpolation within strings similar to Perl or Unix Shell
39 scripts. It also provides various ways to insert arbitrary characters
40 into literal strings even if your editor/IDE doesn't support them.
41 Here's an example:
42 <pre>
43 * (ql:quickload :cl-interpol)
44 * (named-readtables:in-readtable :interpol-syntax)
45 * (let ((a 42))
46 #?&quot;foo: \xC4\N{Latin capital letter U with diaeresis}\nbar: ${a}&quot;)
47 &quot;foo: &Auml;&Uuml;
48 bar: 42&quot;
49 </pre>
50 If you're looking for an alternative syntax for <em>characters</em>, see
51 <a href="https://github.com/edicl/cl-unicode/">CL-UNICODE</a>.
52 <p>
53 CL-INTERPOL comes with a <a
54 href="http://www.opensource.org/licenses/bsd-license.php">BSD-style
55 license</a> so you can basically do with it whatever you want.
56
57 <p>
58 <font color=red><a href="https://github.com/edicl/cl-interpol/archive/master.zip">Download current version</a></font> or visit the <a href="https://github.com/edicl/cl-interpol/">project on Github</a>.
59 </blockquote>
60
61 <br>&nbsp;<br><h3><a class=none name="contents">Contents</a></h3>
62 <ol>
63 <li><a href="#install">Download and installation</a>
64 <li><a href="#mail">Support</a>
65 <li><a href="#syntax">Syntax</a>
66 <ol>
67 <li><a href="#backslash">Backslashes</a>
68 <li><a href="#interpolation">Interpolation</a>
69 <li><a href="#regular">Support for CL-PPCRE/Perl regular expressions</a>
70 </ol>
71 <li><a href="#dictionary">The CL-INTERPOL dictionary</a>
72 <ol>
73 <li><a href="#enable-interpol-syntax"><code>enable-interpol-syntax</code></a>
74 <li><a href="#disable-interpol-syntax"><code>disable-interpol-syntax</code></a>
75 <li><a href="#*list-delimiter*"><code>*list-delimiter*</code></a>
76 <li><a href="#*outer-delimiters*"><code>*outer-delimiters*</code></a>
77 <li><a href="#*inner-delimiters*"><code>*inner-delimiters*</code></a>
78 <li><a href="#*interpolate-format-directives*"><code>*interpolate-format-directives*</code></a>
79 <li><a href="#*regex-delimiters*"><code>*regex-delimiters*</code></a>
80 </ol>
81 <li><a href="#bugs">Known issues</a>
82 <ol>
83 <li><a href="#curly"><code>{n,m}</code> modifiers in extended mode</a>
84 </ol>
85 <li><a href="#ack">Acknowledgements</a>
86 </ol>
87
88 <br>&nbsp;<br><h3><a name="install" class=none>Download and installation</a></h3>
89
90 CL-INTERPOL together with this documentation can be downloaded from <a
91 href="https://github.com/edicl/cl-interpol/archive/master.zip">Github</a>. The
92 current version is 0.2.7.
93 <p>
94 CL-INTERPOL comes with a system definition for <a
95 href="http://www.cliki.net/asdf">ASDF</a> so you can install the library with
96 <pre>
97 (asdf:load-system :cl-interpol)
98 </pre>
99 if you've unpacked it in a place where ASDF can find it. It depends on <a href="https://github.com/edicl/cl-unicode/">CL-UNICODE</a> and <a href="https://github.com/melisgl/named-readtables">NAMED-READTABLES</a>. Installation
100 via <a href="http://www.cliki.net/asdf-install">asdf-install</a> or
101 <a href="https://www.quicklisp.org/beta/">Quicklisp</a>
102 should also be possible.
103 <p>
104 <b>Note:</b> Before you can actually <em>use</em> the new reader
105 syntax you have to enable it with
106 <a href="#enable-interpol-syntax"><code>ENABLE-INTERPOL-SYNTAX</code></a>
107 or via named-readtables:
108 <pre>(named-readtables:in-readtable :interpol-syntax)</pre>
109
110 <p>
111 You can run a test suite which tests most aspects of the library with
112 <pre>
113 (asdf:test-system :cl-interpol)
114 </pre>
115 The test suite depends on <a href="https://github.com/edicl/flexi-streams/">FLEXI-STREAMS</a>.
116 <p>
117 The development version of cl-interpol can be found <a href="https://github.com/edicl/cl-interpol" target="_new">on
118 github</a>. Please use the github issue tracking system to
119 submit bug reports. Patches are welcome, please use <a href="https://github.com/edicl/cl-interpol/pulls">GitHub pull
120 requests</a>.
121
122 <br>&nbsp;<br><h3><a name="syntax" class=none>Syntax</a></h3>
123
124 CL-INTERPOL installs <code class=yellow>?</code> (question mark) as a
125 &quot;sub-character&quot; of the <a
126 href="http://www.lispworks.com/documentation/HyperSpec/Body/26_glo_d.htm#dispatching_macro_character">dispatching
127 macro character</a> <code class=yellow>#</code> (sharpsign), i.e. it relies on
128 the fact that sharpsign is a dispatching macro character in the <a
129 href="http://www.lispworks.com/documentation/HyperSpec/Body/26_glo_c.htm#current_readtable">current
130 readtable</a> when <a
131 href="#enable-interpol-syntax"><code>ENABLE-INTERPOL-SYNTAX</code></a>
132 is invoked.
133 <p>
134 The question mark may optionally be followed by an <code class=yellow>R</code> and
135 an <code class=yellow>X</code> (case doesn't matter) - see <a href="#regular">the
136 section about regular expression syntax</a> below. If both of them are
137 present, the <code class=yellow>R</code> <em>must</em> precede the <code class=yellow>X</code>.
138 <p>
139 The next character is the <a class=none name=outer><em>opening outer delimiter</em></a> which may
140 be one of <code class=yellow>&quot;</code> (double quote), <code class=yellow>'</code>
141 (apostrophe), <code class=yellow>|</code> (vertical bar), <code class=yellow>#</code>
142 (sharpsign), <code class=yellow>/</code> (slash), <code class=yellow>(</code> (left
143 parenthesis), <code class=yellow>&lt;</code> (less than), <code class=yellow>[</code> (left
144 square bracket), or <code class=yellow>{</code> (left curly bracket). (But see <a href="#*outer-delimiters*"><code>*OUTER-DELIMITERS*</code></a>.)
145 <p>
146 The following characters comprise the string which is read until the
147 <em>closing outer delimiter</em> is seen. The closing outer delimiter
148 is the same character as the opening outer delimiter - unless the
149 opening delimiter was one of the last four described below in which
150 case the closing outer delimiter is the corresponding closing (right)
151 bracketing character. So these are all valid CL-INTERPOL string
152 equivalent to <code>&quot;abc&quot;</code>:
153
154 <pre>
155 * #?&quot;abc&quot;
156 &quot;abc&quot;
157 * #?r&quot;abc&quot;
158 &quot;abc&quot;
159 * #?x&quot;abc&quot;
160 &quot;abc&quot;
161 * #?rx&quot;abc&quot;
162 &quot;abc&quot;
163 * #?'abc'
164 &quot;abc&quot;
165 * #?|abc|
166 &quot;abc&quot;
167 * #?#abc#
168 &quot;abc&quot;
169 * #?/abc/
170 &quot;abc&quot;
171 * #?(abc)
172 &quot;abc&quot;
173 * #?[abc]
174 &quot;abc&quot;
175 * #?{abc}
176 &quot;abc&quot;
177 * #?&lt;abc&gt;
178 &quot;abc&quot;
179 </pre>
180
181 A character which would otherwise be a closing outer delimiter can be
182 escaped by a backslash immediately preceding it (unless this backslash
183 is itself escaped by another backslash). Also, the bracketing
184 delimiters can nest, i.e. a right bracketing character which might
185 otherwise be closing outer delimiter will be read as part of the
186 string if it is matched by a preceding left bracketing character
187 within the string.
188 <pre>
189 * #?&quot;abc&quot;
190 &quot;abc&quot;
191 * #?&quot;abc\&quot;&quot;
192 &quot;abc\&quot;&quot;
193 * #?&quot;abc\\&quot;
194 &quot;abc\\&quot;
195 * #?[abc]
196 &quot;abc&quot;
197 * #?[a[b]c]
198 &quot;a[b]c&quot;
199 * #?[a[[b]]c]
200 &quot;a[[b]]c&quot;
201 * #?[a[[][]]b]
202 &quot;a[[][]]b&quot;
203 </pre>
204
205 The characters between the outer delimiters are read one by one and
206 inserted into the resulting string as is unless one of the special
207 characters <a href="#backslash"><code class=yellow>\</code> (backslash)</a>, <code class=yellow>$</code> (dollar sign),
208 or <code class=yellow>@</code> (at-sign) is encountered. The behaviour with respect
209 to these special characters is modeled after Perl because CL-INTERPOL
210 is intended to be usable with <a
211 href="https://github.com/edicl/cl-ppcre/">CL-PPCRE</a>.
212
213 <h4><a name="backslash" class=none>Backslashes</a></h4> Here's a short
214 summary of what might occur after a backslash, originally copied
215 from <code>man&nbsp;perlop</code>. Details below - you can
216 click on the entries in this table to go to the corresponding paragraph.
217
218 <pre class=none>
219 <a class=none href="#tab">\t tab (HT, TAB)
220 \n newline (NL)
221 \r return (CR)
222 \f form feed (FF)
223 \b backspace (BS)
224 \a alarm (bell) (BEL)
225 \e escape (ESC)</a>
226 <a class=none href="#octal">\033 octal char (ESC)</a>
227 <a class=none href="#hex">\x1b hex char (ESC)
228 \x{263a} wide hex char (SMILEY)</a>
229 <a class=none href="#control">\c[ control char (ESC)</a>
230 <a class=none href="#name">\N{name} named char</a>
231
232 <a class=none href="#lower">\l lowercase next char
233 \u uppercase next char</a>
234 <a class=none href="#Upper">\L lowercase till \E
235 \U uppercase till \E
236 \E end case modification</a>
237 <a class=none href="#quote">\Q quote non-word characters till \E</a>
238
239 <a class=none href="#ignl">\<span style="border:1px solid #a0a0a0">&#x2424;</span> ignore the newline and following whitespaces</a>
240 </pre>
241 <p>
242 <a class=none name="tab">If</a> a backslash is followed by
243 <code class=yellow>n</code>, <code class=yellow>r</code>, <code class=yellow>f</code>, <code class=yellow>b</code>,
244 <code class=yellow>a</code>, or <code class=yellow>e</code> (all lowercase) then the corresponding character
245 <code>#\Newline</code>, <code>#\Return</code>, <code>#\Page</code>,
246 <code>#\Backspace</code>, <code>(CODE-CHAR 7)</code>, or
247 <code>(CODE-CHAR 27)</code> is inserted into the string.
248 <pre>
249 * #?&quot;New\nline&quot;
250 &quot;New
251 line&quot;
252 </pre>
253 <p>
254 <a class=none name="octal">If</a> a backslash is followed by one of
255 the digits <code class=yellow>0</code> to <code class=yellow>9</code>, then this digit and
256 the following characters are read and parsed as octal digits and will
257 be interpreted as the character code of the character to insert
258 instead of this sequence. The sequence ends with the first character
259 which is not an octal digit but <em>at most</em> three digits will be
260 read. Only the rightmost eight bits of the resulting number will be
261 used for the character code.
262
263 <pre>
264 * #?"\40\040"
265 " " <font color=orange>;; two spaces</font>
266 * (map 'list #'char-code #?"\0\377\777")
267 (0 255 255) <font color=orange>;; note that \377 and \777 yield the same result</font>
268 * #?"Only\0403 digits!"
269 "Only 3 digits!"
270 * (map 'list #'identity #?"\9")
271 (#\9)
272 </pre>
273 <p>
274 <a class=none name="hex">If</a> a backslash is followed by an <code class=yellow>x</code> (lowercase) the
275 following characters are read and parsed as hexadecimal digits and
276 will be interpreted as the character code of the character to insert
277 instead of this sequence. The sequence of hexadecimal digits ends with
278 the first character which is not one of the characters <code class=yellow>0</code>
279 to <code class=yellow>9</code>, <code class=yellow>a</code> to <code class=yellow>f</code>, or <code class=yellow>A</code>
280 to <code class=yellow>F</code> but <em>at most</em> two digits will be read. If the
281 character immediately following the <code class=yellow>x</code> is a <code class=yellow>{</code>
282 (left curly bracket), then all the following characters up to a
283 <code class=yellow>}</code> (right curly bracket) must be hexadecimal digits and
284 comprise a number which'll be taken as the character code (and which
285 obviously should denote a character known by your Lisp
286 implementation). Note that in both case it is legal that zero digits
287 will be read which'll be interpreted as the character code
288 <code>0</code>.
289 <pre>
290 * (char #?&quot;\x20&quot; 0)
291 #\Space
292 * (char-code (char #?&quot;\x&quot; 0))
293 0
294 * (char-code (char #?&quot;\x{}&quot; 0))
295 0
296 * (<a href="https://github.com/edicl/cl-unicode/" class=none>unicode-name</a> (char #?&quot;\x{2323}&quot; 0))
297 &quot;SMILE&quot;
298 * #?&quot;Only\x202 digits!&quot;
299 &quot;Only 2 digits!&quot;
300 </pre>
301 <p>
302 <a class=none name="control">If</a> a backslash is followed by a
303 <code class=yellow>c</code> (lowercase) then the <a
304 href="http://www.cs.tut.fi/~jkorpela/chars/c0.html">ASCII control
305 code</a> of the following character is inserted into the string. Note
306 that this only defined for <code class=yellow>A</code> to <code class=yellow>Z</code>,
307 <code class=yellow>[</code>, <code class=yellow>\</code>, <code class=yellow>]</code>, <code class=yellow>^</code>, and
308 <code class=yellow>_</code> although CL-INTERPOL will also accept other
309 characters. In fact, the transformation is implemented as
310 <pre>
311 (code-char (logxor #x40 (char-code (char-upcase &lt;<em>char</em>&gt;))))
312 </pre>
313 where <code>&lt;<em>char</em>&gt;</code> is the character following <code class=yellow>\c</code>.
314 <pre>
315 * (char-name (char #?&quot;\cH&quot; 0))
316 <font color=orange>;; see 13.1.7 of the ANSI standard, though</font>
317 &quot;Backspace&quot;
318 * (char= (char #?&quot;\cj&quot; 0) #\Newline)
319 T
320 </pre>
321
322 <p>
323 <a class=none name="name">If</a> a backslash is followed by an
324 <code class=yellow>N</code> (uppercase) the following character <em>must</em> be a
325 <code class=yellow>{</code> (left curly bracket). The characters
326 following the bracket are read until a <code class=yellow>}</code>
327 (right curly bracket) is seen and comprise the Unicode <em>name</em>
328 of the character to be inserted into the string. This name is
329 interpreted as a Unicode character name
330 by <a href="https://github.com/edicl/cl-unicode/">CL-UNICODE</a> and returns
331 the
332 character <code>CHARACTER-NAMED</code>.
333 This obviously also means that you can fine-tune this behaviour using
334 CL-UNICODE's global special variables.
335 <pre>
336 * (unicode-name (char #?"\N{Greek capital letter Sigma}" 0))
337 "GREEK CAPITAL LETTER SIGMA"
338 * (unicode-name (char #?"\N{GREEK CAPITAL LETTER SIGMA}" 0))
339 "GREEK CAPITAL LETTER SIGMA"
340 * (setq *try-abbreviations-p* t)
341 T
342 * (unicode-name (char #?"\N{Greek:Sigma}" 0))
343 "GREEK CAPITAL LETTER SIGMA"
344 * (unicode-name (char #?"\N{Greek:sigma}" 0))
345 "GREEK SMALL LETTER SIGMA"
346 * (setq *scripts-to-try* "Greek")
347 "Greek"
348 * (unicode-name (char #?"\N{Sigma}" 0))
349 "GREEK CAPITAL LETTER SIGMA"
350 * (unicode-name (char #?"\N{sigma}" 0))
351 "GREEK SMALL LETTER SIGMA"
352 </pre>
353
354 Of course, <code class=yellow>\N</code> won't magically make your Lisp implementation Unicode-aware. You can only use the names of characters that are actually supported by your Lisp.
355 <p>
356 <a class=none name="lower">If</a> a backslash is followed by an
357 <code class=yellow>l</code> or a <code class=yellow>u</code> (both lowercase) the following
358 character (if any) is <a href="http://www.lispworks.com/documentation/HyperSpec/Body/f_char_u.htm">downcased or uppercased</a> respectively.
359 <pre>
360 * #?&quot;\lFOO&quot;
361 &quot;fOO&quot;
362 * #?&quot;\ufoo&quot;
363 &quot;Foo&quot;
364 * #?&quot;\l&quot;
365 &quot;&quot;
366 </pre>
367
368 <p>
369 <a class=none name="Upper">If</a> a backslash is followed by an
370 <code class=yellow>L</code> or a <code class=yellow>U</code> (both uppercase) the following
371 characters up to <code class=yellow>\E</code> (uppercase) or another <code class=yellow>\L</code> or
372 <code class=yellow>\U</code> are <a
373 href="http://www.lispworks.com/documentation/HyperSpec/Body/f_stg_up.htm">upcased
374 or downcased</a> respectively. While <code class=yellow>\E</code> simply ends the
375 scope of <code class=yellow>\L</code> or <code class=yellow>\U</code>, another <code class=yellow>\L</code>
376 or <code class=yellow>\U</code> will introduce a new round of upcasing or
377 downcasing.
378 <pre>
379 * #?&quot;\Ufoo\Ebar&quot;
380 &quot;FOObar&quot;
381 * #?&quot;\LFOO\EBAR&quot;
382 &quot;fooBAR&quot;
383 * #?&quot;\LFOO\Ubar&quot;
384 &quot;fooBAR&quot;
385 * #?&quot;\LFOO&quot;
386 &quot;foo&quot;
387 </pre>
388 These examples may seem trivial but <code class=yellow>\U</code> and friends might be very helpful if you <a href="#interpolation">interpolate</a> strings.
389
390 <p>
391 <a class=none name="quote">If</a> a backslash is followed by a
392 <code class=yellow>Q</code> (uppercase) the following characters up to <code class=yellow>\E</code> (uppercase) are <em>quoted</em>, i.e. every character except for <code class=yellow>0</code>
393 to <code class=yellow>9</code>, <code class=yellow>a</code> to <code class=yellow>z</code>, <code class=yellow>A</code>
394 to <code class=yellow>Z</code>, and <code class=yellow>_</code> (underscore) is preceded by a backslash. Corresponding pairs of <code class=yellow>\Q</code> and <code class=yellow>\E</code> can be nested.
395 <pre>
396 * #?&quot;-\Q-\E-&quot;
397 &quot;-\\--&quot;
398 * #?&quot;\Q-\Q-\E-\E&quot;
399 &quot;\\-\\\\\\-\\-&quot;
400 * #?&quot;-\Q-&quot;
401 &quot;-\\-&quot;
402 </pre>
403 As you might have noticed, <code class=yellow>\E</code> is used to end the scope of <code class=yellow>\Q</code> as well as that of <code class=yellow>\L</code> and <code class=yellow>\U</code>. As a consequence, pairs of <code class=yellow>\Q</code> and <code class=yellow>\E</code> can be nested between <code class=yellow>\L</code> or <code class=yellow>\U</code> and <code class=yellow>\E</code> and vice-versa but each occurence of <code class=yellow>\L</code> or <code class=yellow>\U</code> which is preceded by another <code class=yellow>\L</code> or <code class=yellow>\U</code> will immediately end the scope of all enclosed <code class=yellow>\Q</code> modifiers. Hmm, need an example?
404 <pre>
405 * #?&quot;\LAa-\QAa-\EAa-\E&quot;
406 &quot;aa-aa\\-aa-&quot;
407 * #?&quot;\QAa-\LAa-\EAa-\E&quot;
408 &quot;Aa\\-aa\\-Aa\\-&quot;
409 * #?&quot;\U\QAa-\LAa-\EAa-\E&quot;
410 &quot;AA\\-aa-Aa-&quot; <font color=orange>;; note that only the first hyphen is quoted now</font>
411 </pre>
412
413 Quoting characters with <code class=yellow>\Q</code> is especially helpful if you want to <a href="#interpolation">interpolate</a> a string verbatim into a <a href="#regular">regular expression</a>.
414
415 <p>
416 <a class=none name="ignl">If</a> a backslash is placed at the end of a line, it works as the <a href="http://www.lispworks.com/documentation/HyperSpec/Body/22_cic.htm">tilde newline</a> directive to Common Lisp's <code>FORMAT</code> function. That is, the newline immediately following the backslash and any non-newline whitespace characters after the newline are ignored. This escape sequence allows to break long string literals into several lines of code, so as to maintain convenient line width and indentation of code.
417 <pre>
418 * #?&quot;@@ -1,11 +1,12 @@\n Th\n-e\n+at\n quick b\n\
419 @@ -22,18 +22,17 @@\n jump\n-s\n+ed\n over \n\
420 -the\n+a\n laz\n&quot;
421 &quot;@@ -1,11 +1,12 @@
422 Th
423 -e
424 +at
425 quick b
426 @@ -22,18 +22,17 @@
427 jump
428 -s
429 +ed
430 over
431 -the
432 +a
433 laz
434 &quot;
435 </pre>
436
437 <p>
438 All other characters following a backslash are left as is and inserted into the string. This is also true for the backslash itself, for <code class=yellow>$</code>, <code class=yellow>@</code>, and - as mentioned above - for the <a href="#outer">outer closing delimiter</a>.
439 <pre>
440 * #?&quot;\&quot;\\f\o\o\&quot;&quot;
441 &quot;\&quot;\\foo\&quot;&quot;
442 </pre>
443
444 <br>&nbsp;<br><h3><a name="interpolation" class=none>Interpolation</a></h3>
445
446 If a <code class=yellow>$</code> (dollar sign) or <code class=yellow>@</code> (at-sign) is seen
447 and followed by one of <code class=yellow>{</code> (left curly bracket), <code class=yellow>[</code> (left square bracket), <code class=yellow>&lt;</code> (less than), or <code class=yellow>(</code> (left parenthesis) (but see <a href="#*inner-delimiters*"><code>*INNER-DELIMITERS*</code></a>), the
448 characters following the bracket are read up to the corresponding closing (right)
449 bracketing character. They are read as Lisp forms and treated as an <a
450 href="http://www.lispworks.com/documentation/HyperSpec/Body/26_glo_i.htm#implicit_progn">implicit
451 progn</a> the result of which will be inserted into the string at
452 execution time. (Technically this is done by temporarily making the syntax of the closing right bracketing character in the <a
453 href="http://www.lispworks.com/documentation/HyperSpec/Body/26_glo_c.htm#current_readtable">current
454 readtable</a> be the same as the syntax of <code class=yellow>)</code> (right parenthesis) in the <a href="http://www.lispworks.com/documentation/HyperSpec/Body/26_glo_s.htm#standard_readtable">standard readtable</a> and then reading the forms with <a href="http://www.lispworks.com/documentation/HyperSpec/Body/f_rd_del.htm"><code>READ-DELIMITED-LIST</code></a>.)
455 <p>
456 The result of the forms following a <code class=yellow>$</code> (dollar sign) is inserted into the string as with <a href="http://www.lispworks.com/documentation/HyperSpec/Body/f_wr_pr.htm"><code>PRINC</code></a> at execution time. The result of the forms following an <code class=yellow>@</code> (at-sign) <em>must</em> be a list. The elements of this list are inserted into the string one by one as with <code>PRINC</code> interspersed (or &quot;joined&quot; if you prefer) with the contents of the variable <a href="#*list-delimiter*"><code>*LIST-DELIMITER*</code></a> (also inserted as with <code>PRINC</code>).
457 <p>
458 Every other <code class=yellow>$</code> or <code class=yellow>@</code> is inserted into the string as is.
459 <pre>
460 * (let* ((a &quot;foo&quot;)
461 (b #\Space)
462 (c &quot;bar&quot;)
463 (d (list a b c))
464 (x 40))
465 (values #?&quot;$ @&quot;
466 #?&quot;$(a)&quot;
467 #?&quot;$&lt;a&gt;$[b]&quot;
468 #?&quot;\U${a}\E \u${a}&quot;
469 (let ((<a href="#*list-delimiter*" class=none>*list-delimiter*</a> #\*))
470 #?&quot;@{d}&quot;)
471 (let ((<a href="#*list-delimiter*" class=none>*list-delimiter*</a> &quot;&quot;))
472 #?&quot;@{d}&quot;)
473 #?&quot;The result is ${(let ((y 2)) (+ x y))}&quot;
474 #?&quot;${#?'${a} ${c}'} ${x}&quot;)) <font color=orange>;; note the embedded CL-INTERPOL string</font>
475 &quot;$ @&quot;
476 &quot;foo&quot;
477 &quot;foo &quot;
478 &quot;FOO Foo&quot;
479 &quot;foo* *bar&quot;
480 &quot;foo bar&quot;
481 &quot;The result is 42&quot;
482 &quot;foo bar 40&quot;
483 </pre>
484 Interpolations are realized by creating code which is evaluated at
485 execution time. For example, the expansion of
486 <code>#?&quot;\Q-\l${(let&nbsp;((x&nbsp;40))&nbsp;(+&nbsp;x&nbsp;2))}&quot;</code> might look
487 like this:
488
489 <pre>
490 (with-output-to-string (#:G1098)
491 (write-string (cl-ppcre:quote-meta-chars
492 (with-output-to-string (#:G1099)
493 (write-string &quot;-&quot; #:G1099)
494 (let ((#:G1100
495 (format nil &quot;~A&quot;
496 (progn
497 (let ((x 40))
498 (+ x 2))))))
499 (when (plusp (length #:G1100))
500 (setf (char #:G1100 0)
501 (char-downcase (char #:G1100 0))))
502 (write-string #:G1100 #:G1099))))
503 #:G1098))
504 </pre>
505
506 However, if a string read by CL-INTERPOL does not contain interpolations, it is guaranteed to be expanded into a constant Lisp string.
507
508 <br>&nbsp;<br><h3><a name="regular" class=none>Support for CL-PPCRE/Perl regular expressions</a></h3>
509
510 Beyond what has been explained above CL-INTERPOL can support Perl regular expression syntax. This feature is mainly intended for use with <a href="https://github.com/edicl/cl-ppcre/">CL-PPCRE</a> (version 0.7.0 or higher). The <em>regular expression mode</em> is switched on if the <a href="#outer">opening outer delimiter</a> is a <code class=yellow>/</code> (slash) - but see <a href="#*regex-delimiters*"><code>*REGEX-DELIMITERS*</code></a>. It is also on if there's an <code class=yellow>r</code> (lowercase or uppercase) in front of the opening outer delimiter. If there's also an <code class=yellow>x</code> (lowercase or uppercase) in front of the opening outer delimiter (but <em>behind</em> the <code class=yellow>r</code> if it's there), the string will be read in <em>extended mode</em> (see <code>man&nbsp;perlre</code> for a detailed explanation). In these modes the following things are different from what's described above:
511 <ul>
512
513 <li><code class=yellow>\p</code>, <code class=yellow>\P</code>, <code class=yellow>\w</code>, <code class=yellow>\W</code>, <code class=yellow>\s</code>,
514 <code class=yellow>\S</code>, <code class=yellow>\d</code>, and <code class=yellow>\D</code> are never
515 converted to their unescaped (backslash-less) counterparts because
516 they have or can have a special meaning in regular expressions.
517 <pre>
518 * #?#\W\o\w#
519 &quot;Wow&quot;
520 * #?/\W\o\w/
521 &quot;\\Wo\\w&quot;
522 * #?r#\W\o\w#
523 &quot;\\Wo\\w&quot;
524 </pre>
525 <li><code class=yellow>\k</code>, <code class=yellow>\b</code>, <code class=yellow>\B</code>,
526 <code class=yellow>\a</code>, <code class=yellow>\z</code>, and <code class=yellow>\Z</code> are only
527 converted to their unescaped (backslash-less) counterparts if they are within a <em>character class</em> (i.e. enclosed in square brackets) because
528 they have a special meaning in regular expressions outside of character classes.
529 <pre>
530 * #?/\A[\A-\Z]\Z/
531 &quot;\\A[A-Z]\\Z&quot;
532 * #?/\A[]\A-\Z]\Z/
533 &quot;\\A[]A-Z]\\Z&quot;
534 * #?/\A[^]\A-\Z]\Z/
535 &quot;\\A[^]A-Z]\\Z&quot;
536 </pre>
537 <li><a href="#octal">Octal representations of character codes</a> are left as is and not expanded if they're not within character classes and could possible denote a back-reference to a register group. (Actually, this also holds for sequences starting with <code class=yellow>\8</code> or <code class=yellow>\9</code> in compliance with Perl.)
538 <pre>
539 * (map 'list #'identity #?/\0\40[\40]/)
540 (#\Null #\\ #\4 #\0 #\[ #\Space #\])
541 </pre>
542 <li>Characters which are represented by <a href="#octal">octal</a> or <a href="#hex">hexadecimal</a> codes, by <a href="#name">names</a>, or escaped by a preceding backslash are 'protected' by a backslash if they have a special meaning within regular expressions.
543 <pre>
544 * #?&quot;\x2B\\\.[\.]&quot;
545 &quot;+\\.[.]&quot;
546 * #?/\x2B\\\.[\.]/
547 &quot;\\+\\\\\\.[.]&quot; <font color=orange>;; note that the second dot is not 'protected' because it's in a character class</font>
548 </pre>
549 <li>Embedded comments (like <code class=yellow>(?#...)</code>) are removed from the string - with the exception that they are replaced with <code class=yellow>(?:)</code> (a non-capturing, empty group which will be otimized away by CL-PPCRE) if the next character is a hexadecimal digit.
550 <pre>
551 * #?/A(?#n embedded) comment/
552 &quot;A comment&quot;
553 * #?/\1(?#)2/
554 &quot;\\1(?:)2&quot; <font color=orange>;; instead of &quot;\\12&quot; which has a different meaning to the regex engine</font>
555 </pre>
556 <li><a href="#interpolation">Interpolation</a> only works with curly brackets (and only if they haven't been removed from <a href="#*inner-delimiters*"><code>*INNER-DELIMITERS*</code></a>).
557 <pre>
558 * (let ((a 42))
559 (values #?&quot;$(a)&quot; #?&quot;${a}&quot;
560 #?/$(a)/ #?/${a}/))
561 &quot;42&quot;
562 &quot;42&quot;
563 &quot;$(a)&quot;
564 &quot;42&quot;
565 </pre>
566 <li>In extended mode whitespace characters (one of <code>#\Space</code>, <code>#\Tab</code>, <code>#\Linefeed</code>, <code>#\Return</code>, and <code>#\Page</code>) are removed from the string unless they are escaped by a backslash or within a character class.
567 <pre>
568 * #?/ \ [ ]/
569 &quot; [ ]&quot; <font color=orange>;; two spaces in front of square bracket</font>
570 * #?x/ \ [ ]/
571 &quot; [ ]&quot; <font color=orange>;; one space in front of square bracket</font>
572 </pre>
573 <li>In extended mode end-of-line comments (starting with <code class=yellow>#</code> (sharpsign) and ending with the newline character) are removed from the string - with the exception that they are replaced with <code class=yellow>(?:)</code> (a non-capturing, empty group which will be otimized away by CL-PPCRE) if the next character is a hexadecimal digit.
574 <pre>
575 * #?x/[a-z]#blabla
576 \$/
577 &quot;[a-z]$&quot;
578 * #?x/\1#
579 2/
580 &quot;\\1(?:)2&quot; <font color=orange>;; instead of &quot;\\12&quot; which has a different meaning to the regex engine</font>
581 </pre>
582 </ul>
583
584 If all this seems complicated, just keep in mind that this mode is
585 meant so that you can feed strings to <a
586 href="https://github.com/edicl/cl-ppcre/">CL-PPCRE</a> exactly as if you had
587 written them for Perl (without counting Lisp backslashes
588 versus Perl backslashes). However, you should <em>not</em> use
589 both CL-INTERPOL's as well as CL-PPCRE's extended mode at once because
590 this might lead to errors. (CL-PPCRE's will, e.g., throw away
591 whitespace which had been escaped in CL-INTERPOL.)
592 <pre>
593 * (let ((scanner (cl-ppcre:create-scanner &quot; a\\ a &quot; :extended-mode t)))
594 (cl-ppcre:scan scanner &quot;a a&quot;))
595 0
596 3
597 #()
598 #()
599 * (let ((scanner (cl-ppcre:create-scanner #?x/ a\ a /)))
600 (cl-ppcre:scan scanner &quot;a a&quot;))
601 0
602 3
603 #()
604 #()
605 * (let ((scanner (cl-ppcre:create-scanner #?x/ a\ a / :extended-mode t)))
606 <font color=orange>;; wrong, because extended mode is applied twice</font>
607 (cl-ppcre:scan scanner &quot;a a&quot;))
608 NIL
609 </pre>
610
611 <br>&nbsp;<br><h3><a class=none name="dictionary">The CL-INTERPOL dictionary</a></h3>
612
613 CL-INTERPOL exports the following symbols:
614
615 <p><br>[Macro]
616 <br><a class=none name="enable-interpol-syntax"><b>enable-interpol-syntax</b> <i><tt>&amp;key</tt> modify-*readtable*</i>=&gt; |</a>
617
618 <blockquote>
619
620 <p>This is used to enable the reader syntax described <a href="#syntax">above</a>. This macro
621 expands into an <a
622 href="http://www.lispworks.com/documentation/HyperSpec/Body/s_eval_w.htm"><code>EVAL-WHEN</code></a>
623 so that if you use it as a <a
624 href="http://www.lispworks.com/documentation/HyperSpec/Body/26_glo_t.htm#top_level_form">top-level
625 form</a> in a file to be loaded and/or compiled it'll do what you
626 expect.</p>
627
628 <p>If the parameter <code>modify-*readtable*</code> is NIL (the
629 default) this will push the <a
630 href="http://www.lispworks.com/documentation/HyperSpec/Body/26_glo_c.htm#current_readtable">current
631 readtable</a> on a stack so that matching calls of
632 <code>ENABLE-INTERPOL-SYNTAX</code> and <a
633 href="#disable-interpol-syntax"><code>DISABLE-INTERPOL-SYNTAX</code></a>
634 can nest. Otherwise the current value of <code>*readtable*</code> will
635 be modified.</p>
636
637 <p>Note: by default the reader syntax is <em>not</em>
638 enabled after loading CL-INTERPOL.</p>
639
640 </blockquote>
641
642 <p><br>[Macro]
643 <br><a class=none name="disable-interpol-syntax"><b>disable-interpol-syntax</b> =&gt; |</a>
644
645 <blockquote><br>
646
647 This is used to disable the reader syntax described <a href="#syntax">above</a>. This macro
648 expands into an <a
649 href="http://www.lispworks.com/documentation/HyperSpec/Body/s_eval_w.htm"><code>EVAL-WHEN</code></a>
650 so that if you use it as a <a
651 href="http://www.lispworks.com/documentation/HyperSpec/Body/26_glo_t.htm#top_level_form">top-level
652 form</a> in a file to be loaded and/or compiled it'll do what you
653 expect. Technically this'll pop a readtable from the stack described <a href="#enable-interpol-syntax">above</a> so that matching calls of <a href="#enable-interpol-syntax"><code>ENABLE-INTERPOL-SYNTAX</code></a> and <code>DISABLE-INTERPOL-SYNTAX</code> can nest. If the stack is empty (i.e. when <code>DISABLE-INTERPOL-SYNTAX</code> is called without a preceding call to <a href="#enable-interpol-syntax"><code>ENABLE-INTERPOL-SYNTAX</code></a>), the <a href="http://www.lispworks.com/documentation/HyperSpec/Body/26_glo_s.htm#standard_readtable">standard readtable</a> is re-established.
654
655 </blockquote>
656
657 <p><br>[Special variable]
658 <br><a class=none name="*list-delimiter*"><b>*list-delimiter*</b></a>
659
660 <blockquote><br>
661
662 The contents of this variable are inserted between the elements of a list <a href="#interpolation">interpolated with <code class=yellow>@</code></a> at execution time. They are inserted as with <a href="http://www.lispworks.com/documentation/HyperSpec/Body/f_wr_pr.htm"><code>PRINC</code></a>. The default value is <code class=yellow>&quot;&nbsp;&quot;</code> (one space).
663
664 </blockquote>
665
666 <p><br>[Special variable]
667 <br><a class=none name="*outer-delimiters*"><b>*outer-delimiters*</b></a>
668
669 <blockquote><br>
670
671 This is a list of acceptable <a href="#outer">outer delimiters</a>. The elements of this list are either characters or dotted pairs the car and cdr of which are characters. A character denotes a delimiter like <code class=yellow>'</code> (apostrophe) which is the opening as well as the closing delimiter. A dotted pair like <code>(#\{&nbsp;.&nbsp;#\})</code> denotes a pair of matching bracketing delimiters. The name of this list is exported so that you can customize CL-INTERPOL's behaviour by <em>removing</em> elements from this list, you are advised not to add any - specifically you should not add alphanumeric characters or the backslash. Note that this variable has effect at read time so you probably need to wrap an <a
672 href="http://www.lispworks.com/documentation/HyperSpec/Body/s_eval_w.htm"><code>EVAL-WHEN</code></a> around forms that change its value. The default value is
673 <pre>
674 '((#\( . #\))
675 (#\{ . #\})
676 (#\&lt; . #\&gt)
677 (#\[ . #\])
678 #\/ #\| #\&quot; #\' #\#))
679 </pre>
680
681 </blockquote>
682
683 <p><br>[Special variable]
684 <br><a class=none name="*inner-delimiters*"><b>*inner-delimiters*</b></a>
685
686 <blockquote><br>
687
688 This is a list of acceptable delimiters for <a href="#interpolation">interpolation</a>. The elements of this list are either characters or dotted pairs the car and cdr of which are characters. A character denotes a delimiter like <code class=yellow>'</code> (apostrophe) which is the opening as well as the closing delimiter. A dotted pair like <code>(#\{&nbsp;.&nbsp;#\})</code> denotes a pair of matching bracketing delimiters. The name of this list is exported so that you can customize CL-INTERPOL's behaviour by <em>removing</em> elements from this list, you are advised <em>not</em> to add any - specifically you should not add alphanumeric characters or the backslash. Note that this variable has effect at read time so you probably need to wrap an <a
689 href="http://www.lispworks.com/documentation/HyperSpec/Body/s_eval_w.htm"><code>EVAL-WHEN</code></a> around forms that change its value. The default value is
690 <pre>
691 '((#\( . #\))
692 (#\{ . #\})
693 (#\&lt; . #\&gt)
694 (#\[ . #\]))
695 </pre>
696
697 </blockquote>
698
699 <p><br>[Special variable]
700 <br><a class=none name="*interpolate-format-directives*"><b>*interpolate-format-directives*</b></a>
701
702 <blockquote><br>
703
704 This is a boolean value which determines if the ~ character signals
705 the start of an inline format directive. When T sequences with this
706 form:
707
708 <pre>
709 ~paramsX(form)
710 </pre>
711
712 Will be passed to <code>cl:format</code>, with <code>FORM</code> as
713 the one and only argument and <code>params</code> and <code>X</code>
714 are the format directive (with the same syntax as in
715 <code>cl:format</code>).
716
717 Examples:
718
719 <pre>
720 * (let ((x 42)) #?&quot;An integer: ~D(x) ~X(x) ~8,'0B(x)&quot;)
721 &quot;An integer: 42 2A 00101010&quot;
722 </pre>
723
724 </blockquote>
725
726 <p><br>[Special variable]
727 <br><a class=none name="*regex-delimiters*"><b>*regex-delimiters*</b></a>
728
729 <blockquote><br>
730
731 This is a list of <a href="#outer">opening outer delimiters</a> which automatically switch CL-INTERPOL's <a href="#regular">regular expression mode</a> on. The elements of this list are characters. An element of this list must also be an element of <a href="#*outer-delimiters*"><code>*OUTER-DELIMITERS*</code></a> to have any effect.
732 Note that this variable has effect at read time so you probably need to wrap an <a
733 href="http://www.lispworks.com/documentation/HyperSpec/Body/s_eval_w.htm"><code>EVAL-WHEN</code></a> around forms that change its value. The default value is the one-element list <code>'(#\/)</code>.
734
735 </blockquote>
736
737 <br>&nbsp;<br><h3><a class=none name="bugs">Known issues</a></h3>
738
739 <h4><a name="curly" class=none><code>{n,m}</code> modifiers in extended mode</a></h4>
740
741 CL-INTERPOL treats 'potential' <code>{n,m}</code> modifiers differently from <a href="https://github.com/edicl/cl-ppcre/">CL-PPCRE</a> or Perl in <a href="#regular">extended mode</a> <em>if</em> they contain whitespace. CL-INTERPOL will simply remove the whitespace and thus make them valid modifiers for CL-PPCRE while Perl will remove the whitespace but <em>not</em> recognize the character sequence as a modifier. CL-PPCRE behaves like Perl - you decide if this behaviour is sane...:)
742 <pre>
743 * (let ((scanner (cl-ppcre:create-scanner &quot;^a{3, 3}$&quot; :extended-mode t)))
744 (cl-ppcre:scan scanner &quot;aaa&quot;))
745 NIL
746 * (let ((scanner (cl-ppcre:create-scanner &quot;^a{3, 3}$&quot; :extended-mode t)))
747 (cl-ppcre:scan scanner &quot;a{3,3}&quot;))
748 0
749 6
750 #()
751 #()
752 * (cl-ppcre:scan #?x/^a{3, 3}$/ &quot;aaa&quot;)
753 0
754 3
755 #()
756 #()
757 * (cl-ppcre:scan #?x/^a{3, 3}$/ &quot;a{3, 3}&quot;)
758 NIL
759 </pre>
760
761 <br>&nbsp;<br><h3><a class=none name="ack">Acknowledgements</a></h3>
762
763 Thanks to Peter Seibel who had the idea to do this to
764 make <a href="https://github.com/edicl/cl-ppcre/">CL-PPCRE</a> more
765 convenient. Buy <a href="http://www.apress.com/book/bookDisplay.html?bID=237">his
766 book</a>!!!
767
768 <p>
769 $Header: /usr/local/cvsrep/cl-interpol/doc/index.html,v 1.39 2008/07/25 12:52:00 edi Exp $
770 <p><a href="https://edicl.github.io">BACK TO THE HOMEPAGE</a>
771
772 </body>
773 </html>