reference.lisp

   1 ;;;# ParenScript Language Reference
   2
   3 ;;; This chapters describes the core constructs of ParenScript, as
   4 ;;; well as its compilation model. This chapter is aimed to be a
   5 ;;; comprehensive reference for ParenScript developers. Programmers
   6 ;;; looking for how to tweak the ParenScript compiler itself should
   7 ;;; turn to the ParenScript Internals chapter.
   8
   9 ;;;# Statements and Expressions
  10 ;;;t \index{statement}
  11 ;;;t \index{expression}
  12
  13 ;;; In contrast to Lisp, where everything is an expression, JavaScript
  14 ;;; makes the difference between an expression, which evaluates to a
  15 ;;; value, and a statement, which has no value. Examples for
  16 ;;; JavaScript statements are `for', `with' and `while'. Most
  17 ;;; ParenScript forms are expression, but certain special forms are
  18 ;;; not (the forms which are transformed to a JavaScript
  19 ;;; statement). All ParenScript expressions are statements
  20 ;;; though. Certain forms, like `IF' and `PROGN', generate different
  21 ;;; JavaScript constructs whether they are used in an expression
  22 ;;; context or a statement context. For example:
  23
  24 (+ i (if 1 2 3)) => i + (1 ? 2 : 3)
  25
  26 (if 1 2 3)
  27    => if (1) {
  28         2;
  29       } else {
  30         3;
  31       }
  32
  33 ;;;# Symbol conversion
  34 ;;;t \index{symbol}
  35 ;;;t \index{symbol conversion}
  36
  37 ;;; Lisp symbols are converted to JavaScript symbols by following a
  38 ;;; few simple rules. Special characters `!', `?', `#', `$', `@', `%',
  39 ;;; '/', `*' and `+' get replaced by their written-out equivalents
  40 ;;; "bang", "what", "hash", "dollar", "at", "percent", "slash",
  41 ;;; "start" and "plus" respectively.
  42
  43 !?#$@% => bangwhathashdollaratpercent
  44
  45 ;;; The `-' is an indication that the following character should be
  46 ;;; converted to uppercase. Thus, `-' separated symbols are converted
  47 ;;; to camelcase. The `_' character however is left untouched.
  48
  49 bla-foo-bar => blaFooBar
  50
  51 ;;; If you want a JavaScript symbol beginning with an uppercase, you
  52 ;;; can either use a leading `-', which can be misleading in a
  53 ;;; mathematical context, or a leading `*'.
  54
  55 *array => Array
  56
  57 ;;; The `.' character is left as is in symbols. This allows the
  58 ;;; ParenScript programmer to use a practical shortcut when accessing
  59 ;;; slots or methods of JavaScript objects. Instead of writing
  60
  61 (slot-value foobar 'slot)
  62
  63 ;;; we can write
  64
  65 foobar.slot
  66
  67 ;;; A symbol beggining and ending with `+' or `*' is converted to all
  68 ;;; uppercase, to signify that this is a constant or a global
  69 ;;; variable.
  70
  71 *global-array*        => GLOBALARRAY
  72
  73 *global-array*.length => GLOBALARRAY.length
  74
  75 ;;;## Reserved Keywords
  76 ;;;t \index{keyword}
  77 ;;;t \index{reserved keywords}
  78
  79 ;;; The following keywords and symbols are reserved in ParenScript,
  80 ;;; and should not be used as variable names.
  81
  82 ! ~ ++ -- * / % + - << >> >>> < > <= >= == != ==== !== & ^ | && ||
  83 *= /= %= += -= <<= >>= >>>= &= ^= |= 1- 1+
  84 ABSTRACT AND AREF ARRAY BOOLEAN BREAK BYTE CASE CATCH CC-IF CHAR CLASS
  85 COMMA CONST CONTINUE CREATE DEBUGGER DECF DEFAULT DEFUN DEFVAR DELETE
  86 DO DOEACH DOLIST DOTIMES DOUBLE ELSE ENUM EQL EXPORT EXTENDS FALSE
  87 FINAL FINALLY FLOAT FLOOR FOR FUNCTION GOTO IF IMPLEMENTS IMPORT IN INCF
  88 INSTANCEOF INT INTERFACE JS LAMBDA LET LISP LIST LONG MAKE-ARRAY NATIVE NEW
  89 NIL NOT OR PACKAGE PRIVATE PROGN PROTECTED PUBLIC RANDOM REGEX RETURN
  90 SETF SHORT SLOT-VALUE STATIC SUPER SWITCH SYMBOL-MACROLET SYNCHRONIZED T
  91 THIS THROW THROWS TRANSIENT TRY TYPEOF UNDEFINED UNLESS VAR VOID VOLATILE
  92 WHEN WHILE WITH WITH-SLOTS
  93
  94 ;;;# Literal values
  95 ;;;t \index{literal value}
  96
  97 ;;;## Number literals
  98 ;;;t \index{number}
  99 ;;;t \index{number literal}
 100
 101 ; number ::= a Lisp number
 102
 103 ;;;
 104 ;;; ParenScript supports the standard JavaScript literal
 105 ;;; values. Numbers are compiled into JavaScript numbers.
 106
 107 1       => 1
 108
 109 123.123 => 123.123
 110
 111 ;;; Note that the base is not conserved between Lisp and JavaScript.
 112
 113 #x10    => 16
 114
 115 ;;;## String literals
 116 ;;;t \index{string}
 117 ;;;t \index{string literal}
 118
 119 ; string ::= a Lisp string
 120
 121 ;;; Lisp strings are converted into JavaScript literals.
 122
 123 "foobar"      => "foobar"
 124 "bratzel bub" => "bratzel bub"
 125
 126 ;;; Escapes in Lisp are not converted to JavaScript escapes. However,
 127 ;;; to avoid having to use double backslashes when constructing a
 128 ;;; string, you can use the CL-INTERPOL library by Edi Weitz.
 129
 130 ;;;## Array literals
 131 ;;;t \index{array}
 132 ;;;t \index{ARRAY}
 133 ;;;t \index{MAKE-ARRAY}
 134 ;;;t \index{AREF}
 135 ;;;t \index{array literal}
 136
 137 ; (ARRAY {values}*)
 138 ; (MAKE-ARRAY {values}*)
 139 ; (AREF array index)
 140 ;
 141 ; values ::= a ParenScript expression
 142 ; array  ::= a ParenScript expression
 143 ; index  ::= a ParenScript expression
 144
 145 ;;; Array literals can be created using the `ARRAY' form.
 146
 147 (array)       => [ ]
 148
 149 (array 1 2 3) => [ 1, 2, 3 ]
 150
 151 (array (array 2 3)
 152        (array "foobar" "bratzel bub"))
 153    => [ [ 2, 3 ], [ "foobar", "bratzel bub" ] ]
 154
 155 ;;; Arrays can also be created with a call to the `Array' function
 156 ;;; using the `MAKE-ARRAY'. The two forms have the exact same semantic
 157 ;;; on the JavaScript side.
 158
 159 (make-array)       => new Array()
 160
 161 (make-array 1 2 3) => new Array(1, 2, 3)
 162
 163 (make-array
 164  (make-array 2 3)
 165  (make-array "foobar" "bratzel bub"))
 166   => new Array(new Array(2, 3), new Array("foobar", "bratzel bub"))
 167
 168 ;;; Indexing arrays in ParenScript is done using the form `AREF'. Note
 169 ;;; that JavaScript knows of no such thing as an array. Subscripting
 170 ;;; an array is in fact reading a property from an object. So in a
 171 ;;; semantic sense, there is no real difference between `AREF' and
 172 ;;; `SLOT-VALUE'.
 173
 174 ;;;## Object literals
 175 ;;;t \index{CREATE}
 176 ;;;t \index{SLOT-VALUE}
 177 ;;;t \index{WITH-SLOTS}
 178 ;;;t \index{object literal}
 179 ;;;t \index{object}
 180 ;;;t \index{object property}
 181 ;;;t \index{property}
 182
 183 ; (CREATE {name value}*)
 184 ; (SLOT-VALUE object slot-name)
 185 ; (WITH-SLOTS ({slot-name}*) object body)
 186 ;
 187 ; name      ::= a ParenScript symbol or a Lisp keyword
 188 ; value     ::= a ParenScript expression
 189 ; object    ::= a ParenScript object expression
 190 ; slot-name ::= a quoted Lisp symbol
 191 ; body      ::= a list of ParenScript statements
 192
 193 ;;;
 194 ;;; Object literals can be create using the `CREATE' form. Arguments
 195 ;;; to the `CREATE' form is a list of property names and values. To be
 196 ;;; more "lispy", the property names can be keywords.
 197
 198 (create :foo "bar" :blorg 1)
 199    => { foo : "bar",
 200         blorg : 1 }
 201
 202 (create :foo "hihi"
 203         :blorg (array 1 2 3)
 204         :another-object (create :schtrunz 1))
 205    => { foo : "hihi",
 206         blorg : [ 1, 2, 3 ],
 207         anotherObject : { schtrunz : 1 } }
 208
 209 ;;; Object properties can be accessed using the `SLOT-VALUE' form,
 210 ;;; which takes an object and a slot-name.
 211
 212 (slot-value an-object 'foo) => anObject.foo
 213
 214 ;;; A programmer can also use the "." symbol notation explained above.
 215
 216 an-object.foo => anObject.foo
 217
 218 ;;; The form `WITH-SLOTS' can be used to bind the given slot-name
 219 ;;; symbols to a macro that will expand into a `SLOT-VALUE' form at
 220 ;;; expansion time.
 221
 222 (with-slots (a b c) this
 223   (+ a b c))
 224     => this.a + this.b + this.c
 225
 226 ;;;## Regular Expression literals
 227 ;;;t \index{REGEX}
 228 ;;;t \index{regular expression}
 229 ;;;t \index{CL-INTERPOL}
 230
 231 ; (REGEX regex)
 232 ;
 233 ; regex ::= a Lisp string
 234
 235 ;;; Regular expressions can be created by using the `REGEX' form. The
 236 ;;; regex form actually does nothing at all to its argument, and
 237 ;;; prints it as is.
 238
 239 (regex "/foobar/i") => /foobar/i
 240
 241 ;;; Here CL-INTERPOL proves really useful.
 242
 243 (regex #?r"/([^\s]+)foobar/i") => /([^\s]+)foobar/i
 244
 245 ;;;## Literal symbols
 246 ;;;t \index{T}
 247 ;;;t \index{FALSE}
 248 ;;;t \index{NIL}
 249 ;;;t \index{UNDEFINED}
 250 ;;;t \index{THIS}
 251 ;;;t \index{literal symbols}
 252 ;;;t \index{null}
 253 ;;;t \index{true}
 254
 255 ; T, FALSE, NIL, UNDEFINED, THIS
 256
 257 ;;; The Lisp symbols `T' and `FALSE' are converted to their JavaScript
 258 ;;; boolean equivalents `true' and `false'.
 259
 260 T     => true
 261 FALSE => false
 262
 263 ;;; The Lisp symbol `NIL' is converted to the JavaScript keyword
 264 ;;; `null'.
 265
 266 NIL => null
 267
 268 ;;; The Lisp symbol `UNDEFINED' is converted to the JavaScript keyword
 269 ;;; `undefined'.
 270
 271 UNDEFINED => undefined
 272
 273 ;;; The Lisp symbol `THIS' is converted to the JavaScript keyword
 274 ;;; `this'.
 275
 276 THIS => this
 277
 278 ;;;# Variables
 279 ;;;t \index{variable}
 280 ;;;t \index{symbol}
 281
 282 ; variable ::= a Lisp symbol
 283
 284 ;;; All the other literal Lisp values that are not recognized as
 285 ;;; special forms or symbol macros are converted to JavaScript
 286 ;;; variables. This extreme freedom is actually quite useful, as it
 287 ;;; allows the ParenScript programmer to be flexible, as flexible as
 288 ;;; JavaScript itself.
 289
 290 variable    => variable
 291
 292 a-variable  => aVariable
 293
 294 *math       => Math
 295
 296 *math.floor => Math.floor
 297
 298 ;;;# Function calls and method calls
 299 ;;;t \index{function}
 300 ;;;t \index{function call}
 301 ;;;t \index{method}
 302 ;;;t \index{method call}
 303
 304 ; (function {argument}*)
 305 ; (method   object {argument}*)
 306 ;
 307 ; function ::= a ParenScript expression or a Lisp symbol
 308 ; method   ::= a Lisp symbol beginning with .
 309 ; object   ::= a ParenScript expression
 310 ; argument ::= a ParenScript expression
 311
 312 ;;; Any list passed to the JavaScript that is not recognized as a
 313 ;;; macro or a special form (see "Macro Expansion" below) is
 314 ;;; interpreted as a function call. The function call is converted to
 315 ;;; the normal JavaScript function call representation, with the
 316 ;;; arguments given in paren after the function name.
 317
 318 (blorg 1 2) => blorg(1, 2)
 319
 320 (foobar (blorg 1 2) (blabla 3 4) (array 2 3 4))
 321    => foobar(blorg(1, 2), blabla(3, 4), [ 2, 3, 4 ])
 322
 323 ((aref foo i) 1 2) => foo[i](1, 2)
 324
 325 ;;; A method call is a function call where the function name is a
 326 ;;; symbol and begins with a "." . In a method call, the name of the
 327 ;;; function is append to its first argument, thus reflecting the
 328 ;;; method call syntax of JavaScript. Please note that most method
 329 ;;; calls can be abbreviated using the "." trick in symbol names (see
 330 ;;; "Symbol Conversion" above).
 331
 332 (.blorg this 1 2) => this.blorg(1, 2)
 333
 334 (this.blorg 1 2) => this.blorg(1, 2)
 335
 336 (.blorg (aref foobar 1) NIL T)
 337    => foobar[1].blorg(null, true)
 338
 339 ;;;# Operator Expressions
 340 ;;;t \index{operator}
 341 ;;;t \index{operator expression}
 342 ;;;t \index{assignment operator}
 343 ;;;t \index{EQL}
 344 ;;;t \index{NOT}
 345 ;;;t \index{AND}
 346 ;;;t \index{OR}
 347
 348 ; (operator {argument}*)
 349 ; (single-operator argument)
 350 ;
 351 ; operator ::= one of *, /, %, +, -, <<, >>, >>>, < >, EQL,
 352 ;              ==, !=, =, ===, !==, &, ^, |, &&, AND, ||, OR.
 353 ; single-operator ::= one of INCF, DECF, ++, --, NOT, !
 354 ; argument ::= a ParenScript expression
 355
 356 ;;; Operator forms are similar to function call forms, but have an
 357 ;;; operator as function name.
 358 ;;;
 359 ;;; Please note that `=' is converted to `==' in JavaScript. The `='
 360 ;;; ParenScript operator is not the assignment operator. Unlike
 361 ;;; JavaScript, ParenScript supports multiple arguments to the
 362 ;;; operators.
 363
 364 (* 1 2)   => 1 * 2
 365
 366 (= 1 2)   => 1 == 2
 367
 368 (eql 1 2) => 1 == 2
 369
 370 ;;; Note that the resulting expression is correctly parenthized,
 371 ;;; according to the JavaScript operator precedence that can be found
 372 ;;; in table form at:
 373
 374     http://www.codehouse.com/javascript/precedence/
 375
 376 (* 1 (+ 2 3 4) 4 (/ 6 7))
 377   => 1 * (2 + 3 + 4) * 4 * (6 / 7)
 378
 379 ;;; The pre/post increment and decrement operators are also
 380 ;;; available. `INCF' and `DECF' are the pre-incrementing and
 381 ;;; pre-decrementing operators, and `++' and `--' are the
 382 ;;; post-decrementing version of the operators. These operators can
 383 ;;; take only one argument.
 384
 385 (++ i)   => i++
 386
 387 (-- i)   => i--
 388
 389 (incf i) => ++i
 390
 391 (decf i) => --i
 392
 393 ;;; The `1+' and `1-' operators are shortforms for adding and
 394 ;;; substracting 1.
 395
 396 (1- i) => i - 1
 397
 398 (1+ i) => i + 1
 399
 400 ;;; The `not' operator actually optimizes the code a bit. If `not' is
 401 ;;; used on another boolean-returning operator, the operator is
 402 ;;; reversed.
 403
 404 (not (< i 2))   => i >= 2
 405
 406 (not (eql i 2)) => i != 2
 407
 408 ;;;# Body forms
 409 ;;;t \index{body form}
 410 ;;;t \index{PROGN}
 411 ;;;t \index{body statement}
 412
 413 ; (PROGN {statement}*) in statement context
 414 ; (PROGN {expression}*) in expression context
 415 ;
 416 ; statement  ::= a ParenScript statement
 417 ; expression ::= a ParenScript expression
 418
 419 ;;; The `PROGN' special form defines a sequence of statements when
 420 ;;; used in a statement context, or sequence of expression when used
 421 ;;; in an expression context. The `PROGN' special form is added
 422 ;;; implicitly around the branches of conditional executions forms,
 423 ;;; function declarations and iteration constructs.
 424
 425 ;;; For example, in a statement context:
 426
 427 (progn (blorg i) (blafoo i))
 428    => blorg(i);
 429       blafoo(i);
 430
 431 ;;; In an expression context:
 432
 433 (+ i (progn (blorg i) (blafoo i)))
 434    => i + (blorg(i), blafoo(i))
 435
 436 ;;; A `PROGN' form doesn't lead to additional indentation or
 437 ;;; additional braces around it's body.
 438
 439 ;;;# Function Definition
 440 ;;;t \index{function}
 441 ;;;t \index{method}
 442 ;;;t \index{function definition}
 443 ;;;t \index{DEFUN}
 444 ;;;t \index{LAMBDA}
 445 ;;;t \index{closure}
 446 ;;;t \index{anonymous function}
 447
 448 ; (DEFUN name ({argument}*) body)
 449 ; (LAMBDA ({argument}*) body)
 450 ;
 451 ; name     ::= a Lisp Symbol
 452 ; argument ::= a Lisp symbol
 453 ; body     ::= a list of ParenScript statements
 454
 455 ;;; As in Lisp, functions are defined using the `DEFUN' form, which
 456 ;;; takes a name, a list of arguments, and a function body. An
 457 ;;; implicit `PROGN' is added around the body statements.
 458
 459 (defun a-function (a b)
 460   (return (+ a b)))
 461   => function aFunction(a, b) {
 462        return a + b;
 463      }
 464
 465 ;;; Anonymous functions can be created using the `LAMBDA' form, which
 466 ;;; is the same as `DEFUN', but without function name. In fact,
 467 ;;; `LAMBDA' creates a `DEFUN' with an empty function name.
 468
 469 (lambda (a b) (return (+ a b)))
 470   => function (a, b) {
 471        return a + b;
 472      }
 473
 474 ;;;# Assignment
 475 ;;;t \index{assignment}
 476 ;;;t \index{SETF}
 477 ;;;t \index{assignment operator}
 478
 479 ; (SETF {lhs rhs}*)
 480 ;
 481 ; lhs ::= a ParenScript left hand side expression
 482 ; rhs ::= a ParenScript expression
 483
 484 ;;; Assignment is done using the `SETF' form, which is transformed
 485 ;;; into a series of assignments using the JavaScript `=' operator.
 486
 487 (setf a 1) => a = 1
 488
 489 (setf a 2 b 3 c 4 x (+ a b c))
 490    => a = 2;
 491       b = 3;
 492       c = 4;
 493       x = a + b + c;
 494
 495 ;;; The `SETF' form can transform assignments of a variable with an
 496 ;;; operator expression using this variable into a more "efficient"
 497 ;;; assignment operator form. For example:
 498
 499 (setf a (1+ a))          => a++
 500
 501 (setf a (* 2 3 4 a 4 a)) => a *= 2 * 3 * 4 * 4 * a
 502
 503 (setf a (- 1 a))         => a = 1 - a
 504
 505 ;;;# Single argument statements
 506 ;;;t \index{single-argument statement}
 507 ;;;t \index{RETURN}
 508 ;;;t \index{THROW}
 509 ;;;t \index{THROW}
 510 ;;;t \index{function}
 511
 512 ; (RETURN {value}?)
 513 ; (THROW  {value}?)
 514 ;
 515 ; value ::= a ParenScript expression
 516
 517 ;;; The single argument statements `return' and `throw' are generated
 518 ;;; by the form `RETURN' and `THROW'. `THROW' has to be used inside a
 519 ;;; `TRY' form. `RETURN' is used to return a value from a function
 520 ;;; call.
 521
 522 (return 1)       => return 1
 523
 524 (throw "foobar") => throw "foobar"
 525
 526 ;;;# Single argument expression
 527 ;;;t \index{single-argument expression}
 528 ;;;t \index{object creation}
 529 ;;;t \index{object deletion}
 530 ;;;t \index{DELETE}
 531 ;;;t \index{VOID}
 532 ;;;t \index{TYPEOF}
 533 ;;;t \index{INSTANCEOF}
 534 ;;;t \index{NEW}
 535 ;;;t \index{new}
 536
 537 ; (DELETE     {value})
 538 ; (VOID       {value})
 539 ; (TYPEOF     {value})
 540 ; (INSTANCEOF {value})
 541 ; (NEW        {value})
 542 ;
 543 ; value ::= a ParenScript expression
 544
 545 ;;; The single argument expressions `delete', `void', `typeof',
 546 ;;; `instanceof' and `new' are generated by the forms `DELETE',
 547 ;;; `VOID', `TYPEOF', `INSTANCEOF' and `NEW'. They all take a
 548 ;;; ParenScript expression.
 549
 550 (delete (new (*foobar 2 3 4))) => delete new Foobar(2, 3, 4)
 551
 552 (if (= (typeof blorg) *string)
 553     (alert (+ "blorg is a string: " blorg))
 554     (alert "blorg is not a string"))
 555   => if (typeof blorg == String) {
 556        alert("blorg is a string: " + blorg);
 557      } else {
 558        alert("blorg is not a string");
 559      }
 560
 561 ;;;# Conditional Statements
 562 ;;;t \index{conditional statements}
 563 ;;;t \index{IF}
 564 ;;;t \index{WHEN}
 565 ;;;t \index{UNLESS}
 566 ;;;t \index{conditionals}
 567
 568 ; (IF conditional then {else})
 569 ; (WHEN condition then)
 570 ; (UNLESS condition then)
 571 ;
 572 ; condition ::= a ParenScript expression
 573 ; then      ::= a ParenScript statement in statement context, a
 574 ;                 ParenScript expression in expression context
 575 ; else      ::= a ParenScript statement in statement context, a
 576 ;                 ParenScript expression in expression context
 577
 578 ;;; The `IF' form compiles to the `if' javascript construct. An
 579 ;;; explicit `PROGN' around the then branch and the else branch is
 580 ;;; needed if they consist of more than one statement. When the `IF'
 581 ;;; form is used in an expression context, a JavaScript `?', `:'
 582 ;;; operator form is generated.
 583
 584 (if (blorg.is-correct)
 585     (progn (carry-on) (return i))
 586     (alert "blorg is not correct!"))
 587    => if (blorg.isCorrect()) {
 588         carryOn();
 589         return i;
 590       } else {
 591         alert("blorg is not correct!");
 592       }
 593
 594 (+ i (if (blorg.add-one) 1 2))
 595    => i + (blorg.addOne() ? 1 : 2)
 596
 597 ;;; The `WHEN' and `UNLESS' forms can be used as shortcuts for the
 598 ;;; `IF' form.
 599
 600 (when (blorg.is-correct)
 601   (carry-on)
 602   (return i))
 603     => if (blorg.isCorrect()) {
 604          carryOn();
 605          return i;
 606        }
 607
 608 (unless (blorg.is-correct)
 609   (alert "blorg is not correct!"))
 610     => if (!blorg.isCorrect()) {
 611          alert("blorg is not correct!");
 612        }
 613
 614 ;;;# Variable declaration
 615 ;;;t \index{variable}
 616 ;;;t \index{variable declaration}
 617 ;;;t \index{binding}
 618 ;;;t \index{scoping}
 619 ;;;t \index{DEFVAR}
 620 ;;;t \index{LET}
 621
 622 ; (DEFVAR var {value}?)
 623 ; (LET ({var | (var value)) body)
 624 ;
 625 ; var   ::= a Lisp symbol
 626 ; value ::= a ParenScript expression
 627 ; body  ::= a list of ParenScript statements
 628
 629 ;;; Variables (either local or global) can be declared using the
 630 ;;; `DEFVAR' form, which is similar to its equivalent form in
 631 ;;; Lisp. The `DEFVAR' is converted to "var ... = ..." form in
 632 ;;; JavaScript.
 633
 634 (defvar *a* (array 1 2 3)) => var A = [ 1, 2, 3 ]
 635
 636 (if (= i 1)
 637     (progn (defvar blorg "hallo")
 638            (alert blorg))
 639     (progn (defvar blorg "blitzel")
 640            (alert blorg)))
 641    => if (i == 1) {
 642         var blorg = "hallo";
 643         alert(blorg);
 644       } else {
 645         var blorg = "blitzel";
 646         alert(blorg);
 647       }
 648
 649 ;;; A more lispy way to declare local variable is to use the `LET'
 650 ;;; form, which is similar to its Lisp form.
 651
 652 (if (= i 1)
 653     (let ((blorg "hallo"))
 654       (alert blorg))
 655     (let ((blorg "blitzel"))
 656       (alert blorg)))
 657    => if (i == 1) {
 658         var blorg = "hallo";
 659         alert(blorg);
 660       } else {
 661         var blorg = "blitzel";
 662         alert(blorg);
 663       }
 664
 665 ;;; However, beware that scoping in Lisp and JavaScript are quite
 666 ;;; different. For example, don't rely on closures capturing local
 667 ;;; variables in the way you'd think they would.
 668
 669 ;;;# Iteration constructs
 670 ;;;t \index{iteration}
 671 ;;;t \index{iteration construct}
 672 ;;;t \index{loop}
 673 ;;;t \index{array traversal}
 674 ;;;t \index{property}
 675 ;;;t \index{object property}
 676 ;;;t \index{DO}
 677 ;;;t \index{DOTIMES}
 678 ;;;t \index{DOLIST}
 679 ;;;t \index{DOEACH}
 680 ;;;t \index{WHILE}
 681
 682 ; (DO ({var | (var {init}? {step}?)}*) (end-test) body)
 683 ; (DOTIMES (var numeric-form) body)
 684 ; (DOLIST (var list-form) body)
 685 ; (DOEACH (var object) body)
 686 ; (WHILE end-test body)
 687 ;
 688 ; var          ::= a Lisp symbol
 689 ; numeric-form ::= a ParenScript expression resulting in a number
 690 ; list-form    ::= a ParenScript expression resulting in an array
 691 ; object       ::= a ParenScript expression resulting in an object
 692 ; init         ::= a ParenScript expression
 693 ; step         ::= a ParenScript expression
 694 ; end-test     ::= a ParenScript expression
 695 ; body         ::= a list of ParenScript statements
 696
 697 ;;; The `DO' form, which is similar to its Lisp form, is transformed
 698 ;;; into a JavaScript `for' statement. Note that the ParenScript `DO'
 699 ;;; form does not have a return value, that is because `for' is a
 700 ;;; statement and not an expression in JavaScript.
 701
 702 (do ((i 0 (1+ i))
 703      (l (aref blorg i) (aref blorg i)))
 704     ((or (= i blorg.length)
 705          (eql l "Fumitastic")))
 706   (document.write (+ "L is " l)))
 707    => for (var i = 0, l = blorg[i];
 708            !(i == blorg.length || l == "Fumitastic");
 709            i = i + 1, l = blorg[i]) {
 710         document.write("L is " + l);
 711       }
 712
 713 ;;; The `DOTIMES' form, which lets a variable iterate from 0 upto an
 714 ;;; end value, is a shortcut for `DO'.
 715
 716 (dotimes (i blorg.length)
 717   (document.write (+ "L is " (aref blorg i))))
 718    => for (var i = 0; i != blorg.length; i = i++) {
 719         document.write("L is " + blorg[i]);
 720       }
 721
 722 ;;; The `DOLIST' form is a shortcut for iterating over an array. Note
 723 ;;; that this form creates temporary variables using a function called
 724 ;;; `JS-GENSYM', which is similar to its Lisp counterpart `GENSYM'.
 725
 726 (dolist (l blorg)
 727   (document.write (+ "L is " l)))
 728    => var tmpArr1 = blorg;
 729       for (var tmpI2 = 0; tmpI2 < tmpArr1.length;
 730            tmpI2 = tmpI2++) {
 731         var l = tmpArr1[tmpI2];
 732         document.write("L is " + l);
 733       }
 734
 735 ;;; The `DOEACH' form is converted to a `for (var .. in ..)' form in
 736 ;;; JavaScript. It is used to iterate over the enumerable properties
 737 ;;; of an object.
 738
 739 (doeach (i object)
 740    (document.write (+ i " is " (aref object i))))
 741    => for (var i in object) {
 742         document.write(i + " is " + object[i]);
 743       }
 744
 745 ;;; The `WHILE' form is transformed to the JavaScript form `while',
 746 ;;; and loops until a termination test evaluates to false.
 747
 748 (while (film.is-not-finished)
 749   (this.eat (new *popcorn)))
 750    => while (film.isNotFinished()) {
 751         this.eat(new Popcorn);
 752       }
 753
 754 ;;;# The `CASE' statement
 755 ;;;t \index{CASE}
 756 ;;;t \index{switch}
 757
 758 ; (CASE case-value clause*)
 759 ;
 760 ; clause     ::= (value body)
 761 ; case-value ::= a ParenScript expression
 762 ; value      ::= a ParenScript expression
 763 ; body       ::= a list of ParenScript statements
 764
 765 ;;; The Lisp `CASE' form is transformed to a `switch' statement in
 766 ;;; JavaScript. Note that `CASE' is not an expression in
 767 ;;; ParenScript. The default case is not named `T' in ParenScript, but
 768 ;;; `DEFAULT' instead.
 769
 770 (case (aref blorg i)
 771   (1 (alert "one"))
 772   (2 (alert "two"))
 773   (default (alert "default clause")))
 774     => switch (blorg[i]) {
 775          case 1:   alert("one");
 776          case 2:   alert("two");
 777          default:   alert("default clause");
 778        }
 779
 780 ;;;# The `WITH' statement
 781 ;;;t \index{WITH}
 782 ;;;t \index{dynamic scope}
 783 ;;;t \index{binding}
 784 ;;;t \index{scoping}
 785 ;;;t \index{closure}
 786
 787 ; (WITH (object) body)
 788 ;
 789 ; object ::= a ParenScript expression evaluating to an object
 790 ; body   ::= a list of ParenScript statements
 791
 792 ;;; The `WITH' form is compiled to a JavaScript `with' statements, and
 793 ;;; adds the object `object' as an intermediary scope objects when
 794 ;;; executing the body.
 795
 796 (with ((create :foo "foo" :i "i"))
 797   (alert (+ "i is now intermediary scoped: " i)))
 798    => with ({ foo : "foo",
 799               i : "i" }) {
 800         alert("i is now intermediary scoped: " + i);
 801       }
 802
 803 ;;;# The `TRY' statement
 804 ;;;t \index{TRY}
 805 ;;;t \index{CATCH}
 806 ;;;t \index{FINALLY}
 807 ;;;t \index{exception}
 808 ;;;t \index{error handling}
 809
 810 ; (TRY body {(:CATCH (var) body)}? {(:FINALLY body)}?)
 811 ;
 812 ; body ::= a list of ParenScript statements
 813 ; var  ::= a Lisp symbol
 814
 815 ;;; The `TRY' form is converted to a JavaScript `try' statement, and
 816 ;;; can be used to catch expressions thrown by the `THROW'
 817 ;;; form. The body of the catch clause is invoked when an exception
 818 ;;; is catched, and the body of the finally is always invoked when
 819 ;;; leaving the body of the `TRY' form.
 820
 821 (try (throw "i")
 822  (:catch (error)
 823    (alert (+ "an error happened: " error)))
 824  (:finally
 825    (alert "Leaving the try form")))
 826    => try {
 827         throw "i";
 828       } catch (error) {
 829         alert("an error happened: " + error);
 830       } finally {
 831         alert("Leaving the try form");
 832       }
 833
 834 ;;;# The HTML Generator
 835 ;;;t \index{HTML}
 836 ;;;t \index{HTML generation}
 837
 838 ; (HTML html-expression)
 839
 840 ;;; The HTML generator of ParenScript is very similar to the HTML
 841 ;;; generator included in AllegroServe. It accepts the same input
 842 ;;; forms as the AllegroServer HTML generator. However, non-HTML
 843 ;;; construct are compiled to JavaScript by the ParenScript
 844 ;;; compiler. The resulting expression is a JavaScript expression.
 845
 846 (html ((:a :href "foobar") "blorg"))
 847   => "<a href=\"foobar\">blorg</a>"
 848
 849 (html ((:a :href (generate-a-link)) "blorg"))
 850   => "<a href=\"" + generateALink() + "\">blorg</a>"
 851
 852 ;;; We can recursively call the JS compiler in a HTML expression.
 853
 854 (document.write
 855  (html ((:a :href "#"
 856             :onclick (js-inline (transport))) "link")))
 857   => document.write("<a href=\"#\" onclick=\""
 858                     + "javascript:transport();"
 859                     + "\">link</a>")
 860
 861 ;;;# Macrology
 862 ;;;t \index{macro}
 863 ;;;t \index{macrology}
 864 ;;;t \index{DEFJSMACRO}
 865 ;;;t \index{MACROLET}
 866 ;;;t \index{SYMBOL-MACROLET}
 867 ;;;t \index{JS-GENSYM}
 868 ;;;t \index{compiler}
 869
 870 ; (DEFJSMACRO name lambda-list macro-body)
 871 ; (MACROLET ({name lambda-list macro-body}*) body)
 872 ; (SYMBOL-MACROLET ({name macro-body}*) body)
 873 ; (JS-GENSYM {string}?)
 874 ;
 875 ; name        ::= a Lisp symbol
 876 ; lambda-list ::= a lambda list
 877 ; macro-body  ::= a Lisp body evaluating to ParenScript code
 878 ; body        ::= a list of ParenScript statements
 879 ; string      ::= a string
 880
 881 ;;; ParenScript can be extended using macros, just like Lisp can be
 882 ;;; extended using Lisp macros. Using the special Lisp form
 883 ;;; `DEFJSMACRO', the ParenScript language can be
 884 ;;; extended. `DEFJSMACRO' adds the new macro to the toplevel macro
 885 ;;; environment, which is always accessible during ParenScript
 886 ;;; compilation. For example, the `1+' and `1-' operators are
 887 ;;; implemented using macros.
 888
 889 (defjsmacro 1- (form)
 890   `(- ,form 1))
 891
 892 (defjsmacro 1+ (form)
 893   `(+ ,form 1))
 894
 895 ;;; A more complicated ParenScript macro example is the implementation
 896 ;;; of the `DOLIST' form (note how `JS-GENSYM', the ParenScript of
 897 ;;; `GENSYM', is used to generate new ParenScript variable names):
 898
 899 (defjsmacro dolist (i-array &rest body)
 900   (let ((var (first i-array))
 901         (array (second i-array))
 902         (arrvar (js-gensym "arr"))
 903         (idx (js-gensym "i")))
 904     `(let ((,arrvar ,array))
 905       (do ((,idx 0 (++ ,idx)))
 906           ((>= ,idx (slot-value ,arrvar 'length)))
 907         (let ((,var (aref ,arrvar ,idx)))
 908           ,@body)))))
 909
 910 ;;; Macros can be added dynamically to the macro environment by using
 911 ;;; the ParenScript `MACROLET' form (note that while `DEFJSMACRO' is a
 912 ;;; Lisp form, `MACROLET' and `SYMBOL-MACROLET' are ParenScript forms).
 913
 914 ;;; ParenScript also supports symbol macros, which can be introduced
 915 ;;; using the ParenScript form `SYMBOL-MACROLET'. A new macro
 916 ;;; environment is created and added to the current macro environment
 917 ;;; list while compiling the body of the `SYMBOL-MACROLET' form. For
 918 ;;; example, the ParenScript `WITH-SLOTS' is implemented using symbol
 919 ;;; macros.
 920
 921 (defjsmacro with-slots (slots object &rest body)
 922   `(symbol-macrolet ,(mapcar #'(lambda (slot)
 923                                  `(,slot '(slot-value ,object ',slot)))
 924                              slots)
 925     ,@body))
 926
 927 ;;;# The ParenScript Compiler
 928 ;;;t \index{compiler}
 929 ;;;t \index{ParenScript compiler}
 930 ;;;t \index{JS-COMPILE}
 931 ;;;t \index{JS-TO-STRINGS}
 932 ;;;t \index{JS-TO-STATEMENT-STRINGS}
 933 ;;;t \index{JS-TO-STRING}
 934 ;;;t \index{JS-TO-LINE}
 935 ;;;t \index{JS}
 936 ;;;t \index{JS-INLINE}
 937 ;;;t \index{JS-FILE}
 938 ;;;t \index{JS-SCRIPT}
 939 ;;;t \index{nested compilation}
 940
 941 ; (JS-COMPILE expr)
 942 ; (JS-TO-STRINGS compiled-expr position)
 943 ; (JS-TO-STATEMENT-STRINGS compiled-expr position)
 944 ;
 945 ; compiled-expr ::= a compiled ParenScript expression
 946 ; position      ::= a column number
 947 ;
 948 ; (JS-TO-STRING expression)
 949 ; (JS-TO-LINE expression)
 950 ;
 951 ; expression ::= a Lisp list of ParenScript code
 952 ;
 953 ; (JS body)
 954 ; (JS-INLINE body)
 955 ; (JS-FILE body)
 956 ; (JS-SCRIPT body)
 957 ;
 958 ; body ::= a list of ParenScript statements
 959
 960 ;;; The ParenScript compiler can be invoked from withing Lisp and from
 961 ;;; within ParenScript itself. The primary API function is
 962 ;;; `JS-COMPILE', which takes a list of ParenScript, and returns an
 963 ;;; internal object representing the compiled ParenScript.
 964
 965 (js-compile '(foobar 1 2))
 966   => #<JS::FUNCTION-CALL {584AA5DD}>
 967
 968 ;;; This internal object can be transformed to a string using the
 969 ;;; methods `JS-TO-STRINGS' and `JS-TO-STATEMENT-STRINGS', which
 970 ;;; interpret the ParenScript in expression and in statement context
 971 ;;; respectively. They take an additional parameter indicating the
 972 ;;; start-position on a line (please note that the indentation code is
 973 ;;; not perfect, and this string interface will likely be
 974 ;;; changed). They return a list of strings, where each string
 975 ;;; represents a new line of JavaScript code. They can be joined
 976 ;;; together to form a single string.
 977
 978 (js-to-strings (js-compile '(foobar 1 2)) 0)
 979   => ("foobar(1, 2)")
 980
 981 ;;; As a shortcut, ParenScript provides the functions `JS-TO-STRING'
 982 ;;; and `JS-TO-LINE', which return the JavaScript string of the
 983 ;;; compiled expression passed as an argument.
 984
 985 (js-to-string '(foobar 1 2))
 986   => "foobar(1, 2)"
 987
 988 ;;; For static ParenScript code, the macros `JS', `JS-INLINE',
 989 ;;; `JS-FILE' and `JS-SCRIPT' avoid the need to quote the ParenScript
 990 ;;; expression. All these forms add an implicit `PROGN' form around
 991 ;;; the body. `JS' returns a string of the compiled body, where the
 992 ;;; other expression return an expression that can be embedded in a
 993 ;;; HTML generation construct using the AllegroServe HTML
 994 ;;; generator. `JS-SCRIPT' generates a "SCRIPT" node, `JS-INLINE'
 995 ;;; generates a string to be used in node attributs, and `JS-FILE'
 996 ;;; prints the compiled ParenScript code to the HTML stream.
 997
 998 ;;; These macros are also available inside ParenScript itself, and
 999 ;;; generate strings that can be used inside ParenScript code. Note
1000 ;;; that `JS-INLINE' in ParenScript is not the same `JS-INLINE' form
1001 ;;; as in Lisp, for example. The same goes for the other compilation
1002 ;;; macros.
1003