Summary

###########################################################################

	File:     scan.icn

	Subject:  Procedures related to scanning

	Author:   Richard L. Goerwitz, David A. Gamey, and Ralph E. Griswold

	Date:     May 2, 2001

###########################################################################

  This file is in the public domain.

###########################################################################

	Contributors:  Randal L. Schwartz and Cheyenne Wills

###########################################################################

  This module contains procedures related to string scanning:

	balq(c1, c2, c3, c4, c5, s, i1, i2)
		like bal() with quoting from characters in c5.

       balqc(c1, c2, c3, c4, c5, s1, s2, s3, i1, i2)
		like balq() with the addition that balanced characters within
       	"comments", as delimited by the strings s1 and s2, are also
        	excluded from balancing.  In addition, if s1 is given and s2

       limatch(L, c)
		matches items in list L delimited by characters in c

	slashbal(c1, c2, c3, s, i, j)
		like bal() with escape processing

	slashupto(c, s, i, j)
		like upto() with escape processing

	slshupto()
		synonym for slashupto()

	snapshot(title, len)
		snapshot of string scanning with optional title and
		maximum length.

  More extensive documentation proceeds each procedure.

###########################################################################

  Richard L. Goerwitz:

  I am often frustrated at bal()'s inability to deal elegantly with
  the common \backslash escaping convention (a way of telling Unix
  Bourne and C shells, for instance, not to interpret a given
  character as a "metacharacter").  I recognize that bal()'s generic
  behavior is a must, and so I wrote slashbal() to fill the gap.

  Slashbal behaves like bal, except that it ignores, for purposes of
  balancing, any c2/c3 char which is preceded by a backslash.  Note
  that we are talking about internally represented backslashes, and
  not necessarily the backslashes used in Icon string literals.  If
  you have "\(" in your source code, the string produced will have no
  backslash.  To get this effect, you would need to write "\\(."

  BUGS:  Note that, like bal() (v8), slashbal() cannot correctly
  handle cases where c2 and c3 intersect.  Note also that older ver-
  sions of this routine counted from the beginning of the string,
  instead of from i.  This feature came to be regarded as a bug when
  put into actual use (especially when I realized that bal() doesn't
  work this way).

###########################################################################

This file is part of the (main) package.

balq(cstop, copen, cclose, cquote, cescape, s, i1, i2)

: bal() with quote escaping.

balqc(cstop, copen, cclose, cquote, cescape, scm, ecm, s, i1, i2)

: balq() with comment escaping

limatch(l, i)

: matching items in list

slashbal(c1, c2, c3, s, i, j)

: bal() with escapes

slashupto(c, s, i, j)

 for compatibility with the original name

: upto() with escapes

slshupto(c, s, i, j)

 slshupto:  cset x string x integer x integer -> integers
             (c, s, i, j) -> I's (a generator)
    where I's are the integer positions in s[i:j] before characters
    in c that is not preceded by a backslash escape

: upto() with escapes

snapshot(title, len)

: snapshot of string scanning