• Abstract
• Introduction
• Usage
  • Commands for printing
  • Opening and closing
  • Printing error messages
  • Printing progress messages
  • The AlphaTcl package and its preferences
  • Notes
• An example
• Known problems
• License and Disclaimer

Abstract

Introduction

package require terminal

Usage

Commands for printing

Proc [terminal::print_word]

The main command one uses to print some text is the print_word procedure, which has the syntax

terminal::print_word {before} {string} {after} {target}? {flush}?

The {string} argument is the string that will be printed. There is no restriction as to which characters the {string} may contain; the `word' part of the command name refers instead to the fact that there is generally some amount of whitespace (that is managed by the command) around the {string}. The {before} and {after} arguments are used to request that the {string} is separated from surrounding text by at least some grade of whitespace: the possible values are none, space, newline, and emptyline. If the entire {string} does not fit on what remains of the line, then print_word will see to that it is printed on the beginning of a line. The {flush} argument is a boolean for whether the target should be flushed after the {string} has been printed. It defaults to 1 (flush).
The {target} argument can be used to specify to what the string should be printed. This argument can be `term' (the terminal), `log' (the log file), `both', or `none' (which essentially turns the print_word command into a no-op). The most common value is probably log, for information considered too verbose to print on the terminal. If the {target} argument is omitted then the value of the terminal::selector variable is used. This is initialized to both by default, but changing it to log would make a decent emulation of TeX's \batchmode.

Proc [terminal::print]

Besides print_word, there is also a lower-level printing procedure which is part of the interface to terminal, namely terminal::print. It is similar to print_word, but it lacks the {before} and {after} arguments, and it never inserts any whitespace before or after the string it prints. I suspect that it is usually more efficient to do one print_word on a concatenated string than to do several prints on the parts, so it is not unlikely that you will never have to use print directly.
Since some programs do not like very long lines, the terminal package generally puts a bound on how long lines can be and inserts a line break if they become too long. The bound is kept in the terminal::max_print_line variable and can be changed at any time. The default value is 79, which limits the line width to 79 characters. The print and print_word procedures do however react slightly differently to this limit. If the entire {string} to print does not fit on what remains of the line, then print_word will see to that it is printed on the beginning of the following line, but |print| makes no such adjustment. If either procedure prints the $max_print_line'th character on a line then they break the line after that character and put the next character in the {string} first on the following line.

Proc [terminal::print_block]

Another command which is occasionally useful is terminal::print_block. It has the syntax

terminal::print_block {before} {indent} {line-list} {after} {target}? {flush}?

The {line-list} argument is a list of lines that will be printed and the {indent} is a string (which of course can be empty) that will be inserted first in each line. The main difference to print_word is that these lines are not broken no matter how long they are -- this is mainly useful if one is given a block of preformatted text and has to print it as given no matter how long the lines are. If anything but emptyline is given as {before} or {after} then it is treated as newline.

Opening and closing

Proc [terminal::term_open]

As was mentioned above, a target must be opened before anything can be printed on it, as output to closed targets is silently ignored. The terminal is opened using the procedure terminal::term_open, which has the syntax

terminal::term_open {clear} {title}? {file}?

The {clear} argument is a flag for whether the terminal should be cleared after opening; 1 means clear, 0 means leave as it was. Whether clearing actually does anything depends on whether there is some way of defining and doing that with whatever serves as the terminal; it currently has no effect when the terminal is an output channel such as stdout. The {title} argument can be used to specify a title for the terminal (again provided that there is some way of defining and setting that for whatever serves as the terminal). The {title} defaults to `*terminal*'. The {file} argument is an identifier for an open channel to use for terminal output instead of the default stdout. (An obvious alternative is stderr.) In Alpha, where the terminal isn't a channel anyway, this argument is ignored.

Proc [terminal::term_autoopen]

A convenient variation on this procedure is terminal::term_autoopen, which has the syntax

terminal::term_autoopen {banner} {clear} {title}? {file}?

When run in tclsh, this is equivalent to

terminal::term_open $clear $title $file
terminal::print_block newline {} $banner newline term

but when run in Alpha it tries to be more sophisticated. If the terminal window isn't already open, then nothing will be shown until something else is written to the terminal, but at that time the above code will indeed be executed. This is intended mainly for programs which only write something when an error occurs, since opening a terminal window to which nothing interesting will be written can look rather odd.

Proc [terminal::log_open]

The log file is similarly opened using the procedure terminal::log_open, which has the syntax

terminal::log_open {name}

where {name} simply is the file system's name of the file to which the log shall be written. The file is opened in access mode w, so any previous contents in the file are deleted.

Proc [terminal::term_close], [terminal::log_close], [terminal::cleanup]

These opening procedures naturally have closing counterparts: the terminal::term_close and terminal::log_close procedures. Neither procedure takes any arguments. The log_close procedure actually effectuates a file close, but what term_close does is more of a disconnection (you usually don't want the text written to a terminal to disappear just because the program that wrote it doesn't have to write anything more). In either case though both terminal and log file should be closed if they are opened. To simplify this in case there has been any errors there is a procedure terminal::cleanup, which effectuates whatever closing operations are necessary.

Printing error messages

Proc [terminal::print_err]

Since an important class of things written to the terminal will be error messages, there is some point in combining all the related printing actions in a single procedure call. This is what the terminal::print_err procedure is for. The syntax is

terminal::print_err {message} {location} {help}?

where {message}, {location}, and {help} are all lists of strings, each of which correspond to one line of output. The {message} is the ``official'' message that identifies the error and the {location} is something which specifies where the error was detected. The purpose of this argument is to give some clue to where something should be changed (usually a position in some input file) to avoid the error. The {help}, finally, can be used to give some clue to what one should probably do to fix the error. This argument is optional, but can be quite helpful if there is a good value for it. The {help} lines are only written to the log file. The print_err procedure adds a "! " to the beginning of each {message} line (BTW, one such line is usually sufficient) and it also adds a period to the end of the last line of the {message}. The print_err procedure ends by flushing the output.
Each time print_err is called, it increments the terminal::error_count variable by one. When the value becomes greater than that of the terminal::max_error_count variable, print_err will generate the Tcl error `That makes <error_count> errors, please try again.'. The purpose of this is to stop programs that run amok generating an endless stream of error messages. If your program normally generates quite a lot of error messages, you might want to increase max_error_count; it is 100 by default, but it will not be overwritten if the value was already set when the terminal package is loaded. You can also clear the error_count whenever you want, even though it is probably a good idea to do so only in places where you know you're making progress. error_count is automatically cleared when you close the terminal or log file.

Printing progress messages

Processing. ---------- [40%] ---------- [80%] ----- Done.

terminal::make_progress {amount}? {goal}?

Procs [terminal::begin_progress], [terminal::end_progress]

Besides make_progress, there are also the terminal::begin_progress and terminal::end_progress procedures; these print the `Processing.' and `Done.' (both these strings may be changed by giving proper arguments to the procedures) in the above example.

proc do_file {fname} {
   terminal::begin_progress -title "Reading `$fname'."\
	 -percent [file size $fname] -mintime 300
   set fid [open $fname r]
   while {[gets $fid line]>=0} {
	  ##
	  # Do some processing of $line
	  ##
	  terminal::make_progress [tell $fid]
   }
   close $fid
   terminal::end_progress
}

-absolute

Selects the absolute marker format `[<amount>]', where the numerical values printed are simply the {amount} argument of make_progress. In this format, the {goal} amount is never used.

-percent {goal}

Selects the percentage marker format (as shown above), with {goal} as the goal amount.

-fraction

Selects the fraction marker format `[<amount>/<goal>]'.

-goal {goal}

Sets the goal amount to {goal}.

-title {beginning}

Sets the string printed at the beginning of a progress message. Defaults to `Processing.' if not given.

-callsep {call separation}

This requests that make_progress must print at least {call separation} hyphens between each marker printed. The default is 10. Setting this to 0 removes this restriction.

-relsep {relative separation}

This requests that the quotient of {amount} to {goal} must have increased by at least {relative separation} between two successive markers. The default value is 0, which means nothing is requested. A {relative separation} of 0.01 means that it has to increase by at least one percentage point. This condition is ignored if no {goal} value has been given.

-abssep {absolute separation}

This requests that {amount} must have increased by at least {absolute separation} between two successive markers. The default value is 0, which means nothing is requested.

-mintime {milliseconds}

This option controls a test used in Tcl 8. The {milliseconds} is a bound on the wall clock time that should elapse between two effective make_progress calls. (Internally the test is implemented using the after and update commands.)

-mincmds {command count}

This option controls a test based on [info cmdcount] (the number of Tcl commands that have been evaluated in the interpreter); this test is used in all Tcl versions. The {command count} value is the minimal number of commands that should be evaluated between two effective make_progress calls.

-period {period}

This option used to control a test based on the number of times make_progress has been called since the last effective call to it, but now it controls the same test as the -mincmds option. To make the effect somewhat comparable however, the {period} number is multiplied by 100 before it is used as a {command count}.

The AlphaTcl package and its preferences

Window Geometry

This preference can be used for setting a default size and position for the terminal window.

Max Print Line

This is a default value for the maxPrintLine variable, that places a limit on how long the lines written using print_word and friends may be. This is useful if you set the terminal window to be narrow.

Take Over Puts

This flag is only declared if terminalPuts is active. It controls a hack that redefines [puts stdout] and [puts stderr] so that text written to these files will instead show up in the terminal window. When the flag is on, terminal redefines the puts command. Turning the flag off (or deactivating the terminalPuts feature) restores the default definition.

Notes

An example

Known problems

License and Disclaimer

• Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
• Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
• Neither the name of Lars Hellström nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.