next up [*] [*]
Next: Script Files Up: The User Interface Previous: Introduction

Subsections

XSPEC and tcl/tk

XSPEC uses the Tool Command Language (tcl) to process command input. Because tcl is a full scripting language, this interface allows users to write complex scripts with loops, branching, etc., which utilize XSPEC commands. In this section of the help file we describe how to use those features of tcl necessary to give the user similar functionality to that available in previous versions of XSPEC, and to give information on the details of our tcl implementation that may be useful to experienced tcl users. For a description of tcl, see, for example, "Practical Programming in Tcl and Tk", B. Welch, (1997, Prentice Hall).

Tk, tcl's companion graphical user interface (GUI) toolkit, is also loaded by XSPEC on startup. It is planned that future versions of XSPEC will provide an optional GUI side-by-side with the command line interface (CLI). Although XSPEC does not currently use tk, its presence allows users to write XSPEC scripts with graphical interfaces using Tk commands.

A note on command processing

XSPEC's older command parser, described in D.4, is still used, and differs from tcl in a number of ways. As a result, the version of tcl that process XSPEC commands must understand features of the XSPEC parser. In tcl, commands and their arguments are delimited by white space. They are terminated by a newline or semicolon, unless there is an open set of parentheses `{ }' constituting a loop or test structure ( i.e. while, for or if). XSPEC differs from tcl by treating xspec commands as having a single argument (alphanumeric characters, white space, punctuation, and all), which is then passed to XSPEC's internal routines intact.

The # sign is used for comments in tcl, but may appear only at the beginning of a command. tcl and XSPEC both ignore carriage returns on a new line, but XSPEC also ignores the infinite skip character,`/'. The \ character is used in tcl for continuing a command onto the next line. The old - continuation character from previous versions of XSPEC is also supported, but may be deprecated in future releases.

Command Recall/Editing

The XSPEC/tcl interface also uses gnu readline for command input, which allows command line editing and interactive command recall. On most systems, the left and right arrow keys and the backspace/delete key can be used to navigate and edit the command line. The up and down arrow keys can be used to step thru the command history list. Gnu readline is highly customizable, and many more editing/recall functions are available. Readline documentation can be generated in either postscript or html format from the files in the xanadu/readline/doc directory distributed with the source.

The gnu readline inteface can be turned on or off as required, using the command readline (on|off). Giving the command without any arguments displays the current state of the readline interface (enabled or disable). The default is for readline to be enabled.

The default implementation of tcl also supports a C-shell like command recall mechanism. The history command gives a numbered list of the most recently entered commands. Any command in the list can be re-executed by entering !n, where n is the number of the command in the history list. The previous command can be re-executed by entering !!. The most recent command that begins with a string can be re-executed by entering !prefix, where prefix is the string the command begins with.

Note that command recall is implemented using the tcl unknown procedure, part of which is a script file loaded by tcl at run time and may be different or not exist on your system. See the section in this help file on the unknown command for more details on how it is implemented in XSPEC.

Logging

The log command can be used to open a log file to which all input and and output to tcl will be written. Reading these log files can potentially be confusing when logging tcl flow control commands such as while or for. This is because tcl treats the body of these commands as an argument of the command. Thus when the command is echoed to the log file, the entire body of the command is echoed with it.

In order to make this situation less confusing, before commands are echoed to the command file, all newline characters are replaced by semicolons, and the resulting command line is trucated to 80 characters. Then any commands executed with in the body of a flow control command are echoed as they are executed.

Consider the following sequence of tcl commands within XSPEC:

 XSPEC> log
 Logging to file: xspec.log
 XSPEC> set i 1 ; set product 1
 1
 XSPEC> while {$i <= 5} {
 XSPEC> set product [expr $product * $i]
 XSPEC> incr i
 XSPEC> }
 XSPEC> set product
 120
 XSPEC>

This would produce the following output in the file xspec.log:

 Logging to file: xspec.log
 XSPEC> set i 1 
 set product 1
 1
 XSPEC> while {$i <= 5} {;set product [expr $product * $i];incr i;}
   expr $product * $i
  set product [expr $product * $i]
  incr i
   expr $product * $i
  set product [expr $product * $i]
  incr i
   expr $product * $i
  set product [expr $product * $i]
  incr i
   expr $product * $i
  set product [expr $product * $i]
  incr i
   expr $product * $i
  set product [expr $product * $i]
  incr i
 XSPEC> set product
 120
 XSPEC>

Command Completion

tcl attempts to match the name of any entered command as an abbreviation of a valid command (either a tcl or XSPEC command). If the entered command matches more than one valid command, tcl then lists the possible choices, but does not execute the command. For XSPEC commands, aliases have been constructed matching the command to its minimum abbreviation, as listed when typing `?' at the XSPEC prompt (see aliases). For example, the minimum abbreviation for the `plot' command is `pl'. Thus, typing `pl' will execute the plot command, even though this would otherwise be ambiguous with the tk command `place'.

Command completion is also implemented using the tcl unknown procedure, part of which is a script file loaded by tcl at run time, and may be different or not exist on your system. See the section in this help file on the unknown command for more details on how it is implemented in XSPEC.

N.B. tcl explicitly switches off command completion for scripts. Because of the way scripts are implemented in XSPEC, however, command abbreviations nevertheless do work in scripts entered with the @ command, but not when entered from the command line or using the source command. See below for more details about tcl scripting.

Unix Shell Commands

Shell commands can be executed within XSPEC using the exec command (see the help entry on the exec command). When running interactively, if tcl cannot find a command which matches that entered on the command line, it will search for a shell command which matches the entered command. If it finds a match, it automatically executes the shell command via exec. Note that this feature is implemented using the tcl unknown procedure, part of which is a script file loaded by tcl at run time, and may be different or not exist on your system. See the section in this help file on the unknown command for more details on how it is implemented in XSPEC.

Note that the tcl exec command executes the given command directly, without first passing it on to the shell. Thus no globbing (ie. expansion of wildcards such *.pha) is performed. If you wish to pass you command through a shell for wildcard expansion, etc, use the syscall command.

If you want to start a subshell from within XSPEC, simple type the command for starting that shell, ie. type csh in order to start a C-shell. Note that typing exec csh will not work properly (the full expanded command name necessary in this case would be exec >&@stdout <@stdin csh ). Giving the syscall command with no arguments will automatically start a subshell using your current shell.

   
unknown Procedure

tcl provides a facility whereby if it cannot match an entered command to its list of known commands, it calls the unknown procedure, with the unmatched command (along with its arguments) as its argument. The version of init.tcl distributed with tcl contains a version of the unknown procedure. When tcl initializes, it looks in several standard places for a script file named init.tcl, which it executes if found. The unknown procedure is where tcl does command completion and automatic shell command execution.

XSPEC has its own special version of the unknown procedure, which it uses to intercept script processing requests of the form @<script>. At start up time, XSPEC loads its own unknown procedure, and renames the previously defined unknown procedure to tclunknown. If XSPEC is not doing any special processing, it simply passes any unmatched commands on to tclunknown, which then processes them as usual.

These factors need to be taken into consideration for programmers writing tcl scripts for use within XSPEC. For example, if after initialization, users wishing to load a different version of the standard tcl unknown procedure should name that procedure tclunknown, rather than unknown.

  
Aliases

Command name aliases can be constructed using the tcl interp command:

interp alias {} <command_alias> {} <xspec_command>

where <xspec_command> is the name of the command you wish to make an alias for, and <command_alias> is the name of the alias you wish to set for the command. The {} are required syntax.

To delete the alias <command_alias> use the following:

interp alias {} <command_alias> {}

Initialization Script

When running interactively, the user has the option of providing an initialization script, which will be executed after XSPEC completes its startup procedure, ie. just before it begins prompting for commands. The file should be named .xspecrc and located in the user's home directory. If one specifies on the command line a script to run with XSPEC, the initialization script is not executed.

XSPEC Command Result

After being executed, many tcl commands return a result string, which is echoed to the terminal when the command is entered on the command line. When writing complex tcl scripts, this result can be stored and/or used as a test in loops, etc. When XSPEC commands are executed, they write information to the terminal by writing directly to the appropriate output channel. However, when running interactively, the tcl result string is also written to the terminal after the command is executed.

Whether or not XSPEC specific commands actually return tcl results is controlled by the tcl variable xs_return_result. If this variable is non-zero, XSPEC specific commands will return tcl results. The default value is 0 (no tcl results returned).

Essential all XSPEC commands which print the current value of the fit statistic also return this fit statistic as their tcl result. Other commands which return tcl results are freeze, flux, eqwidth, lumin, error, and thleqw. The show command returns various different tcl results based on its options. See the help item for the show command for more details.


next up [*] [*]
Next: Script Files Up: The User Interface Previous: Introduction
Ben Dorman
2003-11-28