Tcl Source Code

Diff
Login
Bounty program for improvements to Tcl and certain Tcl packages.

Differences From Artifact [37f3f8ee4d]:

To Artifact [53b2daaa54]:


     1      1   '\"
     2      2   '\" Copyright (c) 1993 The Regents of the University of California.
     3      3   '\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
     4      4   '\"
     5      5   '\" See the file "license.terms" for information on usage and redistribution
     6      6   '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
     7      7   '\" 
     8         -'\" RCS: @(#) $Id: Tcl.n,v 1.9 2003/02/01 19:48:23 kennykb Exp $
            8  +'\" RCS: @(#) $Id: Tcl.n,v 1.18 2007/12/13 15:22:32 dgp Exp $
     9      9   '\"
    10     10   .so man.macros
    11         -.TH Tcl n "8.1" Tcl "Tcl Built-In Commands"
           11  +.TH Tcl n "8.5" Tcl "Tcl Built-In Commands"
    12     12   .BS
    13     13   .SH NAME
    14     14   Tcl \- Tool Command Language
    15     15   .SH SYNOPSIS
    16     16   Summary of Tcl language syntax.
    17     17   .BE
    18     18   .SH DESCRIPTION
................................................................................
    37     37   in any way it likes, such as an integer, variable name, list,
    38     38   or Tcl script.
    39     39   Different commands interpret their words differently.
    40     40   .IP "[3] \fBWords.\fR"
    41     41   Words of a command are separated by white space (except for
    42     42   newlines, which are command separators).
    43     43   .IP "[4] \fBDouble quotes.\fR"
    44         -If the first character of a word is double-quote (``"'') then
    45         -the word is terminated by the next double-quote character.
           44  +If the first character of a word is double-quote
           45  +.PQ \N'34'
           46  +then the word is terminated by the next double-quote character.
    46     47   If semi-colons, close brackets, or white space characters
    47     48   (including newlines) appear between the quotes then they are treated
    48     49   as ordinary characters and included in the word.
    49     50   Command substitution, variable substitution, and backslash substitution
    50     51   are performed on the characters between the quotes as described below.
    51     52   The double-quotes are not retained as part of the word.
    52         -.IP "[5] \fBBraces.\fR"
    53         -If the first character of a word is an open brace (``{'') then
    54         -the word is terminated by the matching close brace (``}'').
           53  +.VS 8.5 br
           54  +.IP "[5] \fBArgument expansion.\fR"
           55  +If a word starts with the string
           56  +.QW {*}
           57  +followed by a non-whitespace character, then the leading
           58  +.QW {*}
           59  +is removed
           60  +and the rest of the word is parsed and substituted as any other
           61  +word. After substitution, the word is parsed again without
           62  +substitutions, and its words are added to the command being
           63  +substituted. For instance,
           64  +.QW "cmd a {*}{b c} d {*}{e f}"
           65  +is equivalent to
           66  +.QW "cmd a b c d e f" .
           67  +.VE 8.5
           68  +.IP "[6] \fBBraces.\fR"
           69  +If the first character of a word is an open brace
           70  +.PQ {
           71  +and rule [5] does not apply, then
           72  +the word is terminated by the matching close brace
           73  +.PQ } "" .
    55     74   Braces nest within the word: for each additional open
    56     75   brace there must be an additional close brace (however,
    57     76   if an open brace or close brace within the word is
    58     77   quoted with a backslash then it is not counted in locating the
    59     78   matching close brace).
    60     79   No substitutions are performed on the characters between the
    61     80   braces except for backslash-newline substitutions described
    62     81   below, nor do semi-colons, newlines, close brackets,
    63     82   or white space receive any special interpretation.
    64     83   The word will consist of exactly the characters between the
    65     84   outer braces, not including the braces themselves.
    66         -.IP "[6] \fBCommand substitution.\fR"
    67         -If a word contains an open bracket (``['') then Tcl performs
    68         -\fIcommand substitution\fR.
           85  +.IP "[7] \fBCommand substitution.\fR"
           86  +If a word contains an open bracket
           87  +.PQ [
           88  +then Tcl performs \fIcommand substitution\fR.
    69     89   To do this it invokes the Tcl interpreter recursively to process
    70     90   the characters following the open bracket as a Tcl script.
    71     91   The script may contain any number of commands and must be terminated
    72         -by a close bracket (``]'').
           92  +by a close bracket
           93  +.PQ ] "" .
    73     94   The result of the script (i.e. the result of its last command) is
    74     95   substituted into the word in place of the brackets and all of the
    75     96   characters between them.
    76     97   There may be any number of command substitutions in a single word.
    77     98   Command substitution is not performed on words enclosed in braces.
    78         -.IP "[7] \fBVariable substitution.\fR"
    79         -If a word contains a dollar-sign (``$'') then Tcl performs \fIvariable
           99  +.IP "[8] \fBVariable substitution.\fR"
          100  +If a word contains a dollar-sign
          101  +.PQ $
          102  +followed by one of the forms
          103  +described below, then Tcl performs \fIvariable
    80    104   substitution\fR:  the dollar-sign and the following characters are
    81    105   replaced in the word by the value of a variable.
    82    106   Variable substitution may take any of the following forms:
    83    107   .RS
    84    108   .TP 15
    85    109   \fB$\fIname\fR
    86    110   \fIName\fR is the name of a scalar variable;  the name is a sequence
................................................................................
    98    122   \fB${\fIname\fB}\fR
    99    123   \fIName\fR is the name of a scalar variable.  It may contain any
   100    124   characters whatsoever except for close braces.
   101    125   .LP
   102    126   There may be any number of variable substitutions in a single word.
   103    127   Variable substitution is not performed on words enclosed in braces.
   104    128   .RE
   105         -.IP "[8] \fBBackslash substitution.\fR"
   106         -If a backslash (``\e'') appears within a word then
   107         -\fIbackslash substitution\fR occurs.
          129  +.IP "[9] \fBBackslash substitution.\fR"
          130  +If a backslash
          131  +.PQ \e
          132  +appears within a word then \fIbackslash substitution\fR occurs.
   108    133   In all cases but those described below the backslash is dropped and
   109    134   the following character is treated as an ordinary
   110    135   character and included in the word.
   111    136   This allows characters such as double quotes, close brackets,
   112    137   and dollar signs to be included in words without triggering
   113    138   special processing.
   114    139   The following table lists the backslash sequences that are
................................................................................
   138    163   .TP 7
   139    164   \e\fB<newline>\fIwhiteSpace\fR
   140    165   .
   141    166   A single space character replaces the backslash, newline, and all spaces
   142    167   and tabs after the newline.  This backslash sequence is unique in that it
   143    168   is replaced in a separate pre-pass before the command is actually parsed.
   144    169   This means that it will be replaced even when it occurs between braces,
   145         -and the resulting space will be treated as a word separator if it isn't
          170  +and the resulting space will be treated as a word separator if it is not
   146    171   in braces or quotes.
   147    172   .TP 7
   148    173   \e\e
   149         -Backslash (``\e'').
   150         -.VS 8.1 br
          174  +Backslash
          175  +.PQ \e "" .
   151    176   .TP 7
   152    177   \e\fIooo\fR 
   153    178   .
   154    179   The digits \fIooo\fR (one, two, or three of them) give an eight-bit octal 
   155    180   value for the Unicode character that will be inserted.  The upper bits of the
   156    181   Unicode character will be 0.
   157    182   .TP 7
................................................................................
   164    189   be 0.
   165    190   .TP 7
   166    191   \e\fBu\fIhhhh\fR 
   167    192   .
   168    193   The hexadecimal digits \fIhhhh\fR (one, two, three, or four of them) give a
   169    194   sixteen-bit hexadecimal value for the Unicode character that will be
   170    195   inserted.
   171         -.VE
   172    196   .LP
   173    197   Backslash substitution is not performed on words enclosed in braces,
   174    198   except for backslash-newline as described above.
   175    199   .RE
   176         -.IP "[9] \fBComments.\fR"
   177         -If a hash character (``#'') appears at a point where Tcl is
          200  +.IP "[10] \fBComments.\fR"
          201  +If a hash character
          202  +.PQ #
          203  +appears at a point where Tcl is
   178    204   expecting the first character of the first word of a command,
   179    205   then the hash character and the characters that follow it, up
   180    206   through the next newline, are treated as a comment and ignored.
   181    207   The comment character only has significance when it appears
   182    208   at the beginning of a command.
   183         -.IP "[10] \fBOrder of substitution.\fR"
          209  +.IP "[11] \fBOrder of substitution.\fR"
   184    210   Each character is processed exactly once by the Tcl interpreter
   185    211   as part of creating the words of a command.
   186    212   For example, if variable substitution occurs then no further
   187    213   substitutions are performed on the value of the variable;  the
   188    214   value is inserted into the word verbatim.
   189    215   If command substitution occurs then the nested command is
   190    216   processed entirely by the recursive call to the Tcl interpreter;
................................................................................
   197    223   evaluated completely before attempting to evaluate the next.  Thus, a
   198    224   sequence like
   199    225   .CS
   200    226   set y [set x 0][incr x][incr x]
   201    227   .CE
   202    228   will always set the variable \fIy\fR to the value, \fI012\fR.
   203    229   .RE
   204         -.IP "[11] \fBSubstitution and word boundaries.\fR"
   205         -Substitutions do not affect the word boundaries of a command.
          230  +.IP "[12] \fBSubstitution and word boundaries.\fR"
          231  +Substitutions do not affect the word boundaries of a command,
          232  +except for argument expansion as specified in rule [5].
   206    233   For example, during variable substitution the entire value of
   207    234   the variable becomes part of a single word, even if the variable's
   208    235   value contains spaces.