gforth: gforth/doc/gforth.ds

Diff for /gforth/doc/gforth.ds between version 1.92 and 1.116

-version 1.92, Thu Jan 18 14:57:37 2001 UTC
+version 1.116, Sat Mar 22 10:04:08 2003 UTC
  Line 11
  Line 11
  Line 11
  @c          Not an improvement IMO - anton
  @c          and anyway, this should be taken up
  @c          with Karl Berry (the texinfo guy) - anton
+ @c
+ @c Karl Berry writes:
+ @c  If they don't like the all-caps for @var Info output, all I can say is
+ @c  that it's always been that way, and the usage of all-caps for
+ @c  metavariables has a long tradition.  I think it's best to just let it be
+ @c  what it is, for the sake of consistency among manuals.
+ @c
  @comment .. would be useful to have a word that identified all deferred words
  @comment should semantics stuff in intro be moved to another section
- Line 18
+ Line 25
  Line 18
  Line 25
  @comment %**start of header (This is for running Texinfo on a region.)
  @setfilename gforth.info
+ @include version.texi
  @settitle Gforth Manual
- @dircategory GNU programming tools
+ @c @syncodeindex pg cp
- @direntry
- * Gforth: (gforth).             A fast interpreter for the Forth language.
- @end direntry
- @c The Texinfo manual also recommends doing this, but for Gforth it may
- @c  not make much sense
- @c @dircategory Individual utilities
- @c @direntry
- @c * Gforth: (gforth)Invoking Gforth.      gforth, gforth-fast, gforthmi
- @c @end direntry
- @comment @setchapternewpage odd
- @comment TODO this gets left in by HTML converter
  @macro progstyle {}
  Programming style note:
  @end macro
- Line 44
+ Line 41
  Line 44
  Line 41
  @end table
  @end macro
- @comment %**end of header (This is for running Texinfo on a region.)
- @comment ----------------------------------------------------------
  @comment macros for beautifying glossary entries
- @comment if these are used, need to strip them out for HTML converter
- @comment else they get repeated verbatim in HTML output.
- @comment .. not working yet.
  @macro GLOSS-START {}
  @iftex
  @ninerm
- Line 65
+ Line 54
  Line 65
  Line 54
  @end iftex
  @end macro
- @comment ----------------------------------------------------------
+ @comment %**end of header (This is for running Texinfo on a region.)
+ @copying
+ This manual is for Gforth
- @include version.texi
+ (version @value{VERSION}, @value{UPDATED}),
+ a fast and portable implementation of the ANS Forth language
- @ifnottex
+ Copyright @copyright{} 1995, 1996, 1997, 1998, 2000, 2003 Free Software Foundation, Inc.
- This file documents Gforth @value{VERSION}
- Copyright @copyright{} 1995--2000 Free Software Foundation, Inc.
+ @quotation
+ Permission is granted to copy, distribute and/or modify this document
+ under the terms of the GNU Free Documentation License, Version 1.1 or
+ any later version published by the Free Software Foundation; with no
+ Invariant Sections, with the Front-Cover texts being ``A GNU Manual,''
+ and with the Back-Cover Texts as in (a) below.  A copy of the
+ license is included in the section entitled ``GNU Free Documentation
+ License.''
+ (a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
+ this GNU Manual, like GNU software.  Copies published by the Free
+ Software Foundation raise funds for GNU development.''
+ @end quotation
+ @end copying
-      Permission is granted to make and distribute verbatim copies of
+ @dircategory Software development
-      this manual provided the copyright notice and this permission notice
+ @direntry
-      are preserved on all copies.
+ * Gforth: (gforth).             A fast interpreter for the Forth language.
+ @end direntry
- @ignore
+ @c The Texinfo manual also recommends doing this, but for Gforth it may
-      Permission is granted to process this file through TeX and print the
+ @c  not make much sense
-      results, provided the printed document carries a copying permission
+ @c @dircategory Individual utilities
-      notice identical to this one except for the removal of this paragraph
+ @c @direntry
-      (this paragraph not being relevant to the printed manual).
+ @c * Gforth: (gforth)Invoking Gforth.      gforth, gforth-fast, gforthmi
+ @c @end direntry
- @end ignore
-      Permission is granted to copy and distribute modified versions of this
-      manual under the conditions for verbatim copying, provided also that the
-      sections entitled "Distribution" and "General Public License" are
-      included exactly as in the original, and provided that the entire
-      resulting derived work is distributed under the terms of a permission
-      notice identical to this one.
-      Permission is granted to copy and distribute translations of this manual
-      into another language, under the above conditions for modified versions,
-      except that the sections entitled "Distribution" and "General Public
-      License" may be included in a translation approved by the author instead
-      of in the original English.
- @end ifnottex
- @finalout
  @titlepage
- @sp 10
+ @title Gforth
- @center @titlefont{Gforth Manual}
+ @subtitle for version @value{VERSION}, @value{UPDATED}
- @sp 2
+ @author Neal Crook
- @center for version @value{VERSION}
+ @author Anton Ertl
- @sp 2
+ @author David Kuehling
- @center Neal Crook
+ @author Bernd Paysan
- @center Anton Ertl
+ @author Jens Wilke
- @center Bernd Paysan
- @center Jens Wilke
- @sp 3
- @center This manual is permanently under construction and was last updated on 15-Mar-2000
- @comment  The following two commands start the copyright page.
  @page
  @vskip 0pt plus 1filll
- Copyright @copyright{} 1995--2000 Free Software Foundation, Inc.
+ @insertcopying
- @comment !! Published by ... or You can get a copy of this manual ...
-      Permission is granted to make and distribute verbatim copies of
-      this manual provided the copyright notice and this permission notice
-      are preserved on all copies.
-      Permission is granted to copy and distribute modified versions of this
-      manual under the conditions for verbatim copying, provided also that the
-      sections entitled "Distribution" and "General Public License" are
-      included exactly as in the original, and provided that the entire
-      resulting derived work is distributed under the terms of a permission
-      notice identical to this one.
-      Permission is granted to copy and distribute translations of this manual
-      into another language, under the above conditions for modified versions,
-      except that the sections entitled "Distribution" and "General Public
-      License" may be included in a translation approved by the author instead
-      of in the original English.
  @end titlepage
- @node Top, License, (dir), (dir)
+ @contents
  @ifnottex
- Gforth is a free implementation of ANS Forth available on many
+ @node Top, Goals, (dir), (dir)
- personal machines. This manual corresponds to version @value{VERSION}.
+ @top Gforth
+ @insertcopying
  @end ifnottex
  @menu
- * License::                     The GPL
  * Goals::                       About the Gforth Project
  * Gforth Environment::          Starting (and exiting) Gforth
  * Tutorial::                    Hands-on Forth Tutorial
- Line 161
+ Line 125
  Line 161
  Line 125
  * Emacs and Gforth::            The Gforth Mode
  * Image Files::                 @code{.fi} files contain compiled code
  * Engine::                      The inner interpreter and the primitives
- * Binding to System Library::
  * Cross Compiler::              The Cross Compiler
  * Bugs::                        How to report them
  * Origin::                      Authors and ancestors of Gforth
  * Forth-related information::   Books and places to look on the WWW
+ * Licenses::
  * Word Index::                  An item for each Forth word
  * Concept Index::               A menu covering many topics
- Line 179
+ Line 143
  Line 179
  Line 143
  * Command-line editing::
  * Environment variables::       that affect how Gforth starts up
  * Gforth Files::                What gets installed and where
+ * Gforth in pipes::
  * Startup speed::               When 35ms is not fast enough ...
  Forth Tutorial
- Line 246
+ Line 211
  Line 246
  Line 211
  * Tokens for Words::
  * Compiling words::
  * The Text Interpreter::
+ * The Input Stream::
  * Word Lists::
  * Environmental Queries::
  * Files::
- Line 362
+ Line 328
  Line 362
  Line 328
  * String Formats::              How Forth stores strings in memory
  * Displaying characters and strings::  Other stuff
  * Input::                       Input
+ * Pipes::                       How to create your own pipes
  Locals
- Line 511
+ Line 478
  Line 511
  Line 478
  * search-idef::                 Implementation Defined Options
  * search-ambcond::              Ambiguous Conditions
+ Emacs and Gforth
+ * Installing gforth.el::        Making Emacs aware of Forth.
+ * Emacs Tags::                  Viewing the source of a word in Emacs.
+ * Hilighting::                  Making Forth code look prettier.
+ * Auto-Indentation::            Customizing auto-indentation.
+ * Blocks Files::                Reading and writing blocks files.
  Image Files
  * Image Licensing Issues::      Distribution terms for images.
- Line 538
+ Line 513
  Line 538
  Line 513
  * Scheduling::
  * Direct or Indirect Threaded?::
+ * Dynamic Superinstructions::
  * DOES>::
  Primitives
- Line 551
+ Line 527
  Line 551
  Line 527
  * Using the Cross Compiler::
  * How the Cross Compiler Works::
- @end detailmenu
+ Licenses
- @end menu
- @node License, Goals, Top, Top
- @unnumbered GNU GENERAL PUBLIC LICENSE
- @center Version 2, June 1991
- @display
- Copyright @copyright{} 1989, 1991 Free Software Foundation, Inc.
-Temple Place, Suite 330, Boston, MA 02111, USA
- Everyone is permitted to copy and distribute verbatim copies
- of this license document, but changing it is not allowed.
- @end display
- @unnumberedsec Preamble
-   The licenses for most software are designed to take away your
- freedom to share and change it.  By contrast, the GNU General Public
- License is intended to guarantee your freedom to share and change free
- software---to make sure the software is free for all its users.  This
- General Public License applies to most of the Free Software
- Foundation's software and to any other program whose authors commit to
- using it.  (Some other Free Software Foundation software is covered by
- the GNU Library General Public License instead.)  You can apply it to
- your programs, too.
-   When we speak of free software, we are referring to freedom, not
- price.  Our General Public Licenses are designed to make sure that you
- have the freedom to distribute copies of free software (and charge for
- this service if you wish), that you receive source code or can get it
- if you want it, that you can change the software or use pieces of it
- in new free programs; and that you know you can do these things.
-   To protect your rights, we need to make restrictions that forbid
- anyone to deny you these rights or to ask you to surrender the rights.
- These restrictions translate to certain responsibilities for you if you
- distribute copies of the software, or if you modify it.
-   For example, if you distribute copies of such a program, whether
- gratis or for a fee, you must give the recipients all the rights that
- you have.  You must make sure that they, too, receive or can get the
- source code.  And you must show them these terms so they know their
- rights.
-   We protect your rights with two steps: (1) copyright the software, and
- (2) offer you this license which gives you legal permission to copy,
- distribute and/or modify the software.
-   Also, for each author's protection and ours, we want to make certain
- that everyone understands that there is no warranty for this free
- software.  If the software is modified by someone else and passed on, we
- want its recipients to know that what they have is not the original, so
- that any problems introduced by others will not reflect on the original
- authors' reputations.
-   Finally, any free program is threatened constantly by software
- patents.  We wish to avoid the danger that redistributors of a free
- program will individually obtain patent licenses, in effect making the
- program proprietary.  To prevent this, we have made it clear that any
- patent must be licensed for everyone's free use or not licensed at all.
-   The precise terms and conditions for copying, distribution and
- modification follow.
- @iftex
+ * GNU Free Documentation License::  License for copying this manual.
- @unnumberedsec TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
+ * Copying::                         GPL (for copying this software).
- @end iftex
- @ifnottex
- @center TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
- @end ifnottex
- @enumerate 0
- @item
- This License applies to any program or other work which contains
- a notice placed by the copyright holder saying it may be distributed
- under the terms of this General Public License.  The ``Program'', below,
- refers to any such program or work, and a ``work based on the Program''
- means either the Program or any derivative work under copyright law:
- that is to say, a work containing the Program or a portion of it,
- either verbatim or with modifications and/or translated into another
- language.  (Hereinafter, translation is included without limitation in
- the term ``modification''.)  Each licensee is addressed as ``you''.
- Activities other than copying, distribution and modification are not
- covered by this License; they are outside its scope.  The act of
- running the Program is not restricted, and the output from the Program
- is covered only if its contents constitute a work based on the
- Program (independent of having been made by running the Program).
- Whether that is true depends on what the Program does.
- @item
- You may copy and distribute verbatim copies of the Program's
- source code as you receive it, in any medium, provided that you
- conspicuously and appropriately publish on each copy an appropriate
- copyright notice and disclaimer of warranty; keep intact all the
- notices that refer to this License and to the absence of any warranty;
- and give any other recipients of the Program a copy of this License
- along with the Program.
- You may charge a fee for the physical act of transferring a copy, and
- you may at your option offer warranty protection in exchange for a fee.
- @item
- You may modify your copy or copies of the Program or any portion
- of it, thus forming a work based on the Program, and copy and
- distribute such modifications or work under the terms of Section 1
- above, provided that you also meet all of these conditions:
- @enumerate a
- @item
- You must cause the modified files to carry prominent notices
- stating that you changed the files and the date of any change.
- @item
- You must cause any work that you distribute or publish, that in
- whole or in part contains or is derived from the Program or any
- part thereof, to be licensed as a whole at no charge to all third
- parties under the terms of this License.
- @item
- If the modified program normally reads commands interactively
- when run, you must cause it, when started running for such
- interactive use in the most ordinary way, to print or display an
- announcement including an appropriate copyright notice and a
- notice that there is no warranty (or else, saying that you provide
- a warranty) and that users may redistribute the program under
- these conditions, and telling the user how to view a copy of this
- License.  (Exception: if the Program itself is interactive but
- does not normally print such an announcement, your work based on
- the Program is not required to print an announcement.)
- @end enumerate
- These requirements apply to the modified work as a whole.  If
- identifiable sections of that work are not derived from the Program,
- and can be reasonably considered independent and separate works in
- themselves, then this License, and its terms, do not apply to those
- sections when you distribute them as separate works.  But when you
- distribute the same sections as part of a whole which is a work based
- on the Program, the distribution of the whole must be on the terms of
- this License, whose permissions for other licensees extend to the
- entire whole, and thus to each and every part regardless of who wrote it.
- Thus, it is not the intent of this section to claim rights or contest
- your rights to work written entirely by you; rather, the intent is to
- exercise the right to control the distribution of derivative or
- collective works based on the Program.
- In addition, mere aggregation of another work not based on the Program
- with the Program (or with a work based on the Program) on a volume of
- a storage or distribution medium does not bring the other work under
- the scope of this License.
- @item
- You may copy and distribute the Program (or a work based on it,
- under Section 2) in object code or executable form under the terms of
- Sections 1 and 2 above provided that you also do one of the following:
- @enumerate a
- @item
- Accompany it with the complete corresponding machine-readable
- source code, which must be distributed under the terms of Sections
-and 2 above on a medium customarily used for software interchange; or,
- @item
- Accompany it with a written offer, valid for at least three
- years, to give any third party, for a charge no more than your
- cost of physically performing source distribution, a complete
- machine-readable copy of the corresponding source code, to be
- distributed under the terms of Sections 1 and 2 above on a medium
- customarily used for software interchange; or,
- @item
- Accompany it with the information you received as to the offer
- to distribute corresponding source code.  (This alternative is
- allowed only for noncommercial distribution and only if you
- received the program in object code or executable form with such
- an offer, in accord with Subsection b above.)
- @end enumerate
- The source code for a work means the preferred form of the work for
+ @end detailmenu
- making modifications to it.  For an executable work, complete source
+ @end menu
- code means all the source code for all modules it contains, plus any
- associated interface definition files, plus the scripts used to
- control compilation and installation of the executable.  However, as a
- special exception, the source code distributed need not include
- anything that is normally distributed (in either source or binary
- form) with the major components (compiler, kernel, and so on) of the
- operating system on which the executable runs, unless that component
- itself accompanies the executable.
- If distribution of executable or object code is made by offering
- access to copy from a designated place, then offering equivalent
- access to copy the source code from the same place counts as
- distribution of the source code, even though third parties are not
- compelled to copy the source along with the object code.
- @item
- You may not copy, modify, sublicense, or distribute the Program
- except as expressly provided under this License.  Any attempt
- otherwise to copy, modify, sublicense or distribute the Program is
- void, and will automatically terminate your rights under this License.
- However, parties who have received copies, or rights, from you under
- this License will not have their licenses terminated so long as such
- parties remain in full compliance.
- @item
- You are not required to accept this License, since you have not
- signed it.  However, nothing else grants you permission to modify or
- distribute the Program or its derivative works.  These actions are
- prohibited by law if you do not accept this License.  Therefore, by
- modifying or distributing the Program (or any work based on the
- Program), you indicate your acceptance of this License to do so, and
- all its terms and conditions for copying, distributing or modifying
- the Program or works based on it.
- @item
- Each time you redistribute the Program (or any work based on the
- Program), the recipient automatically receives a license from the
- original licensor to copy, distribute or modify the Program subject to
- these terms and conditions.  You may not impose any further
- restrictions on the recipients' exercise of the rights granted herein.
- You are not responsible for enforcing compliance by third parties to
- this License.
- @item
- If, as a consequence of a court judgment or allegation of patent
- infringement or for any other reason (not limited to patent issues),
- conditions are imposed on you (whether by court order, agreement or
- otherwise) that contradict the conditions of this License, they do not
- excuse you from the conditions of this License.  If you cannot
- distribute so as to satisfy simultaneously your obligations under this
- License and any other pertinent obligations, then as a consequence you
- may not distribute the Program at all.  For example, if a patent
- license would not permit royalty-free redistribution of the Program by
- all those who receive copies directly or indirectly through you, then
- the only way you could satisfy both it and this License would be to
- refrain entirely from distribution of the Program.
- If any portion of this section is held invalid or unenforceable under
- any particular circumstance, the balance of the section is intended to
- apply and the section as a whole is intended to apply in other
- circumstances.
- It is not the purpose of this section to induce you to infringe any
- patents or other property right claims or to contest validity of any
- such claims; this section has the sole purpose of protecting the
- integrity of the free software distribution system, which is
- implemented by public license practices.  Many people have made
- generous contributions to the wide range of software distributed
- through that system in reliance on consistent application of that
- system; it is up to the author/donor to decide if he or she is willing
- to distribute software through any other system and a licensee cannot
- impose that choice.
- This section is intended to make thoroughly clear what is believed to
- be a consequence of the rest of this License.
- @item
- If the distribution and/or use of the Program is restricted in
- certain countries either by patents or by copyrighted interfaces, the
- original copyright holder who places the Program under this License
- may add an explicit geographical distribution limitation excluding
- those countries, so that distribution is permitted only in or among
- countries not thus excluded.  In such case, this License incorporates
- the limitation as if written in the body of this License.
- @item
- The Free Software Foundation may publish revised and/or new versions
- of the General Public License from time to time.  Such new versions will
- be similar in spirit to the present version, but may differ in detail to
- address new problems or concerns.
- Each version is given a distinguishing version number.  If the Program
- specifies a version number of this License which applies to it and ``any
- later version'', you have the option of following the terms and conditions
- either of that version or of any later version published by the Free
- Software Foundation.  If the Program does not specify a version number of
- this License, you may choose any version ever published by the Free Software
- Foundation.
- @item
- If you wish to incorporate parts of the Program into other free
- programs whose distribution conditions are different, write to the author
- to ask for permission.  For software which is copyrighted by the Free
- Software Foundation, write to the Free Software Foundation; we sometimes
- make exceptions for this.  Our decision will be guided by the two goals
- of preserving the free status of all derivatives of our free software and
- of promoting the sharing and reuse of software generally.
- @iftex
- @heading NO WARRANTY
- @end iftex
- @ifnottex
- @center NO WARRANTY
- @end ifnottex
- @item
- BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
- FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW.  EXCEPT WHEN
- OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
- PROVIDE THE PROGRAM ``AS IS'' WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED
- OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
- MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.  THE ENTIRE RISK AS
- TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU.  SHOULD THE
- PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING,
- REPAIR OR CORRECTION.
- @item
- IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
- WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
- REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES,
- INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING
- OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED
- TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY
- YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER
- PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE
- POSSIBILITY OF SUCH DAMAGES.
- @end enumerate
- @iftex
- @heading END OF TERMS AND CONDITIONS
- @end iftex
- @ifnottex
- @center END OF TERMS AND CONDITIONS
- @end ifnottex
- @page
- @unnumberedsec How to Apply These Terms to Your New Programs
-   If you develop a new program, and you want it to be of the greatest
- possible use to the public, the best way to achieve this is to make it
- free software which everyone can redistribute and change under these terms.
-   To do so, attach the following notices to the program.  It is safest
- to attach them to the start of each source file to most effectively
- convey the exclusion of warranty; and each file should have at least
- the ``copyright'' line and a pointer to where the full notice is found.
- @smallexample
- @var{one line to give the program's name and a brief idea of what it does.}
- Copyright (C) 19@var{yy}  @var{name of author}
- This program is free software; you can redistribute it and/or modify
- it under the terms of the GNU General Public License as published by
- the Free Software Foundation; either version 2 of the License, or
- (at your option) any later version.
- This program is distributed in the hope that it will be useful,
- but WITHOUT ANY WARRANTY; without even the implied warranty of
- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
- GNU General Public License for more details.
- You should have received a copy of the GNU General Public License
- along with this program; if not, write to the Free Software
- Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, USA.
- @end smallexample
- Also add information on how to contact you by electronic and paper mail.
- If the program is interactive, make it output a short notice like this
- when it starts in an interactive mode:
- @smallexample
- Gnomovision version 69, Copyright (C) 19@var{yy} @var{name of author}
- Gnomovision comes with ABSOLUTELY NO WARRANTY; for details
- type `show w'.
- This is free software, and you are welcome to redistribute it
- under certain conditions; type `show c' for details.
- @end smallexample
- The hypothetical commands @samp{show w} and @samp{show c} should show
- the appropriate parts of the General Public License.  Of course, the
- commands you use may be called something other than @samp{show w} and
- @samp{show c}; they could even be mouse-clicks or menu items---whatever
- suits your program.
- You should also get your employer (if you work as a programmer) or your
- school, if any, to sign a ``copyright disclaimer'' for the program, if
- necessary.  Here is a sample; alter the names:
- @smallexample
- Yoyodyne, Inc., hereby disclaims all copyright interest in the program
- `Gnomovision' (which makes passes at compilers) written by James Hacker.
- @var{signature of Ty Coon}, 1 April 1989
- Ty Coon, President of Vice
- @end smallexample
- This General Public License does not permit incorporating your program into
- proprietary programs.  If your program is a subroutine library, you may
- consider it more useful to permit linking proprietary applications with the
- library.  If this is what you want to do, use the GNU Library General
- Public License instead of this License.
+ @c ----------------------------------------------------------
  @iftex
  @unnumbered Preface
  @cindex Preface
- Line 958
+ Line 548
  Line 958
  Line 548
  @comment TODO much more blurb here.
  @c ******************************************************************
- @node Goals, Gforth Environment, License, Top
+ @node Goals, Gforth Environment, Top, Top
  @comment node-name,     next,           previous, up
  @chapter Goals of Gforth
  @cindex goals of the Gforth project
- Line 1017
+ Line 607
  Line 1017
  Line 607
  * Command-line editing::
  * Environment variables::       that affect how Gforth starts up
  * Gforth Files::                What gets installed and where
+ * Gforth in pipes::
  * Startup speed::               When 35ms is not fast enough ...
  @end menu
- Line 1032
+ Line 623
  Line 1032
  Line 623
  @cindex flags on the command line
  Gforth is made up of two parts; an executable ``engine'' (named
- @file{gforth} or @file{gforth-fast}) and an image file. To start it, you
+ @command{gforth} or @command{gforth-fast}) and an image file. To start it, you
  will usually just say @code{gforth} -- this automatically loads the
  default image file @file{gforth.fi}. In many other cases the default
  Gforth image will be invoked like this:
- Line 1043
+ Line 634
  Line 1043
  Line 634
  This interprets the contents of the files and the Forth code in the order they
  are given.
- In addition to the @file{gforth} engine, there is also an engine called
+ In addition to the @command{gforth} engine, there is also an engine
- @file{gforth-fast}, which is faster, but gives less informative error
+ called @command{gforth-fast}, which is faster, but gives less
- messages (@pxref{Error messages}).  You should use it for debugged,
+ informative error messages (@pxref{Error messages}) and may catch some
+ stack underflows later or not at all.  You should use it for debugged,
  performance-critical programs.
+ Moreover, there is an engine called @command{gforth-itc}, which is
+ useful in some backwards-compatibility situations (@pxref{Direct or
+ Indirect Threaded?}).
  In general, the command line looks like this:
  @example
- Line 1165
+ Line 761
  Line 1165
  Line 761
  signal. This option is useful when the engine and/or the image might be
  severely broken (such that it causes another signal before recovering
  from the first); this option avoids endless loops in such cases.
+ @item --no-dynamic
+ @item --dynamic
+ Disable or enable dynamic superinstructions with replication
+ (@pxref{Dynamic Superinstructions}).
+ @item --no-super
+ Disable dynamic superinstructions, use just dynamic replication; this is
+ useful if you want to patch threaded code (@pxref{Dynamic
+ Superinstructions}).
  @end table
  @cindex loading files at startup
- Line 1327
+ Line 934
  Line 1327
  Line 934
  @comment ----------------------------------------------
- @node Gforth Files, Startup speed, Environment variables, Gforth Environment
+ @node Gforth Files, Gforth in pipes, Environment variables, Gforth Environment
  @section Gforth files
  @cindex Gforth files
- Line 1357
+ Line 964
  Line 1357
  Line 964
  @code{configure} options (listed with @code{configure --help}).
  @comment ----------------------------------------------
- @node Startup speed,  , Gforth Files, Gforth Environment
+ @node Gforth in pipes, Startup speed, Gforth Files, Gforth Environment
+ @section Gforth in pipes
+ @cindex pipes, Gforth as part of
+ Gforth can be used in pipes created elsewhere (described here).  It can
+ also create pipes on its own (@pxref{Pipes}).
+ @cindex input from pipes
+ If you pipe into Gforth, your program should read with @code{read-file}
+ or @code{read-line} from @code{stdin} (@pxref{General files}).
+ @code{Key} does not recognize the end of input.  Words like
+ @code{accept} echo the input and are therefore usually not useful for
+ reading from a pipe.  You have to invoke the Forth program with an OS
+ command-line option, as you have no chance to use the Forth command line
+ (the text interpreter would try to interpret the pipe input).
+ @cindex output in pipes
+ You can output to a pipe with @code{type}, @code{emit}, @code{cr} etc.
+ @cindex silent exiting from Gforth
+ When you write to a pipe that has been closed at the other end, Gforth
+ receives a SIGPIPE signal (``pipe broken'').  Gforth translates this
+ into the exception @code{broken-pipe-error}.  If your application does
+ not catch that exception, the system catches it and exits, usually
+ silently (unless you were working on the Forth command line; then it
+ prints an error message and exits).  This is usually the desired
+ behaviour.
+ If you do not like this behaviour, you have to catch the exception
+ yourself, and react to it.
+ Here's an example of an invocation of Gforth that is usable in a pipe:
+ @example
+ gforth -e ": foo begin pad dup 10 stdin read-file throw dup while \
+  type repeat ; foo bye"
+ @end example
+ This example just copies the input verbatim to the output.  A very
+ simple pipe containing this example looks like this:
+ @example
+ cat startup.fs |
+ gforth -e ": foo begin pad dup 80 stdin read-file throw dup while \
+  type repeat ; foo bye"|
+ head
+ @end example
+ @cindex stderr and pipes
+ Pipes involving Gforth's @code{stderr} output do not work.
+ @comment ----------------------------------------------
+ @node Startup speed,  , Gforth in pipes, Gforth Environment
  @section Startup speed
  @cindex Startup speed
  @cindex speed, startup
- Line 1371
+ Line 1030
  Line 1371
  Line 1030
  improve it; or you may consider ways to reduce the number of startups
  (for example, by using Fast-CGI).
- The first step to improve startup speed is to statically link Gforth, by
+ An easy step that influences Gforth startup speed is the use of the
+ @option{--no-dynamic} option; this decreases image loading speed, but
+ increases compile-time and run-time.
+ Another step to improve startup speed is to statically link Gforth, by
  building it with @code{XLDFLAGS=-static}.  This requires more memory for
  the code and will therefore slow down the first invocation, but
  subsequent invocations avoid the dynamic linking overhead.  Another
- Line 1696
+ Line 1359
  Line 1696
  Line 1359
  examples and short one-off code, you probably want to store your source
  code in files for convenient editing and persistence.  You can use your
  favourite editor (Gforth includes Emacs support, @pxref{Emacs and
- Gforth}) to create @var{file} and use
+ Gforth}) to create @var{file.fs} and use
  @example
- s" @var{file}" included
+ s" @var{file.fs}" included
  @end example
  to load it into your Forth system.  The file name extension I use for
- Line 1708
+ Line 1371
  Line 1708
  Line 1371
  You can easily start Gforth with some files loaded like this:
  @example
- gforth @var{file1} @var{file2}
+ gforth @var{file1.fs} @var{file2.fs}
  @end example
  If an error occurs during loading these files, Gforth terminates,
- Line 1721
+ Line 1384
  Line 1721
  Line 1384
  tests with
  @example
- gforth @var{code} @var{tests} -e bye
+ gforth @var{code.fs} @var{tests.fs} -e bye
  @end example
  (often by performing this command with @kbd{C-x C-e} in Emacs).  The
- Line 2805
+ Line 2468
  Line 2805
  Line 2468
  @end example
  @code{read-line ( addr u1 fd -- u2 flag ior )} reads up to u1 bytes into
- the buffer at addr, and returns the number of bytes read, a flag that's
+ the buffer at addr, and returns the number of bytes read, a flag that is
- true when the end of file is reached, and an error code.
+ false when the end of file is reached, and an error code.
  @code{compare ( addr1 u1 addr2 u2 -- n )} compares two strings and
  returns zero if both strings are equal. It returns a positive number if
- Line 3859
+ Line 3522
  Line 3859
  Line 3522
  the stack. What happens if you try to do a third addition? Pick up the
  first card, pick up the second card -- ah! There is no second card. This
  is called a @dfn{stack underflow} and consitutes an error. If you try to
- do the same thing with Forth it will report an error (probably a Stack
+ do the same thing with Forth it often reports an error (probably a Stack
  Underflow or an Invalid Memory Address error).
  The opposite situation to a stack underflow is a @dfn{stack overflow},
- Line 4493
+ Line 4156
  Line 4493
  Line 4156
  * Tokens for Words::
  * Compiling words::
  * The Text Interpreter::
+ * The Input Stream::
  * Word Lists::
  * Environmental Queries::
  * Files::
- Line 5359
+ Line 5023
  Line 5359
  Line 5023
  doc-fill
  doc-blank
  doc-compare
+ doc-str=
+ doc-str<
+ doc-string-prefix?
  doc-search
  doc--trailing
  doc-/string
  doc-bounds
  @comment TODO examples
- Line 6290
+ Line 5958
  Line 6290
  Line 5958
  doc-noname
  @cindex execution token of last defined word
- doc-lastxt
+ doc-latestxt
  @noindent
  The previous example can be rewritten using @code{noname} and
- @code{lastxt}:
+ @code{latestxt}:
  @example
  Defer deferred
  noname : ( ... -- ... )
    ... ;
- lastxt IS deferred
+ latestxt IS deferred
  @end example
  @noindent
  @code{noname} works with any defining word, not just @code{:}.
- @code{lastxt} also works when the last word was not defined as
+ @code{latestxt} also works when the last word was not defined as
  @code{noname}.  It does not work for combined words, though.  It also has
  the useful property that is is valid as soon as the header for a
  definition has been built. Thus:
  @example
- lastxt . : foo [ lastxt . ] ; ' foo .
+ latestxt . : foo [ latestxt . ] ; ' foo .
  @end example
  @noindent
- Line 6370
+ Line 6038
  Line 6370
  Line 6038
  : stats ( xt -- ) DUP ." (Gathering statistics for " . ." )"
    ... ;  \ other code
- : my: : lastxt postpone literal ['] stats compile, ;
+ : my: : latestxt postpone literal ['] stats compile, ;
  my: foo + - ;
  @end example
- Line 6382
+ Line 6050
  Line 6382
  Line 6050
  @code{my:} is executed.
  @item
  The @code{:} within the definition (the one between @code{my:} and
- @code{lastxt}) is executed, and does just what it always does; it parses
+ @code{latestxt}) is executed, and does just what it always does; it parses
  the input stream for a name, builds a dictionary header for the name
  @code{foo} and switches @code{state} from interpret to compile.
  @item
- The word @code{lastxt} is executed. It puts the @i{xt} for the word that is
+ The word @code{latestxt} is executed. It puts the @i{xt} for the word that is
  being defined -- @code{foo} -- onto the stack.
  @item
  The code that was produced by @code{postpone literal} is executed; this
- Line 6726
+ Line 6394
  Line 6726
  Line 6394
  : @var{inst-format} ( entry-num "name" -- )
    here name string, ( entry-num c-addr ) \ parse and save "name"
    noname create , ( entry-num )
-   lastxt swap cells @var{table} + !
+   latestxt swap cells @var{table} + !
  does> ( addr w -- )
    \ disassemble instruction w at addr
    @@ >r
- Line 6761
+ Line 6429
  Line 6761
  Line 6429
      \ and enters it as u-th entry into table-xt
 @@ swap here name string, ( u table-xt disasm-xt c-addr ) \ remember string
      noname create 2,      \ define anonymous word
-     execute lastxt swap ! \ enter xt of defined word into table-xt
+     execute latestxt swap ! \ enter xt of defined word into table-xt
  does> ( addr w -- )
      \ disassemble instruction w at addr
 @@ >r ( addr w disasm-xt R: c-addr )
- Line 7203
+ Line 6871
  Line 7203
  Line 6871
  interpretation semantics of a named word:
  @example
-' .
+' .   ( n xt )
- execute
+ execute ( )      \ execute the xt (i.e., ".")
  @end example
  doc-'
- Line 7229
+ Line 6897
  Line 7229
  Line 6897
  DROP} or @code{[COMP'] @i{word} DROP} (for details @pxref{Compilation
  token}).
- Another way to get an XT is @code{:noname} or @code{lastxt}
+ Another way to get an XT is @code{:noname} or @code{latestxt}
  (@pxref{Anonymous Definitions}).  For anonymous words this gives an xt
  for the only behaviour the word has (the execution semantics).  For
- named words, @code{lastxt} produces an XT for the same behaviour it
+ named words, @code{latestxt} produces an XT for the same behaviour it
  would produce if the word was defined anonymously.
  @example
- Line 7286
+ Line 6954
  Line 7286
  Line 6954
  @subsection Name token
  @cindex name token
+ Gforth represents named words by the @dfn{name token}, (@i{nt}).  Name
+ token is an abstract data type that occurs as argument or result of the
+ words below.
+ @c !! put this elswhere?
  @cindex name field address
  @cindex NFA
- Gforth represents named words by the @dfn{name token}, (@i{nt}). In
+ The closest thing to the nt in older Forth systems is the name field
- Gforth, the abstract data type @emph{name token} is implemented as a
+ address (NFA), but there are significant differences: in older Forth
- name field address (NFA).
+ systems each word had a unique NFA, LFA, CFA and PFA (in this order, or
+ LFA, NFA, CFA, PFA) and there were words for getting from one to the
+ next.  In contrast, in Gforth 0@dots{}n nts correspond to one xt; there
+ is a link field in the structure identified by the name token, but
+ searching usually uses a hash table external to these structures; the
+ name in Gforth has a cell-wide count-and-flags field, and the nt is not
+ implemented as the address of that count field.
  doc-find-name
+ doc-latest
+ doc->name
  doc-name>int
  doc-name?int
  doc-name>comp
  doc-name>string
+ doc-id.
+ doc-.name
+ doc-.id
  @c ----------------------------------------------------------
  @node Compiling words, The Text Interpreter, Tokens for Words, Words
- Line 7542
+ Line 7226
  Line 7542
  Line 7226
  @code{create}d word can be changed.
  @c ----------------------------------------------------------
- @node The Text Interpreter, Word Lists, Compiling words, Words
+ @node The Text Interpreter, The Input Stream, Compiling words, Words
  @section  The Text Interpreter
  @cindex interpreter - outer
  @cindex text interpreter
- Line 7776
+ Line 7460
  Line 7776
  Line 7460
  doc-restore-input
  doc-evaluate
+ doc-query
- Line 7947
+ Line 7632
  Line 7947
  Line 7632
  @c that, we can also show what's not.  In any case, I have written a
  @c section Compiling Words which also deals with [ ].
- @code{[} and @code{]} also give you the ability to switch into compile
+ @c  !! The following example does not work in Gforth 0.5.9 or later.
- state and back, but we cannot think of any useful Standard application
- for this ability. Pre-ANS Forth textbooks have examples like this:
- @example
- : AA ." this is A" ;
- : BB ." this is B" ;
- : CC ." this is C" ;
- create table ] aa bb cc [
- : go ( n -- ) \ n is offset into table.. 0 for 1st entry
-   cells table + @ execute ;
- @end example
- This example builds a jump table; @code{0 go} will display ``@code{this
- is A}''. Using @code{[} and @code{]} in this example is equivalent to
- defining @code{table} like this:
- @example
- create table ' aa COMPILE, ' bb COMPILE, ' cc COMPILE,
- @end example
- The problem with this code is that the definition of @code{table} is not
- portable -- it @i{compile}s execution tokens into code space. Whilst it
- @i{may} work on systems where code space and data space co-incide, the
- Standard only allows data space to be assigned for a @code{CREATE}d
- word. In addition, the Standard only allows @code{@@} to access data
- space, whilst this example is using it to access code space. The only
- portable, Standard way to build this table is to build it in data space,
- like this:
- @example
+ @c  @code{[} and @code{]} also give you the ability to switch into compile
- create table ' aa , ' bb , ' cc ,
+ @c  state and back, but we cannot think of any useful Standard application
- @end example
+ @c  for this ability. Pre-ANS Forth textbooks have examples like this:
+ @c  @example
+ @c  : AA ." this is A" ;
+ @c  : BB ." this is B" ;
+ @c  : CC ." this is C" ;
+ @c  create table ] aa bb cc [
+ @c  : go ( n -- ) \ n is offset into table.. 0 for 1st entry
+ @c    cells table + @@ execute ;
+ @c  @end example
+ @c  This example builds a jump table; @code{0 go} will display ``@code{this
+ @c  is A}''. Using @code{[} and @code{]} in this example is equivalent to
+ @c  defining @code{table} like this:
+ @c  @example
+ @c  create table ' aa COMPILE, ' bb COMPILE, ' cc COMPILE,
+ @c  @end example
+ @c  The problem with this code is that the definition of @code{table} is not
+ @c  portable -- it @i{compile}s execution tokens into code space. Whilst it
+ @c  @i{may} work on systems where code space and data space co-incide, the
+ @c  Standard only allows data space to be assigned for a @code{CREATE}d
+ @c  word. In addition, the Standard only allows @code{@@} to access data
+ @c  space, whilst this example is using it to access code space. The only
+ @c  portable, Standard way to build this table is to build it in data space,
+ @c  like this:
+ @c  @example
+ @c  create table ' aa , ' bb , ' cc ,
+ @c  @end example
- doc-state
+ @c  doc-state
  @node Interpreter Directives,  , Interpret/Compile states, The Text Interpreter
- Line 8041
+ Line 7728
  Line 8041
  Line 7728
  @c -------------------------------------------------------------
- @node Word Lists, Environmental Queries, The Text Interpreter, Words
+ @node The Input Stream, Word Lists, The Text Interpreter, Words
+ @section The Input Stream
+ @cindex input stream
+ @c !! integrate this better with the "Text Interpreter" section
+ The text interpreter reads from the input stream, which can come from
+ several sources (@pxref{Input Sources}).  Some words, in particular
+ defining words, but also words like @code{'}, read parameters from the
+ input stream instead of from the stack.
+ Such words are called parsing words, because they parse the input
+ stream.  Parsing words are hard to use in other words, because it is
+ hard to pass program-generated parameters through the input stream.
+ They also usually have an unintuitive combination of interpretation and
+ compilation semantics when implemented naively, leading to various
+ approaches that try to produce a more intuitive behaviour
+ (@pxref{Combined words}).
+ It should be obvious by now that parsing words are a bad idea.  If you
+ want to implement a parsing word for convenience, also provide a factor
+ of the word that does not parse, but takes the parameters on the stack.
+ To implement the parsing word on top if it, you can use the following
+ words:
+ @c anton: these belong in the input stream section
+ doc-parse
+ doc-parse-word
+ doc-name
+ doc-word
+ doc-\"-parse
+ doc-refill
+ Conversely, if you have the bad luck (or lack of foresight) to have to
+ deal with parsing words without having such factors, how do you pass a
+ string that is not in the input stream to it?
+ doc-execute-parsing
+ If you want to run a parsing word on a file, the following word should
+ help:
+ doc-execute-parsing-file
+ @c -------------------------------------------------------------
+ @node Word Lists, Environmental Queries, The Input Stream, Words
  @section Word Lists
  @cindex word lists
  @cindex header space
- Line 8467
+ Line 8198
  Line 8467
  Line 8198
  doc-file-size
  doc-resize-file
+ doc-slurp-file
+ doc-slurp-fid
+ doc-stdin
+ doc-stdout
+ doc-stderr
  @c ---------------------------------------------------------
  @node Search Paths,  , General files, Files
- Line 8747
+ Line 8483
  Line 8747
  Line 8483
  * String Formats::              How Forth stores strings in memory
  * Displaying characters and strings::  Other stuff
  * Input::                       Input
+ * Pipes::                       How to create your own pipes
  @end menu
  @node Simple numeric output, Formatted numeric output, Other I/O, Other I/O
- Line 8772
+ Line 8509
  Line 8772
  Line 8509
  doc-f.
  doc-fe.
  doc-fs.
+ doc-f.rdp
  Examples of printing the number 1234.5678E23 in the different floating-point output
  formats are shown below:
- Line 8830
+ Line 8567
  Line 8830
  Line 8567
  doc-#>>
  doc-represent
+ doc-f>str-rdp
+ doc-f>buf-rdp
  @noindent
- Line 8962
+ Line 8701
  Line 8962
  Line 8701
  doc-toupper
  doc-."
  doc-.(
+ doc-.\"
  doc-type
  doc-typewhite
  doc-cr
- Line 8969
+ Line 8709
  Line 8969
  Line 8709
  doc-at-xy
  doc-page
  doc-s"
+ doc-s\"
  doc-c"
  doc-char
  doc-[char]
- Line 9040
+ Line 8781
  Line 9040
  Line 8781
- @node Input,  , Displaying characters and strings, Other I/O
+ @node Input, Pipes, Displaying characters and strings, Other I/O
  @subsection Input
  @cindex input
  @cindex I/O - see input
- Line 9060
+ Line 8801
  Line 9060
  Line 8801
  doc->number
  doc->float
  doc-accept
+ doc-edit-line
  doc-pad
- @c anton: these belong in the input stream section
- doc-parse
- doc-word
- doc-sword
- doc-name
- doc-refill
  @comment obsolescent words..
  doc-convert
- doc-query
  doc-expect
  doc-span
+ @node Pipes,  , Input, Other I/O
+ @subsection Pipes
+ @cindex pipes, creating your own
+ In addition to using Gforth in pipes created by other processes
+ (@pxref{Gforth in pipes}), you can create your own pipe with
+ @code{open-pipe}, and read from or write to it.
+ doc-open-pipe
+ doc-close-pipe
+ If you write to a pipe, Gforth can throw a @code{broken-pipe-error}; if
+ you don't catch this exception, Gforth will catch it and exit, usually
+ silently (@pxref{Gforth in pipes}).  Since you probably do not want
+ this, you should wrap a @code{catch} or @code{try} block around the code
+ from @code{open-pipe} to @code{close-pipe}, so you can deal with the
+ problem yourself, and then return to regular processing.
+ doc-broken-pipe-error
  @c -------------------------------------------------------------
  @node Locals, Structures, Other I/O, Words
  @section Locals
- Line 9467
+ Line 9223
  Line 9467
  Line 9223
  appropriate:
- doc-compile-@local
+ @c doc-compile-@local
- doc-compile-f@local
+ @c doc-compile-f@local
  doc-compile-lp+!
- Line 11456
+ Line 11212
  Line 11456
  Line 11212
  doc-see
  doc-xt-see
+ doc-simple-see
+ doc-simple-see-range
  @node Forgetting words, Debugging, Examining, Programming Tools
  @subsection Forgetting words
- Line 11517
+ Line 11275
  Line 11517
  Line 11275
  location and the stack contents). It is easy to insert. If you use Emacs
  it is also easy to remove (@kbd{C-x ~} in the Emacs Forth mode to
  query-replace them with nothing). The deferred words
- @code{printdebugdata} and @code{printdebugline} control the output of
+ @code{printdebugdata} and @code{.debugline} control the output of
  @code{~~}. The default source location output format works well with
  Emacs' compilation mode, so you can step through the program at the
  source level using @kbd{C-x `} (the advantage over a stepping debugger
- Line 11526
+ Line 11284
  Line 11526
  Line 11284
  doc-~~
  doc-printdebugdata
- doc-printdebugline
+ doc-.debugline
+ @cindex filenames in @code{~~} output
+ @code{~~} (and assertions) will usually print the wrong file name if a
+ marker is executed in the same file after their occurance.  They will
+ print @samp{*somewhere*} as file name if a marker is executed in the
+ same file before their occurance.
  @node Assertions, Singlestep Debugger, Debugging, Programming Tools
  @subsection Assertions
- Line 11591
+ Line 11356
  Line 11591
  Line 11356
  intend to @code{catch} a specific condition, using @code{throw} is
  probably more appropriate than an assertion).
+ @cindex filenames in assertion output
+ Assertions (and @code{~~}) will usually print the wrong file name if a
+ marker is executed in the same file after their occurance.  They will
+ print @samp{*somewhere*} as file name if a marker is executed in the
+ same file before their occurance.
  Definitions in ANS Forth for these assertion words are provided
  in @file{compat/assert.fs}.
- Line 11600
+ Line 11371
  Line 11600
  Line 11371
  @cindex singlestep Debugger
  @cindex debugging Singlestep
+ The singlestep debugger does not work in this release.
  When you create a new word there's often the need to check whether it
  behaves correctly or not. You can do this by typing @code{dbg
  badword}. A debug session might look like this:
- Line 11741
+ Line 11514
  Line 11741
  Line 11514
  is installation-dependent.
  In particular, @code{ip} (Forth instruction pointer) and @code{rp}
- (return stack pointer) are in different places in @code{gforth} and
+ (return stack pointer) may be in different places in @code{gforth} and
- @code{gforth-fast}.  This means that you cannot write a @code{NEXT}
+ @code{gforth-fast}, or different installations.  This means that you
- routine that works on both versions; so for doing @code{NEXT}, I
+ cannot write a @code{NEXT} routine that works reliably on both versions
- recomment jumping to @code{' noop >code-address}, which contains nothing
+ or different installations; so for doing @code{NEXT}, I recommend
- but a @code{NEXT}.
+ jumping to @code{' noop >code-address}, which contains nothing but a
+ @code{NEXT}.
  For general accesses to the inner interpreter's registers, the easiest
  solution is to use explicit register declarations (@pxref{Explicit Reg
- Line 11817
+ Line 11591
  Line 11817
  Line 11591
  changed register assignment.  The stability of the register assignment
  is usually better if you build Gforth with @code{--enable-force-reg}.
- In particular, the return stack pointer and the instruction pointer are
+ The most common use of these registers is to dispatch to the next word
- in memory in @code{gforth}, and usually in registers in
+ (the @code{next} routine).  A portable way to do this is to jump to
- @code{gforth-fast}.  The most common use of these registers is to
+ @code{' noop >code-address} (of course, this is less efficient than
- dispatch to the next word (the @code{next} routine).  A portable way to
+ integrating the @code{next} code and scheduling it well).
- do this is to jump to @code{' noop >code-address} (of course, this is
- less efficient than integrating the @code{next} code and scheduling it
+ Another difference between Gforth version is that the top of stack is
- well).
+ kept in memory in @code{gforth} and, on most platforms, in a register in
+ @code{gforth-fast}.
  @node  Common Disassembler, 386 Assembler, Common Assembler, Assembler and Code Words
  @subsection Common Disassembler
- Line 11842
+ Line 11617
  Line 11842
  Line 11617
  because the recognition of the end of the code is unreliable.  You can
  use @code{disasm} if it did not display enough.  It may display more, if
  the code word is not immediately followed by a named word.  If you have
- something else there, you can follow the word with @code{align last @ ,}
+ something else there, you can follow the word with @code{align latest ,}
  to ensure that the end is recognized.
  @node 386 Assembler, Alpha Assembler, Common Disassembler, Assembler and Code Words
- Line 12032
+ Line 11807
  Line 12032
  Line 11807
  @subsection Other assemblers
  If you want to contribute another assembler/disassembler, please contact
- us (@email{bug-gforth@@gnu.org}) to check if we have such an assembler
+ us (@email{anton@@mips.complang.tuwien.ac.at}) to check if we have such
- already.  If you are writing them from scratch, please use a similar
+ an assembler already.  If you are writing them from scratch, please use
- syntax style as the one we use (i.e., postfix, commas at the end of the
+ a similar syntax style as the one we use (i.e., postfix, commas at the
- instruction names, @pxref{Common Assembler}); make the output of the
+ end of the instruction names, @pxref{Common Assembler}); make the output
- disassembler be valid input for the assembler, and keep the style
+ of the disassembler be valid input for the assembler, and keep the style
  similar to the style we used.
  Hints on implementation: The most important part is to have a good test
- Line 12117
+ Line 11892
  Line 12117
  Line 11892
  doc-dodefer:
  doc-dofield:
+ @cindex definer
+ The following two words generalize @code{>code-address},
+ @code{>does-code}, @code{code-address!}, and @code{does-code!}:
+ doc->definer
+ doc-definer!
  @c -------------------------------------------------------------
  @node Passing Commands to the OS, Keeping track of Time, Threading Words, Words
  @section Passing Commands to the Operating System
- Line 12228
+ Line 12010
  Line 12228
  Line 12010
  @code{Gforth} is able to do a return stack dump for throws generated
  from primitives (e.g., invalid memory address, stack empty etc.);
  @code{gforth-fast} is only able to do a return stack dump from a
- directly called @code{throw} (including @code{abort} etc.).  This is the
+ directly called @code{throw} (including @code{abort} etc.).  Given an
- only difference (apart from a speed factor of between 1.15 (K6-2) and
-(21264)) between @code{gforth} and @code{gforth-fast}.  Given an
  exception caused by a primitive in @code{gforth-fast}, you will
  typically see no return stack dump at all; however, if the exception is
  caught by @code{catch} (e.g., for restoring some state), and then
- Line 12488
+ Line 12268
  Line 12488
  Line 12268
  @item maximum size of a definition name, in characters:
  @cindex maximum size of a definition name, in characters
  @cindex name, maximum length
+ MAXU/8
  @item maximum string length for @code{ENVIRONMENT?}, in characters:
  @cindex maximum string length for @code{ENVIRONMENT?}, in characters
  @cindex @code{ENVIRONMENT?} string length, maximum
+ MAXU/8
  @item method of selecting the user input device:
  @cindex user input device, method of selecting
- Line 13628
+ Line 13408
  Line 13628
  Line 13408
  The word is entered into the word list that was the compilation word list
  at the start of the definition. Any changes to the name field (e.g.,
  @code{immediate}) or the code field (e.g., when executing @code{DOES>})
- are applied to the latest defined word (as reported by @code{last} or
+ are applied to the latest defined word (as reported by @code{latest} or
- @code{lastxt}), if possible, irrespective of the compilation word list.
+ @code{latestxt}), if possible, irrespective of the compilation word list.
  @item search order empty (@code{previous}):
  @cindex @code{previous}, search order empty
- Line 13794
+ Line 13574
  Line 13794
  Line 13574
  @cindex @file{gforth.el}
  @cindex @file{forth.el}
  @cindex Rydqvist, Goran
+ @cindex Kuehling, David
  @cindex comment editing commands
  @cindex @code{\}, editing with Emacs
  @cindex debug tracer editing commands
  @cindex @code{~~}, removal with Emacs
  @cindex Forth mode in Emacs
  Gforth comes with @file{gforth.el}, an improved version of
  @file{forth.el} by Goran Rydqvist (included in the TILE package). The
  improvements are:
  @itemize @bullet
  @item
- A better (but still not perfect) handling of indentation.
+ A better handling of indentation.
+ @item
+ A custom hilighting engine for Forth-code.
  @item
  Comment paragraph filling (@kbd{M-q})
  @item
- Line 13815
+ Line 13599
  Line 13815
  Line 13599
  @item
  Support of the @code{info-lookup} feature for looking up the
  documentation of a word.
+ @item
+ Support for reading and writing blocks files.
  @end itemize
- I left the stuff I do not use alone, even though some of it only makes
+ To get a basic description of these features, enter Forth mode and
- sense for TILE. To get a description of these features, enter Forth mode
+ type @kbd{C-h m}.
- and type @kbd{C-h m}.
  @cindex source location of error or debugging output in Emacs
  @cindex error output, finding the source location in Emacs
- Line 13832
+ Line 13617
  Line 13832
  Line 13617
  message is only a few keystrokes away (@kbd{C-x `} for the next error,
  @kbd{C-c C-c} for the error under the cursor).
+ @cindex viewing the documentation of a word in Emacs
+ @cindex context-sensitive help
+ Moreover, for words documented in this manual, you can look up the
+ glossary entry quickly by using @kbd{C-h TAB}
+ (@code{info-lookup-symbol}, @pxref{Documentation, ,Documentation
+ Commands, emacs, Emacs Manual}).  This feature requires Emacs 20.3 or
+ later and does not work for words containing @code{:}.
+ @menu
+ * Installing gforth.el::        Making Emacs aware of Forth.
+ * Emacs Tags::                  Viewing the source of a word in Emacs.
+ * Hilighting::                  Making Forth code look prettier.
+ * Auto-Indentation::            Customizing auto-indentation.
+ * Blocks Files::                Reading and writing blocks files.
+ @end menu
+ @c ----------------------------------
+ @node Installing gforth.el, Emacs Tags, Emacs and Gforth, Emacs and Gforth
+ @section Installing gforth.el
+ @cindex @file{.emacs}
+ @cindex @file{gforth.el}, installation
+ To make the features from @file{gforth.el} available in Emacs, add
+ the following lines to your @file{.emacs} file:
+ @example
+ (autoload 'forth-mode "gforth.el")
+ (setq auto-mode-alist (cons '("\\.fs\\'" . forth-mode)
+                             auto-mode-alist))
+ (autoload 'forth-block-mode "gforth.el")
+ (setq auto-mode-alist (cons '("\\.fb\\'" . forth-block-mode)
+                             auto-mode-alist))
+ (add-hook 'forth-mode-hook (function (lambda ()
+    ;; customize variables here:
+    (setq forth-indent-level 4)
+    (setq forth-minor-indent-level 2)
+    (setq forth-hilight-level 3)
+    ;;; ...
+ )))
+ @end example
+ @c ----------------------------------
+ @node Emacs Tags, Hilighting, Installing gforth.el, Emacs and Gforth
+ @section Emacs Tags
  @cindex @file{TAGS} file
  @cindex @file{etags.fs}
  @cindex viewing the source of a word in Emacs
  @cindex @code{require}, placement in files
  @cindex @code{include}, placement in files
- Also, if you @code{require} @file{etags.fs}, a new @file{TAGS} file will
+ If you @code{require} @file{etags.fs}, a new @file{TAGS} file will be
- be produced (@pxref{Tags, , Tags Tables, emacs, Emacs Manual}) that
+ produced (@pxref{Tags, , Tags Tables, emacs, Emacs Manual}) that
  contains the definitions of all words defined afterwards. You can then
- find the source for a word using @kbd{M-.}. Note that emacs can use
+ find the source for a word using @kbd{M-.}. Note that Emacs can use
  several tags files at the same time (e.g., one for the Gforth sources
  and one for your program, @pxref{Select Tags Table,,Selecting a Tags
  Table,emacs, Emacs Manual}). The TAGS file for the preloaded words is
- Line 13850
+ Line 13678
  Line 13850
  Line 13678
  and after @code{require} etc., otherwise you will see the same file
  visited several times by commands like @code{tags-search}.
- @cindex viewing the documentation of a word in Emacs
+ @c ----------------------------------
- @cindex context-sensitive help
+ @node Hilighting, Auto-Indentation, Emacs Tags, Emacs and Gforth
- Moreover, for words documented in this manual, you can look up the
+ @section Hilighting
- glossary entry quickly by using @kbd{C-h TAB}
+ @cindex hilighting Forth code in Emacs
- (@code{info-lookup-symbol}, @pxref{Documentation, ,Documentation
+ @cindex highlighting Forth code in Emacs
- Commands, emacs, Emacs Manual}).  This feature requires Emacs 20.3 or
+ @file{gforth.el} comes with a custom source hilighting engine.  When
- later and does not work for words containing @code{:}.
+ you open a file in @code{forth-mode}, it will be completely parsed,
+ assigning faces to keywords, comments, strings etc.  While you edit
+ the file, modified regions get parsed and updated on-the-fly.
+ Use the variable `forth-hilight-level' to change the level of
+ decoration from 0 (no hilighting at all) to 3 (the default).  Even if
+ you set the hilighting level to 0, the parser will still work in the
+ background, collecting information about whether regions of text are
+ ``compiled'' or ``interpreted''.  Those information are required for
+ auto-indentation to work properly.  Set `forth-disable-parser' to
+ non-nil if your computer is too slow to handle parsing.  This will
+ have an impact on the smartness of the auto-indentation engine,
+ though.
+ Sometimes Forth sources define new features that should be hilighted,
+ new control structures, defining-words etc.  You can use the variable
+ `forth-custom-words' to make @code{forth-mode} hilight additional
+ words and constructs.  See the docstring of `forth-words' for details
+ (in Emacs, type @kbd{C-h v forth-words}).
+ `forth-custom-words' is meant to be customized in your
+ @file{.emacs} file.  To customize hilighing in a file-specific manner,
+ set `forth-local-words' in a local-variables section at the end of
+ your source file (@pxref{Local Variables in Files,, Variables, emacs, Emacs Manual}).
+ Example:
+ @example
+[IF]
+    Local Variables:
+    forth-local-words:
+       ((("t:") definition-starter (font-lock-keyword-face . 1)
+         "[ \t\n]" t name (font-lock-function-name-face . 3))
+        ((";t") definition-ender (font-lock-keyword-face . 1)))
+    End:
+ [THEN]
+ @end example
+ @c ----------------------------------
+ @node Auto-Indentation, Blocks Files, Hilighting, Emacs and Gforth
+ @section Auto-Indentation
+ @cindex auto-indentation of Forth code in Emacs
+ @cindex indentation of Forth code in Emacs
+ @code{forth-mode} automatically tries to indent lines in a smart way,
+ whenever you type @key{TAB} or break a line with @kbd{C-m}.
+ Simple customization can be achieved by setting
+ `forth-indent-level' and `forth-minor-indent-level' in your
+ @file{.emacs} file. For historical reasons @file{gforth.el} indents
+ per default by multiples of 4 columns.  To use the more traditional
+-column indentation, add the following lines to your @file{.emacs}:
+ @example
+ (add-hook 'forth-mode-hook (function (lambda ()
+    ;; customize variables here:
+    (setq forth-indent-level 3)
+    (setq forth-minor-indent-level 1)
+ )))
+ @end example
+ If you want indentation to recognize non-default words, customize it
+ by setting `forth-custom-indent-words' in your @file{.emacs}.  See the
+ docstring of `forth-indent-words' for details (in Emacs, type @kbd{C-h
+ v forth-indent-words}).
+ To customize indentation in a file-specific manner, set
+ `forth-local-indent-words' in a local-variables section at the end of
+ your source file (@pxref{Local Variables in Files, Variables,,emacs,
+ Emacs Manual}).
+ Example:
+ @example
+[IF]
+    Local Variables:
+    forth-local-indent-words:
+       ((("t:") (0 . 2) (0 . 2))
+        ((";t") (-2 . 0) (0 . -2)))
+    End:
+ [THEN]
+ @end example
- @cindex @file{.emacs}
+ @c ----------------------------------
- To get all these benefits, add the following lines to your @file{.emacs}
+ @node Blocks Files,  , Auto-Indentation, Emacs and Gforth
- file:
+ @section Blocks Files
+ @cindex blocks files, use with Emacs
+ @code{forth-mode} Autodetects blocks files by checking whether the
+ length of the first line exceeds 1023 characters.  It then tries to
+ convert the file into normal text format.  When you save the file, it
+ will be written to disk as normal stream-source file.
- @example
+ If you want to write blocks files, use @code{forth-blocks-mode}.  It
- (autoload 'forth-mode "gforth.el")
+ inherits all the features from @code{forth-mode}, plus some additions:
- (setq auto-mode-alist (cons '("\\.fs\\'" . forth-mode) auto-mode-alist))
- @end example
+ @itemize @bullet
+ @item
+ Files are written to disk in blocks file format.
+ @item
+ Screen numbers are displayed in the mode line (enumerated beginning
+ with the value of `forth-block-base')
+ @item
+ Warnings are displayed when lines exceed 64 characters.
+ @item
+ The beginning of the currently edited block is marked with an
+ overlay-arrow.
+ @end itemize
+ There are some restrictions you should be aware of.  When you open a
+ blocks file that contains tabulator or newline characters, these
+ characters will be translated into spaces when the file is written
+ back to disk.  If tabs or newlines are encountered during blocks file
+ reading, an error is output to the echo area. So have a look at the
+ `*Messages*' buffer, when Emacs' bell rings during reading.
+ Please consult the docstring of @code{forth-blocks-mode} for more
+ information by typing @kbd{C-h v forth-blocks-mode}).
  @c ******************************************************************
  @node Image Files, Engine, Emacs and Gforth, Top
- Line 13905
+ Line 13836
  Line 13905
  Line 13836
  Since Gforth is distributed under the GNU GPL, the newly created image
  falls under the GNU GPL, too. In particular, this means that if you
  distribute the image, you have to make all of the sources for the image
- available, including those you wrote.  For details see @ref{License, ,
+ available, including those you wrote.  For details see @ref{Copying, ,
  GNU General Public License (Section 3)}.
  If you create an image with @code{cross} (@pxref{cross.fs}), the image
- Line 14283
+ Line 14214
  Line 14283
  Line 14214
  @c ******************************************************************
- @node Engine, Binding to System Library, Image Files, Top
+ @node Engine, Cross Compiler, Image Files, Top
  @chapter Engine
  @cindex engine
  @cindex virtual machine
- Line 14291
+ Line 14222
  Line 14291
  Line 14222
  Reading this chapter is not necessary for programming with Gforth. It
  may be helpful for finding your way in the Gforth sources.
- The ideas in this section have also been published in Bernd Paysan,
+ The ideas in this section have also been published in the following
- @cite{ANS fig/GNU/??? Forth} (in German), Forth-Tagung '93 and M. Anton
+ papers: Bernd Paysan, @cite{ANS fig/GNU/??? Forth} (in German),
- Ertl, @cite{@uref{http://www.complang.tuwien.ac.at/papers/ertl93.ps.Z, A
+ Forth-Tagung '93; M. Anton Ertl,
- Portable Forth Engine}}, EuroForth '93.
+ @cite{@uref{http://www.complang.tuwien.ac.at/papers/ertl93.ps.Z, A
+ Portable Forth Engine}}, EuroForth '93; M. Anton Ertl,
+ @cite{@uref{http://www.complang.tuwien.ac.at/papers/ertl02.ps.gz,
+ Threaded code variations and optimizations (extended version)}},
+ Forth-Tagung '02.
  @menu
  * Portability::
- Line 14334
+ Line 14269
  Line 14334
  Line 14269
  Labels as Values, gcc.info, GNU C Manual}) makes direct and indirect
  threading possible, its @code{long long} type (@pxref{Long Long, ,
  Double-Word Integers, gcc.info, GNU C Manual}) corresponds to Forth's
- double numbers@footnote{Unfortunately, long longs are not implemented
+ double numbers on many systems.  GNU C is freely available on all
- properly on all machines (e.g., on alpha-osf1, long longs are only 64
- bits, the same size as longs (and pointers), but they should be twice as
- long according to @pxref{Long Long, , Double-Word Integers, gcc.info, GNU
- C Manual}). So, we had to implement doubles in C after all. Still, on
- most machines we can use long longs and achieve better performance than
- with the emulation package.}. GNU C is available for free on all
  important (and many unimportant) UNIX machines, VMS, 80386s running
  MS-DOS, the Amiga, and the Atari ST, so a Forth written in GNU C can run
  on all these machines.
- Line 14409
+ Line 14338
  Line 14409
  Line 14338
  @menu
  * Scheduling::
  * Direct or Indirect Threaded?::
+ * Dynamic Superinstructions::
  * DOES>::
  @end menu
- Line 14453
+ Line 14383
  Line 14453
  Line 14383
  NEXT between these parts in several ways; in general, different schemes
  perform best on different processors.  We use a scheme for most
  architectures that performs well for most processors of this
- architecture; in the furture we may switch to benchmarking and chosing
+ architecture; in the future we may switch to benchmarking and chosing
  the scheme on installation time.
- @node Direct or Indirect Threaded?, DOES>, Scheduling, Threading
+ @node Direct or Indirect Threaded?, Dynamic Superinstructions, Scheduling, Threading
  @subsection Direct or Indirect Threaded?
  @cindex threading, direct or indirect?
- @cindex -DDIRECT_THREADED
+ Threaded forth code consists of references to primitives (simple machine
- Both! After packaging the nasty details in macro definitions we
+ code routines like @code{+}) and to non-primitives (e.g., colon
- realized that we could switch between direct and indirect threading by
+ definitions, variables, constants); for a specific class of
- simply setting a compilation flag (@code{-DDIRECT_THREADED}) and
+ non-primitives (e.g., variables) there is one code routine (e.g.,
- defining a few machine-specific macros for the direct-threading case.
+ @code{dovar}), but each variable needs a separate reference to its data.
- On the Forth level we also offer access words that hide the
- differences between the threading methods (@pxref{Threading Words}).
+ Traditionally Forth has been implemented as indirect threaded code,
+ because this allows to use only one cell to reference a non-primitive
- Indirect threading is implemented completely machine-independently.
+ (basically you point to the data, and find the code address there).
- Direct threading needs routines for creating jumps to the executable
- code (e.g. to @code{docol} or @code{dodoes}). These routines are inherently
+ @cindex primitive-centric threaded code
- machine-dependent, but they do not amount to many source lines. Therefore,
+ However, threaded code in Gforth (since 0.6.0) uses two cells for
- even porting direct threading to a new machine requires little effort.
+ non-primitives, one for the code address, and one for the data address;
+ the data pointer is an immediate argument for the virtual machine
- @cindex --enable-indirect-threaded, configuration flag
+ instruction represented by the code address.  We call this
- @cindex --enable-direct-threaded, configuration flag
+ @emph{primitive-centric} threaded code, because all code addresses point
- The default threading method is machine-dependent. You can enforce a
+ to simple primitives.  E.g., for a variable, the code address is for
- specific threading method when building Gforth with the configuration
+ @code{lit} (also used for integer literals like @code{99}).
- flag @code{--enable-direct-threaded} or
- @code{--enable-indirect-threaded}. Note that direct threading is not
+ Primitive-centric threaded code allows us to use (faster) direct
- supported on all machines.
+ threading as dispatch method, completely portably (direct threaded code
+ in Gforth before 0.6.0 required architecture-specific code).  It also
+ eliminates the performance problems related to I-cache consistency that
+implementations have with direct threaded code, and allows
+ additional optimizations.
+ @cindex hybrid direct/indirect threaded code
+ There is a catch, however: the @var{xt} parameter of @code{execute} can
+ occupy only one cell, so how do we pass non-primitives with their code
+ @emph{and} data addresses to them?  Our answer is to use indirect
+ threaded dispatch for @code{execute} and other words that use a
+ single-cell xt.  So, normal threaded code in colon definitions uses
+ direct threading, and @code{execute} and similar words, which dispatch
+ to xts on the data stack, use indirect threaded code.  We call this
+ @emph{hybrid direct/indirect} threaded code.
+ @cindex engines, gforth vs. gforth-fast vs. gforth-itc
+ @cindex gforth engine
+ @cindex gforth-fast engine
+ The engines @command{gforth} and @command{gforth-fast} use hybrid
+ direct/indirect threaded code.  This means that with these engines you
+ cannot use @code{,} to compile an xt.  Instead, you have to use
+ @code{compile,}.
+ @cindex gforth-itc engine
+ If you want to compile xts with @code{,}, use @command{gforth-itc}.
+ This engine uses plain old indirect threaded code.  It still compiles in
+ a primitive-centric style, so you cannot use @code{compile,} instead of
+ @code{,} (e.g., for producing tables of xts with @code{] word1 word2
+ ... [}).  If you want to do that, you have to use @command{gforth-itc}
+ and execute @code{' , is compile,}.  Your program can check if it is
+ running on a hybrid direct/indirect threaded engine or a pure indirect
+ threaded engine with @code{threading-method} (@pxref{Threading Words}).
+ @node Dynamic Superinstructions, DOES>, Direct or Indirect Threaded?, Threading
+ @subsection Dynamic Superinstructions
+ @cindex Dynamic superinstructions with replication
+ @cindex Superinstructions
+ @cindex Replication
+ The engines @command{gforth} and @command{gforth-fast} use another
+ optimization: Dynamic superinstructions with replication.  As an
+ example, consider the following colon definition:
- @node DOES>,  , Direct or Indirect Threaded?, Threading
+ @example
+ : squared ( n1 -- n2 )
+   dup * ;
+ @end example
+ Gforth compiles this into the threaded code sequence
+ @example
+ dup
+ *
+ ;s
+ @end example
+ In normal direct threaded code there is a code address occupying one
+ cell for each of these primitives.  Each code address points to a
+ machine code routine, and the interpreter jumps to this machine code in
+ order to execute the primitive.  The routines for these three
+ primitives are (in @command{gforth-fast} on the 386):
+ @example
+ Code dup
+ ( $804B950 )  add     esi , # -4  \ $83 $C6 $FC
+ ( $804B953 )  add     ebx , # 4  \ $83 $C3 $4
+ ( $804B956 )  mov     dword ptr 4 [esi] , ecx  \ $89 $4E $4
+ ( $804B959 )  jmp     dword ptr FC [ebx]  \ $FF $63 $FC
+ end-code
+ Code *
+ ( $804ACC4 )  mov     eax , dword ptr 4 [esi]  \ $8B $46 $4
+ ( $804ACC7 )  add     esi , # 4  \ $83 $C6 $4
+ ( $804ACCA )  add     ebx , # 4  \ $83 $C3 $4
+ ( $804ACCD )  imul    ecx , eax  \ $F $AF $C8
+ ( $804ACD0 )  jmp     dword ptr FC [ebx]  \ $FF $63 $FC
+ end-code
+ Code ;s
+ ( $804A693 )  mov     eax , dword ptr [edi]  \ $8B $7
+ ( $804A695 )  add     edi , # 4  \ $83 $C7 $4
+ ( $804A698 )  lea     ebx , dword ptr 4 [eax]  \ $8D $58 $4
+ ( $804A69B )  jmp     dword ptr FC [ebx]  \ $FF $63 $FC
+ end-code
+ @end example
+ With dynamic superinstructions and replication the compiler does not
+ just lay down the threaded code, but also copies the machine code
+ fragments, usually without the jump at the end.
+ @example
+ ( $4057D27D )  add     esi , # -4  \ $83 $C6 $FC
+ ( $4057D280 )  add     ebx , # 4  \ $83 $C3 $4
+ ( $4057D283 )  mov     dword ptr 4 [esi] , ecx  \ $89 $4E $4
+ ( $4057D286 )  mov     eax , dword ptr 4 [esi]  \ $8B $46 $4
+ ( $4057D289 )  add     esi , # 4  \ $83 $C6 $4
+ ( $4057D28C )  add     ebx , # 4  \ $83 $C3 $4
+ ( $4057D28F )  imul    ecx , eax  \ $F $AF $C8
+ ( $4057D292 )  mov     eax , dword ptr [edi]  \ $8B $7
+ ( $4057D294 )  add     edi , # 4  \ $83 $C7 $4
+ ( $4057D297 )  lea     ebx , dword ptr 4 [eax]  \ $8D $58 $4
+ ( $4057D29A )  jmp     dword ptr FC [ebx]  \ $FF $63 $FC
+ @end example
+ Only when a threaded-code control-flow change happens (e.g., in
+ @code{;s}), the jump is appended.  This optimization eliminates many of
+ these jumps and makes the rest much more predictable.  The speedup
+ depends on the processor and the application; on the Athlon and Pentium
+ III this optimization typically produces a speedup by a factor of 2.
+ The code addresses in the direct-threaded code are set to point to the
+ appropriate points in the copied machine code, in this example like
+ this:
+ @example
+ primitive  code address
+    dup       $4057D27D
+    *         $4057D286
+    ;s        $4057D292
+ @end example
+ Thus there can be threaded-code jumps to any place in this piece of
+ code.  This also simplifies decompilation quite a bit.
+ @cindex --no-dynamic command-line option
+ @cindex --no-super command-line option
+ You can disable this optimization with @option{--no-dynamic}.  You can
+ use the copying without eliminating the jumps (i.e., dynamic
+ replication, but without superinstructions) with @option{--no-super};
+ this gives the branch prediction benefit alone; the effect on
+ performance depends on the CPU; on the Athlon and Pentium III the
+ speedup is a little less than for dynamic superinstructions with
+ replication.
+ @cindex patching threaded code
+ One use of these options is if you want to patch the threaded code.
+ With superinstructions, many of the dispatch jumps are eliminated, so
+ patching often has no effect.  These options preserve all the dispatch
+ jumps.
+ @cindex --dynamic command-line option
+ On some machines dynamic superinstructions are disabled by default,
+ because it is unsafe on these machines.  However, if you feel
+ adventurous, you can enable it with @option{--dynamic}.
+ @node DOES>,  , Dynamic Superinstructions, Threading
  @subsection DOES>
  @cindex @code{DOES>} implementation
- Line 14491
+ Line 14564
  Line 14491
  Line 14564
  @cindex @code{DOES>}-code
  One of the most complex parts of a Forth engine is @code{dodoes}, i.e.,
  the chunk of code executed by every word defined by a
- @code{CREATE}...@code{DOES>} pair. The main problem here is: How to find
+ @code{CREATE}...@code{DOES>} pair; actually with primitive-centric code,
- the Forth code to be executed, i.e. the code after the
+ this is only needed if the xt of the word is @code{execute}d. The main
- @code{DOES>} (the @code{DOES>}-code)? There are two solutions:
+ problem here is: How to find the Forth code to be executed, i.e. the
+ code after the @code{DOES>} (the @code{DOES>}-code)? There are two
+ solutions:
  In fig-Forth the code field points directly to the @code{dodoes} and the
- @code{DOES>}-code address is stored in the cell after the code address (i.e. at
+ @code{DOES>}-code address is stored in the cell after the code address
- @code{@i{CFA} cell+}). It may seem that this solution is illegal in
+ (i.e. at @code{@i{CFA} cell+}). It may seem that this solution is
- the Forth-79 and all later standards, because in fig-Forth this address
+ illegal in the Forth-79 and all later standards, because in fig-Forth
- lies in the body (which is illegal in these standards). However, by
+ this address lies in the body (which is illegal in these
- making the code field larger for all words this solution becomes legal
+ standards). However, by making the code field larger for all words this
- again. We use this approach for the indirect threaded version and for
+ solution becomes legal again.  We use this approach.  Leaving a cell
- direct threading on some machines. Leaving a cell unused in most words
+ unused in most words is a bit wasteful, but on the machines we are
- is a bit wasteful, but on the machines we are targeting this is hardly a
+ targeting this is hardly a problem.
- problem. The other reason for having a code field size of two cells is
- to avoid having different image files for direct and indirect threaded
- systems (direct threaded systems require two-cell code fields on many
- machines).
- @cindex @code{DOES>}-handler
- The other approach is that the code field points or jumps to the cell
- after @code{DOES>}. In this variant there is a jump to @code{dodoes} at
- this address (the @code{DOES>}-handler). @code{dodoes} can then get the
- @code{DOES>}-code address by computing the code address, i.e., the address of
- the jump to @code{dodoes}, and add the length of that jump field. A variant of
- this is to have a call to @code{dodoes} after the @code{DOES>}; then the
- return address (which can be found in the return register on RISCs) is
- the @code{DOES>}-code address. Since the two cells available in the code field
- are used up by the jump to the code address in direct threading on many
- architectures, we use this approach for direct threading on these
- architectures. We did not want to add another cell to the code field.
  @node Primitives, Performance, Threading, Engine
  @section Primitives
- Line 14538
+ Line 14597
  Line 14538
  Line 14597
  @cindex primitives, automatic generation
  @cindex @file{prims2x.fs}
  Since the primitives are implemented in a portable language, there is no
  longer any need to minimize the number of primitives. On the contrary,
  having many primitives has an advantage: speed. In order to reduce the
  number of errors in primitives and to make programming them easier, we
- provide a tool, the primitive generator (@file{prims2x.fs}), that
+ provide a tool, the primitive generator (@file{prims2x.fs} aka Vmgen,
- automatically generates most (and sometimes all) of the C code for a
+ @pxref{Top, Vmgen, Introduction, vmgen, Vmgen}), that automatically
- primitive from the stack effect notation.  The source for a primitive
+ generates most (and sometimes all) of the C code for a primitive from
- has the following form:
+ the stack effect notation.  The source for a primitive has the following
+ form:
  @cindex primitive source format
  @format
- Line 14616
+ Line 14677
  Line 14616
  Line 14677
  account, most notably @code{?dup}, but also words that do not (always)
  fall through to @code{NEXT}.
+ For more information
  @node TOS Optimization, Produced code, Automatic Generation, Primitives
  @subsection TOS Optimization
  @cindex TOS optimization for primitives
- Line 14692
+ Line 14755
  Line 14692
  Line 14755
  @cindex Gforth performance
  On RISCs the Gforth engine is very close to optimal; i.e., it is usually
- impossible to write a significantly faster engine.
+ impossible to write a significantly faster threaded-code engine.
  On register-starved machines like the 386 architecture processors
  improvements are possible, because @code{gcc} does not utilize the
- Line 14704
+ Line 14767
  Line 14704
  Line 14767
  with gcc-2.95 and gforth-0.4.9; now the most important virtual machine
  registers fit in real registers (and we can even afford to use the TOS
  optimization), resulting in a speedup of 1.14 on the sieve over the
- earlier results.
+ earlier results.  And dynamic superinstructions provide another speedup
+ (but only around a factor 1.2 on the 486).
  @cindex Win32Forth performance
  @cindex NT Forth performance
- Line 14713
+ Line 14777
  Line 14713
  Line 14777
  @cindex PFE performance
  @cindex TILE performance
  The potential advantage of assembly language implementations is not
- necessarily realized in complete Forth systems: We compared Gforth-0.4.9
+ necessarily realized in complete Forth systems: We compared Gforth-0.5.9
  (direct threaded, compiled with @code{gcc-2.95.1} and
  @code{-DFORCE_REG}) with Win32Forth 1.2093 (newer versions are
  reportedly much faster), LMI's NT Forth (Beta, May 1994) and Eforth
- Line 14743
+ Line 14807
  Line 14743
  Line 14807
  @example
  relative      Win32-    NT       eforth       This-
    time  Gforth Forth Forth eforth  +opt   PFE Forth  TILE
- sieve     1.00  1.60  1.32   1.60  0.98  1.82  3.67  9.91
+ sieve      1.00  2.16  1.78   2.16  1.32  2.46  4.96 13.37
- bubble    1.00  1.55  1.66   1.75  1.04  1.78        4.58
+ bubble     1.00  1.93  2.07   2.18  1.29  2.21        5.70
- matmul    1.00  1.71  1.57   1.69  0.86  1.83        4.74
+ matmul     1.00  1.92  1.76   1.90  0.96  2.06        5.32
- fib       1.00  1.76  1.54   1.41  1.00  2.01  3.45  4.96
+ fib        1.00  2.32  2.03   1.86  1.31  2.64  4.55  6.54
  @end example
  You may be quite surprised by the good performance of Gforth when
- Line 14758
+ Line 14822
  Line 14758
  Line 14822
  computes the actual addresses at run time, resulting in two address
  computations per @code{NEXT} (@pxref{Image File Background}).
- Only Eforth with the peephole optimizer performs comparable to
- Gforth. The speedups achieved with peephole optimization of threaded
- code are quite remarkable. Adding a peephole optimizer to Gforth should
- cause similar speedups.
  The speedup of Gforth over PFE, ThisForth and TILE can be easily
  explained with the self-imposed restriction of the latter systems to
  standard C, which makes efficient threading impossible (however, the
- Line 14775
+ Line 14834
  Line 14775
  Line 14834
  with the version of @code{gcc} used. E.g., @code{gcc-2.5.8} failed to
  allocate any of the virtual machine registers into real machine
  registers by itself and would not work correctly with explicit register
- declarations, giving a 1.5 times slower engine (on a 486DX2/66 running
+ declarations, giving a significantly slower engine (on a 486DX2/66
- the Sieve) than the one measured above.
+ running the Sieve) than the one measured above.
  Note that there have been several releases of Win32Forth since the
  release presented here, so the results presented above may have little
- Line 14790
+ Line 14849
  Line 14790
  Line 14849
  Maierhofer (presented at EuroForth '95), an indirect threaded version of
  Gforth is compared with Win32Forth, NT Forth, PFE, ThisForth, and
  several native code systems; that version of Gforth is slower on a 486
- than the direct threaded version used here. You can find a newer version
+ than the version used here. You can find a newer version of these
- of these measurements at
+ measurements at
  @uref{http://www.complang.tuwien.ac.at/forth/performance.html}. You can
  find numbers for Gforth on various machines in @file{Benchres}.
  @c ******************************************************************
- @node Binding to System Library, Cross Compiler, Engine, Top
+ @c @node Binding to System Library, Cross Compiler, Engine, Top
- @chapter Binding to System Library
+ @c @chapter Binding to System Library
- @node Cross Compiler, Bugs, Binding to System Library, Top
+ @c ****************************************************************
+ @node Cross Compiler, Bugs, Engine, Top
  @chapter Cross Compiler
  @cindex @file{cross.fs}
  @cindex cross-compiler
- Line 14947
+ Line 15007
  Line 14947
  Line 15007
  Known bugs are described in the file @file{BUGS} in the Gforth distribution.
- If you find a bug, please send a bug report to
+ If you find a bug, please submit a bug report through
- @email{bug-gforth@@gnu.org}. A bug report should include this
+ @uref{https://savannah.gnu.org/bugs/?func=addbug&group=gforth}.
- information:
  @itemize @bullet
  @item
- Line 14991
+ Line 15050
  Line 14991
  Line 15050
  @file{glosgen.fs}, while Stuart Ramsden has been working on automatic
  support for calling C libraries. Helpful comments also came from Paul
  Kleinrubatscher, Christian Pirker, Dirk Zoller, Marcel Hendrix, John
- Wavrik, Barrie Stott, Marc de Groot, Jorge Acerada, Bruce Hoyt, and
+ Wavrik, Barrie Stott, Marc de Groot, Jorge Acerada, Bruce Hoyt, Robert
- Robert Epprecht. Since the release of Gforth-0.2.1 there were also
+ Epprecht, Dennis Ruffer and David N. Williams. Since the release of
- helpful comments from many others; thank you all, sorry for not listing
+ Gforth-0.2.1 there were also helpful comments from many others; thank
- you here (but digging through my mailbox to extract your names is on my
+ you all, sorry for not listing you here (but digging through my mailbox
- to-do list).
+ to extract your names is on my to-do list).
  Gforth also owes a lot to the authors of the tools we used (GCC, CVS,
  and autoconf, among others), and to the creators of the Internet: Gforth
- Line 15040
+ Line 15099
  Line 15040
  Line 15099
  genealogical information about Forth there.
  @c ------------------------------------------------------------------
- @node Forth-related information, Word Index, Origin, Top
+ @node Forth-related information, Licenses, Origin, Top
  @appendix Other Forth-related information
  @cindex Forth-related information
- Line 15059
+ Line 15118
  Line 15059
  Line 15118
  The ANS Forth standard is most usable in its
  @uref{http://www.taygeta.com/forth/dpans.html, HTML form}.
+ @c ---------------------------------------------------
+ @node  Licenses, Word Index, Forth-related information, Top
+ @appendix Licenses
+ @menu
+ * GNU Free Documentation License::  License for copying this manual.
+ * Copying::                         GPL (for copying this software).
+ @end menu
+ @include fdl.texi
+ @include gpl.texi
  @c ------------------------------------------------------------------
- @node Word Index, Concept Index, Forth-related information, Top
+ @node Word Index, Concept Index, Licenses, Top
  @unnumbered Word Index
  This index is a list of Forth words that have ``glossary'' entries
- Line 15079
+ Line 15153
  Line 15079
  Line 15153
  @c @printindex ky
+ @c -------------------------------------------------------
  @node Concept Index,  , Word Index, Top
  @unnumbered Concept and Word Index
- Line 15088
+ Line 15163
  Line 15088
  Line 15163
  @printindex cp
- @contents
  @bye

-Generate output suitable for use with a patch program
+Legend:



Removed from v.1.92
 


changed lines


 
Added in v.1.116
 Legend:



Removed from v.1.92
 


changed lines


 
Added in v.1.116
-Removed from v.1.92
+Added in v.1.116

CVS Admin

gforth: gforth/doc/gforth.ds

Diff for /gforth/doc/gforth.ds between version 1.92 and 1.116

ViewCVS and CVS Help