:TITLE: Evaluation & Substitutions 1: Grouping arguments with ""
;#
;# RCSID: $Header: /home/clif/CVS_ROOT/TclTutor/Tcl3.lsn,v 1.19 2000/04/24 16:17:52 clif 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:
This lesson is the first of three which discuss the way
TCL handles substitution during command evaluation.
<P>
In Tcl, the evaluation of a command is done is 2 phases.  The first
phase is a single pass of substitutions. The second phase is the
evaluation of the resulting command.  Note that only <I>one</I> pass of
substitutions is made.
<P>
During the substitution phase, several types of substitutions occur.
<P>
A command within square brackets ([]) is replaced
with the return from the execution of that command.
(This will be explained more fully in the lesson
"Results of a Command - Math 101.")
<P>
Double quotes ("") and braces ({}) will both
group words into a single argument during the
substitution phase, however, their behaviors differ.  The
behavior of braces is covered in the next lesson; the
following discussion pertains to double quotes.
<P>
Grouping words within double quotes allows substitutions to
occur within the quotations.  The substituted group is then evaluated
as a single argument.
<P>
In general, the backslash (\) disables substitution for
the single character immediately following the
backslash.
<P>
The exceptions to this last rule are the "Backslash
Sequence" strings, which are substituted as follows:

<P><UL  COMPACT>
<B>string ... output .................................  hex value</B>

<LI>  \a ............. Audible alert (Bell) .......................\x07
<LI>  \b ............. Backspace .....................................  \x08
<LI>  \f .............. Form Feed (Clear screen) ........  \x0c
<LI>  \n ............. New Line ........................................\x0a
<LI>  \r .............. Carriage Return ...........................  \x0d
<LI>  \t .............. Tab ...................................................  \x09
<LI>  \v ............. Vertical Tab ...................................  \x0b
<LI>  \ddd ......... Octal value .................................... d = 0-7
<LI>  \xhh ......... Hex value .......................................  h = 0-9,A-F,a-f
</UL>
<P>
The final exception is the backslash at the end of a
line of text.  This causes the interpreter to ignore
the newline, and treat the text as a single line of
text.  The interpreter will insert a blank space at the
location of the ending backslash.
<P>
If you haven't hit the <B>Run Example</B> button yet, do so now, and examine
the results of the example.  Play around a bit with the example code, and
then go on to the next lesson.
<P>
:TEXT_END:
:LESSON_TEXT_START_LEVEL 1:
This lesson is the first of three which discuss the way
TCL handles substitution during command evaluation.
<P>
In Tcl, the evaluation of a command is done is 2 phases.  The first
phase is a single pass of substitutions. The second phase is the
evaluation of the resulting command.  Note that only <I>one</I> pass of
substitutions is made. Thus in the command
<PRE><CODE>
puts $varName
</CODE></PRE>
the contents of the proper variable are substituted for
<I>$varName</I>, and then the command is executed.
<P>
During the substitution phase, several types of substitutions occur.
<P>
A command within square brackets ([]) is replaced
with the return from the execution of that command.
(This will be explained more fully in the lesson
"Results of a Command - Math 101.")
<P>
Words within double quotes or braces are grouped into
a single argument.  However, double quotes and braces
cause different behavior during the substitution phase.
In this lesson, we will concentrate on the behavior of 
double quotes during the substitution phase.
<P>
Grouping words within double quotes allows substitutions to
occur within the quotations.  The substituted group is then evaluated
as a single argument.
Thus, in the command
<PRE><CODE>
     puts "The current stock value is $varName"
</CODE></PRE>
the current contents of varName are substituted for
$varName, and then the entire string is printed to the
output device.
<P>
In general, the backslash (\) disables substitution for
the single character immediately following the
backslash.  Any character immediately following the
backslash will stand without substitution.
<P>
However, there are specific "Backslash Sequence"
strings which are replaced by specific values during
the substitution phase.  The following backslash
strings will be substituted as shown below.
<P><UL  COMPACT>
<B>string ... output .................................  hex value</B>

<LI>  \a ............. Audible alert (Bell) .......................\x07
<LI>  \b ............. Backspace .....................................  \x08
<LI>  \f .............. Form Feed (Clear screen) ........  \x0c
<LI>  \n ............. New Line ........................................\x0a
<LI>  \r .............. Carriage Return ...........................  \x0d
<LI>  \t .............. Tab ...................................................  \x09
<LI>  \v ............. Vertical Tab ...................................  \x0b
<LI>  \ddd ......... Octal value .................................... d = 0-7
<LI>  \xhh ......... Hex value .......................................  h = 0-9,A-F,a-f
</UL>
<P>
The final exception is the backslash at the end of a
line of text.  This causes the interpreter to ignore
the newline, and treat the text as a single line of
text.  The interpreter will insert a blank space at the
location of the ending backslash.
<P>
If you haven't hit the <B>Run Example</B> button yet, do so now, and examine
the results of the example.  Play around a bit with the example code, and
then go on to the next lesson.
<P>
:TEXT_END:
:LESSON_TEXT_START_LEVEL 2:
This lesson is the first of three which discuss the way 
TCL handles substitution during command evaluation.
<P>
In Tcl, the evaluation of a command is done in two
phases; a substitution phase and a command evaluation
phase.
<P>
The substitution phase is where much of the 'work' in a Tcl program is
done.  The Tcl interpreter looks at each word from left to right and, when it
finds a word that should be replaced by another value, it does that 
replacement.  During the command evaluation phase, the
compiler evaluates the command, and performs whatever
action that command requests.  Because of the
substitutions, the command that is evaluated may not resemble the command
that you typed.
<P>
Note that only <I>one</I> pass of substitutions is made.
<P>  
The Tcl interpreter performs these substitutions:
<DL>
<DD>Replaces <I>$varName</I> with the contents of <I>varName</I>.
<P>

In the example code, Z is set to "Albany".  When <CODE>puts "$Z_LABEL $Z"
</CODE> is evaluated the <I>$Z_LABEL</I> is replaced with the string "The Capitol
of New York is:  ", and the $Z is replaced by "Albany" before 
<CODE>puts</CODE> is called to output the string.  
<P>
<DD>Replaces "Backslash Sequence" strings with their hex value
<P>
<UL  COMPACT>
<B>string ... output .................................  hex value</B>

<LI>  \a ............. Audible alert (Bell) .......................\x07
<LI>  \b ............. Backspace .....................................  \x08
<LI>  \f .............. Form Feed (Clear screen) ........  \x0c
<LI>  \n ............. New Line ........................................\x0a
<LI>  \r .............. Carriage Return ...........................  \x0d
<LI>  \t .............. Tab ...................................................  \x09
<LI>  \v ............. Vertical Tab ...................................  \x0b
<LI>  \ddd ......... Octal value .................................... d = 0-7
<LI>  \xhh ......... Hex value .......................................  h = 0-9,A-F,a-f
</UL>

<LI>Replaces any command within square brackets with the return value of
the command (more detail about this in a couple lessons)
<LI>Replaces a \newline with a space, and merges the following line into 
the current line.
<P>
Some statements get very complex and hard to follow if they are all
typed on a single line.  This facility lets you break up really long
lines into several shorter lines. 
</UL>

<P>
Words within double quotes or braces are evaluated as
a single argument.  However, double quotes and braces 
cause different behavior during the substitution phase.
In this lesson, we will concentrate on the behavior of
double quotes during the substitution phase.
<P>
Grouping words within double quotes allows
substitutions to occur within the quotes during the
substitution phase.  The substituted group is then
evaluated as a single argument.  Thus, in the command
<PRE><CODE>
     puts "The current stock value is $varName"  
</CODE></PRE>
the current contents of varName are substituted for
<I>$varName</I>, and then the entire string is printed to the
output device.
<P>
Except for the "Backslash Sequence" strings and the   
backslash at the end of a line (\newline) described
above, the backslash (\) disables substitution for
the single character immediately following the
backslash.  Any character immediately following the
backslash will stand without substitution.  This is the
way to print a dollar sign ($).  Without the backslash,
the $ is interpreted as a variable place holder.
<P>
If you haven't hit the <B>Run Example</B> button yet, do so now, and examine
the results of the example.  Play around a bit with the example code, and
then go on to the next lesson.
:TEXT_END:
<P>
:CODE_START:
;# Show how a \ affects the $
set Z "Albany"
set Z_LABEL "The Capitol of New York is: "

puts "$Z_LABEL $Z"
puts "$Z_LABEL \$Z"

;# The next line needs a backslash to escape the '$'
puts "\nBen Franklin is on the $100.00 bill"

set a 100.00
puts "Washington is not on the $a bill"    ;# This is not what you want
puts "Lincoln is not on the $$a bill"      ;# This is OK
puts "Hamilton is not on the \$a bill"     ;# This is not what you want
puts "Ben Franklin is on the \$$a bill"    ;# But, this is OK

puts "\n................. examples of escape strings"
puts "Tab\tTab\tTab"
puts "This string prints out \non two lines"
puts "This string comes out\
on a single line"
:TEXT_END:
<P>

