gforth/doc/vmgen.texi - diff

Return to vmgen.texi CVS log

Up to [gforth] / gforth / doc

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

version 1.13, 2002/08/19 07:38:16	version 1.17, 2002/08/22 20:07:33
Line 87 Input File Format	Line 87 Input File Format
* Superinstructions::	* Superinstructions::
* Register Machines:: How to define register VM instructions	* Register Machines:: How to define register VM instructions

	Input File Grammar

	* Eval escapes:: what follows \E

Simple instructions	Simple instructions

* C Code Macros:: Macros recognized by Vmgen	* C Code Macros:: Macros recognized by Vmgen
Line 615 The grammar is in EBNF format, with @cod	Line 619 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
description of the format used for Gforth in @file{prim}.	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	@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 719 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 735 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 1110 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
Line 1691 please let us know.	Line 1746 please let us know.
@chapter Changes	@chapter Changes
@cindex Changes from old versions	@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	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	several things in their source code to use the current version. I
recommend keeping the gforth-0.5.9-20010501 version until you have	recommend keeping the gforth-0.5.9-20010501 version until you have
Line 1725 Also some new macros have to be defined,	Line 1791 Also some new macros have to be defined,
@node Contact, Copying This Manual, Changes, Top	@node Contact, Copying This Manual, Changes, Top
@chapter Contact	@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 ***********************************************************	@c ***********************************************************
@node Copying This Manual, Index, Contact, Top	@node Copying This Manual, Index, Contact, Top
@appendix Copying This Manual	@appendix Copying This Manual

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

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