DOC HOME SITE MAP MAN PAGES GNU INFO SEARCH PRINT BOOK
 

regexp(n)




______________________________________________________________________________


NAME

       regexp - Match a regular expression against a string


SYNOPSIS

       regexp ?switches? exp string ?matchVar? ?subMatchVar subMatchVar ...?
_________________________________________________________________


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).   (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 parenthesized subex-
       pression  within  exp, the next subMatchVar will contain the characters
       that matched the next parenthesized 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 currently 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 prop-
                      erty names that describe various attributes of the regu-
                      lar  expression.  This  switch is primarily intended for
                      debugging purposes.

       -expanded      Enables use of the expanded  regular  expression  syntax
                      where  whitespace and comments are ignored.  This is the
                      same as specifying the (?x)  embedded  option  (see  the
                      re_syntax manual page).

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

       -line          Enables newline-sensitive matching.  By default, newline
                      is a completely ordinary character with no special mean-
                      ing.   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 equivalent to
                      specifying both -linestop and -lineanchor, or  the  (?n)
                      embedded option (see the re_syntax manual page).

       -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 the re_syntax
                      manual page).

       -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 the re_syntax manual page).

       -nocase        Causes  upper-case characters in string to be treated as
                      lower case during the matching 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 contain 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  subexpressions
       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 otherwise.


EXAMPLES

       Find the first occurrence of a word starting with foo in a string  that
       is not actually an instance of foobar, and get the letters following it
       up to the end of the word into a variable:
              regexp {\<foo(?!bar\>)(\w*)} $string -> restOfWord
       Note that the whole matched substring has been placed in  the  variable
       ->  which  is a name chosen to look nice given that we are not actually
       interested in its contents.

       Find the index of the word badger (in any case)  within  a  string  and
       store that in the variable location:
              regexp -indices {(?i)\<badger\>} $string location

       Count the number of octal digits in a string:
              regexp -all {[0-7]} $string

       List  all  words (consisting of all sequences of non-whitespace charac-
       ters) in a string:
              regexp -all -inline {\S+} $string


SEE ALSO

       re_syntax(n), regsub(n)


KEYWORDS

       match, regular expression, string

Tcl                                   8.3                            regexp(n)

Man(1) output converted with man2html