scanset.icn: Procedures setup for string scanning procedures

link scanset
June 4, 1993; Robert J. Alexander
This file is in the public domain.

Procedure to set up for user-written string-scanning procedures that
are in the spirit of Icon's built-ins.

The values passed are the s, i1, i2 parameters which are the last
three arguments to all Icon scanning functions (such as
upto(c,s,i1,i2)).  scan_setup() supplies any appropriate defaults and
returns needed values.

The value returned is a "scan_setup_result" record consisting of two
values:

     1.  The substring of s to be scanned (ss).
     2.  The size of the substring of s that precedes the
         substring to be scanned (offset).

scan_setup() fails if i1 or i2 is out of range with respect to s.

The user-written procedure can then match in the string ss to compute
the position within ss appropriate to the scan (p).  The value
returned (or suspended) to the caller is p + offset (the position
within the original string, s).

For example, the following function finds two words separated by
spaces:

     procedure two_words(s,i1,i2)
        local x,p
        x := scan_setup(s,i1,i2) | fail      # fail if out of range
        x.ss ? suspend {
           tab(upto(&letters)) &
           pos(1) | (move(-1) & tab(any(~&letters))) &
           p := &pos &               # remember starting position
           tab(many(&letters)) &
           tab(many(' ')) &
           tab(many(&letters)) &
           p + x.offset              # return position in original s
           }
     end