Re: doc expression syntax, quoting

[Neil Jerram]

>>>>> "Kevin" == Kevin Ryde <address@hidden> writes:

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

Nice; just a few comments below.


    Kevin> Expression Syntax
    Kevin> =================

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

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

    Kevin>           (define x 123)
    Kevin>           x => 123

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

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

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

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

This suggests the args will still be evaluated, which is often not
true.  How about "but in that case the arguments are not automatically
evaluated".  (Note also "the the" typo.)


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

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

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

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

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

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

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

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

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

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

    Kevin>       - syntax: unquote-splicing expr
    Kevin>       - syntax: , expr

Should be ,@ here.

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

Surely "comma-at", not "at-comma"?

    Kevin>           `unquote-splicing' form.

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

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


    Kevin> _______________________________________________
    Kevin> Guile-devel mailing list
    Kevin> address@hidden
    Kevin> http://mail.gnu.org/mailman/listinfo/guile-devel