Diff for /gforth/doc/vmgen.texi between versions 1.13 and 1.16

version 1.13, 2002/08/19 07:38:16 version 1.16, 2002/08/21 09:36:01
Line 615  The grammar is in EBNF format, with @cod Line 615  The grammar is in EBNF format, with @cod
 of @var{c} and @code{[@var{d}]} meaning 0 or 1 repetitions of @var{d}.  of @var{c} and @code{[@var{d}]} meaning 0 or 1 repetitions of @var{d}.
   
 @cindex free-format, not  @cindex free-format, not
   @cindex newlines, significance in syntax
 Vmgen input is not free-format, so you have to take care where you put  Vmgen input is not free-format, so you have to take care where you put
 spaces and especially newlines; it's not as bad as makefiles, though:  newlines (and, in a few cases, white space).
 any sequence of spaces and tabs is equivalent to a single space.  
   
 @example  @example
 description: @{instruction|comment|eval-escape@}  description: @{instruction|comment|eval-escape|c-escape@}
   
 instruction: simple-inst|superinst  instruction: simple-inst|superinst
   
 simple-inst: ident ' (' stack-effect ' )' newline c-code newline newline  simple-inst: ident '(' stack-effect ')' newline c-code newline newline
   
 stack-effect: @{ident@} ' --' @{ident@}  stack-effect: @{ident@} '--' @{ident@}
   
 super-inst: ident ' =' ident @{ident@}    super-inst: ident '=' ident @{ident@}  
   
 comment:      '\ '  text newline  comment:      '\ '  text newline
   
 eval-escape:  '\E ' text newline  eval-escape:  '\E ' text newline
   
   c-escape:     '\C ' text newline
 @end example  @end example
 @c \+ \- \g \f \c  @c \+ \- \g \f \c
   
 Note that the @code{\}s in this grammar are meant literally, not as  Note that the @code{\}s in this grammar are meant literally, not as
 C-style encodings for non-printable characters.  C-style encodings for non-printable characters.
   
 The C code in @code{simple-inst} must not contain empty lines (because  There are two ways to delimit the C code in @code{simple-inst}:
 Vmgen would mistake that as the end of the simple-inst.  The text in  
 @code{comment} and @code{eval-escape} must not contain a newline.  @itemize @bullet
 @code{Ident} must conform to the usual conventions of C identifiers  
 (otherwise the C compiler would choke on the Vmgen output).  @item
   If you start it with a @samp{@{} at the start of a line (i.e., not even
   white space before it), you have to end it with a @samp{@}} at the start
   of a line (followed by a newline).  In this case you may have empty
   lines within the C code (typically used between variable definitions and
   statements).
   
   @item
   You do not start it with @samp{@{}.  Then the C code ends at the first
   empty line, so you cannot have empty lines within this code.
   
   @end itemize
   
   The text in @code{comment}, @code{eval-escape} and @code{c-escape} must
   not contain a newline.  @code{Ident} must conform to the usual
   conventions of C identifiers (otherwise the C compiler would choke on
   the Vmgen output), except that idents in @code{stack-effect} may have a
   stack prefix (for stack prefix syntax, @pxref{Eval escapes}).
   
   @cindex C escape
   @cindex @code{\C}
   @cindex conditional compilation of Vmgen output
   The @code{c-escape} passes the text through to each output file (without
   the @samp{\C}).  This is useful mainly for conditional compilation
   (i.e., you write @samp{\C #if ...} etc.).
   
   @cindex sync lines
   @cindex @code{#line}
   In addition to the syntax given in the grammer, Vmgen also processes
   sync lines (lines starting with @samp{#line}), as produced by @samp{m4
   -s} (@pxref{Invoking m4, , Invoking m4, m4.info, GNU m4}) and similar
   tools.  This allows associating C compiler error messages with the
   original source of the C code.
   
 Vmgen understands a few extensions beyond the grammar given here, but  Vmgen understands a few extensions beyond the grammar given here, but
 these extensions are only useful for building Gforth.  You can find a  these extensions are only useful for building Gforth.  You can find a
Line 652  description of the format used for Gfort Line 686  description of the format used for Gfort
 @subsection Eval escapes  @subsection Eval escapes
 @cindex escape to Forth  @cindex escape to Forth
 @cindex eval escape  @cindex eval escape
   @cindex @code{\E}
   
   
 @c woanders?  @c woanders?
 The text in @code{eval-escape} is Forth code that is evaluated when  The text in @code{eval-escape} is Forth code that is evaluated when
Line 677  Note that the syntax of this code is not Line 710  Note that the syntax of this code is not
 many other Forth program fragments that could be written in an  many other Forth program fragments that could be written in an
 eval-escape).  eval-escape).
   
   A stack prefix can contain letters, digits, or @samp{:}, and may start
   with an @samp{#}; e.g., in Gforth the return stack has the stack prefix
   @samp{R:}.  This restriction is not checked during the stack prefix
   definition, but it is enforced by the parsing rules for stack items
   later.
   
 If you know Forth, the stack effects of the non-standard words involved  If you know Forth, the stack effects of the non-standard words involved
 are:  are:
 @findex stack  @findex stack
Line 687  are: Line 726  are:
 @example  @example
 stack        ( "name" "pointer" "type" -- )  stack        ( "name" "pointer" "type" -- )
              ( name execution: -- stack )               ( name execution: -- stack )
 type-prefix  ( addr u xt1 xt2 n stack "prefix" -- )  type-prefix  ( addr u item-size stack "prefix" -- )
 single       ( -- xt1 xt2 n )  single       ( -- item-size )
 double       ( -- xt1 xt2 n )  double       ( -- item-size )
 stack-prefix ( stack "prefix" -- )  stack-prefix ( stack "prefix" -- )
 @end example  @end example
   
   An @var{item-size} takes three cells on the stack.
   
 @c --------------------------------------------------------------------  @c --------------------------------------------------------------------
 @node Simple instructions, Superinstructions, Input File Grammar, Input File Format  @node Simple instructions, Superinstructions, Input File Grammar, Input File Format
Line 1061  defining its direct prefix (e.g., @code{ Line 1101  defining its direct prefix (e.g., @code{
 If you are using a preprocessor (e.g., @command{m4}) to generate Vmgen  If you are using a preprocessor (e.g., @command{m4}) to generate Vmgen
 input code, you may want to create @code{#line} directives (aka sync  input code, you may want to create @code{#line} directives (aka sync
 lines).  This error indicates that such a line is not in th syntax  lines).  This error indicates that such a line is not in th syntax
 expected by Vmgen (this should not happen).  expected by Vmgen (this should not happen; please report the offending
   line in a bug report).
   
 @cindex @code{syntax error, wrong char} error  @cindex @code{syntax error, wrong char} error
 @cindex syntax error, wrong char  @cindex syntax error, wrong char
 A syntax error.  Note that Vmgen is sometimes anal retentive about white  A syntax error.  If you do not see right away where the error is, it may
 space, especially about newlines.  be helpful to check the following: Did you put an empty line in a VM
   instruction where the C code is not delimited by braces (then the empty
   line ends the VM instruction)?  If you used brace-delimited C code, did
   you put the delimiting braces (and only those) at the start of the line,
   without preceding white space?  Did you forget a delimiting brace?
   
 @cindex @code{too many stacks} error  @cindex @code{too many stacks} error
 @item too many stacks  @item too many stacks
 Vmgen currently supports 4 stacks; if you need more, let us know.  Vmgen currently supports 3 stacks (plus the instruction stream); if you
   need more, let us know.
   
 @cindex @code{unknown prefix} error  @cindex @code{unknown prefix} error
 @item unknown prefix  @item unknown prefix

Removed from v.1.13  
changed lines
  Added in v.1.16


FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>