1 ;;;# Parenscript Language Reference
3 ;;; Create a useful package for the code here...
5 (defpackage #:ps-ref
(:use
#:ps
))
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.
14 ;;;# Statements and Expressions
15 ;;;t \index{statement}
16 ;;;t \index{expression}
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:
29 (+ i
(if 1 2 3)) => i
+ (1 ?
2 : 3)
38 ;;;# Symbol conversion
40 ;;;t \index{symbol conversion}
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.
48 !?
#@%
=> bangwhathashatpercent
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.
54 bla-foo-bar
=> blaFooBar
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 `*'.
62 ;;; The `.' character is left as is in symbols. This allows the
63 ;;; Parenscript programmer to use a practical shortcut when accessing
64 ;;; slots or methods of JavaScript objects. Instead of writing
66 (slot-value foobar
'slot
)
72 ;;; A symbol beggining and ending with `+' or `*' is converted to all
73 ;;; uppercase, to signify that this is a constant or a global
76 *global-array
* => GLOBALARRAY
78 *global-array
*.length
=> GLOBALARRAY.length
80 ;;;## Reserved Keywords
82 ;;;t \index{reserved keywords}
84 ;;; The following keywords and symbols are reserved in Parenscript,
85 ;;; and should not be used as variable names.
87 ! ~
++ --
* / %
+ -
<< >> >>> < > <= >= == != ==== !== & ^ |
&& ||
*=
88 /= %
= += -
= <<= >>= >>>= &= ^
= |
= 1-
1+ ABSTRACT AND AREF ARRAY
89 BOOLEAN BREAK BYTE CASE CATCH CC-IF CHAR CLASS COMMA CONST CONTINUE
90 CREATE DEBUGGER DECF DEFAULT DEFUN DEFVAR DELETE DO DO
* DOEACH DOLIST
91 DOTIMES DOUBLE ELSE ENUM EQL EXPORT EXTENDS F FALSE FINAL FINALLY
92 FLOAT FLOOR FOR FOR-IN FUNCTION GOTO IF IMPLEMENTS IMPORT IN INCF
93 INSTANCEOF INT INTERFACE JS LABELED-FOR LAMBDA LET LET
* LEXICAL-LET
94 LEXICAL-LET
* LISP LIST LONG MAKE-ARRAY NATIVE NEW NIL NOT OR PACKAGE
95 PRIVATE PROGN PROTECTED PUBLIC RANDOM REGEX RETURN SETF SHORT
96 SLOT-VALUE STATIC SUPER SWITCH SYMBOL-MACROLET SYNCHRONIZED T THIS
97 THROW THROWS TRANSIENT TRY TYPEOF UNDEFINED UNLESS VAR VOID VOLATILE
98 WHEN WHILE WITH WITH-SLOTS
101 ;;;t \index{literal value}
103 ;;;## Number literals
105 ;;;t \index{number literal}
107 ; number ::= a Lisp number
110 ;;; Parenscript supports the standard JavaScript literal
111 ;;; values. Numbers are compiled into JavaScript numbers.
117 ;;; Note that the base is not conserved between Lisp and JavaScript.
121 ;;;## String literals
123 ;;;t \index{string literal}
125 ; string ::= a Lisp string
127 ;;; Lisp strings are converted into JavaScript literals.
131 "bratzel bub" => 'bratzel bub
'
133 ;;; Special characters such as newline and backspace are converted
134 ;;; into their corresponding JavaScript escape sequences.
141 ;;;t \index{MAKE-ARRAY}
143 ;;;t \index{array literal}
146 ; (MAKE-ARRAY {values}*)
149 ; values ::= a Parenscript expression
150 ; array ::= a Parenscript expression
151 ; index ::= a Parenscript expression
153 ;;; Array literals can be created using the `ARRAY' form.
157 (array 1 2 3) => [ 1, 2, 3 ]
160 (array "foobar" "bratzel bub"))
161 => [ [ 2, 3 ], [ 'foobar
', 'bratzel bub
' ] ]
163 ;;; Arrays can also be created with a call to the `Array' function
164 ;;; using the `MAKE-ARRAY'. The two forms have the exact same semantic
165 ;;; on the JavaScript side.
167 (make-array) => new Array
()
169 (make-array 1 2 3) => new Array
(1, 2, 3)
173 (make-array "foobar" "bratzel bub"))
174 => new Array
(new Array
(2, 3), new Array
('foobar
', 'bratzel bub
'))
176 ;;; Indexing arrays in Parenscript is done using the form `AREF'. Note
177 ;;; that JavaScript knows of no such thing as an array. Subscripting
178 ;;; an array is in fact reading a property from an object. So in a
179 ;;; semantic sense, there is no real difference between `AREF' and
182 ;;;## Object literals
184 ;;;t \index{SLOT-VALUE}
185 ;;;t \index{WITH-SLOTS}
186 ;;;t \index{object literal}
188 ;;;t \index{object property}
189 ;;;t \index{property}
191 ; (CREATE {name value}*)
192 ; (SLOT-VALUE object slot-name)
193 ; (WITH-SLOTS ({slot-name}*) object body)
195 ; name ::= a Parenscript symbol or a Lisp keyword
196 ; value ::= a Parenscript expression
197 ; object ::= a Parenscript object expression
198 ; slot-name ::= a quoted Lisp symbol
199 ; body ::= a list of Parenscript statements
202 ;;; Object literals can be create using the `CREATE' form. Arguments
203 ;;; to the `CREATE' form is a list of property names and values. To be
204 ;;; more "lispy", the property names can be keywords.
206 (create :foo
"bar" :blorg
1)
207 => { foo
: 'bar
', blorg
: 1 }
211 :another-object
(create :schtrunz
1))
214 anotherObject
: { schtrunz
: 1 } }
216 ;;; Object properties can be accessed using the `SLOT-VALUE' form,
217 ;;; which takes an object and a slot-name.
219 (slot-value an-object
'foo
) => anObject.foo
221 ;;; A programmer can also use the "." symbol notation explained above.
223 an-object.foo
=> anObject.foo
225 ;;; The form `WITH-SLOTS' can be used to bind the given slot-name
226 ;;; symbols to a macro that will expand into a `SLOT-VALUE' form at
229 (with-slots (a b c
) this
231 => this.a
+ this.b
+ this.c
;
233 ;;;## Regular Expression literals
235 ;;;t \index{regular expression}
236 ;;;t \index{CL-INTERPOL}
240 ; regex ::= a Lisp string
242 ;;; Regular expressions can be created by using the `REGEX' form. If
243 ;;; the argument does not start with a slash, it is surrounded by
244 ;;; slashes to make it a proper JavaScript regex. If the argument
245 ;;; starts with a slash it is left as it is. This makes it possible
246 ;;; to use modifiers such as slash-i (case-insensitive) or
247 ;;; slash-g (match-globally (all)).
249 (regex "foobar") => /foobar
/
251 (regex "/foobar/i") => /foobar
/i
253 ;;; Here CL-INTERPOL proves really useful.
255 (regex #?r
"/([^\s]+)foobar/i") => /([^\s
]+)foobar
/i
257 ;;;## Literal symbols
262 ;;;t \index{UNDEFINED}
264 ;;;t \index{literal symbols}
268 ; T, F, FALSE, NIL, UNDEFINED, THIS
270 ;;; The Lisp symbols `T' and `FALSE' (or `F') are converted to their
271 ;;; JavaScript boolean equivalents `true' and `false'.
279 ;;; The Lisp symbol `NIL' is converted to the JavaScript keyword
284 ;;; The Lisp symbol `UNDEFINED' is converted to the JavaScript keyword
287 UNDEFINED
=> undefined
289 ;;; The Lisp symbol `THIS' is converted to the JavaScript keyword
295 ;;;t \index{variable}
298 ; variable ::= a Lisp symbol
300 ;;; All the other literal Lisp values that are not recognized as
301 ;;; special forms or symbol macros are converted to JavaScript
302 ;;; variables. This extreme freedom is actually quite useful, as it
303 ;;; allows the Parenscript programmer to be flexible, as flexible as
304 ;;; JavaScript itself.
308 a-variable
=> aVariable
312 *math.floor
=> Math.floor
314 ;;;# Function calls and method calls
315 ;;;t \index{function}
316 ;;;t \index{function call}
318 ;;;t \index{method call}
320 ; (function {argument}*)
323 ; function ::= a Parenscript expression or a Lisp symbol
324 ; object ::= a Parenscript expression
325 ; argument ::= a Parenscript expression
327 ;;; Any list passed to the JavaScript that is not recognized as a
328 ;;; macro or a special form (see "Macro Expansion" below) is
329 ;;; interpreted as a function call. The function call is converted to
330 ;;; the normal JavaScript function call representation, with the
331 ;;; arguments given in paren after the function name.
333 (blorg 1 2) => blorg
(1, 2)
335 (foobar (blorg 1 2) (blabla 3 4) (array 2 3 4))
336 => foobar
(blorg(1, 2), blabla
(3, 4), [ 2, 3, 4 ])
338 ((slot-value this
'blorg
) 1 2) => this.blorg
(1, 2)
340 ((aref foo i
) 1 2) => foo
[i](1, 2)
342 ((slot-value (aref foobar 1) 'blorg) NIL T) => foobar[1].blorg(null, true)
344 ;;; Note that while most method calls can be abbreviated using the "."
345 ;;; trick in symbol names (see "Symbol Conversion" above), this is not
346 ;;; advised due to the fact that "object.function" is treated as a
347 ;;; symbol distinct from both "object" and "function," which will
348 ;;; cause problems if Parenscript package prefixes or package
349 ;;; obfuscation is used.
351 (this.blorg 1 2) => this.blorg(1, 2)
353 ;;;# Operator Expressions
354 ;;;t \index{operator}
355 ;;;t \index{operator expression}
356 ;;;t \index{assignment operator}
362 ; (operator {argument}*)
363 ; (single-operator argument)
365 ; operator ::= one of *, /, %, +, -, <<, >>, >>>, < >, EQL,
366 ; ==, !=, =, ===, !==, &, ^, |, &&, AND, ||, OR.
367 ; single-operator ::= one of INCF, DECF, ++, --, NOT, !
368 ; argument ::= a Parenscript expression
370 ;;; Operator forms are similar to function call forms, but have an
371 ;;; operator as function name.
373 ;;; Please note that `=' is converted to `==' in JavaScript. The `='
374 ;;; Parenscript operator is not the assignment operator. Unlike
375 ;;; JavaScript, Parenscript supports multiple arguments to the
384 ;;; Note that the resulting expression is correctly parenthesized,
385 ;;; according to the JavaScript operator precedence that can be found
386 ;;; in table form at:
388 ;;; http://www.codehouse.com/javascript/precedence/
390 (* 1 (+ 2 3 4) 4 (/ 6 7))
391 => 1 * (2 + 3 + 4) * 4 * (6 / 7)
393 ;;; The pre increment and decrement operators are also
394 ;;; available. `INCF' and `DECF' are the pre-incrementing and
395 ;;; pre-decrementing operators. These operators can
396 ;;; take only one argument.
402 ;;; The `1+' and `1-' operators are shortforms for adding and
409 ;;; The `not' operator actually optimizes the code a bit. If `not' is
410 ;;; used on another boolean-returning operator, the operator is
413 (not (< i 2)) => i >= 2
415 (not (eql i 2)) => i != 2
418 ;;;t \index{body form}
420 ;;;t \index{body statement}
422 ; (PROGN {statement}*) in statement context
423 ; (PROGN {expression}*) in expression context
425 ; statement ::= a Parenscript statement
426 ; expression ::= a Parenscript expression
428 ;;; The `PROGN' special form defines a sequence of statements when
429 ;;; used in a statement context, or sequence of expression when used
430 ;;; in an expression context. The `PROGN' special form is added
431 ;;; implicitly around the branches of conditional executions forms,
432 ;;; function declarations and iteration constructs.
434 ;;; For example, in a statement context:
436 (progn (blorg i) (blafoo i))
440 ;;; In an expression context:
442 (+ i (progn (blorg i) (blafoo i)))
443 => i + (blorg(i), blafoo(i))
445 ;;; A `PROGN' form doesn't lead to additional indentation or
446 ;;; additional braces around it's body.
448 ;;;# Function Definition
449 ;;;t \index{function}
451 ;;;t \index{function definition}
455 ;;;t \index{anonymous function}
457 ; (DEFUN name ({argument}*) body)
458 ; (LAMBDA ({argument}*) body)
460 ; name ::= a Lisp Symbol
461 ; argument ::= a Lisp symbol
462 ; body ::= a list of Parenscript statements
464 ;;; As in Lisp, functions are defined using the `DEFUN' form, which
465 ;;; takes a name, a list of arguments, and a function body. An
466 ;;; implicit `PROGN' is added around the body statements.
468 (defun a-function (a b)
470 => function aFunction(a, b) {
474 ;;; Anonymous functions can be created using the `LAMBDA' form, which
475 ;;; is the same as `DEFUN', but without function name. In fact,
476 ;;; `LAMBDA' creates a `DEFUN' with an empty function name.
478 (lambda (a b) (return (+ a b)))
484 ;;;t \index{assignment}
490 ;;;t \index{assignment operator}
495 ; lhs ::= a Parenscript left hand side expression
496 ; rhs ::= a Parenscript expression
501 ; lhs ::= a Parenscript symbol
502 ; rhs ::= a Parenscript expression
504 ;;; Assignment is done using the `SETF', `PSETF', `SETQ', and `PSETQ'
505 ;;; forms, which are transformed into a series of assignments using
506 ;;; the JavaScript `=' operator.
510 (setf a 2 b 3 c 4 x (+ a b c))
516 ;;; The `SETF' form can transform assignments of a variable with an
517 ;;; operator expression using this variable into a more "efficient"
518 ;;; assignment operator form. For example:
520 (setf a (+ a 2 3 4 a)) => a += 2 + 3 + 4 + a;
522 (setf a (- 1 a)) => a = 1 - a;
524 ;;; The `PSETF' and `PSETQ' forms perform parallel assignment of
525 ;;; places or variables using a number of temporary variables created
526 ;;; by `PS-GENSYM'. For example:
537 ;;; The `SETQ' and `PSETQ' forms operate identically to `SETF' and
538 ;;; `PSETF', but throw a compile-time error if the left-hand side form
539 ;;; is not a symbol. For example:
546 ;; => ERROR: The value (AREF A 0) is not of type SYMBOL.
548 ;;; New types of setf places can be defined in one of two ways: using
549 ;;; `DEFSETF' or using `DEFUN' with a setf function name; both are
550 ;;; analogous to their Common Lisp counterparts.
552 ;;; `DEFSETF' supports both long and short forms, while `DEFUN' of a
553 ;;; setf place generates a JavaScript function name with the __setf_
556 (defun (setf color) (new-color el)
557 (setf (slot-value (slot-value el 'style) 'color) new-color))
558 => function __setf_color(newColor, el) {
559 el.style.color = newColor;
562 (setf (color some-div) (+ 23 "em"))
563 => var _js2 = someDiv;
564 var _js1 = 23 + 'em';
565 __setf_color(_js1, _js2);
567 ;;; Note that temporary variables are generated to preserve evaluation
568 ;;; order of the arguments as they would be in Lisp.
570 ;;; The following example illustrates how setf places can be used to
571 ;;; provide a uniform protocol for positioning elements in HTML pages:
573 (defsetf left (el) (offset)
574 `(setf (slot-value (slot-value ,el 'style) 'left) ,offset))
577 (setf (left some-div) (+ 123 "px"))
578 => var _js2 = someDiv;
579 var _js1 = 123 + 'px';
580 _js2.style.left = _js1;
582 (progn (defmacro left (el)
583 `(slot-value ,el 'offset-left))
585 => someDiv.offsetLeft;
587 ;;;# Single argument statements
588 ;;;t \index{single-argument statement}
592 ;;;t \index{function}
597 ; value ::= a Parenscript expression
599 ;;; The single argument statements `return' and `throw' are generated
600 ;;; by the form `RETURN' and `THROW'. `THROW' has to be used inside a
601 ;;; `TRY' form. `RETURN' is used to return a value from a function
604 (return 1) => return 1
606 (throw "foobar") => throw 'foobar'
608 ;;;# Single argument expression
609 ;;;t \index{single-argument expression}
610 ;;;t \index{object creation}
611 ;;;t \index{object deletion}
615 ;;;t \index{INSTANCEOF}
622 ; (INSTANCEOF {value})
625 ; value ::= a Parenscript expression
627 ;;; The single argument expressions `delete', `void', `typeof',
628 ;;; `instanceof' and `new' are generated by the forms `DELETE',
629 ;;; `VOID', `TYPEOF', `INSTANCEOF' and `NEW'. They all take a
630 ;;; Parenscript expression.
632 (delete (new (*foobar 2 3 4))) => delete new Foobar(2, 3, 4)
634 (if (= (typeof blorg) *string)
635 (alert (+ "blorg is a string: " blorg))
636 (alert "blorg is not a string"))
637 => if (typeof blorg == String) {
638 alert('blorg is a string: ' + blorg);
640 alert('blorg is not a string');
643 ;;;# Conditional Statements
644 ;;;t \index{conditional statements}
648 ;;;t \index{conditionals}
650 ; (IF conditional then {else})
651 ; (WHEN condition then)
652 ; (UNLESS condition then)
654 ; condition ::= a Parenscript expression
655 ; then ::= a Parenscript statement in statement context, a
656 ; Parenscript expression in expression context
657 ; else ::= a Parenscript statement in statement context, a
658 ; Parenscript expression in expression context
660 ;;; The `IF' form compiles to the `if' javascript construct. An
661 ;;; explicit `PROGN' around the then branch and the else branch is
662 ;;; needed if they consist of more than one statement. When the `IF'
663 ;;; form is used in an expression context, a JavaScript `?', `:'
664 ;;; operator form is generated.
666 (if (blorg.is-correct)
667 (progn (carry-on) (return i))
668 (alert "blorg is not correct!"))
669 => if (blorg.isCorrect()) {
673 alert('blorg is not correct!');
676 (+ i (if (blorg.add-one) 1 2))
677 => i + (blorg.addOne() ? 1 : 2)
679 ;;; The `WHEN' and `UNLESS' forms can be used as shortcuts for the
682 (when (blorg.is-correct)
685 => if (blorg.isCorrect()) {
690 (unless (blorg.is-correct)
691 (alert "blorg is not correct!"))
692 => if (!blorg.isCorrect()) {
693 alert('blorg is not correct!');
696 ;;;# Variable declaration
697 ;;;t \index{variable}
698 ;;;t \index{variable declaration}
705 ;;;t \index{LEXICAL-LET}
706 ;;;t \index{LEXICAL-LET*}
708 ; (DEFVAR var {value}?)
710 ; (LET ({var | (var value)}*) body)
711 ; (LET* ({var | (var value)}*) body)
712 ; (LEXICAL-LET ({var | (var value)}*) body)
713 ; (LEXICAL-LET* ({var | (var value)}*) body)
715 ; var ::= a Lisp symbol
716 ; value ::= a Parenscript expression
717 ; body ::= a list of Parenscript statements
719 ;;; Parenscript special variables can be declared using the `DEFVAR'
720 ;;; special form, which is similar to its equivalent form in
721 ;;; Lisp. Note that the result is undefined if `DEFVAR' is not used as
722 ;;; a top-level form.
724 (defvar *a* (array 1 2 3)) => var A = [ 1, 2, 3 ]
726 ;;; One feature present in Parenscript that is not part of Common Lisp
727 ;;; are lexically-scoped global variables, which are declared using
728 ;;; the `VAR' special form.
730 ;;; Parenscript provides two versions of the `LET' and `LET*' special
731 ;;; forms for manipulating local variables: `SIMPLE-LET' /
732 ;;; `SIMPLE-LET*' and `LEXICAL-LET' / `LEXICAL-LET*'. By default,
733 ;;; `LET' and `LET*' are aliased to `SIMPLE-LET' and `SIMPLE-LET*',
736 ;;; `SIMPLE-LET' and `SIMPLE-LET*' bind their variable lists using
737 ;;; simple JavaScript assignment. This means that you cannot rely on
738 ;;; the bindings going out of scope at the end of the form.
740 ;;; `LEXICAL-LET' and `LEXICAL-LET*' actually introduce new lexical
741 ;;; environments for the variable bindings by creating anonymous
744 ;;; As you would expect, `SIMPLE-LET' and `LEXICAL-LET' do parallel
745 ;;; binding of their variable lists, while `SIMPLE-LET*' and
746 ;;; `LEXICAL-LET*' bind their variable lists sequentially.
750 (simple-let* ((a 0) (b 1))
756 (simple-let* ((a "World") (b "Hello"))
757 (simple-let ((a b) (b a))
769 (simple-let* ((a 0) (b 1))
770 (lexical-let* ((a 9) (b 8))
782 (simple-let* ((a "World") (b "Hello"))
783 (lexical-let ((a b) (b a))
793 ;;; Moreover, beware that scoping rules in Lisp and JavaScript are
794 ;;; quite different. For example, don't rely on closures capturing
795 ;;; local variables in the way that you would normally expect.
797 ;;;# Iteration constructs
798 ;;;t \index{iteration}
799 ;;;t \index{iteration construct}
801 ;;;t \index{array traversal}
802 ;;;t \index{property}
803 ;;;t \index{object property}
810 ; (DO ({var | (var {init}? {step}?)}*) (end-test {result}?) body)
811 ; (DO* ({var | (var {init}? {step}?)}*) (end-test {result}?) body)
812 ; (DOTIMES (var numeric-form {result}?) body)
813 ; (DOLIST (var list-form {result}?) body)
814 ; (FOR-IN (var object) body)
815 ; (WHILE end-test body)
817 ; var ::= a Lisp symbol
818 ; numeric-form ::= a Parenscript expression resulting in a number
819 ; list-form ::= a Parenscript expression resulting in an array
820 ; object-form ::= a Parenscript expression resulting in an object
821 ; init ::= a Parenscript expression
822 ; step ::= a Parenscript expression
823 ; end-test ::= a Parenscript expression
824 ; result ::= a Parenscript expression
825 ; body ::= a list of Parenscript statements
827 ;;; All interation special forms are transformed into JavaScript `for'
828 ;;; statements and, if needed, lambda expressions.
830 ;;; `DO', `DO*', and `DOTIMES' carry the same semantics as their
831 ;;; Common Lisp equivalents.
833 ;;; `DO*' (note the variety of possible init-forms:
835 (do* ((a) b (c (array "a" "b" "c" "d" "e"))
837 (e (aref c d) (aref c d)))
838 ((or (= d c.length) (eql e "x")))
840 (document.write (+ "a: " a " b: " b "<br/>")))
841 => 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]) {
844 document.write('a: ' + a + ' b: ' + b + '<br/>');
847 ;;; `DO' (note the parallel assignment):
850 (s 0 (+ s i (1+ i))))
852 (document.write (+ "i: " i " s: " s "<br/>")))
860 document.write('i: ' + i + ' s: ' + s + '<br/>');
862 var _js4 = s + i + (i + 1);
867 ;;; compare to `DO*':
870 (s 0 (+ s i (1- i))))
872 (document.write (+ "i: " i " s: " s "<br/>")))
873 => for (var i = 0, s = 0; i <= 10; i += 1, s += i + (i - 1)) {
874 document.write('i: ' + i + ' s: ' + s + '<br/>');
879 (let* ((arr (array "a" "b" "c" "d" "e")))
880 (dotimes (i arr.length)
881 (document.write (+ "i: " i " arr[i]: " (aref arr i) "<br
/>"))))
882 => var arr = ['a', 'b', 'c', 'd', 'e'];
883 for (var i = 0; i < arr.length; i += 1) {
884 document.write('i: ' + i + ' arr[i]: ' + arr[i] + '<br/>');
887 ;;; `DOTIMES' with return value:
890 (alert (+ "Summation to
10 is
"
892 (incf res (1+ i))))))
894 alert('Summation to 10 is ' + (function () {
895 for (var i = 0; i < 10; i += 1) {
901 ;;; `DOLIST' is like CL:DOLIST, but that it operates on numbered JS
904 (let* ((l (list 1 2 4 8 16 32)))
906 (document.write (+ "c
: " c "<br
/>"))))
907 => var l = [1, 2, 4, 8, 16, 32];
908 for (var c = null, _js_arrvar2 = l, _js_idx1 = 0; _js_idx1 < _js_arrvar2.length; _js_idx1 += 1) {
909 c = _js_arrvar2[_js_idx1];
910 document.write('c: ' + c + '<br/>');
913 (let* ((l (list 1 2 4 8 16 32))
915 (alert (+ "Sum of
" l " is
: "
918 => var l = [1, 2, 4, 8, 16, 32];
920 alert('Sum of ' + l + ' is: ' + (function () {
921 for (var c = null, _js_arrvar2 = l, _js_idx1 = 0; _js_idx1 < _js_arrvar2.length; _js_idx1 += 1) {
922 c = _js_arrvar2[_js_idx1];
928 ;;; `FOR-IN' is translated to the JS `for...in' statement.
930 (let* ((obj (create :a 1 :b 2 :c 3)))
932 (document.write (+ i ": " (aref obj i) "<br
/>"))))
933 => var obj = { a : 1, b : 2, c : 3 };
935 document.write(i + ': ' + obj[i] + '<br/>');
938 ;;; The `WHILE' form is transformed to the JavaScript form `while',
939 ;;; and loops until a termination test evaluates to false.
941 (while (film.is-not-finished)
942 (this.eat (new *popcorn)))
943 => while (film.isNotFinished()) {
944 this.eat(new Popcorn);
947 ;;;# The `CASE' statement
952 ; (CASE case-value clause*)
954 ; clause ::= (value body) | ((value*) body) | t-clause
955 ; case-value ::= a Parenscript expression
956 ; value ::= a Parenscript expression
957 ; t-clause ::= {t | otherwise | default} body
958 ; body ::= a list of Parenscript statements
960 ;;; The Lisp `CASE' form is transformed to a `switch' statement in
961 ;;; JavaScript. Note that `CASE' is not an expression in
965 ((1 "one
") (alert "one
"))
967 (t (alert "default clause
")))
968 => switch (blorg[i]) {
977 alert('default clause');
980 ; (SWITCH case-value clause*)
981 ; clause ::= (value body) | (default body)
983 ;;; The `SWITCH' form is the equivalent to a javascript switch statement.
984 ;;; No break statements are inserted, and the default case is named `DEFAULT'.
985 ;;; The `CASE' form should be prefered in most cases.
987 (switch (aref blorg i)
988 (1 (alert "If I get here
"))
989 (2 (alert "I also get here
"))
990 (default (alert "I always get here
")))
991 => switch (blorg[i]) {
992 case 1: alert('If I get here');
993 case 2: alert('I also get here');
994 default: alert('I always get here');
997 ;;;# The `WITH' statement
999 ;;;t \index{dynamic scope}
1000 ;;;t \index{binding}
1001 ;;;t \index{scoping}
1002 ;;;t \index{closure}
1004 ; (WITH object body)
1006 ; object ::= a Parenscript expression evaluating to an object
1007 ; body ::= a list of Parenscript statements
1009 ;;; The `WITH' form is compiled to a JavaScript `with' statements, and
1010 ;;; adds the object `object' as an intermediary scope objects when
1011 ;;; executing the body.
1013 (with (create :foo "foo
" :i "i
")
1014 (alert (+ "i is now intermediary scoped
: " i)))
1015 => with ({ foo : 'foo', i : 'i' }) {
1016 alert('i is now intermediary scoped: ' + i);
1019 ;;;# The `TRY' statement
1022 ;;;t \index{FINALLY}
1023 ;;;t \index{exception}
1024 ;;;t \index{error handling}
1026 ; (TRY body {(:CATCH (var) body)}? {(:FINALLY body)}?)
1028 ; body ::= a list of Parenscript statements
1029 ; var ::= a Lisp symbol
1031 ;;; The `TRY' form is converted to a JavaScript `try' statement, and
1032 ;;; can be used to catch expressions thrown by the `THROW'
1033 ;;; form. The body of the catch clause is invoked when an exception
1034 ;;; is catched, and the body of the finally is always invoked when
1035 ;;; leaving the body of the `TRY' form.
1039 (alert (+ "an error happened
: " error)))
1041 (alert "Leaving the try form
")))
1045 alert('an error happened: ' + error);
1047 alert('Leaving the try form');
1050 ;;;# The HTML Generator
1051 ;;;t \index{PS-HTML}
1052 ;;;t \index{HTML generation}
1054 ; (PS-HTML html-expression)
1056 ;;; The HTML generator of Parenscript is very similar to the htmlgen
1057 ;;; HTML generator library included with AllegroServe. It accepts the
1058 ;;; same input forms as the AllegroServer HTML generator. However,
1059 ;;; non-HTML construct are compiled to JavaScript by the Parenscript
1060 ;;; compiler. The resulting expression is a JavaScript expression.
1062 (ps-html ((:a :href "foobar
") "blorg
"))
1063 => '<A HREF=\"foobar\">blorg</A>'
1065 (ps-html ((:a :href (generate-a-link)) "blorg
"))
1066 => '<A HREF=\"' + generateALink() + '\">blorg</A>'
1068 ;;; We can recursively call the Parenscript compiler in an HTML
1072 (ps-html ((:a :href "#"
1073 :onclick (ps-inline (transport))) "link
")))
1074 => document.write('<A HREF=\"#\" ONCLICK=\"' + ('javascript:' + 'transport' + '(' + ')') + '\">link</A>')
1076 ;;; Forms may be used in attribute lists to conditionally generate
1077 ;;; the next attribute. In this example the textarea is sometimes disabled.
1079 (let* ((disabled nil)
1081 (setf element.inner-h-t-m-l
1082 (ps-html ((:textarea (or disabled (not authorized)) :disabled "disabled
")
1084 => var disabled = null;
1085 var authorized = true;
1088 + (disabled || !authorized ? ' DISABLED=\"' + 'disabled' + '\"' : '')
1089 + '>Edit me</TEXTAREA>';
1093 ;;;t \index{macrology}
1094 ;;;t \index{DEFPSMACRO}
1095 ;;;t \index{DEFMACRO/PS}
1096 ;;;t \index{DEFMACRO+PS}
1097 ;;;t \index{DEFINE-PS-SYMBOL-MACRO}
1098 ;;;t \index{IMPORT-MACROS-FROM-LISP}
1099 ;;;t \index{MACROLET}
1100 ;;;t \index{SYMBOL-MACROLET}
1101 ;;;t \index{PS-GENSYM}
1102 ;;;t \index{compiler}
1104 ; (DEFPSMACRO name lambda-list macro-body)
1105 ; (DEFPSMACRO/PS name lambda-list macro-body)
1106 ; (DEFPSMACRO+PS name lambda-list macro-body)
1107 ; (DEFINE-PS-SYMBOL-MACRO symbol expansion)
1108 ; (IMPORT-MACROS-FROM-LISP symbol*)
1109 ; (MACROLET ({name lambda-list macro-body}*) body)
1110 ; (SYMBOL-MACROLET ({name macro-body}*) body)
1111 ; (PS-GENSYM {string})
1113 ; name ::= a Lisp symbol
1114 ; lambda-list ::= a lambda list
1115 ; macro-body ::= a Lisp body evaluating to Parenscript code
1116 ; body ::= a list of Parenscript statements
1117 ; string ::= a string
1119 ;;; Parenscript can be extended using macros, just like Lisp can be
1120 ;;; extended using Lisp macros. Using the special Lisp form
1121 ;;; `DEFPSMACRO', the Parenscript language can be
1122 ;;; extended. `DEFPSMACRO' adds the new macro to the toplevel macro
1123 ;;; environment, which is always accessible during Parenscript
1124 ;;; compilation. For example, the `1+' and `1-' operators are
1125 ;;; implemented using macros.
1127 (defpsmacro 1- (form)
1130 (defpsmacro 1+ (form)
1133 ;;; A more complicated Parenscript macro example is the implementation
1134 ;;; of the `DOLIST' form (note how `PS-GENSYM', the Parenscript of
1135 ;;; `GENSYM', is used to generate new Parenscript variable names):
1137 (defpsmacro dolist ((var array &optional (result nil result?)) &body body)
1138 (let ((idx (ps-gensym "_js_idx
"))
1139 (arrvar (ps-gensym "_js_arrvar
")))
1143 ((>= ,idx (slot-value ,arrvar 'length))
1144 ,@(when result? (list result)))
1145 (setq ,var (aref ,arrvar ,idx))
1148 ;;; Macros can be defined in Parenscript code itself (as opposed to
1149 ;;; from Lisp) by using the Parenscript `MACROLET' and `DEFMACRO'
1150 ;;; forms. Note that macros defined this way are defined in a null
1151 ;;; lexical environment (ex - (let ((x 1)) (defmacro baz (y) `(+ ,y
1152 ;;; ,x))) will not work), since the surrounding Parenscript code is
1153 ;;; just translated to JavaScript and not actually evaluated.
1155 ;;; Parenscript also supports the use of macros defined in the
1156 ;;; underlying Lisp environment. Existing Lisp macros can be imported
1157 ;;; into the Parenscript macro environment by
1158 ;;; `IMPORT-MACROS-FROM-LISP'. This functionality enables code sharing
1159 ;;; between Parenscript and Lisp, and is useful in debugging since the
1160 ;;; full power of Lisp macroexpanders, editors and other supporting
1161 ;;; facilities can be used. However, it is important to note that the
1162 ;;; macroexpansion of Lisp macros and Parenscript macros takes place
1163 ;;; in their own respective environments, and many Lisp macros
1164 ;;; (especially those provided by the Lisp implementation) expand into
1165 ;;; code that is not usable by Parenscript. To make it easy for users
1166 ;;; to take advantage of these features, two additional macro
1167 ;;; definition facilities are provided by Parenscript: `DEFMACRO/PS'
1168 ;;; and `DEFMACRO+PS'. `DEFMACRO/PS' defines a Lisp macro and then
1169 ;;; imports it into the Parenscript macro environment, while
1170 ;;; `DEFMACRO+PS' defines two macros with the same name and expansion,
1171 ;;; one in Parenscript and one in Lisp. `DEFMACRO+PS' is used when the
1172 ;;; full 'macroexpand' of the Lisp macro yields code that cannot be
1173 ;;; used by Parenscript.
1175 ;;; Parenscript also supports symbol macros, which can be introduced
1176 ;;; using the Parenscript form `SYMBOL-MACROLET' or defined in Lisp
1177 ;;; with `DEFINE-PS-SYMBOL-MACRO'. For example, the Parenscript
1178 ;;; `WITH-SLOTS' is implemented using symbol macros.
1180 (defpsmacro with-slots (slots object &rest body)
1181 `(symbol-macrolet ,(mapcar #'(lambda (slot)
1182 `(,slot '(slot-value ,object ',slot)))
1186 ;;;# The Parenscript namespace system
1187 ;;;t \index{package}
1188 ;;;t \index{namespace}
1189 ;;;t \index{PS-PACKAGE-PREFIX}
1191 ; (setf (PS-PACKAGE-PREFIX package-designator) string)
1193 ;;; Although JavaScript does not offer namespacing or a package
1194 ;;; system, Parenscript does provide a namespace mechanism for
1195 ;;; generated JavaScript by integrating with the Common Lisp package
1196 ;;; system. Since Parenscript code is normally read in by the Lisp
1197 ;;; reader, all symbols (except for uninterned ones, ie - those
1198 ;;; specified with the #: reader macro) have a Lisp package. By
1199 ;;; default, no packages are prefixed. You can specify that symbols in
1200 ;;; a particular package receive a prefix when translated to
1201 ;;; JavaScript with the `PS-PACKAGE-PREFIX' place.
1203 (defpackage "PS-REF.MY-LIBRARY
"
1204 (:use "PARENSCRIPT
"))
1205 (setf (ps-package-prefix "PS-REF.MY-LIBRARY
") "my_library_
")
1207 (defun ps-ref.my-library::library-function (x y)
1209 -> function my_library_libraryFunction(x, y) {
1213 ;;;# Identifier obfuscation
1214 ;;;t \index{obfuscation}
1215 ;;;t \index{identifiers}
1216 ;;;t \index{OBFUSCATE-PACKAGE}
1217 ;;;t \index{UNOBFUSCATE-PACKAGE}
1219 ; (OBFUSCATE-PACKAGE package-designator &optional symbol-map)
1220 ; (UNOBFUSCATE-PACKAGE package-designator)
1222 ;;; Similar to the namespace mechanism, Parenscript provides a
1223 ;;; facility to generate obfuscated identifiers in specified CL
1224 ;;; packages. The function `OBFUSCATE-PACKAGE' may optionally be
1225 ;;; passed a hash-table or a closure that maps symbols to their
1226 ;;; obfuscated counterparts. By default, the mapping is done using
1229 (defpackage "PS-REF.OBFUSCATE-ME
")
1230 (obfuscate-package "PS-REF.OBFUSCATE-ME
"
1231 (let ((code-pt-counter #x8CF0)
1232 (symbol-map (make-hash-table)))
1234 (or (gethash symbol symbol-map)
1235 (setf (gethash symbol symbol-map)
1236 (make-symbol (string (code-char (incf code-pt-counter)))))))))
1238 (defun ps-ref.obfuscate-me::a-function (a b ps-ref.obfuscate-me::foo)
1239 (+ a (ps-ref.my-library::library-function b ps-ref.obfuscate-me::foo)))
1240 -> function 賱(a, b, 賲) {
1241 a + my_library_libraryFunction(b, 賲);
1244 ;;; The obfuscation and namespace facilities can be used on packages
1245 ;;; at the same time.
1247 ;;;# The Parenscript Compiler
1248 ;;;t \index{compiler}
1249 ;;;t \index{Parenscript compiler}
1253 ;;;t \index{PS-INLINE}
1254 ;;;t \index{PS-INLINE*}
1259 ; (PS1* parenscript-form)
1260 ; (PS-INLINE form &optional *js-string-delimiter*)
1261 ; (PS-INLINE* form &optional *js-string-delimiter*)
1265 ; body ::= Parenscript statements comprising an implicit `PROGN'
1267 ;;; For static Parenscript code, the macro `PS' compiles the provided
1268 ;;; forms at Common Lisp macro-expansion time. `PS*' and `PS1*'
1269 ;;; evaluate their arguments and then compile them. All these forms
1270 ;;; except for `PS1*' treat the given forms as an implicit
1273 ;;; `PS-INLINE' and `PS-INLINE*' take a single Parenscript form and
1274 ;;; output a string starting with "javascript
:" that can be used in
1275 ;;; HTML node attributes. As well, they provide an argument to bind
1276 ;;; the value of *js-string-delimiter* to control the value of the
1277 ;;; JavaScript string escape character to be compatible with whatever
1278 ;;; the HTML generation mechanism is used (for example, if HTML
1279 ;;; strings are delimited using #\', using #\" will avoid conflicts
1280 ;;; without requiring the output JavaScript code to be escaped). By
1281 ;;; default the value is taken from *js-inline-string-delimiter*.
1283 ;;; Parenscript can also call out to arbitrary Common Lisp code at
1284 ;;; code output time using the special form `LISP'. The form provided
1285 ;;; to `LISP' is evaluated, and its result is compiled as though it
1286 ;;; were Parenscript code. For `PS' and `PS-INLINE', the Parenscript
1287 ;;; output code is generated at macro-expansion time, and the `LISP'
1288 ;;; statements are inserted inline and have access to the enclosing
1289 ;;; Common Lisp lexical environment. `PS*' and `PS1*' evaluate the
1290 ;;; `LISP' forms with eval, providing them access to the current
1291 ;;; dynamic environment only.