diff --git a/collects/scribblings/honu/honu.scrbl b/collects/scribblings/honu/honu.scrbl new file mode 100644 index 0000000000..3ccf83f6c7 --- /dev/null +++ b/collects/scribblings/honu/honu.scrbl @@ -0,0 +1,236 @@ +#lang scribble/doc +@(require scribble/manual + scribble/bnf + (for-label scheme)) + +@(define lcomma (litchar ", ")) + +@title{@bold{Honu}} + +@defterm{Honu} is a family of languages built on top of Scheme. Honu +syntax resembles Java. Like Scheme, however, Honu has no fixed syntax, +because Honu supports extensibility through macros and a base syntax +of @as-index{H-expressions}, which are analogous to S-expressions. + +The Honu language currently exists only as a undocumented +prototype. Scheme's parsing and printing of H-expressions is +independent of the Honu language, however, so it is documented here. + +@table-of-contents[] + +@; ---------------------------------------------------------------------- + +@section{H-expressions} + +The Scheme reader incorporates an H-expression reader, and Scheme's +printer also supports printing values in Honu syntax. The reader can +be put into H-expression mode either by including @litchar{#hx} in the +input stream, or by calling @scheme[read-honu] or +@scheme[read-honu-syntax] instead of @scheme[read] or +@scheme[read-syntax]. Similarly, @scheme[print] (or, more precisely, +the default print handler) produces Honu output when the +@scheme[print-honu] parameter is set to @scheme[#t]. + +When the reader encounters @litchar{#hx}, it reads a single +H-expression, and it produces an S-expression that encodes the +H-expression. Except for atomic H-expressions, evaluating this +S-expression as Scheme is unlikely to succeed. In other words, +H-expressions are not intended as a replacement for S-expressions to +represent Scheme code. + +Honu syntax is normally used via @litchar{#lang honu}, which reads +H-expressions repeatedly until an end-of-file is encountered, and +processes the result as a module in the Honu language. + +Ignoring whitespace, an H-expression is either + +@itemize{ + + @item{a number (see @secref["honu:numbers"]);} + + @item{an identifier (see @secref["honu:identifiers"]);} + + @item{a string (see @secref["honu:strings"]);} + + @item{a character (see @secref["honu:chars"]);} + + @item{a sequence of H-expressions between parentheses (see @secref["honu:parens"]);} + + @item{a sequence of H-expressions between square brackets (see @secref["honu:parens"]);} + + @item{a sequence of H-expressions between curly braces (see @secref["honu:parens"]);} + + @item{a comment followed by an H-expression (see @secref["honu:comments"]);} + + @item{@litchar{#;} followed by two H-expressions (see @secref["honu:comments"]);} + + @item{@litchar{#hx} followed by an H-expression;} + + @item{@litchar{#sx} followed by an S-expression (see @secref[#:doc +'(lib "scribblings/reference/reference.scrbl") "reader"]).} + +} + +Within a sequence of H-expressions, a sub-sequence between angle +brackets is represented specially (see @secref["honu:parens"]). + +Whitespace for H-expressions is as in Scheme: any character for which +@scheme[char-whitespace?] returns true counts as a whitespace. + +@; ---------------------------------------------------------------------- + +@subsection[#:tag "honu:numbers"]{Numbers} + +The syntax for Honu numbers is the same as for Java. The S-expression +encoding of a particular H-expression number is the obvious Scheme +number. + +@; ---------------------------------------------------------------------- + +@subsection[#:tag "honu:identifiers"]{Identifiers} + +The syntax for Honu identifiers is the union of Java identifiers plus +@litchar{;}, @litchar{,}, and a set of operator identifiers. An +@defterm{operator identifier} is any combination of the following +characters: + +@t{ + @hspace[2] @litchar{+} @litchar{-} @litchar{_} @litchar{=} @litchar{?} + @litchar{:} @litchar{<} @litchar{>} @litchar{.} @litchar{!} @litchar{%} + @litchar{^} @litchar{&} @litchar{*} @litchar{/} @litchar{~} @litchar{|} +} + +The S-expression encoding of an H-expression identifier is the obvious +Scheme symbol. + +Input is parsed to form maximally long identifiers. For example, the +input @litchar{int->int;} is parsed as four H-expressions represented +by symbols: @scheme['int], @scheme['->], @scheme['int], and +@scheme['|;|]. + +@; ---------------------------------------------------------------------- + +@subsection[#:tag "honu:strings"]{Strings} + +The syntax for an H-expression string is exactly the same as for an +S-expression string, and an H-expression string is represented by the +obvious Scheme string. + +@; ---------------------------------------------------------------------- + +@subsection[#:tag "honu:chars"]{Characters} + +The syntax for an H-expression character is the same as for an +H-expression string that has a single content character, except that a +@litchar{'} surrounds the character instead of @litchar{"}. The +S-expression representation of an H-expression character is the +obvious Scheme character. + +@; ---------------------------------------------------------------------- + +@subsection[#:tag "honu:parens"]{Parentheses, Brackets, and Braces} + +A H-expression between @litchar{(} and @litchar{)}, @litchar["["] and +@litchar["]"], or @litchar["{"] and @litchar["}"] is represented by a +Scheme list. The first element of the list is @scheme['#%parens] for a +@litchar{(}...@litchar{)} sequence, @scheme['#%brackets] for a +@litchar["["]...@litchar["]"] sequence, or @scheme['#%braces] for a +@litchar["{"]...@litchar["}"] sequence. The remaining elements are the +Scheme representations for the grouped H-expressions in order. + +In an H-expression sequence, when a @litchar{<} is followed by a +@litchar{>}, and when nothing between the @litchar{<} and @litchar{>} +is an immediate symbol containing a @litchar{=}, @litchar{&}, or +@litchar{|}, then the sub-sequence is represented by a Scheme list +that starts with @scheme['#%angles] and continues with the elements of +the sub-sequence between the @litchar{<} and @litchar{>} +(exclusive). This representation is applied recursively, so that angle +brackets can be nested. + +An angle-bracketed sequence by itself is not a single H-expression, +since the @litchar{<} by itself is a single H-expression; the +angle-bracket conversion is performed only when representing sequences +of H-expressions. + +Symbols with a @litchar{=}, @litchar{&}, or @litchar{|} prevent +angle-bracket formation because they correspond to operators that +normally have lower or equal precedence compared to less-than and +greater-than operators. + +@; ---------------------------------------------------------------------- + +@subsection[#:tag "honu:comments"]{Comments} + +An H-expression comment starts with either @litchar{//} or +@litchar{/*}. In the former case, the comment runs until a linefeed or +return. In the second case, the comment runs until @litchar{*/}, but +@litchar{/*}...@litchar{*/} comments can be nested. Comments are +treated like whitespace. + +A @litchar{#;} starts an H-expression comment, as in S-expressions. It +is followed by an H-expression to be treated as whitespace. Note that +@litchar{#;} is equivalent to @litchar{#sx#;#hx}. + +@; ---------------------------------------------------------------------- + +@subsection{Honu Output Printing} + +Some Scheme values have a standard H-expression representation. For +values with no H-expression representation but with a +@scheme[read]able S-expression form, the Scheme printer produces an +S-expression prefixed with @litchar{#sx}. For values with neither an +H-expression form nor a @scheme[read]able S-expression form, then +printer produces output of the form @litchar{#<}...@litchar{>}, as in +Scheme mode. The @scheme[print-honu] parameter controls whether +Scheme's printer produces Scheme or Honu output. + +The values with H-expression forms are as follows: + +@itemize{ + + @item{Every real number has an H-expression form, although the + representation for an exact, non-integer rational number is + actually three H-expressions, where the middle H-expression is + @scheme[/].} + + @item{Every character string is represented the same in H-expression + form as its S-expression form.} + + @item{Every character is represented like a single-character string, + but (1) using a @litchar{'} as the delimiter instead of + @litchar{"}, and (2) protecting a @litchar{'} character content + with a @litchar{\} instead of protecting @litchar{"} character + content.} + + @item{A list is represented with the H-expression sequence + @litchar{list(}@nonterm{v}@|lcomma|...@litchar{)}, + where each @nonterm{v} is the representation of each element of + the list.} + + @item{A pair that is not a list is represented with the H-expression + sequence + @litchar{cons(}@nonterm{v1}@|lcomma|@nonterm{v2}@litchar{)}, + where @nonterm{v1} and @nonterm{v2} are the representations of + the pair elements.} + + @item{A vector's representation depends on the value of the + @scheme[print-vector-length] parameter. If it is @scheme[#f], + the vector is represented with the H-expression sequence + @litchar{vectorN(}@nonterm{v}@|lcomma|...@litchar{)}, where + each @nonterm{v} is the representation of each element of the + vector. If @scheme[print-vector-length] is set to @scheme[#t], + the vector is represented with the H-expression sequence + @litchar{vectorN(}@nonterm{n}@|lcomma|@nonterm{v}@|lcomma|...@litchar{)}, + where @nonterm{n} is the length of the vector and each + @nonterm{v} is the representation of each element of the + vector, and multiple instances of the same value at the end of + the vector are represented by a single @nonterm{v}.} + + @item{The empty list is represented as the H-expression + @litchar{null}.} + + @item{True is represented as the H-expression @litchar{true}.} + + @item{False is represented as the H-expression @litchar{false}.} + +} diff --git a/collects/scribblings/honu/info.ss b/collects/scribblings/honu/info.ss new file mode 100644 index 0000000000..d589b0fe77 --- /dev/null +++ b/collects/scribblings/honu/info.ss @@ -0,0 +1,4 @@ +(module info setup/infotab + (define name "Scribblings: Honu") + (define scribblings '(("honu.scrbl" (multi-page main-doc))))) +