Added defsetf long-form.

[clinton/parenscript.git] / docs / reference.lisp

diff --git a/docs/reference.lisp b/docs/reference.lisp
index 0b5ba4b..d7219f5 100644 (file)
--- a/docs/reference.lisp
+++ b/docs/reference.lisp
@@ -222,7 +222,7 @@ an-object.foo => anObject.foo
 
 (with-slots (a b c) this
   (+ a b c))
-    => this.a + this.b + this.c;
+    => (this).a + (this).b + (this).c;
 
 ;;;## Regular Expression literals
 ;;;t \index{REGEX}
@@ -491,7 +491,7 @@ a-variable  => aVariable
 ;;; Assignment is done using the `SETF' form, which is transformed
 ;;; into a series of assignments using the JavaScript `=' operator.
 
-(setf a 1) => a = 1
+(setf a 1) => a = 1;
 
 (setf a 2 b 3 c 4 x (+ a b c))
    => a = 2;
@@ -503,11 +503,11 @@ a-variable  => aVariable
 ;;; operator expression using this variable into a more "efficient"
 ;;; assignment operator form. For example:
 
-(setf a (1+ a))          => a++
+(setf a (1+ a))          => a++;
 
-(setf a (* 2 3 4 a 4 a)) => a *= 2 * 3 * 4 * 4 * a
+(setf a (+ a 2 3 4 a))   => a += 2 + 3 + 4 + a;
 
-(setf a (- 1 a))         => a = 1 - a
+(setf a (- 1 a))         => a = 1 - a;
 
 ;;;# Single argument statements
 ;;;t \index{single-argument statement}
@@ -818,7 +818,7 @@ a-variable  => aVariable
 ;;;t \index{scoping}
 ;;;t \index{closure}
 
-; (WITH (object) body)
+; (WITH object body)
 ;
 ; object ::= a ParenScript expression evaluating to an object
 ; body   ::= a list of ParenScript statements
@@ -827,7 +827,7 @@ a-variable  => aVariable
 ;;; adds the object `object' as an intermediary scope objects when
 ;;; executing the body.
 
-(with ((create :foo "foo" :i "i"))
+(with (create :foo "foo" :i "i")
   (alert (+ "i is now intermediary scoped: " i)))
    => with ({ foo : 'foo',
               i : 'i' }) {
@@ -894,6 +894,23 @@ a-variable  => aVariable
   => document.write
      ('<a href=\"#\" onclick=\"' + 'javascript:transport();' + '\">link</a>')
 
+;;; Forms may be used in attribute lists to conditionally generate
+;;; the next attribute. In this example the textarea is sometimes disabled.
+
+(let ((disabled nil)
+      (authorized t))
+   (setf element.inner-h-t-m-l
+         (html ((:textarea (or disabled (not authorized)) :disabled "disabled")
+                "Edit me"))))
+  =>  {
+        var disabled = null;
+        var authorized = true;
+        element.innerHTML =
+        '<textarea'
+        + (disabled || !authorized ? ' disabled=\"' + 'disabled' + '\"' : '')
+        + '>Edit me</textarea>';
+      }
+
 ; (CSS-INLINE css-expression)
 
 ;;; Stylesheets can also be created in ParenScript.
@@ -959,9 +976,28 @@ a-variable  => aVariable
         (let ((,var (aref ,arrvar ,idx)))
           ,@body)))))
 
-;;; Macros can be added dynamically to the macro environment by using
-;;; the ParenScript `MACROLET' form (note that while `DEFJSMACRO' is a
-;;; Lisp form, `MACROLET' and `SYMBOL-MACROLET' are ParenScript forms).
+;;; Macros can be defined in ParenScript itself (as opposed to Lisp)
+;;; by using the ParenScript `MACROLET' and 'DEFMACRO' forms.
+
+;;; ParenScript also supports the use of macros defined in the
+;;; underlying Lisp. Existing Lisp macros can be imported into the
+;;; ParenScript macro environment by 'IMPORT-MACROS-FROM-LISP'. This
+;;; functionality enables code sharing between ParenScript and Lisp,
+;;; and is useful in debugging since the full power of Lisp
+;;; macroexpanders, editors and other supporting facilities can be
+;;; used. However, it is important to note that the macroexpansion of
+;;; Lisp macros and ParenScript macros takes place in their own
+;;; respective environments, and many Lisp macros (especially those
+;;; provided by the Lisp implementation) expand into code that is not
+;;; usable by ParenScript. To make it easy for users to take advantage
+;;; of these features, two additional macro definition facilities are
+;;; provided by ParenScript: 'DEFMACRO/JS' and
+;;; 'DEFMACRO+JS'. 'DEFMACRO/JS' defines a Lisp macro and then imports
+;;; it into the ParenScript macro environment, while 'DEFMACRO+JS'
+;;; defines two macros with the same name and expansion, one in
+;;; ParenScript and one in Lisp. 'DEFMACRO+JS' is used when the full
+;;; 'macroexpand' of the Lisp macro yields code that cannot be used by
+;;; ParenScript.
 
 ;;; ParenScript also supports symbol macros, which can be introduced
 ;;; using the ParenScript form `SYMBOL-MACROLET'. A new macro