So far in this book, you used gets to read input from stdin (the keyboard), using a command such as one of the following:

set line [gets stdin]
get stdin line

The first gets command reads input from stdin, discards the terminating newline, and returns the fetched line, which the set command stores in the variable $line. If a blank line had been read, gets would have returned the empty string, which would have been stored in $line. To differentiate between a blank line and the end-of-file, you have to use the EOF command on the I/O channel (stdin in this case). If EOF returns 1, end-of-file has been reached; if EOF returns 0, gets has not reached end-of-file.

The second gets command also reads input from stdin but, in this case, stores the input in the variable $line itself after discarding the trailing newline. In this form, gets returns the number of characters it read (not counting the newline). If it reads a blank line, then gets returns 0. If it encounters the end-of-file, gets returns -1. For file I/O, I think this form of gets is easiest to use because it automatically detects end-of-file, saving you from having to check for end-of-file conditions with an EOF call. This is the form of the command I’ll use for the rest of the book when dealing with input from a file. For keyboard input, I’ll continue to use the first form of the gets command.

Applying what you learned in the previous section about I/O channels, if you replace stdin with a channel ID returned by the open command, you can read from a file. The following script, gets.tcl in this chapter’s code directory, demonstrates opening and reading a file:

set fileId [open sonnet20.txt r]
set totalChars 0
set totalLines 0

while {[set cnt [gets $fileId line]] != -1} {
    puts "($cnt chars) $line"
    incr totalChars $cnt
    incr totalLines
}
puts "read $totalChars chars"
puts "read $totalLines lines"

close $fileId

The first command opens sonnet20.txt for reading. The next two commands set a couple of counter variables I use while reading the input file. The most complicated part of the script is the while loop. In English, it simply means, “Read a line of input from the file, store the input text in the variable named line and the number of characters read in cnt. Keep doing this until you encounter end-of-file.” Inside the while loop, for each line read, I display the number of characters read (not counting the terminating newline) and the text of the line; then I increment the number of characters read (incr totalChars $cnt) and the number of lines read. When gets hits the end-of-file, control drops out of the while loop, at which point I display the total number of characters and lines read, close the input file, and exit the program.

If you execute gets.tcl, the output should look like the following:

$ ./gets.tcl
(2 chars) XX
(0 chars)
(46 chars) A woman's face with nature's own hand painted,
(45 chars) Hast thou, the master mistress of my passion;
(42 chars) A woman's gentle heart, but not acquainted
(50 chars) With shifting change, as is false women's fashion:
(54 chars) An eye more bright than theirs, less false in rolling,
(39 chars) Gilding the object whereupon it gazeth;
(43 chars) A man in hue all 'hues' in his controlling,
(50 chars) Which steals men's eyes and women's souls amazeth.
(40 chars) And for a woman wert thou first created;
(48 chars) Till Nature, as she wrought thee, fell a-doting,
(36 chars) And by addition me of thee defeated,
(42 chars) By adding one thing to my purpose nothing.
(54 chars)   But since she prick'd thee out for women's pleasure,
(53 chars)   Mine be thy love and thy love's use their treasure.
(0 chars)
read 644 chars
read 17 lines

If you don’t want or need to read and process an input file line-by-line, you can use the read command, which reads a specific number of characters or the entire file. read’s syntax is:

read ?-nonewline? id
read id numChars

id is the file to read and numChars, if present, indicates how many characters to read from id. read’s return value is the data read from id. In the first form of the command, read reads the entire file and, if -nonewline is specified, discards the last character of the file if it is a newline. In the second form of the command, read reads exactly numChars characters, unless it encounters EOF before reading the specified number of characters. In the latter case, read returns the data it was able to read.

Before explaining why you might want to use read instead of gets, have a look at the following script, read.tcl in this chapter’s code directory. The source file, wssnt10.txt, is the complete text of Shakespeare’s sonnets, courtesy of Project Gutenberg (http://www.gutenberg.org/etext/1041), and is also included in the code directory:

# Read the entire file
set fileId [open wssnt10.txt r]
set input [read $fileId]
puts "Read [string length $input] characters"
close $fileId

# Read the file 1024 characters at a time
set fileId [open wssnt10.txt r]
while {![eof $fileId]} {
      set input [read $fileId 1024]
      puts "Read [string length $input] characters"
}
close $fileId

In the first block of code, I read the entire file and then closed it. The second block of code reopens the file, reads it in 1024-character blocks, and then closes it. First, I have to close the input file explicitly and then reopen it before trying to read it a second time. Why? After the first read command completes, the file pointer is positioned at the end of the file. Accordingly, the next read or gets command has nothing to read. Closing and reopening the file resets the file pointer to the beginning of the file. As it happens, there’s a smarter way to move the file pointer, the seek command, which you’ll meet in the section, “Moving the File Pointer: Random Access I/O,” later in this chapter.

Second, notice that the while condition uses the EOF command to test for an end-of-file condition on $fileId. Unlike the gets command, read does not return a special value (referred to as a sentinel value, or just a sentinel) to indicate it’s at the end of the file. In fact, in the absence of the EOF command, read would happily continue to “read” the file, it just wouldn’t return anything, so the script would be stuck in an infinite loop.

When you execute this script, the output should look like the following. I’ll only show the first and last three lines of the output here to preserve space:

$ ./read.tcl
read 107701 characters
read 1024 characters
read 1024 characters
...
read 1024 characters
read 1024 characters
read 181 characters

Hardly riveting output, but the last line bears discussion. Although the read command requested 1024 characters, there were only 181 left in the input file, so read returned what was available.

Why use read instead of gets? Suitability is one reason, but the primary reason is efficiency. In this context, suitability just means that the task you are trying to perform might not require processing a file line-by-line or that the data itself isn’t appropriate for line-by-line input. For example, a binary file can contain embedded newline characters that aren’t used for line breaks per se. In such a case, read is the right command to use.

Although reading and processing input line-by-line with gets is convenient and easy, it is inefficient for large files because multiple small disk read operations are much slower than a single large read that takes advantage of the disk’s read-ahead functionality. How inefficient? Consider Table 8.2. It shows the time required to read a 1GB text file using gets, using read to slurp up the entire file in one large read, and using read with various block sizes.

As you can see in Table 8.2, read is much more efficient than gets. If you want to try this experiment yourself, create a 1GB file named bigfile and execute the script readtest.tcl in the readtest subdirectory of this chapter’s code directory. Of course, the performance you see will be different on your system.

Note: This Is Not a Rigorous Benchmark!

The I/O speeds reported by readtest.tcl are relative. The results are influenced by CPU speed, available memory, the other processes running on the system, the type and speed of your hard disk, the amount of on-disk cache, the filesystem type, the phase of the moon, and what you ate for lunch today. Use readtest.tcl to gain insight into the performance of gets and read, not to establish whether your computer is an I/O speed machine or a boat anchor.

As explained and shown in previous chapters, puts writes data to an output channel. So far, the output “channels” have been the screen, specifically, standard output and standard error (stdout and stderr, respectively) and, as you saw earlier in this chapter, disk files. In the general case, though, a channel is any stream capable of receiving output. So, in addition to stdout, stderr, and file IDs returned by the open command, puts can also write a network socket created by the socket command (I don’t discuss network I/O in this book) or an output medium created by a Tcl extension. For example, you can use puts to send data to a printer or to a serial device (such as a mouse or a modem) if you have an output channel that has been set up for such a purpose.

To simplify the presentation, I’ve glossed over some of puts’ subtleties because they are fine points that would obscure the point I am trying to make. For example, Tcl buffers output, so data you want to print using puts won’t appear until the buffer is full or the buffer is specifically flushed (using the flush command). Buffering is handled by the underlying operating system, although you can modify buffering behavior using special-purpose Tcl commands.

Another issue I haven’t addressed is how puts handles newlines. For better or worse, each of the major operating systems uses different end-of-line (EOL) sequences differently. Linux, UNIX, Macintosh OS X, and related systems use a linefeed character ( ) to indicate EOL; Macintosh systems before OS X use a carriage return ( ); and Microsoft Windows (and MS-DOS and OS/2) use a carriage return followed by a linefeed ( ). In large part, you don’t have to concern yourself with this because Tcl handles the EOL translations for you automatically, converting EOLs to the character sequence appropriate for the host operating system. However, you can modify this behavior using the fconfigure command. Again, this is an advanced topic I won’t cover in this book.

The point to take away from this discussion is that Tcl and puts by and large do the right thing with respect to output. If you find you need greater control, the capability is there. In the meantime, you can use puts for output and be blissfully ignorant of its under-the-covers details.

If you have ever written C, chances are very good that you have used C’s printf() function to print formatted output. Tcl’s format command is much like printf(). The biggest difference is that format doesn’t print the string it formats, it just returns the formatted string. Printing the formatted string is handled with the puts command. format’s syntax is:

format spec ?val ...?

format formats one or more values, specified by val in the syntax diagram, according to the format specification defined by spec. The format specification can consist of up to six parts:

I’m going to focus on the items on the flags: field width, precision specifier, and conversion character. The position and word-length specifiers are less commonly used and are used in situations this book won’t cover. Each argument of the format specifier begins with a percent sign, %, followed by zero or more modifiers, and ends with a conversion character.

Conversion characters indicate how to print, or convert, the corresponding argument in the value list. Although conversion characters appear last in the format specification, I cover them first so you’ll know what you’re trying to format. Table 8.3 lists the most frequently used conversion characters.

A complete list of conversion characters is available in the format man page (man 3tcl format). For example, to format a string, you would use the command, format "%s" "string to format". The command format "%d:%x" int_val hex_val would format a signed integer, followed by a literal colon, followed by a lowercase hexadecimal value. Although not specifically necessary, I use double quotes around the format specifier as a matter of habit. If the format specifier or the value to format contains embedded spaces, the quotes would be necessary.

Flags are modifiers used to specify padding and justification of the formatted output. Table 8.4 lists the valid flags.

After the flags, you can specify a minimum field width and an optional precision value. For example, to format the floating point value 1.98, you could use any of the following commands (see format.tcl in this chapter’s code directory):

puts [format "%f" 1.98]
puts [format "%5f" 1.98]
puts [format "%5.2f" 1.98]

The first command uses the default floating point formatting (%f). The second command uses a field width of 5 (%5f). The third command uses the same field width and adds a precision specifier (%5.2f). These commands correspond to the following output:

1.980000
  1.980000
 1.98

On my OS X system, the second line of output was not indented as it should have been. This is known as A Bug. Most of the example scripts in this chapter use format commands, so you can refer to these scripts for more examples of using the format command. The man page has complete details.

scan str spec ?varName ...?

Most of the code is in Block 0, the procedure definitions. The first procedure, ReadPuzzle, opens the puzzle data file passed as an argument and splits the data into three lists. To make sense of the data parsing, have a look at a sample data line from puzzle.txt:

2 5 e o p e n u g r i v c

Each row of data translates to a single row in the game grid. The data points are space-delimited. The first two values contain the starting and ending locations of the word in that row, and the rest of the data (11 letters) constitutes the row to display on the game grid. For example, in the record above, the word of interest begins in the second column and ends in the fifth column of the row. The columns are numbered from one, so the word in this row is “open.” The while loop reads the data file line-by-line and uses lappend to create three ordered lists of starting and stopping locations and the text lines (starts, stop, and lines, respectively).

DisplayPuzzle uses a UNIX-specific command, clear, to clear the screen between each round. Because clear is an external command, not a Tcl built-in, I use the Tcl exec command to execute and redirect clear’s ouput to stdout. The balance of the procedure is a simple for loop that uses the format command to display a nicely formatted line, consisting of the row number and the letters. I use the length of one of the lists as the loop control value; each of the three lists has the same length, so I could have used any of them.

GetPlayerLine solicits the row number in which the player is interested. The min and max arguments set the minimum and maximum values for the row number. If the player inputs a number outside of that range, the script terminates after printing a short usage message. Otherwise, GetPlayerLine returns the line number the user entered. GetPlayerWord asks the player to type in the word and returns it to the calling procedure.

The GuessCorrect procedure is word_search.tcl’s workhorse. It accepts two arguments, the line number entered in GetPlayerLine and the word entered in GetPlayerWord, and then it compares the player’s guess to the target word embedded in the data line. It returns true if the player’s word matches the puzzle’s word and false otherwise. I use list manipulation to extract the target word from the puzzle data. Recall that lists are indexed from zero. The line number displayed to the player and the starting and ending points for each word in the data file, however, are indexed from one. Accordingly, to extract the correct data, I have to subtract 1 from both $playerLine and from the index value passed to the lindex commands. I use the join command to convert the list of discrete letters returned by the lrange to a proper string. This step is necessary because lrange returns a list of elements that are separated by spaces, and I need a string to perform the comparison in the string match command.

Block 1, as you can see, is short and to the point. It invokes ReadPuzzle, sets the game loop control variable to y, and then enters the game play loop. The while loop displays the game grid, calls GetPlayerLine and GetPlayerWord to set up the comparison, and then calls GuessCorrect to evaluate the guess. It displays the result and then asks the player to play again. The way the enclosing while loop is written, gameplay terminates if the player enters anything but Y or y.

Here are some exercises you can try to practice what you learned in this chapter:

You won’t get very far in your Tcl programming before it will become desirable, if not downright necessary, to read and write files. Use open and close to create I/O channels, the essential first step for performing file I/O. The gets and read commands can be used to read files, while the puts command works for writing files. If you prefer attractive, easy-to-read output, you’ll spend quality time with the format command. Sequential file I/O is often the appropriate way to access files, but there are many situations in which you know exactly where in a file you need to be. In other cases, you might want to update a particular piece of data in a file. In such situations, random file access, brought to you by seek and tell, are the tickets to file I/O happiness.

This chapter concludes your whirlwind introduction to Tcl programming. With the material in these first eight chapters, and plenty of practice, you have everything you need to get started writing GUI programs using Tcl’s graphical counterpart, Tk.