docs/reference.lisp

   1 ;;;# Parenscript Language Reference
   2
   3 ;;; Create a useful package for the code here...
   4 (in-package #:cl-user)
   5 (defpackage #:ps-ref (:use #:ps))
   6 (in-package #:ps-ref)
   7
   8 ;;; This chapters describes the core constructs of Parenscript, as
   9 ;;; well as its compilation model. This chapter is aimed to be a
  10 ;;; comprehensive reference for Parenscript developers. Programmers
  11 ;;; looking for how to tweak the Parenscript compiler itself should
  12 ;;; turn to the Parenscript Internals chapter.
  13
  14 ;;;# Statements and Expressions
  15 ;;;t \index{statement}
  16 ;;;t \index{expression}
  17
  18 ;;; In contrast to Lisp, where everything is an expression, JavaScript
  19 ;;; makes the difference between an expression, which evaluates to a
  20 ;;; value, and a statement, which has no value. Examples for
  21 ;;; JavaScript statements are `for', `with' and `while'. Most
  22 ;;; Parenscript forms are expression, but certain special forms are
  23 ;;; not (the forms which are transformed to a JavaScript
  24 ;;; statement). All Parenscript expressions are statements
  25 ;;; though. Certain forms, like `IF' and `PROGN', generate different
  26 ;;; JavaScript constructs whether they are used in an expression
  27 ;;; context or a statement context. For example:
  28
  29 (+ i (if 1 2 3)) => i + (1 ? 2 : 3);
  30
  31 (if 1 2 3)
  32 => if (1) {
  33        2;
  34    } else {
  35        3;
  36    };
  37
  38 ;;;# Symbol conversion
  39 ;;;t \index{symbol}
  40 ;;;t \index{symbol conversion}
  41
  42 ;;; Lisp symbols are converted to JavaScript symbols by following a
  43 ;;; few simple rules. Special characters `!', `?', `#', `@', `%',
  44 ;;; '/', `*' and `+' get replaced by their written-out equivalents
  45 ;;; "bang", "what", "hash", "at", "percent", "slash",
  46 ;;; "start" and "plus" respectively. The `$' character is untouched.
  47
  48 !?#@% => bangwhathashatpercent;
  49
  50 ;;; The `-' is an indication that the following character should be
  51 ;;; converted to uppercase. Thus, `-' separated symbols are converted
  52 ;;; to camelcase. The `_' character however is left untouched.
  53
  54 bla-foo-bar => blaFooBar;
  55
  56 ;;; If you want a JavaScript symbol beginning with an uppercase, you
  57 ;;; can either use a leading `-', which can be misleading in a
  58 ;;; mathematical context, or a leading `*'.
  59
  60 *array => Array;
  61
  62 ;;; A symbol beggining and ending with `+' or `*' is converted to all
  63 ;;; uppercase, to signify that this is a constant or a global
  64 ;;; variable.
  65
  66 *global-array*        => GLOBALARRAY;
  67
  68 ;;;## Reserved Keywords
  69 ;;;t \index{keyword}
  70 ;;;t \index{reserved keywords}
  71
  72 ;;; The following keywords and symbols are reserved in Parenscript,
  73 ;;; and should not be used as variable names.
  74
  75 ! ~ ++ -- * / % + - << >> >>> < > <= >= == != ==== !== & ^ | && || *=
  76 /= %= += -= <<= >>= >>>= &= ^= |= 1- 1+ @ ABSTRACT AND AREF ARRAY
  77 BOOLEAN BREAK BYTE CASE CATCH CC-IF CHAR CLASS COMMA CONST CONTINUE
  78 CREATE DEBUGGER DECF DEFAULT DEFUN DEFVAR DELETE DO DO* DOEACH DOLIST
  79 DOTIMES DOUBLE ELSE ENUM EQL EXPORT EXTENDS F FALSE FINAL FINALLY
  80 FLOAT FLOOR FOR FOR-IN FUNCTION GOTO IF IMPLEMENTS IMPORT IN INCF
  81 INSTANCEOF INT INTERFACE JS LABELED-FOR LAMBDA LET LET* LISP LIST LONG
  82 MAKE-ARRAY NATIVE NEW NIL NOT OR PACKAGE PRIVATE PROGN PROTECTED
  83 PUBLIC RANDOM REGEX RETURN SETF SHORT SLOT-VALUE STATIC SUPER SWITCH
  84 SYMBOL-MACROLET SYNCHRONIZED T THIS THROW THROWS TRANSIENT TRY TYPEOF
  85 UNDEFINED UNLESS VAR VOID VOLATILE WHEN WHILE WITH WITH-SLOTS
  86
  87 ;;;# Literal values
  88 ;;;t \index{literal value}
  89
  90 ;;;## Number literals
  91 ;;;t \index{number}
  92 ;;;t \index{number literal}
  93
  94 ; number ::= a Lisp number
  95
  96 ;;;
  97 ;;; Parenscript supports the standard JavaScript literal
  98 ;;; values. Numbers are compiled into JavaScript numbers.
  99
 100 1       => 1;
 101
 102 123.123 => 123.123;
 103
 104 ;;; Note that the base is not conserved between Lisp and JavaScript.
 105
 106 #x10    => 16;
 107
 108 ;;;## String literals
 109 ;;;t \index{string}
 110 ;;;t \index{string literal}
 111
 112 ; string ::= a Lisp string
 113
 114 ;;; Lisp strings are converted into JavaScript literals.
 115
 116 "foobar"      => 'foobar';
 117
 118 "bratzel bub" => 'bratzel bub';
 119
 120 ;;; Special characters such as newline and backspace are converted
 121 ;;; into their corresponding JavaScript escape sequences.
 122
 123 "       "   => '\\t';
 124
 125 ;;;## Array literals
 126 ;;;t \index{array}
 127 ;;;t \index{ARRAY}
 128 ;;;t \index{MAKE-ARRAY}
 129 ;;;t \index{AREF}
 130 ;;;t \index{array literal}
 131
 132 ; (ARRAY {values}*)
 133 ; (MAKE-ARRAY {values}*)
 134 ; (AREF array index)
 135 ;
 136 ; values ::= a Parenscript expression
 137 ; array  ::= a Parenscript expression
 138 ; index  ::= a Parenscript expression
 139
 140 ;;; Array literals can be created using the `ARRAY' form.
 141
 142 (array)       => [  ];
 143
 144 (array 1 2 3) => [ 1, 2, 3 ];
 145
 146 (array (array 2 3)
 147        (array "foobar" "bratzel bub"))
 148 => [ [ 2, 3 ], [ 'foobar', 'bratzel bub' ] ];
 149
 150 ;;; Arrays can also be created with a call to the `Array' function
 151 ;;; using the `MAKE-ARRAY'. The two forms have the exact same semantic
 152 ;;; on the JavaScript side.
 153
 154 (make-array)       => new Array();
 155
 156 (make-array 1 2 3) => new Array(1, 2, 3);
 157
 158 (make-array
 159  (make-array 2 3)
 160  (make-array "foobar" "bratzel bub"))
 161 => new Array(new Array(2, 3), new Array('foobar', 'bratzel bub'));
 162
 163 ;;; Indexing arrays in Parenscript is done using the form `AREF'. Note
 164 ;;; that JavaScript knows of no such thing as an array. Subscripting
 165 ;;; an array is in fact reading a property from an object. So in a
 166 ;;; semantic sense, there is no real difference between `AREF' and
 167 ;;; `SLOT-VALUE'.
 168
 169 ;;;## Object literals
 170 ;;;t \index{CREATE}
 171 ;;;t \index{SLOT-VALUE}
 172 ;;;t \index{@}
 173 ;;;t \index{WITH-SLOTS}
 174 ;;;t \index{object literal}
 175 ;;;t \index{object}
 176 ;;;t \index{object property}
 177 ;;;t \index{property}
 178
 179 ; (CREATE {name value}*)
 180 ; (SLOT-VALUE object slot-name)
 181 ; (WITH-SLOTS ({slot-name}*) object body)
 182 ;
 183 ; name      ::= a Parenscript symbol or a Lisp keyword
 184 ; value     ::= a Parenscript expression
 185 ; object    ::= a Parenscript object expression
 186 ; slot-name ::= a quoted Lisp symbol
 187 ; body      ::= a list of Parenscript statements
 188
 189 ;;;
 190 ;;; Object literals can be create using the `CREATE' form. Arguments
 191 ;;; to the `CREATE' form is a list of property names and values. To be
 192 ;;; more "lispy", the property names can be keywords.
 193
 194 (create foo "bar" :blorg 1)
 195 => { foo : 'bar', 'blorg' : 1 };
 196
 197 (create foo "hihi"
 198         blorg (array 1 2 3)
 199         another-object (create :schtrunz 1))
 200 => { foo : 'hihi',
 201      blorg : [ 1, 2, 3 ],
 202      anotherObject : { 'schtrunz' : 1 } };
 203
 204 ;;; Object properties can be accessed using the `SLOT-VALUE' form,
 205 ;;; which takes an object and a slot-name.
 206
 207 (slot-value an-object 'foo) => anObject.foo;
 208
 209 ;;; The convenience macro `@' is provided to make multiple levels of
 210 ;;; indirection easy to express
 211
 212 (@ an-object foo bar) => anObject.foo.bar;
 213
 214 ;;; The form `WITH-SLOTS' can be used to bind the given slot-name
 215 ;;; symbols to a macro that will expand into a `SLOT-VALUE' form at
 216 ;;; expansion time.
 217
 218 (with-slots (a b c) this
 219   (+ a b c))
 220 => this.a + this.b + this.c;
 221
 222 ;;;## Regular Expression literals
 223 ;;;t \index{REGEX}
 224 ;;;t \index{regular expression}
 225 ;;;t \index{CL-INTERPOL}
 226
 227 ; (REGEX regex)
 228 ;
 229 ; regex ::= a Lisp string
 230
 231 ;;; Regular expressions can be created by using the `REGEX' form. If
 232 ;;; the argument does not start with a slash, it is surrounded by
 233 ;;; slashes to make it a proper JavaScript regex. If the argument
 234 ;;; starts with a slash it is left as it is. This makes it possible
 235 ;;; to use modifiers such as slash-i (case-insensitive) or
 236 ;;; slash-g (match-globally (all)).
 237
 238 (regex "foobar") => /foobar/;
 239
 240 (regex "/foobar/i") => /foobar/i;
 241
 242 ;;; Here CL-INTERPOL proves really useful.
 243
 244 (regex #?r"/([^\s]+)foobar/i") => /([^\s]+)foobar/i;
 245
 246 ;;;## Literal symbols
 247 ;;;t \index{T}
 248 ;;;t \index{F}
 249 ;;;t \index{FALSE}
 250 ;;;t \index{NIL}
 251 ;;;t \index{UNDEFINED}
 252 ;;;t \index{THIS}
 253 ;;;t \index{literal symbols}
 254 ;;;t \index{null}
 255 ;;;t \index{true}
 256
 257 ; T, F, FALSE, NIL, UNDEFINED, THIS
 258
 259 ;;; The Lisp symbols `T' and `FALSE' (or `F') are converted to their
 260 ;;; JavaScript boolean equivalents `true' and `false'.
 261
 262 T     => true;
 263
 264 FALSE => false;
 265
 266 F => false;
 267
 268 ;;; The Lisp symbol `NIL' is converted to the JavaScript keyword
 269 ;;; `null'.
 270
 271 NIL => null;
 272
 273 ;;; The Lisp symbol `UNDEFINED' is converted to the JavaScript keyword
 274 ;;; `undefined'.
 275
 276 UNDEFINED => undefined;
 277
 278 ;;; The Lisp symbol `THIS' is converted to the JavaScript keyword
 279 ;;; `this'.
 280
 281 THIS => this;
 282
 283 ;;;# Variables
 284 ;;;t \index{variable}
 285 ;;;t \index{symbol}
 286
 287 ; variable ::= a Lisp symbol
 288
 289 ;;; All the other literal Lisp values that are not recognized as
 290 ;;; special forms or symbol macros are converted to JavaScript
 291 ;;; variables. This extreme freedom is actually quite useful, as it
 292 ;;; allows the Parenscript programmer to be flexible, as flexible as
 293 ;;; JavaScript itself.
 294
 295 variable    => variable;
 296
 297 a-variable  => aVariable;
 298
 299 *math       => Math;
 300
 301 ;;;# Function calls and method calls
 302 ;;;t \index{function}
 303 ;;;t \index{function call}
 304 ;;;t \index{method}
 305 ;;;t \index{method call}
 306
 307 ; (function {argument}*)
 308
 309 ;
 310 ; function ::= a Parenscript expression or a Lisp symbol
 311 ; object   ::= a Parenscript expression
 312 ; argument ::= a Parenscript expression
 313
 314 ;;; Any list passed to the JavaScript that is not recognized as a
 315 ;;; macro or a special form (see "Macro Expansion" below) is
 316 ;;; interpreted as a function call. The function call is converted to
 317 ;;; the normal JavaScript function call representation, with the
 318 ;;; arguments given in paren after the function name.
 319
 320 (blorg 1 2) => blorg(1, 2);
 321
 322 (foobar (blorg 1 2) (blabla 3 4) (array 2 3 4))
 323 => foobar(blorg(1, 2), blabla(3, 4), [ 2, 3, 4 ]);
 324
 325 ((slot-value this 'blorg) 1 2) => this.blorg(1, 2);
 326
 327 ((aref foo i) 1 2) => foo[i](1, 2);
 328
 329 ((slot-value (aref foobar 1) 'blorg) NIL T) => foobar[1].blorg(null, true);
 330
 331 ;;;# Operator Expressions
 332 ;;;t \index{operator}
 333 ;;;t \index{operator expression}
 334 ;;;t \index{assignment operator}
 335 ;;;t \index{EQL}
 336 ;;;t \index{NOT}
 337 ;;;t \index{AND}
 338 ;;;t \index{OR}
 339
 340 ; (operator {argument}*)
 341 ; (single-operator argument)
 342 ;
 343 ; operator ::= one of *, /, %, +, -, <<, >>, >>>, < >, EQL,
 344 ;              ==, !=, =, ===, !==, &, ^, |, &&, AND, ||, OR.
 345 ; single-operator ::= one of INCF, DECF, ++, --, NOT, !
 346 ; argument ::= a Parenscript expression
 347
 348 ;;; Operator forms are similar to function call forms, but have an
 349 ;;; operator as function name.
 350 ;;;
 351 ;;; Please note that `=' is converted to `==' in JavaScript. The `='
 352 ;;; Parenscript operator is not the assignment operator.
 353
 354 (* 1 2)   => 1 * 2;
 355
 356 (= 1 2)   => 1 == 2;
 357
 358 ;;; Note that the resulting expression is correctly parenthesized,
 359 ;;; according to the JavaScript operator precedence that can be found
 360 ;;; in table form at:
 361
 362 ;;;    http://www.codehouse.com/javascript/precedence/
 363
 364 (* 1 (+ 2 3 4) 4 (/ 6 7))
 365 => 1 * (2 + 3 + 4) * 4 * (6 / 7);
 366
 367 ;;; The pre increment and decrement operators are also
 368 ;;; available. `INCF' and `DECF' are the pre-incrementing and
 369 ;;; pre-decrementing operators. These operators can
 370 ;;; take only one argument.
 371
 372 (incf i) => ++i;
 373
 374 (decf i) => --i;
 375
 376 ;;; The `1+' and `1-' operators are shortforms for adding and
 377 ;;; substracting 1.
 378
 379 (1- i) => i - 1;
 380
 381 (1+ i) => i + 1;
 382
 383 ;;; If `not' is used on another boolean-returning operator, the
 384 ;;; operator is reversed.
 385
 386 (not (< i 2))   => i >= 2;
 387
 388 ;;;# Body forms
 389 ;;;t \index{body form}
 390 ;;;t \index{PROGN}
 391 ;;;t \index{body statement}
 392
 393 ; (PROGN {statement}*) in statement context
 394 ; (PROGN {expression}*) in expression context
 395 ;
 396 ; statement  ::= a Parenscript statement
 397 ; expression ::= a Parenscript expression
 398
 399 ;;; The `PROGN' special form defines a sequence of statements when
 400 ;;; used in a statement context, or sequence of expression when used
 401 ;;; in an expression context. The `PROGN' special form is added
 402 ;;; implicitly around the branches of conditional executions forms,
 403 ;;; function declarations and iteration constructs.
 404
 405 ;;; For example, in a statement context:
 406
 407 (progn (blorg i) (blafoo i))
 408 => blorg(i);
 409    blafoo(i);
 410
 411 ;;; In an expression context:
 412
 413 (+ i (progn (blorg i) (blafoo i)))
 414 => i + (blorg(i), blafoo(i));
 415
 416 ;;; A `PROGN' form doesn't lead to additional indentation or
 417 ;;; additional braces around it's body.
 418
 419 ;;;# Function Definition
 420 ;;;t \index{function}
 421 ;;;t \index{method}
 422 ;;;t \index{function definition}
 423 ;;;t \index{DEFUN}
 424 ;;;t \index{LAMBDA}
 425 ;;;t \index{closure}
 426 ;;;t \index{anonymous function}
 427
 428 ; (DEFUN name ({argument}*) body)
 429 ; (LAMBDA ({argument}*) body)
 430 ;
 431 ; name     ::= a Lisp Symbol
 432 ; argument ::= a Lisp symbol
 433 ; body     ::= a list of Parenscript statements
 434
 435 ;;; As in Lisp, functions are defined using the `DEFUN' form, which
 436 ;;; takes a name, a list of arguments, and a function body. An
 437 ;;; implicit `PROGN' is added around the body statements.
 438
 439 (defun a-function (a b)
 440   (return (+ a b)))
 441 => function aFunction(a, b) {
 442        return a + b;
 443    };
 444
 445 ;;; Anonymous functions can be created using the `LAMBDA' form, which
 446 ;;; is the same as `DEFUN', but without function name. In fact,
 447 ;;; `LAMBDA' creates a `DEFUN' with an empty function name.
 448
 449 (lambda (a b) (return (+ a b)))
 450 => function (a, b) {
 451        return a + b;
 452    };
 453
 454 ;;;# Assignment
 455 ;;;t \index{assignment}
 456 ;;;t \index{SETF}
 457 ;;;t \index{PSETF}
 458 ;;;t \index{SETQ}
 459 ;;;t \index{PSETQ}
 460 ;;;t \index{DEFSETF}
 461 ;;;t \index{assignment operator}
 462
 463 ; (SETF {lhs rhs}*)
 464 ; (PSETF {lhs rhs}*)
 465 ;
 466 ; lhs ::= a Parenscript left hand side expression
 467 ; rhs ::= a Parenscript expression
 468
 469 ; (SETQ {lhs rhs}*)
 470 ; (PSETQ {lhs rhs}*)
 471 ;
 472 ; lhs ::= a Parenscript symbol
 473 ; rhs ::= a Parenscript expression
 474
 475 ;;; Assignment is done using the `SETF', `PSETF', `SETQ', and `PSETQ'
 476 ;;; forms, which are transformed into a series of assignments using
 477 ;;; the JavaScript `=' operator.
 478
 479 (setf a 1) => a = 1;
 480
 481 (setf a 2 b 3 c 4 x (+ a b c))
 482 => a = 2;
 483    b = 3;
 484    c = 4;
 485    x = a + b + c;
 486
 487 ;;; The `SETF' form can transform assignments of a variable with an
 488 ;;; operator expression using this variable into a more "efficient"
 489 ;;; assignment operator form. For example:
 490
 491 (setf a (+ a 2 3 4 a))   => a += 2 + 3 + 4 + a;
 492
 493 (setf a (- 1 a))         => a = 1 - a;
 494
 495 ;;; The `PSETF' and `PSETQ' forms perform parallel assignment of
 496 ;;; places or variables using a number of temporary variables created
 497 ;;; by `PS-GENSYM'.  For example:
 498
 499 (let ((a 1) (b 2))
 500   (psetf a b b a))
 501 => var a = 1;
 502    var b = 2;
 503    var _js1 = b;
 504    var _js2 = a;
 505    a = _js1;
 506    b = _js2;
 507
 508 ;;; The `SETQ' and `PSETQ' forms operate identically to `SETF' and
 509 ;;; `PSETF', but throw a compile-time error if the left-hand side form
 510 ;;; is not a symbol.   For example:
 511
 512 (setq a 1)   => a = 1;
 513
 514 ;; but...
 515
 516 (setq (aref a 0) 1)
 517 ;; => ERROR: The value (AREF A 0) is not of type SYMBOL.
 518
 519 ;;; New types of setf places can be defined in one of two ways: using
 520 ;;; `DEFSETF' or using `DEFUN' with a setf function name; both are
 521 ;;; analogous to their Common Lisp counterparts.
 522
 523 ;;; `DEFSETF' supports both long and short forms, while `DEFUN' of a
 524 ;;; setf place generates a JavaScript function name with the __setf_
 525 ;;; prefix:
 526
 527 (defun (setf color) (new-color el)
 528   (setf (slot-value (slot-value el 'style) 'color) new-color))
 529 => function __setf_color(newColor, el) {
 530        el.style.color = newColor;
 531    };
 532
 533 (setf (color some-div) (+ 23 "em"))
 534 => var _js2 = someDiv;
 535    var _js1 = 23 + 'em';
 536    __setf_color(_js1, _js2);
 537
 538 ;;; Note that temporary variables are generated to preserve evaluation
 539 ;;; order of the arguments as they would be in Lisp.
 540
 541 ;;; The following example illustrates how setf places can be used to
 542 ;;; provide a uniform protocol for positioning elements in HTML pages:
 543
 544 (defsetf left (el) (offset)
 545   `(setf (slot-value (slot-value ,el 'style) 'left) ,offset))
 546 => null;
 547
 548 (setf (left some-div) (+ 123 "px"))
 549 => var _js2 = someDiv;
 550    var _js1 = 123 + 'px';
 551    _js2.style.left = _js1;
 552
 553 (macrolet ((left (el)
 554              `(slot-value ,el 'offset-left)))
 555   (left some-div))
 556 => someDiv.offsetLeft;
 557
 558 ;;;# Single argument statements
 559 ;;;t \index{single-argument statement}
 560 ;;;t \index{RETURN}
 561 ;;;t \index{THROW}
 562 ;;;t \index{THROW}
 563 ;;;t \index{function}
 564
 565 ; (RETURN {value}?)
 566 ; (THROW  {value}?)
 567 ;
 568 ; value ::= a Parenscript expression
 569
 570 ;;; The single argument statements `return' and `throw' are generated
 571 ;;; by the form `RETURN' and `THROW'. `THROW' has to be used inside a
 572 ;;; `TRY' form. `RETURN' is used to return a value from a function
 573 ;;; call.
 574
 575 (return 1)       => return 1;
 576
 577 (throw "foobar") => throw 'foobar';
 578
 579 ;;;# Single argument expression
 580 ;;;t \index{single-argument expression}
 581 ;;;t \index{object creation}
 582 ;;;t \index{object deletion}
 583 ;;;t \index{DELETE}
 584 ;;;t \index{VOID}
 585 ;;;t \index{TYPEOF}
 586 ;;;t \index{INSTANCEOF}
 587 ;;;t \index{NEW}
 588 ;;;t \index{new}
 589
 590 ; (DELETE     {value})
 591 ; (VOID       {value})
 592 ; (TYPEOF     {value})
 593 ; (INSTANCEOF {value})
 594 ; (NEW        {value})
 595 ;
 596 ; value ::= a Parenscript expression
 597
 598 ;;; The single argument expressions `delete', `void', `typeof',
 599 ;;; `instanceof' and `new' are generated by the forms `DELETE',
 600 ;;; `VOID', `TYPEOF', `INSTANCEOF' and `NEW'. They all take a
 601 ;;; Parenscript expression.
 602
 603 (delete (new (*foobar 2 3 4))) => delete new Foobar(2, 3, 4);
 604
 605 (if (= (typeof blorg) *string)
 606     (alert (+ "blorg is a string: " blorg))
 607     (alert "blorg is not a string"))
 608 => if (typeof blorg == String) {
 609        alert('blorg is a string: ' + blorg);
 610    } else {
 611        alert('blorg is not a string');
 612    };
 613
 614 ;;;# Conditional Statements
 615 ;;;t \index{conditional statements}
 616 ;;;t \index{IF}
 617 ;;;t \index{WHEN}
 618 ;;;t \index{UNLESS}
 619 ;;;t \index{conditionals}
 620
 621 ; (IF conditional then {else})
 622 ; (WHEN condition then)
 623 ; (UNLESS condition then)
 624 ;
 625 ; condition ::= a Parenscript expression
 626 ; then      ::= a Parenscript statement in statement context, a
 627 ;                 Parenscript expression in expression context
 628 ; else      ::= a Parenscript statement in statement context, a
 629 ;                 Parenscript expression in expression context
 630
 631 ;;; The `IF' form compiles to the `if' javascript construct. An
 632 ;;; explicit `PROGN' around the then branch and the else branch is
 633 ;;; needed if they consist of more than one statement. When the `IF'
 634 ;;; form is used in an expression context, a JavaScript `?', `:'
 635 ;;; operator form is generated.
 636
 637 (if ((@ blorg is-correct))
 638     (progn (carry-on) (return i))
 639     (alert "blorg is not correct!"))
 640 => if (blorg.isCorrect()) {
 641        carryOn();
 642        return i;
 643    } else {
 644        alert('blorg is not correct!');
 645    };
 646
 647 (+ i (if ((@ blorg add-one)) 1 2))
 648 => i + (blorg.addOne() ? 1 : 2);
 649
 650 ;;; The `WHEN' and `UNLESS' forms can be used as shortcuts for the
 651 ;;; `IF' form.
 652
 653 (when ((@ blorg is-correct))
 654   (carry-on)
 655   (return i))
 656 => if (blorg.isCorrect()) {
 657        carryOn();
 658        return i;
 659    };
 660
 661 (unless ((@ blorg is-correct))
 662   (alert "blorg is not correct!"))
 663 => if (!blorg.isCorrect()) {
 664        alert('blorg is not correct!');
 665    };
 666
 667 ;;;# Variable declaration
 668 ;;;t \index{variable}
 669 ;;;t \index{variable declaration}
 670 ;;;t \index{binding}
 671 ;;;t \index{scoping}
 672 ;;;t \index{DEFVAR}
 673 ;;;t \index{VAR}
 674 ;;;t \index{LET}
 675 ;;;t \index{LET*}
 676
 677 ; (DEFVAR var {value}?)
 678 ; (VAR var {value}?)
 679 ; (LET ({var | (var value)}*) body)
 680 ; (LET* ({var | (var value)}*) body)
 681 ;
 682 ; var   ::= a Lisp symbol
 683 ; value ::= a Parenscript expression
 684 ; body  ::= a list of Parenscript statements
 685
 686 ;;; Parenscript special variables can be declared using the `DEFVAR'
 687 ;;; special form, which is similar to its equivalent form in
 688 ;;; Lisp. Note that the result is undefined if `DEFVAR' is not used as
 689 ;;; a top-level form.
 690
 691 (defvar *a* (array 1 2 3)) => var A = [ 1, 2, 3 ];
 692
 693 ;;; One feature present in Parenscript that is not part of Common Lisp
 694 ;;; are lexically-scoped global variables, which are declared using
 695 ;;; the `VAR' special form.
 696
 697 ;;; Parenscript provides the `LET' and `LET*' special forms for
 698 ;;; creating new variable bindings. Both special forms implement
 699 ;;; lexical scope by renaming the provided variables via `GENSYM', and
 700 ;;; implement dynamic binding using `TRY'-`FINALY'. Note that
 701 ;;; top-level `LET' and `LET*' forms will create new global variables.
 702
 703 ;;; Moreover, beware that scoping rules in Lisp and JavaScript are
 704 ;;; quite different. For example, don't rely on closures capturing
 705 ;;; local variables in the way that you would normally expect.
 706
 707
 708 ;;; examples:
 709
 710 (progn
 711   (defvar *a* 4)
 712   (let ((x 1)
 713         (*a* 2))
 714     (let* ((y (+ x 1))
 715            (x (+ x y)))
 716       (+ *a* x y))))
 717 => var A = 4;
 718    var x = 1;
 719    var A_TMPSTACK1;
 720    try {
 721        A_TMPSTACK1 = A;
 722        A = 2;
 723        var y = x + 1;
 724        var x2 = x + y;
 725        A + x2 + y;
 726    } finally {
 727        A = A_TMPSTACK1;
 728    };
 729
 730 ;;;# Iteration constructs
 731 ;;;t \index{iteration}
 732 ;;;t \index{iteration construct}
 733 ;;;t \index{loop}
 734 ;;;t \index{array traversal}
 735 ;;;t \index{property}
 736 ;;;t \index{object property}
 737 ;;;t \index{DO}
 738 ;;;t \index{DOTIMES}
 739 ;;;t \index{DOLIST}
 740 ;;;t \index{FOR-IN}
 741 ;;;t \index{WHILE}
 742
 743 ; (DO ({var | (var {init}? {step}?)}*) (end-test {result}?) body)
 744 ; (DO* ({var | (var {init}? {step}?)}*) (end-test {result}?) body)
 745 ; (DOTIMES (var numeric-form {result}?) body)
 746 ; (DOLIST (var list-form {result}?) body)
 747 ; (FOR-IN (var object) body)
 748 ; (WHILE end-test body)
 749 ;
 750 ; var          ::= a Lisp symbol
 751 ; numeric-form ::= a Parenscript expression resulting in a number
 752 ; list-form    ::= a Parenscript expression resulting in an array
 753 ; object-form  ::= a Parenscript expression resulting in an object
 754 ; init         ::= a Parenscript expression
 755 ; step         ::= a Parenscript expression
 756 ; end-test     ::= a Parenscript expression
 757 ; result       ::= a Parenscript expression
 758 ; body         ::= a list of Parenscript statements
 759
 760 ;;; All interation special forms are transformed into JavaScript `for'
 761 ;;; statements and, if needed, lambda expressions.
 762
 763 ;;; `DO', `DO*', and `DOTIMES' carry the same semantics as their
 764 ;;; Common Lisp equivalents.
 765
 766 ;;; `DO*' (note the variety of possible init-forms:
 767
 768 (do* ((a) b (c (array "a" "b" "c" "d" "e"))
 769       (d 0 (1+ d))
 770       (e (aref c d) (aref c d)))
 771      ((or (= d (@ c length)) (== e "x")))
 772   (setf a d b e)
 773   ((@ document write) (+ "a: " a " b: " b "<br/>")))
 774 => for (var a = null, b = null, c = ['a', 'b', 'c', 'd', 'e'], d = 0, e = c[d]; !(d == c.length || e == 'x'); d += 1, e = c[d]) {
 775        a = d;
 776        b = e;
 777        document.write('a: ' + a + ' b: ' + b + '<br/>');
 778    };
 779
 780 ;;; `DO'
 781
 782 (do ((i 0 (1+ i))
 783      (s 0 (+ s i (1+ i))))
 784     ((> i 10))
 785   ((@ document write) (+ "i: " i " s: " s "<br/>")))
 786 => var i = 0;
 787    var s = 0;
 788    for (; i <= 10; ) {
 789        document.write('i: ' + i + ' s: ' + s + '<br/>');
 790        var _js1 = i + 1;
 791        var _js2 = s + i + (i + 1);
 792        i = _js1;
 793        s = _js2;
 794    };
 795
 796 ;;; compare to `DO*':
 797
 798 (do* ((i 0 (1+ i))
 799       (s 0 (+ s i (1- i))))
 800      ((> i 10))
 801   ((@ document write) (+ "i: " i " s: " s "<br/>")))
 802 => for (var i = 0, s = 0; i <= 10; i += 1, s += i + (i - 1)) {
 803        document.write('i: ' + i + ' s: ' + s + '<br/>');
 804    };
 805
 806 ;;; `DOTIMES':
 807
 808 (let ((arr (array "a" "b" "c" "d" "e")))
 809   (dotimes (i (@ arr length))
 810     ((@ document write) (+ "i: " i " arr[i]: " (aref arr i) "<br/>"))))
 811 => var arr = ['a', 'b', 'c', 'd', 'e'];
 812    for (var i = 0; i < arr.length; i += 1) {
 813        document.write('i: ' + i + ' arr[i]: ' + arr[i] + '<br/>');
 814    };
 815
 816 ;;; `DOTIMES' with return value:
 817
 818 (let ((res 0))
 819   (alert (+ "Summation to 10 is "
 820             (dotimes (i 10 res)
 821               (incf res (1+ i))))))
 822 => var res = 0;
 823    alert('Summation to 10 is ' + (function () {
 824        for (var i = 0; i < 10; i += 1) {
 825            res += i + 1;
 826        };
 827        return res;
 828    })());
 829
 830 ;;; `DOLIST' is like CL:DOLIST, but that it operates on numbered JS
 831 ;;; arrays/vectors.
 832
 833 (let ((l (list 1 2 4 8 16 32)))
 834   (dolist (c l)
 835     ((@ document write) (+ "c: " c "<br/>"))))
 836 => var l = [1, 2, 4, 8, 16, 32];
 837    for (var c = null, _js_arrvar2 = l, _js_idx1 = 0; _js_idx1 < _js_arrvar2.length; _js_idx1 += 1) {
 838        c = _js_arrvar2[_js_idx1];
 839        document.write('c: ' + c + '<br/>');
 840    };
 841
 842 (let ((l '(1 2 4 8 16 32))
 843       (s 0))
 844   (alert (+ "Sum of " l " is: "
 845             (dolist (c l s)
 846               (incf s c)))))
 847 => var l = [1, 2, 4, 8, 16, 32];
 848    var s = 0;
 849    alert('Sum of ' + l + ' is: ' + (function () {
 850        for (var c = null, _js_arrvar2 = l, _js_idx1 = 0; _js_idx1 < _js_arrvar2.length; _js_idx1 += 1) {
 851            c = _js_arrvar2[_js_idx1];
 852            s += c;
 853        };
 854        return s;
 855    })());
 856
 857 ;;; `FOR-IN' is translated to the JS `for...in' statement.
 858
 859 (let ((obj (create a 1 b 2 c 3)))
 860   (for-in (i obj)
 861     ((@ document write) (+ i ": " (aref obj i) "<br/>"))))
 862 => var obj = { a : 1, b : 2, c : 3 };
 863    for (var i in obj) {
 864        document.write(i + ': ' + obj[i] + '<br/>');
 865    };
 866
 867 ;;; The `WHILE' form is transformed to the JavaScript form `while',
 868 ;;; and loops until a termination test evaluates to false.
 869
 870 (while ((@ film is-not-finished))
 871   ((@ this eat) (new *popcorn)))
 872 => while (film.isNotFinished()) {
 873        this.eat(new Popcorn);
 874    };
 875
 876 ;;;# The `CASE' statement
 877 ;;;t \index{CASE}
 878 ;;;t \index{SWITCH}
 879 ;;;t \index{switch}
 880
 881 ; (CASE case-value clause*)
 882 ;
 883 ; clause     ::= (value body) | ((value*) body) | t-clause
 884 ; case-value ::= a Parenscript expression
 885 ; value      ::= a Parenscript expression
 886 ; t-clause   ::= {t | otherwise | default} body
 887 ; body       ::= a list of Parenscript statements
 888
 889 ;;; The Lisp `CASE' form is transformed to a `switch' statement in
 890 ;;; JavaScript. Note that `CASE' is not an expression in
 891 ;;; Parenscript.
 892
 893 (case (aref blorg i)
 894   ((1 "one") (alert "one"))
 895   (2 (alert "two"))
 896   (t (alert "default clause")))
 897 => switch (blorg[i]) {
 898        case 1:
 899        case 'one':
 900            alert('one');
 901            break;
 902        case 2:
 903            alert('two');
 904            break;
 905        default:
 906            alert('default clause');
 907        };
 908
 909 ; (SWITCH case-value clause*)
 910 ; clause     ::= (value body) | (default body)
 911
 912 ;;; The `SWITCH' form is the equivalent to a javascript switch statement.
 913 ;;; No break statements are inserted, and the default case is named `DEFAULT'.
 914 ;;; The `CASE' form should be prefered in most cases.
 915
 916 (switch (aref blorg i)
 917   (1 (alert "If I get here"))
 918   (2 (alert "I also get here"))
 919   (default (alert "I always get here")))
 920 => switch (blorg[i]) {
 921        case 1: alert('If I get here');
 922        case 2: alert('I also get here');
 923        default: alert('I always get here');
 924    };
 925
 926 ;;;# The `WITH' statement
 927 ;;;t \index{WITH}
 928 ;;;t \index{dynamic scope}
 929 ;;;t \index{binding}
 930 ;;;t \index{scoping}
 931 ;;;t \index{closure}
 932
 933 ; (WITH object body)
 934 ;
 935 ; object ::= a Parenscript expression evaluating to an object
 936 ; body   ::= a list of Parenscript statements
 937
 938 ;;; The `WITH' form is compiled to a JavaScript `with' statements, and
 939 ;;; adds the object `object' as an intermediary scope objects when
 940 ;;; executing the body.
 941
 942 (with (create foo "foo" i "i")
 943   (alert (+ "i is now intermediary scoped: " i)))
 944 => with ({ foo : 'foo', i : 'i' }) {
 945        alert('i is now intermediary scoped: ' + i);
 946    };
 947
 948 ;;;# The `TRY' statement
 949 ;;;t \index{TRY}
 950 ;;;t \index{CATCH}
 951 ;;;t \index{FINALLY}
 952 ;;;t \index{exception}
 953 ;;;t \index{error handling}
 954
 955 ; (TRY body {(:CATCH (var) body)}? {(:FINALLY body)}?)
 956 ;
 957 ; body ::= a list of Parenscript statements
 958 ; var  ::= a Lisp symbol
 959
 960 ;;; The `TRY' form is converted to a JavaScript `try' statement, and
 961 ;;; can be used to catch expressions thrown by the `THROW'
 962 ;;; form. The body of the catch clause is invoked when an exception
 963 ;;; is catched, and the body of the finally is always invoked when
 964 ;;; leaving the body of the `TRY' form.
 965
 966 (try (throw "i")
 967  (:catch (error)
 968    (alert (+ "an error happened: " error)))
 969  (:finally
 970    (alert "Leaving the try form")))
 971 => try {
 972        throw 'i';
 973    } catch (error) {
 974        alert('an error happened: ' + error);
 975    } finally {
 976        alert('Leaving the try form');
 977    };
 978
 979 ;;;# The HTML Generator
 980 ;;;t \index{PS-HTML}
 981 ;;;t \index{HTML generation}
 982
 983 ; (PS-HTML html-expression)
 984
 985 ;;; The HTML generator of Parenscript is very similar to the htmlgen
 986 ;;; HTML generator library included with AllegroServe. It accepts the
 987 ;;; same input forms as the AllegroServer HTML generator. However,
 988 ;;; non-HTML construct are compiled to JavaScript by the Parenscript
 989 ;;; compiler. The resulting expression is a JavaScript expression.
 990
 991 (ps-html ((:a :href "foobar") "blorg"))
 992 => '<A HREF=\"foobar\">blorg</A>';
 993
 994 (ps-html ((:a :href (generate-a-link)) "blorg"))
 995 => '<A HREF=\"' + generateALink() + '\">blorg</A>';
 996
 997 ;;; We can recursively call the Parenscript compiler in an HTML
 998 ;;; expression.
 999
1000 ((@ document write)
1001   (ps-html ((:a :href "#"
1002                 :onclick (ps-inline (transport))) "link")))
1003 => document.write('<A HREF=\"#\" ONCLICK=\"' + ('javascript:' + 'transport()') + '\">link</A>');
1004
1005 ;;; Forms may be used in attribute lists to conditionally generate
1006 ;;; the next attribute. In this example the textarea is sometimes disabled.
1007
1008 (let ((disabled nil)
1009       (authorized t))
1010    (setf (@ element inner-h-t-m-l)
1011          (ps-html ((:textarea (or disabled (not authorized)) :disabled "disabled")
1012                 "Edit me"))))
1013 => var disabled = null;
1014    var authorized = true;
1015    element.innerHTML =
1016    '<TEXTAREA'
1017    + (disabled || !authorized ? ' DISABLED=\"' + 'disabled' + '\"' : '')
1018    + '>Edit me</TEXTAREA>';
1019
1020 ;;;# Macrology
1021 ;;;t \index{macro}
1022 ;;;t \index{macrology}
1023 ;;;t \index{DEFPSMACRO}
1024 ;;;t \index{DEFMACRO/PS}
1025 ;;;t \index{DEFMACRO+PS}
1026 ;;;t \index{DEFINE-PS-SYMBOL-MACRO}
1027 ;;;t \index{IMPORT-MACROS-FROM-LISP}
1028 ;;;t \index{MACROLET}
1029 ;;;t \index{SYMBOL-MACROLET}
1030 ;;;t \index{PS-GENSYM}
1031 ;;;t \index{compiler}
1032
1033 ; (DEFPSMACRO name lambda-list macro-body)
1034 ; (DEFPSMACRO/PS name lambda-list macro-body)
1035 ; (DEFPSMACRO+PS name lambda-list macro-body)
1036 ; (DEFINE-PS-SYMBOL-MACRO symbol expansion)
1037 ; (IMPORT-MACROS-FROM-LISP symbol*)
1038 ; (MACROLET ({name lambda-list macro-body}*) body)
1039 ; (SYMBOL-MACROLET ({name macro-body}*) body)
1040 ; (PS-GENSYM {string})
1041 ;
1042 ; name        ::= a Lisp symbol
1043 ; lambda-list ::= a lambda list
1044 ; macro-body  ::= a Lisp body evaluating to Parenscript code
1045 ; body        ::= a list of Parenscript statements
1046 ; string      ::= a string
1047
1048 ;;; Parenscript can be extended using macros, just like Lisp can be
1049 ;;; extended using Lisp macros. Using the special Lisp form
1050 ;;; `DEFPSMACRO', the Parenscript language can be
1051 ;;; extended. `DEFPSMACRO' adds the new macro to the toplevel macro
1052 ;;; environment, which is always accessible during Parenscript
1053 ;;; compilation. For example, the `1+' and `1-' operators are
1054 ;;; implemented using macros.
1055
1056 (defpsmacro 1- (form)
1057   `(- ,form 1))
1058
1059 (defpsmacro 1+ (form)
1060   `(+ ,form 1))
1061
1062 ;;; A more complicated Parenscript macro example is the implementation
1063 ;;; of the `DOLIST' form (note how `PS-GENSYM', the Parenscript of
1064 ;;; `GENSYM', is used to generate new Parenscript variable names):
1065
1066 (defpsmacro dolist ((var array &optional (result nil result?)) &body body)
1067   (let ((idx (ps-gensym "_js_idx"))
1068         (arrvar (ps-gensym "_js_arrvar")))
1069     `(do* (,var
1070            (,arrvar ,array)
1071            (,idx 0 (1+ ,idx)))
1072           ((>= ,idx (slot-value ,arrvar 'length))
1073            ,@(when result? (list result)))
1074        (setq ,var (aref ,arrvar ,idx))
1075        ,@body)))
1076
1077 ;;; Macros can be defined in Parenscript code itself (as opposed to
1078 ;;; from Lisp) by using the Parenscript `MACROLET' and `DEFMACRO'
1079 ;;; forms. Note that macros defined this way are defined in a null
1080 ;;; lexical environment (ex - (let ((x 1)) (defmacro baz (y) `(+ ,y
1081 ;;; ,x))) will not work), since the surrounding Parenscript code is
1082 ;;; just translated to JavaScript and not actually evaluated.
1083
1084 ;;; Parenscript also supports the use of macros defined in the
1085 ;;; underlying Lisp environment. Existing Lisp macros can be imported
1086 ;;; into the Parenscript macro environment by
1087 ;;; `IMPORT-MACROS-FROM-LISP'. This functionality enables code sharing
1088 ;;; between Parenscript and Lisp, and is useful in debugging since the
1089 ;;; full power of Lisp macroexpanders, editors and other supporting
1090 ;;; facilities can be used. However, it is important to note that the
1091 ;;; macroexpansion of Lisp macros and Parenscript macros takes place
1092 ;;; in their own respective environments, and many Lisp macros
1093 ;;; (especially those provided by the Lisp implementation) expand into
1094 ;;; code that is not usable by Parenscript. To make it easy for users
1095 ;;; to take advantage of these features, two additional macro
1096 ;;; definition facilities are provided by Parenscript: `DEFMACRO/PS'
1097 ;;; and `DEFMACRO+PS'. `DEFMACRO/PS' defines a Lisp macro and then
1098 ;;; imports it into the Parenscript macro environment, while
1099 ;;; `DEFMACRO+PS' defines two macros with the same name and expansion,
1100 ;;; one in Parenscript and one in Lisp. `DEFMACRO+PS' is used when the
1101 ;;; full 'macroexpand' of the Lisp macro yields code that cannot be
1102 ;;; used by Parenscript.
1103
1104 ;;; Parenscript also supports symbol macros, which can be introduced
1105 ;;; using the Parenscript form `SYMBOL-MACROLET' or defined in Lisp
1106 ;;; with `DEFINE-PS-SYMBOL-MACRO'. For example, the Parenscript
1107 ;;; `WITH-SLOTS' is implemented using symbol macros.
1108
1109 (defpsmacro with-slots (slots object &rest body)
1110   `(symbol-macrolet ,(mapcar #'(lambda (slot)
1111                                  `(,slot '(slot-value ,object ',slot)))
1112                              slots)
1113     ,@body))
1114
1115 ;;;# The Parenscript namespace system
1116 ;;;t \index{package}
1117 ;;;t \index{namespace}
1118 ;;;t \index{PS-PACKAGE-PREFIX}
1119
1120 ; (setf (PS-PACKAGE-PREFIX package-designator) string)
1121
1122 ;;; Although JavaScript does not offer namespacing or a package
1123 ;;; system, Parenscript does provide a namespace mechanism for
1124 ;;; generated JavaScript by integrating with the Common Lisp package
1125 ;;; system. Since Parenscript code is normally read in by the Lisp
1126 ;;; reader, all symbols (except for uninterned ones, ie - those
1127 ;;; specified with the #: reader macro) have a Lisp package. By
1128 ;;; default, no packages are prefixed. You can specify that symbols in
1129 ;;; a particular package receive a prefix when translated to
1130 ;;; JavaScript with the `PS-PACKAGE-PREFIX' place.
1131
1132 (defpackage "PS-REF.MY-LIBRARY"
1133   (:use "PARENSCRIPT"))
1134 (setf (ps-package-prefix "PS-REF.MY-LIBRARY") "my_library_")
1135
1136 (defun ps-ref.my-library::library-function (x y)
1137   (return (+ x y)))
1138   -> function my_library_libraryFunction(x, y) {
1139         return x + y;
1140      };
1141
1142 ;;;# Identifier obfuscation
1143 ;;;t \index{obfuscation}
1144 ;;;t \index{identifiers}
1145 ;;;t \index{OBFUSCATE-PACKAGE}
1146 ;;;t \index{UNOBFUSCATE-PACKAGE}
1147
1148 ; (OBFUSCATE-PACKAGE package-designator &optional symbol-map)
1149 ; (UNOBFUSCATE-PACKAGE package-designator)
1150
1151 ;;; Similar to the namespace mechanism, Parenscript provides a
1152 ;;; facility to generate obfuscated identifiers in specified CL
1153 ;;; packages. The function `OBFUSCATE-PACKAGE' may optionally be
1154 ;;; passed a hash-table or a closure that maps symbols to their
1155 ;;; obfuscated counterparts. By default, the mapping is done using
1156 ;;; `PS-GENSYM'.
1157
1158 (defpackage "PS-REF.OBFUSCATE-ME")
1159 (obfuscate-package "PS-REF.OBFUSCATE-ME"
1160   (let ((code-pt-counter #x8CF0)
1161         (symbol-map (make-hash-table)))
1162     (lambda (symbol)
1163       (or (gethash symbol symbol-map)
1164           (setf (gethash symbol symbol-map)
1165                 (make-symbol (string (code-char (incf code-pt-counter)))))))))
1166
1167 (defun ps-ref.obfuscate-me::a-function (a b ps-ref.obfuscate-me::foo)
1168   (+ a (ps-ref.my-library::library-function b ps-ref.obfuscate-me::foo)))
1169   -> function 賱(a, b, 賲) {
1170        a + my_library_libraryFunction(b, 賲);
1171      };
1172
1173 ;;; The obfuscation and namespace facilities can be used on packages
1174 ;;; at the same time.
1175
1176 ;;;# The Parenscript Compiler
1177 ;;;t \index{compiler}
1178 ;;;t \index{Parenscript compiler}
1179 ;;;t \index{PS}
1180 ;;;t \index{PS*}
1181 ;;;t \index{PS1*}
1182 ;;;t \index{PS-INLINE}
1183 ;;;t \index{PS-INLINE*}
1184 ;;;t \index{LISP}
1185
1186 ; (PS &body body)
1187 ; (PS* &body body)
1188 ; (PS1* parenscript-form)
1189 ; (PS-INLINE form &optional *js-string-delimiter*)
1190 ; (PS-INLINE* form &optional *js-string-delimiter*)
1191
1192 ; (LISP lisp-forms)
1193 ;
1194 ; body ::= Parenscript statements comprising an implicit `PROGN'
1195
1196 ;;; For static Parenscript code, the macro `PS' compiles the provided
1197 ;;; forms at Common Lisp macro-expansion time. `PS*' and `PS1*'
1198 ;;; evaluate their arguments and then compile them. All these forms
1199 ;;; except for `PS1*' treat the given forms as an implicit
1200 ;;; `PROGN'.
1201
1202 ;;; `PS-INLINE' and `PS-INLINE*' take a single Parenscript form and
1203 ;;; output a string starting with "javascript:" that can be used in
1204 ;;; HTML node attributes. As well, they provide an argument to bind
1205 ;;; the value of *js-string-delimiter* to control the value of the
1206 ;;; JavaScript string escape character to be compatible with whatever
1207 ;;; the HTML generation mechanism is used (for example, if HTML
1208 ;;; strings are delimited using #\', using #\" will avoid conflicts
1209 ;;; without requiring the output JavaScript code to be escaped). By
1210 ;;; default the value is taken from *js-inline-string-delimiter*.
1211
1212 ;;; Parenscript can also call out to arbitrary Common Lisp code at
1213 ;;; code output time using the special form `LISP'. The form provided
1214 ;;; to `LISP' is evaluated, and its result is compiled as though it
1215 ;;; were Parenscript code. For `PS' and `PS-INLINE', the Parenscript
1216 ;;; output code is generated at macro-expansion time, and the `LISP'
1217 ;;; statements are inserted inline and have access to the enclosing
1218 ;;; Common Lisp lexical environment. `PS*' and `PS1*' evaluate the
1219 ;;; `LISP' forms with eval, providing them access to the current
1220 ;;; dynamic environment only.