NAME

get_command_text - High level input routine

SYNOPSIS

#include "l/l_io.h"

Example compile flags (system dependent):
  -DLINUX_X86_64 -DLINUX_X86_64_OPTERON  -DGNU_COMPILER 
   -I/home/kobus/include
   -L/home/kobus/misc/load/linux_x86_64_opteron -L/usr/lib/x86_64-linux-gnu
  -lKJB                               -lfftw3  -lgsl -lgslcblas -ljpeg  -lSVM -lstdc++                    -lpthread -lSLATEC -lg2c    -lacml -lacml_mv -lblas -lg2c      -lncursesw 


long get_command_text
(
	const char *program_name,
	char *command,
	size_t max_len
);

PARAMETERS

const char *program_name: Program name, used by help and for prompt.
char *command: Buffer for command read.
size_t max_len: Size of buffer.

DESCRIPTION

This routine is the basic KJB library high level input routine. It provides support for continued lines (last char is one a line is a "-"), multiple commands on a line (commands are separated by semi-colons). In addition, this routine provides support for an initialzation file and a history file (described below). then this routine provides support for editing and re-entering previous lines. (If the program is not interactive, then this routine reads from stdin). Finally, this routine implements a number of commands. These commands are invisible from the calling program. This routine only returns when the user enters a command which it does not know (or there is an error in the processing of a command that it does know). Some of the commans are best understood in terms of writing input "script" files. The commands implemented are: | quit / stop / exit / ctl-D STOP returns EOF

  line with only whitespace   NULL      consumes line
  Line begining with #        comment   consumes line
  Line begining with *        comment   consumes line
  Line begining with %        echo      echo's line

  <   <file>                  read      takes input from <file>
                                        until EOF. Recursion
                                        is allowed.

  ?                      user-input     promps user for next command

  Line begining with !        system    executes rest, if in PATH

  beep { < num > }            beep      Beep <num> times, with 1/2
                                        second between beeps.

  ...                         wait      User is prompted for return
                                        to continue.

  help { < topic > }          help      Uses kjb_help for help

  loop <num> <command>        loop      Behaves as though the command
                                        line was typed <num> times.

  sleep { < num > }           sleep     sleeps for <num> seconds, or
                                        1 if <num> is omitted.

This list will likely be extended in the future. This routine implements a initialization file. On the first call, it first reads the commands from an initialization file if it can find one. The first place to look is the file pointed to in the environment variable <PROGRAM>_INIT, where <PROGRAM> is the string program_name in upper case. If that does not exist, then .<program> in the current directory is used, and if that does not exist, then .<program> in the home directory is used. This routine implements the read of the command history from previous sessions stored int the file ".<program>-history". This routine also implements an ad hoc method of synchronously suspending program exection remotely. The original impetus for this is for scripts which drive devices, etc, which are operating in a light controlled room. If someone needs to enter the room, then the program needs to stop at a point where entering the room is safe, and resuming execution is also safe. Thus, if a file named "STOP" exists in the current directory, then the program will stop between commands. When it stops, it will create a file named "STOPPED_AND_WAITING". When the file "STOP" is removed, the program will remove "STOPPED_AND_WAITING", and continue. This suspension method applies even to the very first command, and thus the program can be started and frozen before executing any commands, to be re-started for double remotely. This may prove to be useful when one needs to exit the room before an experiment begins (there are other ways to accomplish this, so it is not clear if this will be used much).

RETURNS

On success, this routine returnes the number of characters in "command". It returns EOF if the end if input has been reached, or the user entered stop/exit/quit/q/. It returns ERROR if there was an error in the read, or (much more likely) an error in a preprocessed command. If error is returned, then the reason is available to kjb_print_error. If the input command is larger than max_len, then TRUNCATED is returned. See also; kjb_help, kjb_print_error, BUFF_GET_COMMAND_TEXT

NOTES

Currently the comment character does not change with the user settable comment charater as this is an option for data files. However, I could change my mind on this at some point.

MACROS

BUFF_GET_COMMAND_TEXT

DISCLAIMER

This software is not adequatedly tested. It is recomended that results are checked independantly where appropriate.

AUTHOR

Kobus Barnard

DOCUMENTER