add honu mini docs
svn: r8056
This commit is contained in:
Matthew Flatt
parent
e3b4751adb
commit
444e2abd12
236
collects/scribblings/honu/honu.scrbl
Normal file
236
collects/scribblings/honu/honu.scrbl
Normal file
|
|
@ -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}.}
|
||||||
|
|
||||||
|
}
|
||||||
4
collects/scribblings/honu/info.ss
Normal file
4
collects/scribblings/honu/info.ss
Normal file
|
|
@ -0,0 +1,4 @@
|
||||||
|
(module info setup/infotab
|
||||||
|
(define name "Scribblings: Honu")
|
||||||
|
(define scribblings '(("honu.scrbl" (multi-page main-doc)))))
|
||||||
|
|
||||||
Loading…
Reference in New Issue
Block a user