:TITLE: Evaluation & Substitutions 3: Grouping arguments with []
;#
;# RCSID: $Header: /cvsroot/tcl/tcltutorial/original/Tcl5.lsn,v 1.1 2004/11/04 16:01:14 davidw Exp $
;# Copyright (c) 1995 Clif Flynt
;# 9300 Fleming Rd.
;# Dexter, MI  48130
;# clif@cflynt.com
;# See file "NOTICE" for licensing terms.
;#
:LESSON_TEXT_START_LEVEL 0:
During the substitution phase, a string within square brackets ([])
will be evaluated as a command, and will be replaced by 
the return value of the command, unless the square bracket
has been escaped with a backslash.
<P>
This is the functional equivalent of the back
single quote in sh programming, or calling a function in C, but is
actually part of the Tcl substitution phase.  

:TEXT_END: 

:LESSON_TEXT_START_LEVEL 1:

You gain access to the results of a command by placing the command in
square brackets ([]).  This is the functional equivalent of the back
single quote in sh programming, or calling a function in C, but is
actually part of the Tcl substitution phase. 

<P>

As the Tcl interpreter reads in a line it
replaces all the $variables with their values.  If a portion of the string 
is grouped with square brackets, then the string within the  square brackets
is passed to the evaluation portion of the interpreter, a
substitution pass is made, and the result of the command replaces the
square bracketed string.  

<P>
The exceptions to this rule are as follows:
<UL>
<LI> A square bracket that is escaped with a \ is considered as a literal square bracket.
<LI> A square bracket within braces is not modified during the substitution phase.
</UL>
<P>
Run the examples, and examine the output to see how the brackets, quotes
and braces are used. 
:TEXT_END:

:LESSON_TEXT_START_LEVEL 2:
Most computer programming tasks involve manipulating
data with commands, and storing the data to be accessed
again later by other commands.  In TCL you gain access
to the results of a command by placing the command string
within square brackets ([]).

<P>

In the previous lessons, we learned that as the TCL
reads in a line, it replaces all the $variables with
their values.  When the TCL interpreter encounters a
string within square brackets, the bracketed string is
passed to the evaluation portion of the interpreter.
The evaluation portion makes a single substitution
pass, and then executes the command, exactly as if the
bracketed string appeared on a line by itself without
brackets.  However, the result of the command then
replaces the bracketed string, and the interpreter
continues with the substitution pass on the line
as it now appears with the substituted command result.

<P>

The mechanism for this is that when the interpreter encounters a string
within square brackets, 
the string within the brackets is passed to the evaluation portion of
the interpreter.  The evaluation portion of the interpreter makes a single
substitution pass, and then executes the command, 
exactly the same as if the string appeared on a line by
itself with no brackets.  However, when the command has executed, the
result of the command replaces the square bracketed string, and the
interpreter continues with the substitution pass on the first string. 
<P>
Glance at the third line in the example:
<PRE><CODE>
set y [set x "def"]
</CODE></PRE>

Remember that a <B>set</B> command returns the current value of the
variable being set.  In this command the string within the
square brackets assigns the value <B>"def"</B> to the variable <B>x</B>.
During the substitution phase, this string is extracted from the command
and is executed.  The results of the assignment are now put into the command
string, replacing the bracketed string, and the command now resembles:
<PRE><CODE>
set y "def".
</CODE></PRE>
Then the command is executed, and "def" is assigned to y.


<P>
The exceptions to this rule are as follows:
<UL>
<LI> A square bracket that is escaped with a \ is considered as a literal square bracket.
<LI> A square bracket within braces is not modified during the substitution phase.
</UL>
<P>
Run the examples, and examine the output to see how the brackets, quotes
and braces are used. 
:TEXT_END:

:CODE_START:
set x "abc"
puts "A simple substitution: $x\n"

set y [set x "def"]
puts "Remember that set returns the new value of the variable: X: $x Y: $y\n"

set z {[set x "This is a string within quotes within braces"]}
puts "Note the curly braces: $z\n"

set a "[set x {This is a string within braces within quotes}]"
puts "See how the set is executed: $a"
puts "\$x is: $x\n"

set b "\[set y {This is a string within braces within quotes}]"
puts "Note the \\ escapes the bracket:\n \$b is: $b"
puts "\$y is: $y"

:TEXT_END: