reference.html 59.6 KB
Newer Older
1
2
3
<!DOCTYPE html>

<html lang="en">
4
5

  <head>
6
7
8
9
    <meta charset="utf-8">
    <meta name="viewport"
          content="width=device-width, initial-scale=1"
          >
10

11
12
13
14
    <title>Parenscript Reference Manual</title>

    <style type="text/css">
      body {
15
16
        max-width: 70ex;
        margin: auto;
17
      }
18
19
      dl {
        margin-left: 2em;
20
      }
21
22
23
24
      dt {
        margin-top: 0.5ex;
        border: 1px solid #d5d5d5;
        background: #f9f9f9;
25
26
      }
      dd {
27
28
29
30
31
32
33
34
35
36
37
        margin-top: 0.5ex;
      }
      p {
        margin-left: 1em;
      }
      pre {
        margin: 0;
      }
      samp {
        color: #60a;
        font-weight: bolder;
38
39
40
41
42
      }
    </style>
  </head>

  <body>
43
    <h1 style="text-align:center;">Parenscript Reference Manual</h1>
44

45
46
47
48
49
50
51
52
53
54
55
56
57
58
    <p>
      Copyright 2005 Marco Baringer.<br/>
      Copyright 2006 Henrik Hjelte.<br/>
      Copyright 2009-2012, 2018 Vladimir Sedach.<br/>

      Permission is granted to copy, distribute and/or modify this
      document under the terms of the GNU Free Documentation License,
      Version 1.3 or any later version published by the Free Software
      Foundation; with no Invariant Sections, no Front-Cover Texts,
      and no Back-Cover Texts. A copy of the license can be
      found <a href="https://www.gnu.org/licenses/fdl.html">on the
      GNU website</a>.
    </p>

59
60
61
    <h2>Table of Contents</h2>

    <ol>
62
      <li><a href="#section-notation">Notation used in this manual</a></li>
63
64
      <li><a href="#section-ps-compiler">The Parenscript compiler</a></li>
      <li><a href="#section-symbolconv">Symbol conversion</a></li>
65
66
67
68
69
70
      <li><a href="#section-namespace">The Parenscript namespace system</a>
        <ul>
          <li><a href="#section-obfuscation">Identifier obfuscation</a></li>
          <li><a href="#section-minification">Minification</a></li>
        </ul>
      </li>
71
      <li><a href="#reserved-symbols">Reserved symbols</a></li>
72
      <li><a href="#section-statements-expressions">Statements, expressions, and return</a></li>
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
      <li><a href="#section-types">Types and type predicates</a></li>
      <li><a href="#section-literals">Literals</a>
        <ul>
          <li><a href="#ssection-numbers">Numbers</a></li>
          <li><a href="#ssection-strings-chars">Strings and characters</a></li>
          <li><a href="#ssection-regex">Regular expressions</a></li>
          <li><a href="#ssection-booleans">Booleans and undefined</a></li>
        </ul>
      </li>
      <li><a href="#section-objects">Objects</a></li>
      <li><a href="#section-arrays">Arrays</a></li>
      <li><a href="#section-arithmetic">Arithmetic and boolean operators</a></li>
      <li><a href="#section-math">Mathematical functions and constants</a></li>
      <li><a href="#section-blocks">Blocks</a></li>
      <li><a href="#section-functions">Functions and multiple values</a></li>
      <li><a href="#section-control-transfer">Control transfer and exceptions</a></li>
      <li><a href="#section-conditionals">Conditionals</a></li>
      <li><a href="#section-variables">Variable binding and declaration</a></li>
      <li><a href="#section-assignment">Assignment</a></li>
      <li><a href="#section-iteration">Iteration</a></li>
      <li><a href="#section-macros">Macros</a>
        <ul>
          <li><a href="#ssection-defining-macros">Defining macros</a></li>
          <li><a href="#ssection-symbol-macros">Symbol macros</a></li>
          <li><a href="#ssection-gensym">Gensym</a></li>
        </ul>
      </li>
      <li><a href="#section-utilities">Utilities</a>
        <ul>
          <li><a href="#ssection-dom">DOM</a></li>
          <li><a href="#ssection-html-gen">HTML generation</a></li>
        </ul>
      </li>
106
      <li><a href="#section-runtime-library">Run-time library</a></li>
107
108
      <li><a href="#section-slime-integration">SLIME integration</a></li>
    </ol>
109

110
111
112
113
114
115
116
117
118
119
    <h2 id="section-notation">Notation used in this manual</h2>
    <ul>
      <li><code>Lisp form</code></li>
      <li><var>Lisp variable</var></li>
      <li>(<code>lisp-function-name</code> <var>lisp-function-argument</var>)</li>
      <li><samp>JavaScript code</samp></li>
      <li><dl><dt>Term</dt><dd>Definition of term</dd></dl></li>
      <li><dl><dt><code>(Lisp forms)</code></dt><dd><samp>Lisp forms compiled to JavaScript;</samp></dd></dl></li>
    </ul>

120
    <h2 id="section-ps-compiler">The Parenscript compiler</h2>
121

122
    <ul>
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
      <li>(<code id="ps">PS</code> &amp;body <var>body</var>)</li>
      <li>(<code id="ps-to-stream">PS-TO-STREAM</code> <var>stream</var> &amp;body <var>body</var>)</li>
      <li>(<code id="ps*">PS*</code> &amp;rest <var>body</var>)</li>
      <li>(<code id="ps-doc">PS-DOC</code> &amp;body <var>body</var>)</li>
      <li>(<code id="ps-doc*">PS-DOC*</code> &amp;body <var>body</var>)</li>
      <li>(<code id="ps-inline">PS-INLINE</code> <var>form</var> &amp;optional <var>*JS-STRING-DELIMITER*</var>)</li>
      <li>(<code id="ps-inline*">PS-INLINE*</code> <var>form</var> &amp;optional <var>*JS-STRING-DELIMITER*</var>)</li>
      <li>(<code id="ps-compile-stream">PS-COMPILE-STREAM</code> <var>stream</var>)</li>
      <li>(<code id="ps-compile-file">PS-COMPILE-FILE</code> <var>file</var>)</li>
      <li>(<code id="lisp">LISP</code> <var>lisp-form</var>)</li>
      <li>(<code id="symbol-to-js-string">SYMBOL-TO-JS-STRING</code> <var>symbol</var>)</li>

      <li><var id="*js-target-version*">*JS-TARGET-VERSION*</var></li>
      <li><var id="*parenscript-stream*">*PARENSCRIPT-STREAM*</var></li>
      <li><var id="*js-string-delimiter*">*JS-STRING-DELIMITER*</var></li>
      <li><var id="*js-inline-string-delimiter*">*JS-INLINE-STRING-DELIMITER*</var></li>
      <li><var id="*ps-read-function*">*PS-READ-FUNCTION*</var></li>
      <li><var id="*version*">*VERSION*</var></li>
      <li><var id="*defined-operators*">*DEFINED-OPERATORS*</var></li>
142
143
144
    </ul>

    <dl>
145
      <dt><var>body</var></dt> <dd>implicit <code>PROGN</code></dd>
146
    </dl>
147

148
149
150
151
152
153
154
155
156
157
158
159
160
    <p>The difference between the regular and <code>*</code> versions
      of the Parenscript compiler forms is roughly the difference
      between <code>COMPILE</code>
      and <code>EVAL</code>. The <code>*</code> forms are functions
      that do all compilation when they are evaluated, while the
      regular forms are macros that do almost all (except for the use
      of the <code>LISP</code> special form, see below) compilation at
      macro-expansion time.</p>

    <p><code>PS</code> and <code>PS*</code> are the main interfaces to
      the Parenscript compiler. They come with <code>PS-DOC</code>
      and <code>PS-DOC*</code> counterparts which compile the given
      code
161
162
163
      with <a href="#*ps-gensym-counter*"><var>*PS-GENSYM-COUNTER*</var></a>
      bound to <kbd>0</kbd>, and are useful for writing automated
      tests.</p>
164
165
166
167

    <p>By default, Parenscript writes output to a string. You can
      output directly to a stream in one of two ways: either by
      using <code>PS-TO-STREAM</code> instead of <code>PS</code>, or by
168
      binding <var>*PARENSCRIPT-STREAM*</var> before
169
      calling <code>PS*</code>.</p>
170

171
172
    <p><code>PS-INLINE</code> and <code>PS-INLINE*</code> take a single
      Parenscript form and output a string starting
173
      with <samp>javascript:</samp> that can be used in HTML node
174
      attributes. As well, they provide an argument to bind the value of
175
      <var>*JS-STRING-DELIMITER*</var> to control the value of the
176
177
178
179
180
181
      JavaScript string escape character to be compatible with
      whatever the HTML generation mechanism is used (for example, if
      HTML strings are delimited using <code>#\'</code>,
      using <code>#\&quot;</code> will avoid conflicts without
      requiring the output JavaScript code to be escaped). By default
      the value is taken
182
      from <var>*JS-INLINE-STRING-DELIMITER*</var>.</p>
183
184
185
186

    <p>Parenscript code can be compiled from a stream or file
      via <code>PS-COMPILE-STREAM</code>
      and <code>PS-COMPILE-FILE</code>, respectively. The special
187
      variable <var>*PS-READ-FUNCTION*</var> is bound to the function
188
189
190
191
192
      used to read the forms from the file/stream (<code>READ</code> by
      default), and can be used to provide completely customizable
      syntax for Parenscript files.</p>

    <p>Parenscript can also call out to arbitrary Common Lisp code at
193
      <em>output time</em> (that is, every time an expression containing
194
      a call to the Parenscript compiler is evaluated, compared
195
      to <em>compile time</em>, where the effect is accomplished using
196
197
198
199
200
201
202
203
204
      macros) using the special form <code>LISP</code>. The form
      provided to <code>LISP</code> is evaluated, and its result is
      compiled as though it were Parenscript code. For <code>PS</code>
      and <code>PS-INLINE</code>, the Parenscript output code is
      generated at macro-expansion time, and the <code>LISP</code>
      statements are inserted inline into the output and have access
      to the enclosing Common Lisp lexical
      environment. <code>PS*</code> and <code>PS1*</code> evaluate the
      <code>LISP</code> forms using <code>EVAL</code>, providing them
205
206
207
      access to the current dynamic environment only
      (using <code>LISP</code> when calling the <code>*</code> forms
      is not strictly necessary, as the values can be inserted inline
208
209
      into code).</p>

210
    <p><var>*JS-TARGET-VERSION*</var> (<kbd>"1.3"</kbd> by default)
211
212
213
214
215
216
217
218
219
220
221
222
223
      controls which version of JavaScript that Parenscript
      targets. For newer versions of JS, some Parenscript special
      forms may compile to more concise and/or efficient expressions
      that are not present in earlier versions of JavaScript.</p>

    <p><code>SYMBOL-TO-JS-STRING</code> is the Parenscript function
      responsible for translating Common Lisp symbols to JavaScript
      identifiers (see the section
      on <a href="#section-symbolconv">symbol conversion</a> for the
      translation rules). It is helpful for writing libraries or other
      pieces of code that will interface with Parenscript-generated
      JavaScript.</p>

224
225
226
227
    <p>Newer versions of Parenscript may implement Common Lisp special
    forms, functions or macros that were left unimplemented by earlier
    versions. This can cause problems if your code provides
    implementations for those forms itself. To help deal with
228
    this, <var>*DEFINED-OPERATORS*</var> provides a list of special
229
    forms, macros, and symbol macros defined by Parenscript
230
    itself. <var>*VERSION*</var> is bound to the current release
231
232
    version number of Parenscript.</p>

233
234
    <h2 id="section-symbolconv">Symbol conversion</h2>

235
    <p>Parenscript supports output for both case-sensitive and
236
237
238
    case-insensitive symbols. By default the Lisp reader up-cases all
    symbols. By setting <code>readtable-case</code>
    to <a href="http://www.lispworks.com/documentation/lw50/CLHS/Body/23_ab.htm"><code>:invert</code></a>
239
    (you can use
240
    the <a href="https://common-lisp.net/project/named-readtables/">named-readtables</a>
241
242
    library to make this more convenient) symbol case is preserved,
    and Parenscript will output mixed-case symbols
243
    (like <samp>encodeURIComponent</samp>) correctly.</p>
244
245
246
247

    <p>Lisp symbols (other than keywords) that are all uppercase or
      contain special characters are converted to JavaScript
      identifiers by following a few simple rules. Special
248
249
250
251
252
253
254
      characters <code>!, ?, #, @, %, /, *</code> and <code>+</code>
      get replaced by their written-out equivalents "bang", "what",
      "hash", "at", "percent", "slash", "start" and "plus"
      respectively. The <code>$</code> character is untouched.</p>

    <dl>
      <dt><code>!?#@%</code></dt>
255
      <dd><samp>bangwhathashatpercent;</samp></dd>
256
257
258
259
260
261
262
    </dl>

    <p>The <code>-</code> is an indication that the following
      character should be converted to uppercase.</p>

    <dl>
      <dt><code>bla-foo-bar</code></dt>
263
      <dd><samp>blaFooBar;</samp></dd>
264
265
266
267
268
269
270
    </dl>

    <p>JavaScript identifiers that begin with an uppercase letter can
      be obtained with a leading <code>-</code> or <code>*</code>.</p>

    <dl>
      <dt><code>*array</code></dt>
271
      <dd><samp>Array;</samp></dd>
272
273
274
275
276
277
278
279
    </dl>

    <p>A symbol starting and ending with <code>+</code>
      or <code>*</code> is converted to all uppercase, to signify that
      this is a constant or a global variable.</p>

    <dl>
      <dt><code>*global-array*</code></dt>
280
      <dd><samp>GLOBALARRAY;</samp></dd>
281
282
283
284
285
286
287
288
289
290
291
    </dl>

    <p>Keywords are not translated to JavaScript identifiers, but are
      printed in lower case without any character substitution as
      strings. This is done because strings are the closest equivalent
      to Common Lisp keywords (being self-evaluating objects in
      JavaScript), and to permit keywords to be used for identifying
      various symbols (for example, as tokens in a parser).</p>

    <dl>
      <dt><code>:+</code></dt>
292
      <dd><samp>'+';</samp></dd>
293
294

      <dt><code>:foo-Bar</code></dt>
295
      <dd><samp>'foo-bar';</samp></dd>
296
297
298
299
    </dl>

    <h2 id="section-namespace">The Parenscript namespace system</h2>
    <ul>
300
301
302
303
304
305
306
307
308
      <li>
        (<code id="in-package">in-package</code> <var>package-designator</var>)
      </li>
      <li>
        (<code id="use-package">use-package</code> <var>package-designator</var>)
      </li>
      <li>
        (setf (<code id="ps-package-prefix">PS-PACKAGE-PREFIX</code> <var>package-designator</var>) <var>string</var>)
      </li>
309
310
    </ul>

311
312
313
314
315
316
317
318
319
320
321
322
    <p>
      Although JavaScript does not offer namespacing or a package
      system, Parenscript does provide a namespace mechanism for
      generated JavaScript by integrating with the Common Lisp package
      system. Since Parenscript code is normally read in by the Lisp
      reader, all symbols (except for uninterned ones, i.e. - those
      specified with the <code>#:</code> reader macro) have a Lisp
      package. By default, no packages are prefixed. You can specify
      that symbols in a particular package receive a prefix when
      translated to JavaScript with the
      <var>PS-PACKAGE-PREFIX</var> place.
    </p>
323

324
325
326
    <dl>
      <dt>
        <pre><code>(defpackage "PS-REF.MY-LIBRARY"
327
328
  (:use "PARENSCRIPT"))

329
330
(setf (ps-package-prefix "PS-REF.MY-LIBRARY") "my_library_")

331
332
(ps (defun ps-ref.my-library::library-function (x y)
      (+ x y)))</code></pre>
333
      </dt>
334
335
336

      <dd>
        <pre><samp>function my_library_libraryFunction(x, y) {
337
    return x + y;
338
};</samp></pre>
339
340
341
      </dd>
    </dl>

342
343
344
345
346
347
    <p>
      Parenscript provides <code>IN-PACKAGE</code>
      and <code>USE-PACKAGE</code> special forms, primarily useful
      with <a href="#ps-compile-file"><code>PS-COMPILE-FILE</code></a>
      and <a href="#ps-compile-stream"><code>PS-COMPILE-STREAM</code></a>.
    </p>
348
349
350

    <h3 id="section-obfuscation">Identifier obfuscation</h3>
    <ul>
351
352
353
354
355
356
      <li>
        (<code id="obfuscate-package">OBFUSCATE-PACKAGE</code> <var>package-designator</var> &amp;optional <var>symbol-map</var>)
      </li>
      <li>
        (<code id="unobfuscate-package">UNOBFUSCATE-PACKAGE</code> <var>package-designator</var>)
      </li>
357
358
359
360
361
362
363
364
365
    </ul>

    <p>Similar to the namespace mechanism, Parenscript provides a
      facility to generate obfuscated identifiers in specified CL
      packages. The function <code>OBFUSCATE-PACKAGE</code> may
      optionally be passed a closure that maps symbols to their
      obfuscated counterparts. By default, the mapping is done
      using <code><a href="#ps-gensym">PS-GENSYM</a></code>.</p>

366
367
368
369
    <dl>
      <dt>
        <pre><code>(defpackage "PS-REF.OBFUSCATE-ME")

370
371
372
373
374
375
(obfuscate-package "PS-REF.OBFUSCATE-ME"
  (let ((code-pt-counter #x8CF6)
        (symbol-map (make-hash-table)))
    (lambda (symbol)
      (or (gethash symbol symbol-map)
          (setf (gethash symbol symbol-map)
376
                (make-symbol (string (code-char (incf code-pt-counter)))))))))
377

378
379
(defun ps-ref.obfuscate-me::a-function (a b ps-ref.obfuscate-me::foo)
  (+ a (ps-ref.my-library::library-function b ps-ref.obfuscate-me::foo)))</code></pre>
380
      </dt>
381
382
383

      <dd>
<pre><samp>function 賷(a, b, 賸) {
384
    return a + libraryFunction(b, 賸);
385
};</samp></pre>
386
387
388
389
390
391
      </dd>
    </dl>

    <p>The obfuscation and namespace facilities can be used on packages
      at the same time.</p>

392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
    <p>Since Parenscript doesn't know anything about the DOM or other
    JavaScript libraries, library function and property names might be
    inadvertently obfuscated. To help prevent that, Parenscript comes
    with
    the <code>ps-dom1-symbols</code>, <code>ps-dom2-symbols</code>, <code>ps-window-wd-symbols</code>, <code>ps-dom-nonstandard-symbols</code>
    and <code>ps-dhtml-symbols</code> symbol packages that define
    various DOM property and function identifiers as exported symbols
    (in both case-sensitive and insensitive variants), which you can
    import into your packages to help prevent symbols
    like <code>pageXOffset</code> from being
    obfuscated. The <code>ps-dhtml-symbols</code> package contains the
    broadest range of symbols and is most generally useful.</p>

    <p>If you use obfuscation and external JavaScript libraries, you
    can use the same technique to define your own packages with
    symbols that will not be obfuscated.</p>

409
410
    <h3 id="section-minification">Minification</h3>
    <ul>
411
412
      <li><var id="*ps-print-pretty*">*PS-PRINT-PRETTY*</var></li>
      <li><var id="*indent-num-spaces*">*INDENT-NUM-SPACES*</var></li>
413
414
    </ul>

415
416
417
418
419
    <p><var>*PS-PRINT-PRETTY*</var> and <var>*INDENT-NUM-SPACES*</var>
      control whether the resulting JavaScript code is pretty-printed,
      and if so, how many spaces go into each indent level,
      respectively. By default the code is pretty-printed
      with <kbd>4</kbd> spaces per indent level.</p>
420

421
    <p>Setting <var>*PS-PRINT-PRETTY*</var> to nil and turning
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
    on <a href="#section-obfuscation">obfuscation</a> will minify the
    generated JavaScript code.</p>

    <h2 id="reserved-symbols">Reserved symbols</h2>

    <p>The following symbols are reserved in Parenscript, and should not
      be used as variable names.</p>

    <code>
      ! ~ ++ -- * / % + - &lt;&lt; &gt;&gt; &gt;&gt;&gt; &lt; &gt;
      &lt;= &gt;= == != === !== & ^ | && || *= /= %= += -= &lt;&lt;=
      &gt;&gt;= &gt;&gt;&gt;= &= ^= |= 1- 1+ @ ABSTRACT AND AREF ARRAY
      BOOLEAN BREAK BYTE CASE CATCH CHAR CLASS COMMA CONST CONTINUE
      CREATE DEBUGGER DECF DEFAULT DEFUN DEFVAR DELETE DO DO* DOEACH
      DOLIST DOTIMES DOUBLE ELSE ENUM EQL EXPORT EXTENDS F FALSE FINAL
      FINALLY FLOAT FLOOR FOR FOR-IN FUNCTION GOTO IF IMPLEMENTS
      IMPORT IN INCF INSTANCEOF INT INTERFACE JS LABELED-FOR LAMBDA
      LET LET* LISP LIST LONG MAKE-ARRAY NATIVE NEW NIL NOT OR PACKAGE
      PRIVATE PROGN PROTECTED PUBLIC RANDOM REGEX RETURN SETF SHORT
      GETPROP STATIC SUPER SWITCH SYMBOL-MACROLET SYNCHRONIZED T THIS
      THROW THROWS TRANSIENT TRY TYPEOF UNDEFINED UNLESS VAR VOID
      VOLATILE WHEN WHILE WITH WITH-SLOTS
    </code>

446
447
    <h2 id="section-statements-expressions">Statements, expressions, and return</h2>

448
449
    <p>
      In contrast to Lisp, where everything is an expression,
450
451
      JavaScript makes an arbitrary distinction between expressions,
      which yield a value and can be nested in other expressions, and
452
453
      statements, which have no value and cannot occur in expressions.
    </p>
454

455
456
    <p>
      Some Parenscript special forms compile to expressions, while
457
458
459
460
461
462
      others can only compile to statements. Certain Parenscript
      forms, like <code>IF</code> and <code>PROGN</code>, generate
      different JavaScript depending on if they are used in an
      expression context or a statement context. In such cases,
      Parenscript tries to generate statement code if possible to
      increase readability, only falling back to the expression code
463
464
      if it is necessary.
    </p>
465

466
467
468
469
470
471
472
473
474
475
476
477
    <dl>
      <dt>
        <code>(+ i (if x (foo) (bar)))</code>
      </dt>

      <dd>
        <samp>i + (x ? foo() : bar());</samp>
      </dd>

      <dt>
        <code>(if x (foo) (bar))</code>
      </dt>
478

479
480
      <dd>
<pre><samp>if (x) {
481
482
483
    foo();
} else {
    bar();
484
485
};</samp></pre>
      </dd>
486
487
      </dl>

488
489
490
491
492
493
    <p>
      One important feature found in Lisp but absent from JavaScript
      is implicit return from functions. Parenscript automatically
      provides implicit return for JavaScript statements and
      expressions:
    </p>
494
495

    <dl>
496
497
498
      <dt>
        <pre><code>(defun foo (x)
  (1+ x))</code></pre>
499
      </dt>
500
501
502

      <dd>
        <pre><samp>function foo(x) {
503
    return x + 1;
504
};</samp></pre>
505
506
      </dd>

507
508
      <dt>
        <pre><code>(lambda (x)
509
510
511
  (case x
    (1 (loop repeat 3 do (alert "foo")))
    (:bar (alert "bar"))
512
    (otherwise 4)))</code></pre>
513
      </dt>
514
515
516

      <dd>
        <pre><samp>function (x) {
517
518
519
520
521
522
523
524
    switch (x) {
    case 1:
        for (var _js1 = 0; _js1 < 3; _js1 += 1) {
            alert('foo');
        };
        return null;
    case 'bar':
        return alert('bar');
525
    default:
526
527
        return 4;
    };
528
};</samp></pre>
529
530
      </dd>
    </dl>
531

532
533
534
535
    <p>
      Parenscript generates code that works around the JavaScript
      expression-statement dichotomy in an unobtrusive way:
    </p>
536
537

    <dl>
538
      <dt>
539
        <pre><code>(+ 1 (dotimes (x 3) (if (= x 2) (return (+ x x)))))</code></pre>
540
541
      </dt>

542
      <dd>
543
544
545
546
547
548
549
        <pre><samp>(function () {
    for (var x = 0; x < 3; x += 1) {
        if (x === 2) {
            return x + x;
        };
    };
})() + 1;</samp></pre>
550
551
      </dd>
    </dl>
552

553
554
    <h2 id="section-types">Types and type predicates</h2>
    <ul>
555
556
557
558
559
560
561
562
563
      <li>(<code id="typeof">TYPEOF</code> <var>object</var>)</li>
      <li>(<code id="instanceof">INSTANCEOF</code> <var>object</var> <var>type</var>)</li>
      <li>(<code id="null">NULL</code> <var>object</var>)</li>
      <li>(<code id="undefined_1">UNDEFINED</code> <var>object</var>)</li>
      <li>(<code id="defined">DEFINED</code> <var>object</var>)</li>
      <li>(<code id="stringp">STRINGP</code> <var>object</var>)</li>
      <li>(<code id="numberp">NUMBERP</code> <var>object</var>)</li>
      <li>(<code id="functionp">FUNCTIONP</code> <var>object</var>)</li>
      <li>(<code id="objectp">OBJECTP</code> <var>object</var>)</li>
564
565
566
    </ul>

    <dl>
567
568
      <dt><var>object</var></dt> <dd>an expression yielding an object</dd>
      <dt><var>type</var></dt> <dd>a type designator</dd>
569
570
571
572
573
574
575
    </dl>

    <p>Parenscript is based around the JavaScript type system, and
    does not introduce any new types or objects, nor does it attempt
    to provide a Common Lisp-like interface to the type system.</p>

    <h2 id="section-literals">Literals</h2>
576

577
    <h3 id="ssection-numbers">Numbers</h3>
578

579
580
581
582
583
    <p>Parenscript prints all integer literals as integers, and floats
    and rationals as floats, in base 10.</p>

    <dl>
      <dt><code>1</code></dt>
584
      <dd><samp>1;</samp></dd>
585

586
      <dt><code>123.123</code></dt>
587
      <dd><samp>123.123;</samp></dd>
588

589
      <dt><code>3/4</code></dt>
590
      <dd><samp>0.75;</samp></dd>
591

592
      <dt><code>#x10</code></dt>
593
      <dd><samp>16;</samp></dd>
594
595
596
    </dl>

    <h3 id="ssection-strings-chars">Strings and characters</h3>
597

598
599
600
601
    <p>Lisp strings are converted to JavaScript strings.</p>

    <dl>
      <dt><code>"foobar"</code></dt>
602
      <dd><samp>'foobar';</samp></dd>
603
604
605
606
607
608
609
610
    </dl>

    <p>Parenscript makes no effort to interpolate C-style escape
    strings. Rather, non-printable characters in Lisp strings are
    output using escape sequences:</p>

    <dl>
      <dt><code>#\Tab</code></dt>
611
      <dd><samp>'\t';</samp></dd>
612
613

      <dt><code>"\\n"</code></dt>
614
      <dd><samp>'\\n';</samp></dd>
615
616
617
618
    </dl>

    <h3 id="ssection-regex">Regular expressions</h3>
    <ul>
619
      <li>(<code id="regex">REGEX</code> <var>regex</var>)</li>
620
621
622
    </ul>

    <dl>
623
      <dt><var>regex</var></dt> <dd>a string</dd>
624
625
626
627
628
629
630
631
632
    </dl>

    <p>Regular expressions can be created by using
      the <code>REGEX</code> form. If the argument does not start with
      <code>/</code>, it is surrounded by <code>/</code>, otherwise it
      is left as it is.</p>

    <dl>
      <dt><code>(regex "foobar")</code></dt>
633
      <dd><samp>/foobar/;</samp></dd>
634
635

      <dt><code>(regex "/foobar/i")</code></dt>
636
      <dd><samp>/foobar/i;</samp></dd>
637
638
    </dl>

639
    <p><a href="https://edicl.github.io/cl-interpol/">CL-INTERPOL</a> is
640
      convenient for writing regular expressions:</p>
641

642
643
    <dl>
      <dt><code>(regex #?r"/([^\s]+)foobar/i")</code></dt>
644
      <dd><samp>/([^\s]+)foobar/i;</samp></dd>
645
646
647
648
649
650
    </dl>

    <h3 id="ssection-booleans">Booleans and undefined</h3>
    <ul>
      <li><code id="t">T</code></li>
      <li><code id="f">F</code></li>
651
      <li><code id="false">FALSE</code></li>
652
653
654
655
656
657
      <li><code id="nil">NIL</code></li>
      <li><code id="undefined">UNDEFINED</code></li>
    </ul>

    <p><code>T</code> and <code>FALSE</code> (or <code>F</code>) are
      converted to their JavaScript boolean
658
      equivalents <samp>true</samp> and <samp>false</samp>.</p>
659
660

    <p><code>NIL</code> is converted to the JavaScript keyword
661
      <samp>null</samp>.</p>
662
663

    <p><code>UNDEFINED</code> is converted to the JavaScript global
664
    variable <a href="https://developer.mozilla.org/en/Core_JavaScript_1.5_Reference/Global_Properties/undefined"><samp>undefined</samp></a>.</p>
665
666
667

    <h2 id="section-objects">Objects</h2>
    <ul>
668
669
670
671
672
673
674
      <li>(<code id="new">NEW</code> <var>constructor</var>)</li>
      <li>(<code id="create">CREATE</code> {<var>name</var> <var>value</var>}*)</li>
      <li>(<code id="getprop">GETPROP</code> <var>object</var> {<var>slot-specifier</var>}*)</li>
      <li>(<code id="@">@</code> {<var>slot-specifier</var>}*)</li>
      <li>(<code id="chain">CHAIN</code> {<var>slot-specifier</var> | <var>function-call</var>}*)</li>
      <li>(<code id="with-slots">WITH-SLOTS</code> ({<var>slot-name</var>}*) <var>object</var> <var>body</var>)</li>
      <li>(<code id="delete">DELETE</code> <var>object</var>)</li>
675
676
677
    </ul>

    <dl>
678
679
680
681
682
683
      <dt><var>constructor</var></dt> <dd>a function call to an object constructor</dd>
      <dt><var>name</var></dt> <dd>symbol, string or keyword</dd>
      <dt><var>value</var></dt> <dd>an expression</dd>
      <dt><var>object</var></dt> <dd>an expression yielding an object</dd>
      <dt><var>slot-specifier</var></dt> <dd>a quoted symbol, a string, a number, or an expression yielding a string or number</dd>
      <dt><var>body</var></dt> <dd>implicit <code>PROGN</code></dd>
684
685
    </dl>

686
687
688
    <p>The <code>NEW</code> operator maps to JavaScript like:</p>

    <dl>
689
      <dt><code>(new (-Person age shoe-size))</code></dt>
690
      <dd><samp>new Person(age, shoeSize);</samp></dd>
691
692
693
694
    </dl>

    <p>Object literals are created
      with <code>CREATE</code>. <code>CREATE</code> takes a property
695
696
697
      list of property names and values.</p>

    <dl>
698
699
700
701
702
703
704
      <dt>
        <code>(create foo "bar" :blorg 1)</code>
      </dt>

      <dd>
        <samp>{ foo : 'bar', 'blorg' : 1 };</samp>
      </dd>
705

706
707
      <dt>
        <pre><code>(create foo "hihi"
708
        blorg (array 1 2 3)
709
        another-object (create :schtrunz 1))</code></pre>
710
      </dt>
711
712
713

      <dd>
<pre><samp>{ foo : 'hihi',
714
     blorg : [ 1, 2, 3 ],
715
     anotherObject : { 'schtrunz' : 1 } };</samp></pre>
716
717
718
719
720
721
722
723
724
      </dd>
    </dl>

    <p>Object properties can be accessed using
      <code>GETPROP</code>, which takes an object and a list of
      properties.</p>

    <dl>
      <dt><code>(getprop obj 'foo)</code></dt>
725
      <dd><samp>obj.foo;</samp></dd>
726
727

      <dt><code>(getprop obj foo)</code></dt>
728
      <dd><samp>obj[foo];</samp></dd>
729
730

      <dt><code>(getprop element i 'child-node 0 'node-value)</code></dt>
731
      <dd><samp>element[i].childNode[0].nodeValue;</samp></dd>
732
733
734
735
736
737
738
    </dl>

    <p>The convenience macro <code>@</code> quotes all its given
    symbol slot-specifiers to save typing:</p>

    <dl>
      <dt><code>(@ an-object foo bar)</code></dt>
739
      <dd><samp>anObject.foo.bar;</samp></dd>
740
741

      <dt><code>(@ foo bar child-node 0 node-value)</code></dt>
742
      <dd><samp>foo.bar.childNode[0].nodeValue;</samp></dd>
743
744
745
746
747
748
749
    </dl>

    <p><code>CHAIN</code> can be used to conveniently chain together
    accessors and function calls:</p>

    <dl>
      <dt><code>(chain foo (bar x y) 0 baz)</code></dt>
750
      <dd><samp>foo.bar(x, y)[0].baz;</samp></dd>
751
752
753
754
755
756
757
    </dl>

    <p><code>WITH-SLOTS</code> can be used to bind the given
      slot-names to a symbol macro that will expand into
      a <code>GETPROP</code> form at expansion time:</p>

    <dl>
758
759
760
      <dt>
<pre><code>(with-slots (a b c) this
  (+ a b c))</code></pre>
761
      </dt>
762
763
764
765

      <dd>
        <samp>this.a + this.b + this.c;</samp>
      </dd>
766
767
768
769
    </dl>

    <h2 id="section-arrays">Arrays</h2>
    <ul>
770
771
772
773
774
775
776
777
778
779
      <li>(<code id="array">ARRAY</code> {<var>value</var>}*)</li>
      <li>(<code id="list">LIST</code> {<var>value</var>}*)</li>
      <li>(<code id="[]">[]</code> {<var>value</var>}*)</li>
      <li>(<code id="make-array">MAKE-ARRAY</code> {<var>value</var>}*)</li>
      <li>(<code id="length">LENGTH</code> <var>array</var>)</li>
      <li>(<code id="aref">AREF</code> <var>array</var> <var>index</var>)</li>
      <li>(<code id="elt">ELT</code> <var>array</var> <var>index</var>)</li>
      <li>(<code id="destructuring-bind">DESTRUCTURING-BIND</code> <var>bindings</var> <var>array</var> <var>body</var>)</li>
      <li>(<code id="concatenate">CONCATENATE 'STRING</code> {<var>value</var>}*)</li>
      <li>(<code id="append">APPEND</code> {<var>value</var>}*)</li>
780
781
782
    </ul>

    <dl>
783
784
785
      <dt><var>value</var></dt> <dd>an expression</dd>
      <dt><var>array</var></dt> <dd>an expression</dd>
      <dt><var>index</var></dt> <dd>an expression</dd>
786
787
788
789
790
791
792
    </dl>

    <p>Array literals can be created using the <code>ARRAY</code>
      or <code>LIST</code> forms.</p>

    <dl>
      <dt><code>(array)</code></dt>
793
      <dd><samp>[];</samp></dd>
794
795

      <dt><code>(array 1 2 3)</code></dt>
796
      <dd><samp>[1, 2, 3];</samp></dd>
797
798

      <dt><code>(list (foo) (bar) 3)</code></dt>
799
      <dd><samp>[foo(), bar(), 3];</samp></dd>
800

801
802
803
      <dt>
        <pre><code>(array (array 2 3)
  (array "foo" "bar"))</code></pre>
804
      </dt>
805
806
807
808

      <dd>
        <samp>[[ 2, 3 ], ['foo', 'bar']];</samp>
      </dd>
809
810
    </dl>

811
812
813
814
815
    <p>The <code>[]</code> macro treats list arguments as quoted,
    making it easy to write nested array literals:</p>

    <dl>
      <dt><code>([] 1 2 (3 4) 5 6)</code></dt>
816
      <dd><samp>[1, 2, [3, 4], 5, 6];</samp></dd>
817
818
    </dl>

819
820
821
822
823
    <p>Arrays can also be created with a call to the <code>Array</code>
      function using <code>MAKE-ARRAY</code>.</p>

    <dl>
      <dt><code>(make-array)</code></dt>
824
      <dd><samp>new Array();</samp></dd>
825

826
      <dt><code>(make-array 1 2 3)</code></dt>
827
      <dd><samp>new Array(1, 2, 3);</samp></dd>
828

829
830
      <dt>
        <pre><code>(make-array
831
 (make-array 2 3)
832
 (make-array "foobar" "bratzel bub"))</code></pre>
833
      </dt>
834
835
836
837

      <dd>
        <samp>new Array(new Array(2, 3), new Array('foobar', 'bratzel bub'));</samp>
      </dd>
838
839
840
841
842
843
    </dl>

    <p>Array elements can be accessed using <code>AREF</code> or <code>ELT</code>.</p>

    <h2 id="section-arithmetic">Arithmetic and boolean operators</h2>
    <ul>
844
845
      <li>(&lt;operator&gt; {<var>argument</var>}*)</li>
      <li>(&lt;single-operator&gt; <var>argument</var>)</li>
846
847
848
849
    </ul>

    <dl>
      <dt>&lt;operator&gt;</dt>
850
      <dd>one of <code>*, /, +, -, <, >, <=, >=, =, AND, ASH, EQ, EQL, EQUAL, LOGAND, LOGIOR, LOGXOR, MOD, OR, REM, SETF</code>
851
852
      </dd>
      <dt>&lt;single-operator&gt;</dt>
853
      <dd>one of <code>DECF, INCF, LOGNOT, NOT</code></dd>
854

855
      <dt><var>argument</var></dt> <dd>an expression</dd>
856
    </dl>
857

858
859
860
    <p>Operator forms are similar to function call forms, but have an
      operator as function name.</p>

861
    <p>Please note that <code>=</code> is converted to <samp>===</samp> in
862
863
864
865
866
      JavaScript. The <code>=</code> Parenscript operator is not the
      assignment operator.</p>

    <dl>
      <dt><code>(* 1 2)</code></dt>
867
      <dd><samp>1 * 2;</samp></dd>
868

869
      <dt><code>(= 1 2)</code></dt>
870
      <dd><samp>1 === 2;</samp></dd>
871
872
    </dl>

873
874
875
876
    <p>The negation of equality operators are obtained by through <code>NOT</code>. For example:</p>

    <dl>
      <dt><code>(not (eql 1 2))</code></dt>
877
      <dd><samp>1 !== 2</samp></dd>
878
879
880
881
882
883
884
    </dl>

    <p>The operators that in CL have variable arity convert into multiple calls
    to the equivalent operators in JavaScript</p>

    <dl>
      <dt><code>(logxor 1 3 7 15)</code></dt>
885
      <dd><samp>1 ^ 3 ^ 7 ^ 15 </samp></dd>
886
887
    </dl>

888
889
    <h2 id="section-math">Mathematical functions and constants</h2>
    <ul>
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
      <li>(<code id="max">MAX</code> {<var>number</var>}*)</li>
      <li>(<code id="min">MIN</code> {<var>number</var>}*)</li>
      <li>(<code id="floor">FLOOR</code> <var>number</var> &amp;optional <var>divisor</var>)</li>
      <li>(<code id="ceiling">CEILING</code> <var>number</var> &amp;optional <var>divisor</var>)</li>
      <li>(<code id="round">ROUND</code> <var>number</var> &amp;optional <var>divisor</var>)</li>
      <li>(<code id="sin">SIN</code> <var>number</var>)</li>
      <li>(<code id="cos">COS</code> <var>number</var>)</li>
      <li>(<code id="tan">TAN</code> <var>number</var>)</li>
      <li>(<code id="asin">ASIN</code> <var>number</var>)</li>
      <li>(<code id="acos">ACOS</code> <var>number</var>)</li>
      <li>(<code id="atan">ATAN</code> <var>number1</var> &amp;optional <var>number2</var>)</li>
      <li>(<code id="sinh">SINH</code> <var>number</var>)</li>
      <li>(<code id="cosh">COSH</code> <var>number</var>)</li>
      <li>(<code id="tanh">TANH</code> <var>number</var>)</li>
      <li>(<code id="asinh">ASINH</code> <var>number</var>)</li>
      <li>(<code id="acosh">ACOSH</code> <var>number</var>)</li>
      <li>(<code id="atanh">ATANH</code> <var>number</var>)</li>
      <li>(<code id="1+">1+</code> <var>number</var>)</li>
      <li>(<code id="1-">1-</code> <var>number</var>)</li>
      <li>(<code id="abs">ABS</code> <var>number</var>)</li>
      <li>(<code id="evenp">EVENP</code> <var>number</var>)</li>
      <li>(<code id="oddp">ODDP</code> <var>number</var>)</li>
      <li>(<code id="exp">EXP</code> <var>number</var>)</li>
      <li>(<code id="expt">EXPT</code> <var>base</var> <var>power</var>)</li>
      <li>(<code id="log">LOG</code> <var>number</var> &amp;optional <var>base</var>)</li>
      <li>(<code id="sqrt">SQRT</code> <var>number</var>)</li>
      <li>(<code id="random">RANDOM</code> &amp;optional <var>limit</var>)</li>

      <li><var id="pi">PI</var></li>
919
920
    </ul>

921
922
    <p>
      The mathematical functions listed above work mostly like their
923
924
925
      Common Lisp counterparts when called directly, with the
      exception that complex numbers are not supported. However, most
      of them are implemented as macros, and as such cannot be treated
926
927
      as first-class functions.
    </p>
928
929
930

    <h2 id="section-blocks">Blocks</h2>
    <ul>
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
      <li>
        (<code id="block">BLOCK</code> <var>name</var> {<var>expression</var> | <var>statement</var>}*)
      </li>
      <li>
        (<code id="progn">PROGN</code> {<var>statement</var>}*) in statement context
      </li>
      <li>
        (<code>PROGN</code> {<var>expression</var>}*) in expression context
      </li>
      <li>
        (<code id="prog1">PROG1</code> {<var>expression</var> | <var>statement</var>}*)
      </li>
      <li>
        (<code id="prog2">PROG2</code> {<var>expression</var> | <var>statement</var>}*)
      </li>
      <li>
        (<code id="eval-when">EVAL-WHEN</code> {<var>expression</var> | <var>statement</var>}*)
      </li>
949
950
951
    </ul>

    <dl>
952
      <dt><var>name</var></dt> <dd>Name/tag of the block. A symbol or nil.</dd>
953
954
      <dt><var>statement</var></dt> <dd>a form that compiles to a statement</dd>
      <dt><var>expression</var></dt> <dd>a form that compiles to an expression</dd>
955
956
    </dl>

957
958
959
960
    <p>
      The translation of <code>PROGN</code> depends on whether it is
      found in a statement or expression context:
    </p>
961

962
963
    <dl>
      <dt><code>(progn (blorg i) (blafoo i))</code></dt>
964
965
966
      <dd>
<pre><samp>blorg(i);
blafoo(i);</samp></pre>
967
968
969
      </dd>

      <dt><code>(+ i (progn (blorg i) (blafoo i)))</code></dt>
970
      <dd><samp>i + (blorg(i), blafoo(i));</samp></dd>
971
972
    </dl>

973
974
975
976
977
978
979
980
981
982
    <p>
      The Parenscript <code>EVAL-WHEN</code> special operator has a
      slightly different meaning from the Common Lisp one. The code in
      the <code>EVAL-WHEN</code> special form is assumed to be Common
      Lisp code in <code>:compile-toplevel</code>
      and <code>:load-toplevel</code> situations, and is executed by
      the Parenscript compiler, and is assumed to be Parenscript code
      in the <code>:execute</code> situation, when it is run as
      JavaScript.
    </p>
983

984
985
    <h2 id="section-functions">Functions and multiple values</h2>
    <ul>
986
987
988
989
990
991
992
993
994
      <li>(<code id="defun">DEFUN</code> <var>name</var> <var>lambda-list</var> <var>body</var>)</li>
      <li>(<code id="lambda">LAMBDA</code> <var>lambda-list</var> <var>body</var>)</li>
      <li>(<code id="flet">FLET</code> ({(<var>name</var> <var>lambda-list</var> <var>body</var>)}*) <var>body</var>)</li>
      <li>(<code id="labels">LABELS</code> ({(<var>name</var> <var>lambda-list</var> <var>body</var>)}*) <var>body</var>)</li>
      <li>(<code id="values">VALUES</code> {<var>expression</var>}*)</li>
      <li>(<code id="multiple-value-bind">MULTIPLE-VALUE-BIND</code> ({<var>var</var>}*) <var>expression</var> <var>body</var>)</li>
      <li>(<code id="apply">APPLY</code> <var>function</var> {<var>expression</var>}*)</li>
      <li>(<code id="funcall">FUNCALL</code> <var>function</var> {<var>expression</var>}*)</li>
      <li><var id="this">THIS</var></li>
995
996
997
    </ul>

    <dl>
998
999
1000
1001
1002
1003
      <dt><var>expression</var></dt> <dd>a form that compiles to an expression</dd>
      <dt><var>name</var></dt> <dd>a symbol</dd>
      <dt><var>lambda-list</var></dt> <dd>a lambda list</dd>
      <dt><var>body</var></dt> <dd>implicit <code>PROGN</code></dd>
      <dt><var>var</var></dt> <dd>a symbol naming a variable</dd>
      <dt><var>function</var></dt> <dd>an expression that yields a function</dd>
1004
1005
    </dl>

1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
    <p>
      New function definitions can be introduced using all the regular
      Lisp forms
      - <code>DEFUN</code>, <code>LAMBDA</code>, <code>FLET</code>,
      and <code>LABELS</code>. Function lambda lists
      support <code>&amp;optional</code>, <code>&amp;rest</code> and
      <code>&amp;key</code> arguments.
    </p>

    <p>
      The Parenscript multiple value facility passes the first return
      value using the regular JavaScript convention, therefore
      functions returning multiple values can be called by regular
      JavaScript code and <code>MULTIPLE-VALUE-BIND</code> works with
      regular JavaScript functions.
    </p>

    <p>
      <code>APPLY</code> is a macro that expands into a call to the
      JavaScript <code>apply</code> method.
    </p>
1027

1028
1029
    <h2 id="section-control-transfer">Control transfer and exceptions</h2>
    <ul>
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
      <li>
        (<code id="return">RETURN</code> {<var>value</var>}?)
      </li>
      <li>
        (<code id="return-from">RETURN-FROM</code> <var>name</var> {<var>value</var>}?)
      </li>
      <li>
        (<code id="throw">THROW</code> {<var>exp</var>}?)
      </li>
      <li>
        (<code id="try">TRY</code> <var>form</var>
1041
        {(<code id="catch">:CATCH</code> (<var>var</var>) <var>body</var>)}?
1042
1043
1044
1045
1046
1047
1048
1049
        {(<code id="finally">:FINALLY</code> <var>body</var>)}?)
      </li>
      <li>
        (<code id="unwind-protect">UNWIND-PROTECT</code> <var>protected-form</var> <var>cleanup-form</var>)
      </li>
      <li>
        (<code id="ignore-errors">IGNORE-ERRORS</code> <var>body</var>)
      </li>
1050
1051
1052
    </ul>

    <dl>
1053
      <dt><var>value</var></dt> <dd>a statement or expression</dd>
1054
      <dt><var>name</var></dt> <dd>name of block to return from</dd>
1055
1056
1057
      <dt><var>exp</var></dt> <dd>an expression</dd>
      <dt><var>var</var></dt> <dd>variable to which the value of the caught <code>THROW</code> is bound</dd>
      <dt><var>body</var></dt> <dd>implicit <code>PROGN</code></dd>
1058
1059
    </dl>

1060
1061
1062
1063
    <p>
      Parenscript support nested blocks and the <code>RETURN</code>
      and <code>RETURN-FROM</code> special forms.
    </p>
1064
1065

    <dl>
1066
      <dt>
1067
1068
1069
1070
1071
1072
1073
1074
<pre><code>(defun foo (x)
  (progn
    (abc)
    (return-from foo
      (case x
        (1 :a)
        (2 :b)))
    (xyz)))</code></pre>
1075
      </dt>
1076
1077

      <dd>
1078
1079
<pre><samp>function foo(x) {
    abc();
1080
1081
1082
1083
1084
1085
    switch (x) {
    case 1:
        return 'a';
    case 2:
        return 'b';
    };
1086
    return xyz();
1087
};</samp></pre>
1088
1089
1090
      </dd>
    </dl>

1091
1092
1093
1094
1095
    <p>
      Currently, <code>THROW</code> translates directly into the
      JavaScript <samp>throw</samp>, to be used with <code>TRY</code>,
      which is translated to the JavaScript <samp>try</samp>.
    </p>
1096
1097

    <dl>
1098
1099
      <dt>
<pre><code>(try (throw "i")
1100
1101
1102
 (:catch (error)
   (alert (+ "an error happened: " error)))
 (:finally
1103
   (alert "Leaving the try form")))</code></pre>
1104
      </dt>
1105
1106
1107

      <dd>
<pre><samp>try {
1108
1109
1110
1111
1112
       throw 'i';
   } catch (error) {
       alert('an error happened: ' + error);
   } finally {
       alert('Leaving the try form');
1113
   };</samp></pre>
1114
1115
1116
1117
1118
      </dd>
    </dl>

    <h2 id="section-conditionals">Conditionals</h2>
    <ul>
1119
1120
1121
1122
1123
1124
      <li>(<code id="if">IF</code> <var>condition</var> <var>then</var> {<var>else</var>})</li>
      <li>(<code id="when">WHEN</code> <var>condition</var> <var>then</var>)</li>
      <li>(<code id="unless">UNLESS</code> <var>condition</var> <var>then</var>)</li>
      <li>(<code id="cond">COND</code> {<var>clause</var>}*)</li>
      <li>(<code id="case">CASE</code> <var>case-value</var> <var>clause</var>*)</li>
      <li>(<code id="switch">SWITCH</code> <var>case-value</var> <var>clause</var>*)</li>
1125
1126
1127
1128
      <li><code id="break">BREAK</code></li>
    </ul>

    <dl>
1129
1130
1131
1132
      <dt><var>condition</var></dt> <dd>an expression</dd>
      <dt><var>then</var></dt> <dd>a statement in statement context, or an expression in expression context</dd>
      <dt><var>else</var></dt> <dd>a statement in statement context, or an expression in expression context</dd>
      <dt><var>clause</var></dt> <dd>(&lt;<var>value</var>&gt; <var>body</var>) | (<var>default</var> <var>body</var>)</dd>
1133
1134
1135
1136
1137
1138
1139
    </dl>

    <p><code>IF, WHEN, UNLESS</code> and <code>COND</code> work like
    their Lisp counterparts, and are compiled either into statements
    or expressions, depending on the context:</p>

    <dl>
1140
1141
      <dt>
        <code>(cond ((= x 1) (+ x (if (foo y) 2 3))))</code>
1142
      </dt>
1143
1144
1145

      <dd>
<pre><samp>if (x == 1) {
1146
    x + (foo(y) ? 2 : 3);
1147
};</samp></pre>
1148
1149
1150
      </dd>
    </dl>

1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
    <p>
      <code>CASE</code> works similar to its Common Lisp equivalent.
    </p>

    <p>
      An additional form, <code>SWITCH</code>, takes the same syntax
      as <code>CASE</code>, but the individual branches must be
      terminated with the
      symbol <a href="#break"><code>BREAK</code></a>. This allows
      C-style case "fall-throughs" in <code>switch</code> statements:
    </p>
1162
1163

    <dl>
1164
1165
      <dt>
<pre><code>(switch (aref blorg i)
1166
  (1 (alert "If I get here"))
1167
  (2 (alert "I also get here")
1168
     break)
1169
  (default (alert "I always get here")))</code></pre>
1170
      </dt>
1171
1172
1173

      <dd>
<pre><samp>switch (blorg[i]) {
1174
1175
1176
1177
1178
case 1:
    alert('If I get here');
case 2:
    alert('I also get here');
    break;
1179
default:
1180
    alert('I always get here');
1181
};</samp></pre>
1182
1183
1184
1185
1186
1187
1188
1189
      </dd>
    </dl>

    <p>Note that the default case in a <code>SWITCH</code> statement
    must be named <code id="default">DEFAULT</code>.</p>

    <h2 id="section-variables">Variable binding and declaration</h2>
    <ul>
1190
1191
1192
      <li>(<code id="let">LET</code> ({<var>var</var> | (<var>var</var> <var>value</var>)}*) <var>body</var>)</li>
      <li>(<code id="let*">LET*</code> ({<var>var</var> | (<var>var</var> <var>value</var>)}*) <var>body</var>)</li>
      <li>(<code id="defvar">DEFVAR</code> <var>var</var> {<var>value</var>}?)</li>
1193
      <li>(<code id="defparameter">DEFPARAMETER</code> <var>var</var> {<var>value</var>}?)</li>
1194
      <li>(<code id="var">VAR</code> <var>var</var> {<var>value</var>}?)</li>
1195
1196
1197
    </ul>

    <dl>
1198
1199
1200
1201
      <dt><var>var</var></dt> <dd>a symbol</dd>
      <dt><var>value</var></dt> <dd>an expression</dd>
      <dt><var>body</var></dt> <dd>implicit <code>PROGN</code></dd>
      <dt><var>object</var></dt> <dd>an expression evaluating to an object</dd>
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
    </dl>

    <p>Parenscript provides the <code>LET</code> and <code>LET*</code>
      special forms for creating new variable bindings. Both special
      forms implement lexical scope by renaming the provided variables
      via <a href="#ps-gensym"><code>GENSYM</code></a>, and implement
      dynamic binding
      using <a href="#try"><code>TRY-FINALLY</code></a>.</p>

    <p>Special variables can be declared using
      <code>DEFVAR</code>. Note that the result is undefined
      if <code>DEFVAR</code> does not occur as a top-level form.</p>

    <p>One Parenscript feature that is not part of Common Lisp is the
      lexically-scoped global variable, which is declared using
      the <code>VAR</code> special form. The result is undefined
      if <code>VAR</code> does not occur as a top-level form.</p>

    <p>An example of variable declaration and binding:</p>

    <dl>
1223
1224
      <dt>
<pre><code>(defvar *a* 4)
1225
1226
1227
1228
1229
1230
1231
(var *b* 3)
(lambda ()
  (let ((x 1)
        (*a* 2)
        (*b* 6))
    (let* ((y (+ x 1))
           (x (+ x y)))
1232
      (+ *a* *b* x y))))</code></pre>
1233
      </dt>
1234
1235
1236

      <dd>
<pre><samp>var A = 4;
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
var B = 3;
function () {
    var x = 1;
    var B = 6;
    var A_TMPSTACK1;
    try {
        A_TMPSTACK1 = A;
        A = 2;
        var y = x + 1;
        var x2 = x + y;
        return A + B + x2 + y;
    } finally {
        A = A_TMPSTACK1;
    };