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, unless -inline is specified (see below).   (Regu-
       lar expression matching is described in the re_syntax ref-
       erence 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:

       -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.

       -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).

       -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.
       -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).

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

       -all           Causes the regular expression to be matched
                      as many times as possible  in  the  string,
                      returning   the  total  number  of  matches
                      found.  If this  is  specified  with  match
                      variables,  they  will continue information
                      for the last match only.

       -inline        Causes the command to return,  as  a  list,
                      the  data that would otherwise be placed in
                      match variables.  When using -inline, match
                      variables  may  not  be specified.  If used
                      with -all, the list will be concatenated at
                      each  iteration,  such  that a flat list is
                      always returned.  For each match iteration,
                      the  command  will append the overall match
                      data, plus one element for each  subexpres-
                      sion  in  the regular expression.  Examples
                      are:
                          regexp -inline -- {\w(\w)} " inlined "
                       => {in n}
                          regexp -all -inline -- {\w(\w)} " inlined "
                       => {in n li i ne e}

       -start index   Specifies a character index offset into the
                      string   to   start  matching  the  regular
                      expression at.  When using this switch, `^'
                      will  not  match the beginning of the line,
                      and \A will still match the  start  of  the
                      string at index.  If -indices is specified,
                      the indices will be indexed  starting  from
                      the absolute beginning of the input string.
                      index will be constrained to the bounds  of
                      the input string.

       --             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), regsub(n)


KEYWORDS
       match, regular expression, string
