doc expression syntax, quoting

[Kevin Ryde]

This is some words to propose for the currently empty Expression
Syntax section of the manual.  In particular it describes quote and
quasiquote, which don't otherwise appear in the manual.



Expression Syntax
=================

An expression to be evaluated takes one of the following forms.

 - syntax: <symbol>
     A symbol is evaluated by dereferencing.  A binding of that symbol
     is sought and the value there used.  For example,

          (define x 123)
          x => 123

 - syntax: (proc [args ...])
     A parenthesised expression is a function call.  PROC and each
     argument are evaluated, then the function (which PROC evaluated
     to) is called with those arguments.

     The order in which PROC and the arguments are evaluated is
     unspecified, so be careful when using expressions with side
     effects.

          (max 1 2 3) => 3
          
          (define (get-some-proc)  min)
          ((get-some-proc) 1 2 3) => 1

     The same sort of parenthesised form is used for a macro invocation,
     but in that case the the macro is applied before evaluating the
     arguments.  See the descriptions of macros for more on this (*note
     Macros::, and *note Syntax Rules::).

 - syntax: <constant>
     Number, string, character and boolean constants evaluate "to
     themselves", so can appear as literals.

          123     => 123
          99.9    => 99.9
          "hello" => "hello"
          #\z     => #\z
          #t      => #t

     Note that an application must not attempt to modify literal
     strings, since they may be in read-only memory.

 - syntax: quote data
 - syntax: ' data
     Quoting is used to obtain a literal symbol (instead of a variable
     reference), a literal list (instead of a function call), or a
     literal vector.  ' is simply a shorthand for a `quote' form.  For
     example,

          'x                   => x
          '(1 2 3)             => (1 2 3)
          '#(1 (2 3) 4)        => #(1 (2 3) 4)
          (quote x)            => x
          (quote (1 2 3))      => (1 2 3)
          (quote #(1 (2 3) 4)) => #(1 (2 3) 4)

     Note that an application must not attempt to modify literal lists
     or vectors obtained from a `quote' form, since they may be in
     read-only memory.

 - syntax: quasiquote data
 - syntax: ` data
     Backquote quasi-quotation is like `quote', but selected
     sub-expressions are evaluated.  This is a convenient way to
     construct a list or vector structure most of which is constant,
     but at certain points should have expressions substituted.

     The same effect can always be had with suitable `list', `cons' or
     `vector' calls, but quasi-quoting is often easier.

      - syntax: unquote expr
      - syntax: , expr
          Within the quasiquote DATA, `unquote' or `,' indicates an
          expression to be evaluated and inserted.  The comma syntax `,'
          is simply a shorthand for an `unquote' form.  For example,

               `(1 2 ,(* 9 9) 3 4)      => (1 2 81 3 4)
               `(1 (unquote (+ 1 1)) 3) => (1 2 3)
               `#(1 ,(/ 12 2))          => #(1 6)

      - syntax: unquote-splicing expr
      - syntax: , expr
          Within the quasiquote DATA, `unquote-splicing' or `,@'
          indicates an expression to be evaluated and the elements of
          the returned list inserted.  EXPR must evaluate to a list.
          The "at-comma" syntax `,@' is simply a shorthand for an
          `unquote-splicing' form.

               (define x '(2 3))
               `(1 ,@x 4)                         => (1 2 3 4)
               `(1 (unquote-splicing (map 1+ x))) => (1 3 4)
               `#(9 ,@x 9)                        => #(9 2 3 9)

          Notice `,@' differs from plain `,' in the way one level of
          nesting is stripped.  For `,@' the elements of a returned list
          are inserted, whereas with `,' it would be the list itself
          inserted.