title: PARSE-AREA!
description:
    PARSE-AREA! ( c-addr len -- )       "parse-area-store"

    Set the parse area to the string specified by (addr,len).
    Assuming that (addr,len) in within the refill buffer,
    adjust >IN and the variable that holds the length of the
    input source ( #TIB on some systems) appropriately.

See:
 PARSE-AREA@ ../parse-area-fetch/index.html
 SOURCE! ../source-store/index.html

definition-of-terms:
    For definition of the source refill buffer, see SOURCE! ../source-store/index.html

implementation:

: PARSE-AREA! ( a l -- )
        SWAP SOURCE DROP ( l a sa )
        - DUP >IN ! + #TIB !
;
\ #TIB ! is unstandard; it sets the length of the input buffer.

The following definition half-functional:
it is enough if you do not want to change the end of the input buffer
via PARSE-AREA! . It just ignores the length of the string passed to it.

: PARSE-AREA! ( addr len -- )
    DROP  SOURCE DROP  -  >IN !
;

Its advantage is that it is almost ANS-standard, with the only dependency
on char size being one. To make it standard, insert 1 CHARS / before >IN ! .
The programs that work with half-functional PARSE-AREA! will also work with
fully functional PARSE-AREA! , but not vice versa.

words-from-the-inventor:

J.Brien wrote:

> My aim with PARSE-AREA@  etc. is [...] to unify the use of
> parsing and pattern-matching words. It's quite useful to
> treat a data as 'source' - you don't have to worry about
> reserving buffers and opening and closing files. Just kick
> off the process with ' xt FILE-PARSE (was that the name we
> finally settled on - I forget) or  INCLUDE an ascii text
> file and define the first word in it as a Forth definition -
> as can be done with XML or HTML files.
>
> [...] PARSE and WORD are  often not the tools required.  So,
> use COMPARE, SEARCH, etc to write general pattern-matching
> words with the stack diagram
>
>                  PatternMatch   \ ca u --  ca1 u1 ca2 u2 ;
> where
>    ca1 u1 = string-still-to-match
> and
>    ca2 u2 = string-matched
>
> and use them in the form:
>
> ~~~tag[code]tag~~~ PARSE-AREA@  PatternMatch /dosomething/ PARSE-AREA! ~~~tag[/code]tag~~~

<hr>
The old version of this page:
<small>
<small>
description:
    PARSE-AREA! ( c-addr len -- )       "parse-area-store"

    Set the parse area to the string specified by (addr,len).
    If the new parse area is within the current input buffer,
    adjust >IN appropriately. Else, make (c-addr,len) the input buffer
    and store 0 to >IN . Do not modify SOURCE-ID.

notes:
    The system must be aware of this word.
    It must maintain the input buffer (returned by SOURCE and read by
    parsing words) and the source refill buffer (written to by REFILL)
    separately. PARSE-AREA! allows program to set the input buffer
    outside of the source refill buffer. REFILL is required to
    set the input buffer back to the source refill buffer.

See:
 PARSE-AREA@ ../parse-area-fetch/index.html
 SOURCE! ../source-store/index.html

definition-of-terms:
    For definition of the source refill buffer, see SOURCE! ../source-store/index.html


words-from-the-inventor:

J.Brien wrote:

> My aim with PARSE-AREA@  etc. is [...] to unify the use of
> parsing and pattern-matching words. It's quite useful to
> treat a data as 'source' - you don't have to worry about
> reserving buffers and opening and closing files. Just kick
> off the process with ' xt FILE-PARSE (was that the name we
> finally settled on - I forget) or  INCLUDE an ascii text
> file and define the first word in it as a Forth definition -
> as can be done with XML or HTML files.
>
> [...] PARSE and WORD are  often not the tools required.  So,
> use COMPARE, SEARCH, etc to write general pattern-matching
> words with the stack diagram
>
>                  PatternMatch   \ ca u --  ca1 u1 ca2 u2 ;
> where
>    ca1 u1 = string-still-to-match
> and
>    ca2 u2 = string-matched
>
> and use them in the form:
>
> ~~~tag[code]tag~~~ PARSE-AREA@  PatternMatch /dosomething/ PARSE-AREA!
~~~tag[/code]tag~~~

implementation:

( by mlg)
: PARSE-AREA! ( c-addr len -- )
    2DUP SOURCE ( a l a l sa sl )
    ROT - >R -  ( a l a-sa ) ( r: sl-l )
    R@ <>  R@ 0< OR
    IF
        R> DROP SOURCE!
    ELSE
        2DROP R> >IN !
    THEN
;
\ if sl-l = a-sa , that is, sl+sa = a+l,
\ and if sl-l >= 0 , that is, l <= sl,
\ then it is within the same input buffer and we adjust >IN .

For some applications, such as some parsers, PARSE-AREA! can
do nothing else than adjust >IN by the appropriate number
of characters. In other words, the full-featured functionality
of PARSE-AREA! shown above is not always necessary.

</small>
</small>