1 ;;;# ParenScript Language Reference
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.
9 ;;;# Statements and Expressions
10 ;;;t \index{statement}
11 ;;;t \index{expression}
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:
24 (+ i
(if 1 2 3)) => i
+ (1 ?
2 : 3)
33 ;;;# Symbol conversion
35 ;;;t \index{symbol conversion}
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.
43 !?
#$
@%
=> bangwhathashdollaratpercent
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.
49 bla-foo-bar
=> blaFooBar
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 `*'.
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
61 (slot-value foobar
'slot
)
67 ;;; A symbol beggining and ending with `+' or `*' is converted to all
68 ;;; uppercase, to signify that this is a constant or a global
71 *global-array
* => GLOBALARRAY
73 *global-array
*.length
=> GLOBALARRAY.length
75 ;;;## Reserved Keywords
77 ;;;t \index{reserved keywords}
79 ;;; The following keywords and symbols are reserved in ParenScript,
80 ;;; and should not be used as variable names.
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
95 ;;;t \index{literal value}
99 ;;;t \index{number literal}
101 ; number ::= a Lisp number
104 ;;; ParenScript supports the standard JavaScript literal
105 ;;; values. Numbers are compiled into JavaScript numbers.
111 ;;; Note that the base is not conserved between Lisp and JavaScript.
115 ;;;## String literals
117 ;;;t \index{string literal}
119 ; string ::= a Lisp string
121 ;;; Lisp strings are converted into JavaScript literals.
124 "bratzel bub" => "bratzel bub"
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.
133 ;;;t \index{MAKE-ARRAY}
135 ;;;t \index{array literal}
138 ; (MAKE-ARRAY {values}*)
141 ; values ::= a ParenScript expression
142 ; array ::= a ParenScript expression
143 ; index ::= a ParenScript expression
145 ;;; Array literals can be created using the `ARRAY' form.
149 (array 1 2 3) => [ 1, 2, 3 ]
152 (array "foobar" "bratzel bub"))
153 => [ [ 2, 3 ], [ "foobar", "bratzel bub" ] ]
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.
159 (make-array) => new Array
()
161 (make-array 1 2 3) => new Array
(1, 2, 3)
165 (make-array "foobar" "bratzel bub"))
166 => new Array
(new Array
(2, 3), new Array
("foobar", "bratzel bub"))
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
174 ;;;## Object literals
176 ;;;t \index{SLOT-VALUE}
177 ;;;t \index{WITH-SLOTS}
178 ;;;t \index{object literal}
180 ;;;t \index{object property}
181 ;;;t \index{property}
183 ; (CREATE {name value}*)
184 ; (SLOT-VALUE object slot-name)
185 ; (WITH-SLOTS ({slot-name}*) object body)
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
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.
198 (create :foo
"bar" :blorg
1)
204 :another-object
(create :schtrunz
1))
207 anotherObject
: { schtrunz
: 1 } }
209 ;;; Object properties can be accessed using the `SLOT-VALUE' form,
210 ;;; which takes an object and a slot-name.
212 (slot-value an-object
'foo
) => anObject.foo
214 ;;; A programmer can also use the "." symbol notation explained above.
216 an-object.foo
=> anObject.foo
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
222 (with-slots (a b c
) this
224 => this.a
+ this.b
+ this.c
226 ;;;## Regular Expression literals
228 ;;;t \index{regular expression}
229 ;;;t \index{CL-INTERPOL}
233 ; regex ::= a Lisp string
235 ;;; Regular expressions can be created by using the `REGEX' form. The
236 ;;; regex form actually does nothing at all to its argument, and
239 (regex "/foobar/i") => /foobar
/i
241 ;;; Here CL-INTERPOL proves really useful.
243 (regex #?r
"/([^\s]+)foobar/i") => /([^\s
]+)foobar
/i
245 ;;;## Literal symbols
249 ;;;t \index{UNDEFINED}
251 ;;;t \index{literal symbols}
255 ; T, FALSE, NIL, UNDEFINED, THIS
257 ;;; The Lisp symbols `T' and `FALSE' are converted to their JavaScript
258 ;;; boolean equivalents `true' and `false'.
263 ;;; The Lisp symbol `NIL' is converted to the JavaScript keyword
268 ;;; The Lisp symbol `UNDEFINED' is converted to the JavaScript keyword
271 UNDEFINED
=> undefined
273 ;;; The Lisp symbol `THIS' is converted to the JavaScript keyword
279 ;;;t \index{variable}
282 ; variable ::= a Lisp symbol
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.
292 a-variable
=> aVariable
296 *math.floor
=> Math.floor
298 ;;;# Function calls and method calls
299 ;;;t \index{function}
300 ;;;t \index{function call}
302 ;;;t \index{method call}
304 ; (function {argument}*)
305 ; (method object {argument}*)
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
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.
318 (blorg 1 2) => blorg
(1, 2)
320 (foobar (blorg 1 2) (blabla 3 4) (array 2 3 4))
321 => foobar
(blorg(1, 2), blabla
(3, 4), [ 2, 3, 4 ])
323 ((aref foo i
) 1 2) => foo
[i](1, 2)
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).
332 (.blorg this 1 2) => this.blorg(1, 2)
334 (this.blorg 1 2) => this.blorg(1, 2)
336 (.blorg (aref foobar 1) NIL T)
337 => foobar[1].blorg(null, true)
339 ;;;# Operator Expressions
340 ;;;t \index{operator}
341 ;;;t \index{operator expression}
342 ;;;t \index{assignment operator}
348 ; (operator {argument}*)
349 ; (single-operator argument)
351 ; operator ::= one of *, /, %, +, -, <<, >>, >>>, < >, EQL,
352 ; ==, !=, =, ===, !==, &, ^, |, &&, AND, ||, OR.
353 ; single-operator ::= one of INCF, DECF, ++, --, NOT, !
354 ; argument ::= a ParenScript expression
356 ;;; Operator forms are similar to function call forms, but have an
357 ;;; operator as function name.
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
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:
374 http://www.codehouse.com/javascript/precedence/
376 (* 1 (+ 2 3 4) 4 (/ 6 7))
377 => 1 * (2 + 3 + 4) * 4 * (6 / 7)
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.
393 ;;; The `1+' and `1-' operators are shortforms for adding and
400 ;;; The `not' operator actually optimizes the code a bit. If `not' is
401 ;;; used on another boolean-returning operator, the operator is
404 (not (< i 2)) => i >= 2
406 (not (eql i 2)) => i != 2
409 ;;;t \index{body form}
411 ;;;t \index{body statement}
413 ; (PROGN {statement}*) in statement context
414 ; (PROGN {expression}*) in expression context
416 ; statement ::= a ParenScript statement
417 ; expression ::= a ParenScript expression
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.
425 ;;; For example, in a statement context:
427 (progn (blorg i) (blafoo i))
431 ;;; In an expression context:
433 (+ i (progn (blorg i) (blafoo i)))
434 => i + (blorg(i), blafoo(i))
436 ;;; A `PROGN' form doesn't lead to additional indentation or
437 ;;; additional braces around it's body.
439 ;;;# Function Definition
440 ;;;t \index{function}
442 ;;;t \index{function definition}
446 ;;;t \index{anonymous function}
448 ; (DEFUN name ({argument}*) body)
449 ; (LAMBDA ({argument}*) body)
451 ; name ::= a Lisp Symbol
452 ; argument ::= a Lisp symbol
453 ; body ::= a list of ParenScript statements
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.
459 (defun a-function (a b)
461 => function aFunction(a, b) {
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.
469 (lambda (a b) (return (+ a b)))
475 ;;;t \index{assignment}
477 ;;;t \index{assignment operator}
481 ; lhs ::= a ParenScript left hand side expression
482 ; rhs ::= a ParenScript expression
484 ;;; Assignment is done using the `SETF' form, which is transformed
485 ;;; into a series of assignments using the JavaScript `=' operator.
489 (setf a 2 b 3 c 4 x (+ a b c))
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:
499 (setf a (1+ a)) => a++
501 (setf a (* 2 3 4 a 4 a)) => a *= 2 * 3 * 4 * 4 * a
503 (setf a (- 1 a)) => a = 1 - a
505 ;;;# Single argument statements
506 ;;;t \index{single-argument statement}
510 ;;;t \index{function}
515 ; value ::= a ParenScript expression
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
522 (return 1) => return 1
524 (throw "foobar") => throw "foobar"
526 ;;;# Single argument expression
527 ;;;t \index{single-argument expression}
528 ;;;t \index{object creation}
529 ;;;t \index{object deletion}
533 ;;;t \index{INSTANCEOF}
540 ; (INSTANCEOF {value})
543 ; value ::= a ParenScript expression
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.
550 (delete (new (*foobar 2 3 4))) => delete new Foobar(2, 3, 4)
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);
558 alert("blorg is not a string");
561 ;;;# Conditional Statements
562 ;;;t \index{conditional statements}
566 ;;;t \index{conditionals}
568 ; (IF conditional then {else})
569 ; (WHEN condition then)
570 ; (UNLESS condition then)
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
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.
584 (if (blorg.is-correct)
585 (progn (carry-on) (return i))
586 (alert "blorg is not correct!"))
587 => if (blorg.isCorrect()) {
591 alert("blorg is not correct!");
594 (+ i (if (blorg.add-one) 1 2))
595 => i + (blorg.addOne() ? 1 : 2)
597 ;;; The `WHEN' and `UNLESS' forms can be used as shortcuts for the
600 (when (blorg.is-correct)
603 => if (blorg.isCorrect()) {
608 (unless (blorg.is-correct)
609 (alert "blorg is not correct!"))
610 => if (!blorg.isCorrect()) {
611 alert("blorg is not correct!");
614 ;;;# Variable declaration
615 ;;;t \index{variable}
616 ;;;t \index{variable declaration}
622 ; (DEFVAR var {value}?)
623 ; (LET ({var | (var value)) body)
625 ; var ::= a Lisp symbol
626 ; value ::= a ParenScript expression
627 ; body ::= a list of ParenScript statements
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
634 (defvar *a* (array 1 2 3)) => var A = [ 1, 2, 3 ]
637 (progn (defvar blorg "hallo")
639 (progn (defvar blorg "blitzel")
645 var blorg = "blitzel";
649 ;;; A more lispy way to declare local variable is to use the `LET'
650 ;;; form, which is similar to its Lisp form.
653 (let ((blorg "hallo"))
655 (let ((blorg "blitzel"))
661 var blorg = "blitzel";
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.
669 ;;;# Iteration constructs
670 ;;;t \index{iteration}
671 ;;;t \index{iteration construct}
673 ;;;t \index{array traversal}
674 ;;;t \index{property}
675 ;;;t \index{object property}
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)
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
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.
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);
713 ;;; The `DOTIMES' form, which lets a variable iterate from 0 upto an
714 ;;; end value, is a shortcut for `DO'.
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]);
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'.
727 (document.write
(+ "L is " l
)))
728 => var tmpArr1
= blorg
;
729 for
(var tmpI2
= 0; tmpI2 < tmpArr1.length;
731 var l
= tmpArr1
[tmpI2];
732 document.write("L is " + l);
735 ;;; The `DOEACH' form is converted to a `for (var .. in ..)' form in
736 ;;; JavaScript. It is used to iterate over the enumerable properties
740 (document.write (+ i " is " (aref object i))))
741 => for (var i in object) {
742 document.write(i + " is " + object[i]);
745 ;;; The `WHILE' form is transformed to the JavaScript form `while',
746 ;;; and loops until a termination test evaluates to false.
748 (while (film.is-not-finished)
749 (this.eat (new *popcorn)))
750 => while (film.isNotFinished()) {
751 this.eat(new Popcorn);
754 ;;;# The `CASE' statement
758 ; (CASE case-value clause*)
760 ; clause ::= (value body)
761 ; case-value ::= a ParenScript expression
762 ; value ::= a ParenScript expression
763 ; body ::= a list of ParenScript statements
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.
773 (default (alert "default clause")))
774 => switch (blorg[i]) {
775 case 1: alert("one");
776 case 2: alert("two");
777 default: alert("default clause");
780 ;;;# The `WITH' statement
782 ;;;t \index{dynamic scope}
787 ; (WITH (object) body)
789 ; object ::= a ParenScript expression evaluating to an object
790 ; body ::= a list of ParenScript statements
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.
796 (with ((create :foo "foo" :i "i"))
797 (alert (+ "i is now intermediary scoped: " i)))
798 => with ({ foo : "foo",
800 alert("i is now intermediary scoped: " + i);
803 ;;;# The `TRY' statement
807 ;;;t \index{exception}
808 ;;;t \index{error handling}
810 ; (TRY body {(:CATCH (var) body)}? {(:FINALLY body)}?)
812 ; body ::= a list of ParenScript statements
813 ; var ::= a Lisp symbol
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.
823 (alert (+ "an error happened: " error)))
825 (alert "Leaving the try form")))
829 alert("an error happened: " + error);
831 alert("Leaving the try form");
834 ;;;# The HTML Generator
836 ;;;t \index{HTML generation}
838 ; (HTML html-expression)
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.
846 (html ((:a :href "foobar") "blorg"))
847 => "<a href=\"foobar\">blorg</a>"
849 (html ((:a :href (generate-a-link)) "blorg"))
850 => "<a href=\"" + generateALink() + "\">blorg</a>"
852 ;;; We can recursively call the JS compiler in a HTML expression.
856 :onclick (js-inline (transport))) "link")))
857 => document.write("<a href=\"#\" onclick=\""
858 + "javascript:transport();"
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}
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}?)
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
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.
889 (defjsmacro 1- (form)
892 (defjsmacro 1+ (form)
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):
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)))
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).
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
921 (defjsmacro with-slots (slots object &rest body)
922 `(symbol-macrolet ,(mapcar #'(lambda (slot)
923 `(,slot '(slot-value ,object ',slot)))
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}
936 ;;;t \index{JS-INLINE}
938 ;;;t \index{JS-SCRIPT}
939 ;;;t \index{nested compilation}
942 ; (JS-TO-STRINGS compiled-expr position)
943 ; (JS-TO-STATEMENT-STRINGS compiled-expr position)
945 ; compiled-expr ::= a compiled ParenScript expression
946 ; position ::= a column number
948 ; (JS-TO-STRING expression)
949 ; (JS-TO-LINE expression)
951 ; expression ::= a Lisp list of ParenScript code
958 ; body ::= a list of ParenScript statements
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.
965 (js-compile '(foobar 1 2))
966 => #<JS::FUNCTION-CALL {584AA5DD}>
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.
978 (js-to-strings (js-compile '(foobar 1 2)) 0)
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.
985 (js-to-string '(foobar 1 2))
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.
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