NAME
       regexp - Match a regular expression against a string


SYNOPSIS
       regexp  ?switches? exp string ?matchVar? ?subMatchVar sub-
       MatchVar ...?


DESCRIPTION
       Determines whether the regular expression exp matches part
       or  all  of  string  and  returns  1  if  it does, 0 if it
       doesn't.  (Regular expression matching is described in the
       re_syntax reference page.)

       If  additional  arguments  are specified after string then
       they are treated as the names of  variables  in  which  to
       return  information  about which part(s) of string matched
       exp.  MatchVar will be set to the  range  of  string  that
       matched  all  of  exp.  The first subMatchVar will contain
       the characters in string that matched the leftmost  paren-
       thesized  subexpression  within  exp, the next subMatchVar
       will contain the characters that matched the  next  paren-
       thesized subexpression to the right in exp, and so on.

       If  the initial arguments to regexp start with - then they
       are treated as switches.  The following switches are  cur-
       rently supported:

       -nocase        Causes  upper-case  characters in string to
                      be treated as lower case during the  match-
                      ing process.

       -indices       Changes what is stored in the subMatchVars.
                      Instead of storing the matching  characters
                      from  string,  each variable will contain a
                      list of  two  decimal  strings  giving  the
                      indices  in  string  of  the first and last
                      characters in the matching range of charac-
                      ters.

       -expanded      Enables use of the expanded regular expres-
                      sion syntax where whitespace  and  comments
                      are  ignored.  This is the same as specify-
                      ing the (?x) embedded option (see  METASYN-
                      TAX, below).

       -line          Enables   newline-sensitive  matching.   By
                      default, newline is a  completely  ordinary
                      character  with  no  special meaning.  With
                      this flag, `[^' bracket expressions and `.'
                      never  match  newline, `^' matches an empty
                      string after any newline in addition to its
                      normal  function,  and `$' matches an empty
                      string before any newline  in  addition  to
                      its  normal function.  This flag is equiva-
                      lent to specifying both -linestop and -lin-
                      eanchor,  or  the (?n) embedded option (see
                      METASYNTAX, below).

       -linestop      Changes  the  behavior  of   `[^'   bracket
                      expressions  and  `.'  so that they stop at
                      newlines.  This is the same  as  specifying
                      the  (?p)  embedded option (see METASYNTAX,
                      below).

       -lineanchor    Changes the behavior of `^'  and  `$'  (the
                      ``anchors'')  so  they  match the beginning
                      and end of a line  respectively.   This  is
                      the  same  as  specifying the (?w) embedded
                      option (see METASYNTAX, below).

       -about         Instead of attempting to match the  regular
                      expression,   returns   a  list  containing
                      information about the  regular  expression.
                      The  first  element of the list is a subex-
                      pression count.  The second  element  is  a
                      list  of property names that describe vari-
                      ous attributes of the  regular  expression.
                      This   switch  is  primarily  intended  for
                      debugging purposes.

       --             Marks the end of  switches.   The  argument
                      following  this  one will be treated as exp
                      even if it starts with a -.

       If there are more subMatchVar's than parenthesized  subex-
       pressions  within exp, or if a particular subexpression in
       exp doesn't match the string (e.g. because  it  was  in  a
       portion  of  the expression that wasn't matched), then the
       corresponding subMatchVar will be  set  to  ``-1  -1''  if
       -indices  has  been specified or to an empty string other-
       wise.


SEE ALSO
       re_syntax(n)


KEYWORDS
       match, regular expression, string
