--- gforth/doc/vmgen.texi 2002/08/19 07:38:16 1.13 +++ gforth/doc/vmgen.texi 2002/08/22 20:07:33 1.17 @@ -87,6 +87,10 @@ Input File Format * Superinstructions:: * Register Machines:: How to define register VM instructions +Input File Grammar + +* Eval escapes:: what follows \E + Simple instructions * C Code Macros:: Macros recognized by Vmgen @@ -615,45 +619,83 @@ The grammar is in EBNF format, with @cod of @var{c} and @code{[@var{d}]} meaning 0 or 1 repetitions of @var{d}. @cindex free-format, not +@cindex newlines, significance in syntax 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: -any sequence of spaces and tabs is equivalent to a single space. +newlines (and, in a few cases, white space). @example -description: @{instruction|comment|eval-escape@} +description: @{instruction|comment|eval-escape|c-escape@} 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 eval-escape: '\E ' text newline + +c-escape: '\C ' text newline @end example @c \+ \- \g \f \c Note that the @code{\}s in this grammar are meant literally, not as C-style encodings for non-printable characters. -The C code in @code{simple-inst} must not contain empty lines (because -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. -@code{Ident} must conform to the usual conventions of C identifiers -(otherwise the C compiler would choke on the Vmgen output). +There are two ways to delimit the C code in @code{simple-inst}: + +@itemize @bullet + +@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 these extensions are only useful for building Gforth. You can find a description of the format used for Gforth in @file{prim}. +@menu +* Eval escapes:: what follows \E +@end menu + +@node Eval escapes, , Input File Grammar, Input File Grammar @subsection Eval escapes @cindex escape to Forth @cindex eval escape - - +@cindex @code{\E} @c woanders? The text in @code{eval-escape} is Forth code that is evaluated when @@ -677,6 +719,12 @@ Note that the syntax of this code is not many other Forth program fragments that could be written in an 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 are: @findex stack @@ -687,12 +735,13 @@ are: @example stack ( "name" "pointer" "type" -- ) ( name execution: -- stack ) -type-prefix ( addr u xt1 xt2 n stack "prefix" -- ) -single ( -- xt1 xt2 n ) -double ( -- xt1 xt2 n ) +type-prefix ( addr u item-size stack "prefix" -- ) +single ( -- item-size ) +double ( -- item-size ) stack-prefix ( stack "prefix" -- ) @end example +An @var{item-size} takes three cells on the stack. @c -------------------------------------------------------------------- @node Simple instructions, Superinstructions, Input File Grammar, Input File Format @@ -1061,16 +1110,22 @@ defining its direct prefix (e.g., @code{ 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 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 syntax error, wrong char -A syntax error. Note that Vmgen is sometimes anal retentive about white -space, especially about newlines. +A syntax error. If you do not see right away where the error is, it may +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 @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 @item unknown prefix @@ -1691,6 +1746,17 @@ please let us know. @chapter Changes @cindex Changes from old versions +Use-visible changes between 0.5.9-20010501 and 0.5.9-20020822: + +There is now a manual (in info, HTML, Postscript, or plain text format). + +There is the vmgen-ex2 variant of the vmgen-ex example; the new +variant uses a union type instead of lots of casting. + +Both variants of the example can now be compiled with an ANSI C compiler +(using switch dispatch and losing quite a bit of performance); tested +with @command{lcc}. + Users of the gforth-0.5.9-20010501 version of Vmgen need to change several things in their source code to use the current version. I recommend keeping the gforth-0.5.9-20010501 version until you have @@ -1725,6 +1791,16 @@ Also some new macros have to be defined, @node Contact, Copying This Manual, Changes, Top @chapter Contact +To report a bug, use +@url{https://savannah.gnu.org/bugs/?func=addbug&group_id=2672}. + +For discussion on Vmgen (e.g., how to use it), use the mailing list +@email{bug-vmgen@@mail.freesoftware.fsf.org} (use +@url{http://mail.gnu.org/mailman/listinfo/help-vmgen} to subscribe). + +You can find vmgen information at +@url{http://www.complang.tuwien.ac.at/anton/vmgen/}. + @c *********************************************************** @node Copying This Manual, Index, Contact, Top @appendix Copying This Manual