10 The ifeffit command-line program

The main program distributed with IFEFFIT is simply called ifeffit (or ifeffit.exe on Win32 systems) and runs the basic command interpreter we've been discussing throughout this tutorial. If you've been following along with the examples, you've run this program already. This, the final section of the tutorial, will give a few additional details of using this program. The emphasis here will be on the Unix version.

On Unix and Unix-like systems, the ifeffit program uses the GNU Readline library which supports command-line editing, which greatly enhances the usability of the command-line program by letting you 1) recall previous commands, 2) edit them with keyboard commands, and 3) use tab-completion. In short, the up-arrow and down-arrow keys work to scroll through previous commands, you can easily edit the command-line, and you can use the tab key to help you finish typing commands and file names.

Following the usual GNU Readline behavior, 'emacs keybindings' are used, and there is a large number of 'control-keyboard-sequences' to assist editing the current command line. For example Ctrl-a (that's holding the control key and 'a' at the same time) will move to the beginning of the line, Ctrl-e will move to the end of the line. Both Ctrl-f and the right-arrow key will move one character to the right, and Ctrl-b and the left-arrow key will move one character to the left. Ctrl-p is the same as the up-arrow key, and Ctrl-n is the same as the down-arrow key, and will scroll through the previous and next commands in the ``history buffer''. Ctrl-k will cut the text from the current cursor position to the end of the line, and Ctrl-y will insert that cut text at the current point of the cursor. Following the behavior of many shell programs, Ctrl-d has a dual purpose: on an empty line it will exit the program (essentially the same as typing 'quit'!), while on a non-empty line it will erase one character at a time. Ctrl-h, on the other hand, will erase one character at a time backwards. There are several more control-sequences available for more rapid command-line editing - consult the Readline documentation.

Tab completion means that if you've typed read at the command prompt and then hit the tab key, the program will guess that you wanted to type the command name read_data, and complete this word for you. If you type re and hit tab, you should hear a beep because there are more than one possible completions - hitting tab again will show the three possibilities read_data, rename, and restore. For the first word on a command-line, ifeffit will use a restricted set of commands for tab completion (type 'help' or hit the tab key twice at the command prompt). For later words on the command-line, ifeffit will use the set of files in the current working directory for tab completion.

In addition to keeping a 'command history' for the current session, ifeffit will maintain a recent history of commands between sessions, and re-load the command history on start-up. This allows you to scroll through the commands of earlier sessions. The commands are kept in memory, and re-saved into ahistory file when ifeffit exits. This file can be used as a record of your session, and as a starting place for batch command files, scripts, and macros.

The name of the history file and the number of commands saved can be set with the environmental variables IFF_HISTORY_FILE and IFF_HISTORY_LINES. If these variables aren't set, the history file used will be named .ifeffit_hist in your home directory and will contain up to 500 command lines.

When ifeffit is started, two 'start-up files' will be loaded, if found. These are loaded simply as command files, as if you typed their contents to the command-line. First, startup.iff in the installation directory (typically /usr/local/share/ifeffit) is loaded, and then the file .ifeffit in your home directory is loaded. These start-up files are intended for site-wide or personal definitions for common macros and color-table preferences. In fact, these start-up files are not only loaded by the command-line program, but are loaded by the underlying library, and so the definitions given in these start-up files can be used in scripts written using the IFEFFIT library in perl or python. This can lead to a portability problem for scripts, however, and it is not necessarily recommended to rely on definitions in start-up files in lengthy scripts.

When starting theifeffit program, you can give a list of IFEFFIT command files and save files that will effectively be loaded or restoreed as necessary before the command-prompt is given to you. Just to be clear, these are loaded after any start-up files, so definitions in start-up files can be used in ``loaded'' files. If multiple files are listed they will be loaded / restoreed in the order specified. To run a command file in 'batch mode', or non-interactively, you can use the -x switch, which will load all the files on the command line and then exit, without ever showing the command prompt. Note that pause statements, which would normally wait for your input are skipped in this 'batch mode'. For example,

  ~> ifeffit  my_file.iff

will load my_file.iff and then give you the command prompt to continue, while

  ~> ifeffit -x my_file.iff

will run my_file.iff and then exit. If running in batch mode, you may want to redirect the screen output to a file (ifeffit -x my_file.iff > my_file.out ), or use the -q switch (ifeffit -q -x my_file.iff) to ``run quietly'', suppressing screen output altogether.

While in an ifeffit session, there are a few additional commands available besides the standard commands of the IFEFFIT library. The standard Unix ``shell commands'' ls, cd, pwd, and more work to give information about the current directory and files. Additional shell commands can be executed by preceding it with a ! sign, as in

  Ifeffit> ! gv  ifeffit.ps

which will run gv (a popular postscript viewer) for you. Putting an ampersand & at the end of this line will run the job in the background so that you can continue typing in the ifeffit shell as well. That makes an effective way to edit command files:

  Ifeffit> ! emacs test_cmnd.iff  &
  Ifeffit> load test_cmnd.iff

Finally, typing 'help' at the ifeffit prompt will give a one-line description of the more common IFEFFIT commands.