PARSE-NAME

`PARSE-NAME`

Poll standings

See below for voting instructions.

Systems

[ ] conforms to ANS Forth.
 MPE VFX Forth for Windows/DOS/Linux
 MPE Forth 6 cross compilers
 Gforth
 bigFORTH
 PFE (Guido Draheim)
 iForth (Marcel Hendrix)
[ ] already implements the proposal in full since release [ ]:
 4th 3.5a (Hans Bezemer)
 iForth 3.0
[ ] implements the proposal in full in a development version:
 Gforth
 bigFORTH
 PFE
[ ] will implement the proposal in full in release [ ].
 VFX Forth 3.8 for Windows/DOS/Linux
 Gforth 0.7
 bigFORTH 2.1.1
 PFE 33.67
[ ] will implement the proposal in full in some future release.
 MPE Forth 6 cross compilers (after 6.3)
 Quartus Forth
There are no plans to implement the proposal in full in [ ].
[ ] will never implement the proposal in full:

Programmers

[ ] I have used (parts of) this proposal in my programs:
 Ruvim Pinka
 Robert Epprecht
 Hans Bezemer
[ ] I would use (parts of) this proposal in my programs if the systems
    I am interested in implemented it:
 Anton Ertl
 Bernd Paysan
[ ] I would use (parts of) this proposal in my programs if this
    proposal was in the Forth standard:
 David N. Williams
 Stephen Pelc
[ ] I would not use (parts of) this proposal in my programs.

Informal results

Quartus Forth 2.0.0: After you add the following definition, Quartus Forth implements the proposal in full:
```
' parse-word alias parse-name
```
PFE also implements the functionality under the name PARSE-WORD.

Change history

2005-05-06: Added information about Mops' PARSE-WORD.
2005-04-22: This is a renamed version of the PARSE-WORD RfD. Apart from the naming issue the main difference to the first PARSE-WORD RfD is the addition of a section on white space, and a section on passing an explicit delimiter.

Problem

How do we parse a word from the input stream?

PARSE does not skip leading delimiters, and you cannot specify that you want to parse for white space.

WORD skips leading delimiters, but you cannot specify parsing for white space, it creates a counted string (not the preferred representation), the length of the string is therefore limited, it requires a separate buffer (typically limitinmg the string size even more, and the copying to that buffer consumes time); WORD also requires passing a delimiter, although skipping leading delimiters only makes sense for white-space delimiters. ANS Forth does not specify the lifetime of the resulting string precisely.

Proposal

PARSE-NAME  ( "name" -- c-addr u ) CORE-EXT

Skip leading white space and parse name delimited by a white space character.

c-addr is the address within the input buffer and u is the length of the selected string. If the parse area is empty or contains only white space, the resulting string has length zero.

Typical Use

PARSE-NAME some-name TYPE

Remarks

Lifetime

The lifetime of the resulting string is specified implicitly through "within the input buffer", as is done in PARSE; i.e., the string will be usable until the next input buffer is read, for whatever reason (REFILL, INCLUDED, etc.). Should the lifetime be made more explicit?

Existing practice

ANS Forth mentions a PARSE-WORD with essentially the same definition in A.6.2.2008. Open Firmware also defines PARSE-WORD with the same definition. The only difference between these definitions and the current definition is that the current definition makes it explicit what happens when there is only white space in the input buffer.

Several systems have implemented a PARSE-WORD compatible with this specification, e.g., Gforth and Quartus.

However, several systems have implemented words called PARSE-WORD that are incompatible with this specification (e.g., MPE's Forths, MinForth, CHForth, F83, Jforth, 4th; Mops is also incompatible, but in a less problematic way), and Stephen Pelc indicated that MPE's Forth would never implement this word with the name PARSE-WORD.

Therefore, a new name is needed for this functionality, and a strawpoll indicated the most support for PARSE-NAME.

What is white space?

I believe that the only white space allowed in ANS Forth programs consists of BL (section 3.4.1.1, treatment of control characters is implementation-defined), but this proposal was written such that it would not need rewriting if the definition of white space was extended in the future.

One other probably widely used and accepted white space character is TAB, but extending the definition of white space may be better left to another RfD.

Systems that support TAB: Gforth, VFX Forth and MPE v6+ embedded systems.

Why not take a delimiter?

WORD takes a delimiter and does with it what PARSE-NAME does with white space. Shouldn't PARSE-NAME also take a delimiter? This is a bad idea, for the following reasons:

Skipping leading delimiters only makes sense when the delimiter is white space.
Most Forth systems support more white space characters than just BL. On these systems a word that takes a delimiter has to special-case the BL input and call a factor like PARSE-NAME. This proposal is about the factor, not the word taking the delimiter.

In a posting a number of uses (in iForth code) of a delimiter-taking word were analysed; the following uses of delimiters were found:

BL

The perfect application for PARSE-NAME.

0

Getting the rest of the line by parsing for an impossible delimiter. 0 PARSE would have given the same result.

Other delimiters, e.g., "

These uses were bugs, and PARSE should have been used instead of the skip-leading-delimiters word. One example of that was .STATUS", which would have accepted

.STATUS" """a string"

and done the wrong thing for

.STATUS" " DUP

Implementation and Tests

Comments

Andrey Cherezov writes: "In the SP-Forth/4 (spf.sourceforge.net) there is 'NextWord' word compatible with this specification."

Voting instructions

Fill out the appropriate ballot(s) below and mail it/them to me <anton@mips.complang.tuwien.ac.at>. Your vote will be published (including your name (without email address) and/or the name of your system) here. You can vote (or change your vote) at any time by mailing to me, and the results will be published here.

Note that you can be both a system implementor and a programmer, so you can submit both kinds of ballots.

Ballot for systems

If you maintain several systems, please mention the systems separately in the ballot. Insert the system name or version between the brackets. Multiple hits for the same system are possible (if they do not conflict).

[ ] conforms to ANS Forth.
[ ] already implements the proposal in full since release [ ].
[ ] implements the proposal in full in a development version.
[ ] will implement the proposal in full in release [ ].
[ ] will implement the proposal in full in some future release.
There are no plans to implement the proposal in full in [ ].
[ ] will never implement the proposal in full.

If you want to provide information on partial implementation, please do so informally, and I will aggregate this information in some way.

Ballot for programmers

Just mark the statements that are correct for you (e.g., by putting an "x" between the brackets). If some statements are true for some of your programs, but not others, please mark the statements for the dominating class of programs you write.

[ ] I have used (parts of) this proposal in my programs.
[ ] I would use (parts of) this proposal in my programs if the systems
    I am interested in implemented it.
[ ] I would use (parts of) this proposal in my programs if this
    proposal was in the Forth standard.
[ ] I would not use (parts of) this proposal in my programs.

If you feel that there is closely related functionality missing from the proposal (especially if you have used that in your programs), make an informal comment, and I will collect these, too. Note that the best time to voice such issues is the RfD stage.

Anton Ertl