Skip to content

Commit

Permalink
Tweaked XML documentation and added double-quoting, case rules and !r…
Browse files Browse the repository at this point in the history 
…aw blocks to Javascript documentation.
  • Loading branch information
Dave Gurnell committed Jun 7, 2009
1 parent 3383552 commit 5929c5e
Show file tree
Hide file tree
Showing 2 changed files with 87 additions and 40 deletions.
111 changes: 80 additions & 31 deletions scribblings/javascript-syntax.scrbl
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,20 +4,74 @@

@(define-eval js-eval (for-syntax scheme/base) (planet untyped/mirrors/javascript/javascript))

@title[#:tag "javascript-syntax"]{Javascript syntax}
@title[#:tag "javascript-syntax"]{Constructing Javascript fragments}

@defmodule[(planet untyped/mirrors/javascript/syntax)]

Mirrors provides a set of macros for rendering blocks of Javascript, intended to replace Jay McCarthy's @tt{javascript.plt} (which is no longer in development). Very little checking is performed to make sure the Javascript code makes sense.
@section{Javascript macros}

@defform/subs[
Mirrors provides the following macros for creating blocks of Javascript:

@defform[(js js-stmt ...)]{
Builds a block of Javascript. See @secref["js-stmt"] for the syntax of @scheme[js-stmt].

@examples[
#:eval js-eval
(let ([message "Hello world"])
(pretty-print (js (alert ,message))))]

To prevent double-quoting errors, it is a syntax error to use the following Mirrors quote forms within a @scheme[js] block: @scheme[xml], @scheme[xml*], @scheme[xml-attrs], @scheme[xml-attrs*], @scheme[opt-xml], @scheme[opt-xml-attr], @scheme[js], @scheme[opt-js]:

@interaction[
#:eval js-eval
(js (js))]

You can get around this restriction using the uppercase form, @scheme[JS], described below.}

@defform[(JS js-stmt ...)]{
Like @scheme[js], but permits the use of the lowercase Mirrors quote forms as @scheme[js-stmt]@schemeidfont{s}:

@interaction[
#:eval js-eval
(code:line (pretty-print (JS (js))) (code:comment "'js()' function call"))]

It is a syntax error to use the following identifiers in expression position within a @scheme[JS] block: @scheme[XML], @scheme[XML*], @scheme[XML-ATTRS], @scheme[XML-ATTRS*], @scheme[OPT-XML], @scheme[OPT-XML-ATTR], @scheme[JS], @scheme[OPT-JS]:

@interaction[
#:eval js-eval
(JS (JS))]}

@defform[(opt-js boolean-expr js-stmt ...)]{

Syntactic shorthand for:

@schemeblock[
(if boolean-expr
(js js-stmt ...)
(js))]

@examples[
#:eval js-eval
(javascript->string (opt-js #t (alert "This statement will be printed....")))
(javascript->string (opt-js #f (alert "...but this statement won't.")))]}

@defform[(OPT-JS boolean-expr js-stmt ...)]{
Like @scheme[opt-js], but follows the same double-quoting rules as @scheme[JS].}

-----------------------------------

@section[#:tag "js-stmt"]{Javascript syntax}

The forms above use the same parenthetical Javascript syntax:

@schemegrammar*[
#:literals (function !begin !block if do while for for-in break continue return with switch !label throw try unquote unquote-splicing
!array !object !index !dot !all ? new function null this id _)
(js js-stmt ...)
([js-stmt js-decl
[js-stmt js-decl
(custom-syntax-id js-stmt ...)
(!begin js-stmt ...)
(!block js-stmt ...)
(!raw string-expr)
(!regexp str regexp-key ...)
(if js-expr js-stmt js-stmt)
(do js-stmt ... js-expr)
Expand Down Expand Up @@ -51,6 +105,7 @@ Mirrors provides a set of macros for rendering blocks of Javascript, intended to
(!object [property js-expr] ...)
(!index js-expr js-expr)
(!dot js-expr dot-expr ...)
(!raw string-expr)
(!all js-expr ...)
(? js-expr js-expr js-expr)
(new js-expr js-expr ...)
Expand All @@ -63,22 +118,34 @@ Mirrors provides a set of macros for rendering blocks of Javascript, intended to
number-literal
string-literal
(quote symbol-literal)]
[js-operator (code:line ...) (code:comment "symbolic Javascript operator: =, +, etc")]
[custom-syntax-id id]
[js-operator (code:line ... (code:comment "Javascript operator: =, +, etc"))]
[custom-syntax-id (code:line id (code:comment "bound by define-js-syntax"))]
[regexp-key (code:line #:global? boolean-literal)
(code:line #:global? (unquote boolean-expr))
(code:line #:ci? boolean-literal)
(code:line #:ci? (unquote boolean-expr))]
[dot-expr (code:line id (code:comment "property-style accessor : a.b"))
(code:line (!index id expr) (code:comment "array-index-style accessor: a.b[1]"))
(code:line (id js-expr ...) (code:comment "method-style accessor: a.b(1, 2)"))]
[dot-expr (code:line id (code:comment "property-style: a.b"))
(code:line (!index id expr) (code:comment "array-style: a.b[1]"))
(code:line (id js-expr ...) (code:comment "method-style: a.b(1, 2)"))]
[opt-decl _
var-decl]
[opt-expr _
expr])]{
Builds a Javascript declaration, statement or expression. Unquote can be used to insert Scheme expressions resulting in Boolean, numeric, string, symbol, bytes or URL values.
expr]]

@scheme[!raw] forms are treated as statements or expressions depending on their context. Semicolons and parentheses are added automatically depending on the interpretation of the block:

@examples[
#:eval js-eval
(code:comment "raw statements are followed by semicolons:")
(display (javascript->pretty-string
(js (alert "First statement")
(!raw "alert(\"Second sta tement\")")
(alert "Third statement"))))
(code:comment "raw expressions are surrounded by parentheses:")
(display (javascript->pretty-string
(js (alert (+ 1 (!raw "2") 3)))))]

@scheme[custom-syntax-id] indicates an identifier bound with @scheme[define-javascript-syntax].}
@section{Custom Javascript syntax}

@defform*[[(define-javascript-syntax (id arg ...) js-expr)
(define-javascript-syntax id js-transformer)
Expand Down Expand Up @@ -108,24 +175,6 @@ The second and third forms behave like @scheme[define-match-expander]. @scheme[j
(javascript->string (js (!min 1 2)))
(!min 1 2)]}

@defform[(opt-js boolean-expr js-stmt ...)]{

Syntactic shorthand for:

@schemeblock[
(if boolean-expr
(js js-stmt ...)
(js))]

Only works at the statement level.

@examples[
#:eval js-eval
(javascript->string
(opt-js #t (alert "This alert will be shown....")))
(javascript->string
(opt-js #f (alert "...but this alert won't.")))]}

@defproc[(javascript? [val any]) boolean?]{
Returns @scheme[#t] if @scheme[val] is a Javascript declaration, statement or expression.}

Expand Down
16 changes: 7 additions & 9 deletions scribblings/xml-syntax.scrbl
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,13 +5,11 @@

@(define-eval xml-eval (for-syntax scheme/base) (planet untyped/mirrors/xml/xml))

@title[#:tag "xml-syntax"]{XML syntax}
@title[#:tag "xml-syntax"]{Constructing XML fragments}

@defmodule[(planet untyped/mirrors/xml/syntax)]

@section{XML macros}

Mirrors provides the following macros for building XML:
Mirrors provides the following macros for creating blocks of XML:

@defform[(xml xml-expr ...)]{
Builds a block of XML, optimising any immutable blocks of markup into @scheme[!raw] blocks to reduce memory consumption and rendering time. See @secref["xml-expr"] for the syntax of @scheme[xml-expr].
Expand All @@ -25,22 +23,22 @@ To prevent double-quoting errors, it is a syntax error to use the following Mirr

@interaction[
#:eval xml-eval
(xml (xml "this is bad"))]
(xml (xml))]

You can get around this restriction using the uppercase form, @scheme[XML], described below.}

@defform[(XML xml-expr ...)]{
Like @scheme[xml], but permits the use of the lowercase Mirrors quote forms within the @scheme[xml-expr]@schemeidfont{s}:
Like @scheme[xml], but permits the use of the lowercase Mirrors quote forms as @scheme[xml-expr]@schemeidfont{s}:

@interaction[
#:eval xml-eval
(XML (xml "this is okay"))]
(code:line (XML (xml)) (code:comment "'<xml/>' tag"))]

It is a syntax error to use the following identifiers in expression position within an @scheme[XML] block: @scheme[XML], @scheme[XML*], @scheme[XML-ATTRS], @scheme[XML-ATTRS*], @scheme[OPT-XML], @scheme[OPT-XML-ATTR], @scheme[JS], @scheme[OPT-JS]:

@interaction[
#:eval xml-eval
(XML (XML "this is bad"))]}
(XML (XML))]}

@defform[(xml* xml-expr ...)]{
Like @scheme[xml], but skips the optimisation of static markup, leaving the element structure intact for later traversal and manipulation:
Expand Down Expand Up @@ -119,7 +117,7 @@ Like @scheme[opt-xml-attr], but follows the same double-quoting rules as @scheme

@section[#:tag "xml-expr"]{XML expression syntax}

The above forms the same XML syntax, inspired by the syntax of Neil van Dyke's @italic{HtmlPrag} package:
The forms above use the same XML syntax, inspired by the syntax of Neil van Dyke's @italic{HtmlPrag} package:

@schemegrammar*[
#:literals (\@ & U !comment !cdata !pi !raw id xml attribute quotable-value symbol integer)
Expand Down

0 comments on commit 5929c5e

Please sign in to comment.