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

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

                       => {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


Man(1) output converted with man2html