home *** CD-ROM | disk | FTP | other *** search
/ InfoMagic Source Code 1993 July / THE_SOURCE_CODE_CD_ROM.iso / languages / tcl / tcl7.0b1 / doc / regsub.n < prev    next >
Encoding:
Text File  |  1993-06-17  |  3.5 KB  |  89 lines
  1. '\"
  2. '\" Copyright (c) 1993 The Regents of the University of California.
  3. '\" All rights reserved.
  4. '\"
  5. '\" Permission is hereby granted, without written agreement and without
  6. '\" license or royalty fees, to use, copy, modify, and distribute this
  7. '\" documentation for any purpose, provided that the above copyright
  8. '\" notice and the following two paragraphs appear in all copies.
  9. '\"
  10. '\" IN NO EVENT SHALL THE UNIVERSITY OF CALIFORNIA BE LIABLE TO ANY PARTY
  11. '\" FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES
  12. '\" ARISING OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF THE UNIVERSITY OF
  13. '\" CALIFORNIA HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  14. '\"
  15. '\" THE UNIVERSITY OF CALIFORNIA SPECIFICALLY DISCLAIMS ANY WARRANTIES,
  16. '\" INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
  17. '\" AND FITNESS FOR A PARTICULAR PURPOSE.  THE SOFTWARE PROVIDED HEREUNDER IS
  18. '\" ON AN "AS IS" BASIS, AND THE UNIVERSITY OF CALIFORNIA HAS NO OBLIGATION TO
  19. '\" PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.
  20. '\" 
  21. '\" $Header: /user6/ouster/tcl/man/RCS/regsub.n,v 1.2 93/06/17 13:31:43 ouster Exp $ SPRITE (Berkeley)
  22. '\" 
  23. .so man.macros
  24. .HS regsub tcl
  25. .BS
  26. '\" Note:  do not modify the .SH NAME line immediately below!
  27. .SH NAME
  28. regsub \- Perform substitutions based on regular expression pattern matching
  29. .SH SYNOPSIS
  30. \fBregsub \fR?\fIswitches\fR? \fIexp string subSpec varName\fR
  31. .BE
  32.  
  33. .SH DESCRIPTION
  34. .PP
  35. This command matches the regular expression \fIexp\fR against
  36. \fIstring\fR,
  37. .VS
  38. and it copies \fIstring\fR to the variable whose name is
  39. given by \fIvarName\fR.
  40. The command returns 1 if there is a match and 0 if there isn't.
  41. If there is a match, then while copying \fIstring\fR to \fIvarName\fR
  42. the portion of \fIstring\fR that
  43. .VE
  44. matched \fIexp\fR is replaced with \fIsubSpec\fR.
  45. If \fIsubSpec\fR contains a ``&'' or ``\e0'', then it is replaced
  46. in the substitution with the portion of \fIstring\fR that
  47. matched \fIexp\fR.
  48. If \fIsubSpec\fR contains a ``\e\fIn\fR'', where \fIn\fR is a digit
  49. between 1 and 9, then it is replaced in the substitution with
  50. the portion of \fIstring\fR that matched the \fIn\fR-th
  51. parenthesized subexpression of \fIexp\fR.
  52. Additional backslashes may be used in \fIsubSpec\fR to prevent special
  53. interpretation of ``&'' or ``\e0'' or ``\e\fIn\fR'' or
  54. backslash.
  55. The use of backslashes in \fIsubSpec\fR tends to interact badly
  56. with the Tcl parser's use of backslashes, so it's generally
  57. safest to enclose \fIsubSpec\fR in braces if it includes
  58. backslashes.
  59. .LP
  60. If the initial arguments to \fBregexp\fR start with \fB\-\fR then
  61. .VS
  62. they are treated as switches.  The following switches are
  63. currently supported:
  64. .TP 10
  65. \fB\-all\fR
  66. All ranges in \fIstring\fR that match \fIexp\fR are found and
  67. substitution is performed for each of these ranges.
  68. Without this switch only the first
  69. matching range is found and substituted.
  70. If \fB\-all\fR is specified, then ``&'' and ``\e\fIn\fR''
  71. sequences are handled for each substitution using the information
  72. from the corresponding match.
  73. .TP 10
  74. \fB\-nocase\fR
  75. Upper-case characters in \fIstring\fR will be converted to lower-case
  76. before matching against \fIexp\fR;  however, substitutions specified
  77. by \fIsubSpec\fR use the original unconverted form of \fIstring\fR.
  78. .TP 10
  79. \fB\-\|\-\fR
  80. Marks the end of switches.  The argument following this one will
  81. be treated as \fIexp\fR even if it starts with a \fB\-.
  82. .VE
  83. .PP
  84. See the manual entry for \fBregexp\fR for details on the interpretation
  85. of regular expressions.
  86.  
  87. .SH KEYWORDS
  88. match, pattern, regular expression, substitute
  89.