SPAN

     Creates a pattern matching the longest string containing only
     characters from the specified string, range, or buffer.

  Syntax

     pattern := SPAN ({string | range | buffer} [, {FORWARD | REVERSE}])

     Parameters

     string               A string containing the characters that TPU is
                          to match in the searched text.

     range                A range containing the characters that TPU is
                          to match in the searched text.

     buffer               A buffer containing the characters that TPU is
                          to match in the searched text.

     FORWARD              A keyword directing TPU to match characters in
                          the forward direction.

     REVERSE              A keyword directing TPU to match characters as
                          follows:  First, match characters in the forward
                          direction until TPU finds a character that is
                          not a member of the set of characters in the
                          specified buffer, range, or string.  Next, return
                          to the first character that SPAN matched and start
                          matching characters in the reverse direction until
                          TPU finds a character not in the specified
                          buffer, range, or string.  You can specify REVERSE
                          only if you are using SPAN in the first element of
                          a pattern being used in a reverse search.  In
                          other contexts, specifying REVERSE has no effect.

                          The behavior enabled by REVERSE allows an
                          alternate form of reverse search.  By default, a
                          reverse search stops as soon as a successful match
                          occurs, even if there might have been a longer
                          successful match in the reverse direction.  By
                          specifying REVERSE with SPAN, you direct TPU
                          not to stop matching in either direction until it
                          has matched as many characters as possible.

  Comments

     SPAN matches one or more characters, each of which must appear in the
     string, range, or buffer passed as the first parameter.  SPAN matches
     as many characters as possible, stopping only if it finds a character
     not present in the string, range, or buffer, or if it reaches the end
     of a line.  SPAN does not cross line boundaries.  To match a pattern
     that may cross one or more line boundaries, use SPANL.

  Examples

     1.  pat1 := SPAN ("1234567890");

         Creates a pattern matching any sequence of numerals and any number
         of contiguous digits on one line.

     2.  pat1 := SPAN ("1234567890", FORWARD);

         This statement has exactly the same effect as Example 1.

     3.  vowel_pattern := SPAN ('aeiouy', REVERSE);

         This statement defines the variable "vowel_pattern" to mean the
         longest string of characters that are all vowels.  If you use the
         following statement:

         the_range := SEARCH (vowel_pattern, REVERSE);

         when the cursor is on the "a" in the word "liaison", then the
         variable "the_range" contains the string "iai".  This is because
         when you use SPAN with REVERSE as the first element of a pattern,
         and then use that pattern in a reverse search, SPAN matches as many
         characters as possible in both the forward and reverse directions.

         If the cursor is on the "a" but you define the variable
         "vowel_pattern" without the REVERSE keyword, like this:

         vowel_pattern := SCAN ('aeiouy');

         and then do a reverse search, "the_range" contains the string "ai",
         showing that the search matched from the starting point forward but
         did not return to the starting point to match backward as well.

  Related Topics

  ANCHOR       ANY       ARB              MATCH      NOTANY     SCAN
  SCANL        SEARCH    SEARCH_QUIETLY   SPANL      UNANCHOR