Tcl-Programming.HOWTO

Tom Poindexter, December 1999

Well, this is really not a HOWTO, but rather some quick links to follow
and some simple advice for the brave.


Tcl resources:

newsgroups:
        comp.lang.tcl       newcomers *always* welcome, 70-100 posts/day
        comp.lang.tcl.announce    
                     archives at www.egroups.com/group/tcl_announce/info.html
                     and of course www.deja.com 

general sites to visit (all http://):
        www.tclconsortium.org
        www.scriptics.com               primary tcl software site unix/win/mac
        www.neosoft.com/tcl/            primary tcl archive, extensions, code
        www.tcltk.com
        www.wwinfo.com/tcl/
        www.sco.com/Technology/tcl/Tcl.html
        starbase.neosoft.com/~claird/comp.lang.tcl/
        www.cetus-links.org/oo_tcl_tk.html

faqs:
        www.tclfaq.wservice.com/tcl-faq/             pointers to many Tcl faqs
        www.tclfaq.wservice.com/tcl-faq/part1.html     comp.lang.tcl faq part1
        www.tclfaq.wservice.com/tcl-faq/part2.html       "    "   "   "  part2
        www.tclfaq.wservice.com/tcl-faq/part3.html       "    "   "   "  part3
        www.tclfaq.wservice.com/tcl-faq/part4.html       "    "   "   "  part4
        www.tclfaq.wservice.com/tcl-faq/part5.html       "    "   "   "  part5
	www.scriptics.com/resource/doc/faq/
        
manual pages (Tcl-To-Go currently uses Tcl & Tk versions 8.0.5):
	www.tclconsortium.org/resources/manpages/
	www.scriptics.com/resource/doc/manual/

tutorials:
        www.msen.com/~clif/TclTutor.html
        starbase.neosoft.com/%7Eclaird/comp.lang.tcl/tcl_tutorials.html

tcl'ers wiki (collaborative web):
        mini.net/cgi-bin/wikit/

book lists:
        www.tclconsortium.org/books/index.vet
        www.scriptics.com/resource/doc/books/
	(or search at www.amazon.com  www.bn.com  or your other fav book store)

conferences:
        www.usenix.org/events/tcl2k/    
                                past proceedings available for usenix members
        conferences.oreilly.com/tcl/




For the hard-core brave ("Manuals?  We don't need no stinking manuals!"):

  0. Just start 'tclsh8.0' or 'wish8.0', and start typing.  tclsh8.0 is the
     Tcl interpreter; wish8.0 is the Tcl interpreter with the Tk windowing
     extension.

  1. Tcl syntax is very simple, just command names followed by arguments.

  2. Commands are terminated by ';' or more commonly, a newline.

  3. There are no control statements, instead there are control commands,
     e.g., 'if' is a command that takes an expression argument, and an 
     argument to be executed if the expression is true, etc.  All command
     arguments must be on the same logical line:

	if {$isTrue} {			(note: the if command starts here
	   do_something			 and has 4 arguments.  the 'true code
	} else {			 block' and 'false code block' are 
	   do_something_else		 arguments that cross physical lines.
	}				 a newline here terminates the command.)

	if {$isTrue}			(note: this code is incorrect, since 
	 {				 the 'true code block' starts on a
	 }				 new line.  The 'if' command will 
	else				 complain that 'no script following ...'
	 {				 since the 'true code' block' begins
	 }				 on a new line.)

  4. The only programmer accessible datatype is string.  Internally, Tcl
     uses string, integer, double, and other values to store information.
     Some commands interpret strings to be numbers.  Some commands interpret
     strings as a list of strings.  Tcl has arrays whose indices are 
     strings; simulate multi-dimensional arrays by combining strings to form
     a single index:
	
	set name "John Doe"
	set list_of_names [list $name "Richard Roe"]
	set second_name [lindex $list_of_names 1]
	set address($name,street) "123 Main Street"
	set address($name,city)   Denver
	set address($name,state)  Colorado

  5. Quoting, Tcl compared to Shell:
	Tcl   /bin/sh
	 \	\		quote a single character,
	 ""	""		quote a string, allow $ and [ ] substitutions
	 {}	''		quote a string, no substitutions, eats newlines
	 []	``		execute another command and return it's value
	 $	$		variable expansion

	quoting must nest properly { } and [ ]:

		set this_is_an_error {some stuff here with close brace } }
		set this_is_ok       {some stuff here with close brace \} }

	also, \ can specify special characters, e.g. \012  \n  \xa   all 
	represent a newline.   \ as the last character of a line (just before
	the actual newline) causes a line continuation. 

  6. The only command you need to know to start with is 'info', which tells
     you things about the interpreter, just startup tclsh or wish, and 
     start typing: 

	info 	    
		wrong # args: should be "info option ?arg arg ...?"
	info x      
		bad option "x": must be args, body, cmdcount, commands, etc.
	info commands   
		now you're cooking!

	make your own commands with the 'proc' command:
	proc add_two {i j} {
	    return [expr {$i + $j}]
	}

  7. Comments begin a line with '#', but have two important, sometimes subtle,
     rules:  
	a) they can only be placed where a command is expected, '#' must be
           the first non-whitespace character.

		# this is a comment
		set x "boat"  # this causes an error, looks like more arguments
		set x "car"  ;# this is ok, since a new command starts after ';'

		switch $x {
		    # error, a command (or comment) cannot start here! this 
		    # area is part of the arguments to the 'switch' command.

		    boat {
		        # ok, since this is inside a block of code
		   	set answer "traveling by boat"
		    }
		}

	b) comments that have Tcl quoting characters must be balanced!  
           Comments can be thought of as completely inert commands, but
	   they must parse correctly and have balanced quoting.

		# notice that this comment continues onto the { next line
			because of the open brace, close it here }

		# if {$x == $y} {          this comment causes an error
		if {$x == $y && $foo} {
 		   do_somthing
		}

  8. Tcl often blurs the distinction between data and code, which can be
     quite useful at times.  Tcl performs $ and [ ] substitutions exactly 
     once before executing a command.  You have to quote things you don't want 
     interpreted, or cause inner evaluation on things you want 
     interpreted twice:

	set some_cmd {puts {hello world}}
	eval $some_cmd

	set myvar x
	set $myvar boat			;# variable 'x' really gets set 
	puts "travel by [set $myvar]"	;# get the value of 'x'

  10. Read some code!!  Tcl-To-Go is nearly all source code.  Copy some of the
     programs in /usr/tcltk/lib/bingz to another directory, and gunzip.  Start
     browsing the code. 

  11. Have fun!


