---

lissom.c

Go to the documentation of this file.

#include <string.h>
#include <time.h>
#include <stdio.h>

#include "ipc.h"
#include "cmdparam.h"
#include "binarysave.h"
#include "inputs.h"
#include "globals.h"


/* Optional support for the GNU readline library */
#ifdef USE_READLINE_LIBRARY

typedef char   *CPFunction (char *, int);
typedef char **CPPFunction (char *, int);
extern CPPFunction *rl_attempted_completion_function;
EXTERNAL_C_LINKAGE char *readline (  char *prompt);
EXTERNAL_C_LINKAGE void add_history (char *string);
EXTERNAL_C_LINKAGE char **completion_matches (char *text, CPFunction *entry_function);
#endif


/******************************************************************************/
/* Defines and typedefs                                                       */
/******************************************************************************/

#define MAX_PROMPT_CHARS 1024



/******************************************************************************/
/* Global variables                                                           */
/******************************************************************************/

#define RCFILENAME ".lissomrc"

bool has_command_file=false;

const char lissom_version[]="4.0";

/* Main page for generated code documentation */
const char title_string[]=
"                         RF-LISSOM SOFTWARE\n"
"\n"
"                           James A. Bednar\n"
"                   Department of Computer Sciences\n"
"                  The University of Texas at Austin\n"
"\n"
"                         Version: %s\n"
"                 Compiled on %s at %s.\n";


const char intro_string[]=
"`lissom' is a Receptive-Field LISSOM implementation that currently\n"
"runs on single-processor UNIX machines.  Since `lissom' is a living\n"
"program used for research, all documentation in this file and others\n"
"should be considered preliminary, incomplete, outdated, and otherwise\n"
"inaccurate.  Then again, it is hopefully better than nothing ;^).\n\n"

"This program is free software; you can redistribute it and/or modify it\n"
"under the terms of the GNU General Public License version 2 as published\n"
"by the Free Software Foundation. This program is distributed in the hope\n"
"that it will be useful, but without any warranty; without even the\n"
"implied warranty of merchantability or fitness for a particular purpose.\n"
"See the GNU General Public License for more details.\n\n"

"Copyright (C) 1995,1996,1997,1998,1999,2000,2001,2002,2003 James A. Bednar\n";


const char usage[]=
"Usage: %s [<options>]*\n\n"

" where <options> may be any of the following:\n\n"

"   --no-init-file                  Do not process any " RCFILENAME " file(s).\n"
"                                   If present must be the first option given.\n\n"

"   <param>=<value>                 Set the given parameter to the given value\n\n"

"   --help                          Print this message\n\n"

"   [--file] <command file>         Execute commands in the given file\n\n"
"   --train                         Train network until tend\n"
"   --test                          Test network (without learning) until tend\n\n"

"   --batch                         Suppress interactive prompt & image viewing\n"
"   --interactive                   Force interactive prompt\n"
"   --remote                        Use ppm_remote_viewer, not ppm_image_viewer\n\n"
"   --display                       Call the plot cmd for every presentation\n\n"

"   --filebase <basename>           Basename to use for generated files\n\n"

"   --verbose                       Increase level of messages printed\n\n"
"   --quiet                         Reduce level of messages printed\n\n"

"   --command '<command> [<arg>]*'  Execute the given command with given args\n"
"   -c '<command> [<arg>]*'         Shortcut for --command\n\n"


"Each option is processed strictly in the order given on the command line,\n"
"repeatedly if given more than once.  This means that you can e.g. set\n"
"a parameter to have one value when processing one command file, and another\n"
"when processing the next, or else override a value set in one before going\n"
"on to the next.  After the options have all been processed, interactive\n"
"command-prompt mode is entered if requested explicitly or if no command\n"
"has yet been executed that caused the network to be initialized. Type\n"
"`help' in interactive mode for more information on commands and parameters.\n";


const char param_help_string[]= 
"Parameters are given values using the command `set', which takes\n"
"any number of pairs of parameter names and values in the form \n"
"[[[::]<path>::]<name>=<value>], up to the maximum number of\n"
"command arguments defined in cmdparam.h.  See `help set' for\n"
"information about valid parameter values, such as numeric\n"
"expressions.  See `help parameters list' to find out what\n"
"parameters are available.  See `help constants list' to find\n"
"out available symbolic constants, which are like parameters\n"
"except they cannot be set.\n\n"

"Type `help <name>' for more information about a particular\n"
"parameter, and for even more information search the source code\n"
"to see where that parameter is used.  Be careful not to assume\n"
"that a given parameter is supported in all cases where it might\n"
"conceptually apply, since the code is continually under\n"
"development; if in doubt check the code or run an experiment.\n\n"

"Nearly all parameters have default values, but the default will often\n"
"need to be overridden for a particular case.  Many parameters also\n"
"have hard-coded limits, and `set' will (in most cases) refuse\n"
"to set the value if the limits are violated.  Legal ranges for\n"
"parameters often begin at Uninitialized, which is currently -1.\n"
"Uninitialized generally means that the program will try to\n"
"dynamically determine an appropriate default; see the help for a\n"
"particular parameter for more information.   The help lists the\n"
"current parameter value and the current limits on its value, but\n"
"remember that these differ at different times and for different\n"
"compilation constant definitions.  An asterisk in a range (`*')\n"
"indicates that there is no limit of the indicated type, e.g.\n"
"`[0,*]' denotes a parameter which may take any positive value.\n\n"

"Note that, at this time, dynamic restructuring of the network connections\n"
"is supported only for the special case of decreasing exc_rad.  Changes to\n"
"other network architecture parameters will be refused after a network is\n"
"initialized.\n\n";


const char cmd_help_string[]=
"Commands may be specified through any of the following means, listed\n"
"in order of processing (and thus in reverse order of precedence):\n\n"

"  ${HOME}/" RCFILENAME "                        (if present)\n"
"  ./" RCFILENAME "                              (if present)\n"
"  file(s) specified on the command-line    (if any, in order)\n"
"  command-prompt command(s)                (if any, as entered)\n\n"

"Arguments to the set command (e.g. 'x=y') can be entered in lieu of a\n"
"command; see the documentation for set for more details. In all other\n"
"cases a command consists of a command name followed by its arguments,\n"
"separated by spaces, all on a single line except that multiple\n"
"command-file lines ending in a backslash (`\\') are concatenated.  Single\n"
"or double quotes may be used to ensure that an argument containing spaces\n"
"is interpreted as a single argument.  At the command prompt or in a command\n"
"file, blank lines and comment lines (lines whose first non-blank character\n"
"is `#') are ignored.  Comments are also allowed after commands if they are\n"
"preceded by `#'.\n\n"

"Type `help command <name>' for more information about a particular\n"
"command, and for more information than that search the source code for\n"
"cmd_<name> see where that command is defined.  Each command may take\n"
"a certain fixed minimum number of arguments, followed by an arbitrary\n"
"number of optional arguments.  Some commands accept named arguments\n"
"of the form x=y following the command name; if so they will list which\n"
"arguments are accepted.  Almost all commands accept the same\n"
"form of expressions for all numeric and string arguments as the\n"
"`set' command does; see `help set' for more details.\n\n"

"In practice, the first command file specified on the command line, if\n"
"any, will usually be used to set the starting values of training\n"
"parameters. It will often also set up automatic changes to some of\n"
"these parameters at predetermined times during training (see help\n"
"for the command `hook').  For instance, the excitatory radius is\n"
"generally decreased as training progresses, and this is usually done\n"
"using `hook' with `set'.\n\n"

"The actual training and/or testing of the network can be performed by\n"
"adding more commands (e.g. `training' or `testing') to the end of\n"
"first command file.  However, to keep that file general often you will\n"
"want to put such commands into a second file, so that it can be\n"
"omitted when working with the network interactively.  If just simple\n"
"training until `tend' is desired, the second file isn't needed; just\n"
"specify the appropriate command on the command line, e.g. `--train',\n"
"`--test' or `--command ...', or type it at the interactive prompt.\n\n"

"The global and per-directory options files (named " RCFILENAME ") are\n"
"useful for setting host-specific parameters, such as running_remotely,\n"
"or e.g. default network parameter sizes.\n";


const char file_types_string[]=
"%s can create many files over the course of a run.  Depending\n"
"on the commands used, different files will be created, but most will\n"
"be of one of the formats below.  All of the filenames should start\n"
"with the value of the filebase parameter.  This parameter defaults to\n"
"`lissom' for runs with no command file, the name of the first command\n"
"file (minus `.param' extension, if any).  The extensions may be any of\n"
"the following:\n\n"
// (No-longer generated files are commented out)

".<t>.params               Command file with parameter values as defined\n"
"                          when init_network was called; can be used to\n"
"                          recreate a starting state later.\n\n"
                           
".log                      Generic logging output from commands, if any\n\n"
                           
".<t>.<angle>.p<pres>.ppm  Input and activity image in PPM format.\n\n"
                           
//".input                  Input patterns on retina in ASCII.\n"
//".act                    Network activities in ASCII.\n\n"
//".map                    Center of gravity of each neuron, in ASCII retinal\n"
//"                        coordinates.\n"
//".od                     Ocular dominance values of each neuron, in ASCII.\n\n"
                           
".aff_map.ppm              PPM plot of afferent weights to each neuron.\n\n"
                           
".<t>.or.ppm               Orientation map in PPM format.\n\n"
                           
//".<t>.or                 Orientation and specificity of each neuron in ASCII.\n"
//".<t>.sp                 Sigma of major and minor axes of preferred input\n"
//"                        Gaussian for each neuron, in ASCII.\n\n"
                           
//".<t>.features           Retinotopic points of interest.\n"
//".<t>.spfeatures         Spatial frequency points of interest.\n"
//".<t>.odfeatures         Ocular dominance points of interest.\n\n"
                           
".<t>.wts                  ASCII or binary weight state file.\n\n"
".<t>.wts.<ui>_<uj>.ppm    Weights for the neuron (ui,uj) in PPM format\n"
                           
//".<ui>_<uj>.<t>.ex.ma    Mathematica plot of excitatory weights.\n"
//".<ui>_<uj>.<t>.in.ma    Mathematica plot of inhibitory weights.\n"
//".<ui>_<uj>.<t>.mx.ma    Mathematica plot of Mexican hats (exc+inh weights).\n"
//".<ui>_<uj>.<t>.aff.ma   Mathematica plot of afferent weights.\n"
//".<ui>_<uj>.<t>.od.ma    Mathematica plot of ocular dominance.\n"
//".<ui>_<uj>.<t>.ex.mp    Maple plot of excitatory weights.\n"
//".<ui>_<uj>.<t>.in.mp    Maple plot of inhibitory lateral weights.\n"
//".<ui>_<uj>.<t>.mx.mp    Maple plot of Mexican hats (exc+inh weights).\n"
//".<ui>_<uj>.<t>.aff.mp   Maple plot of afferent weights.\n"
//".<ui>_<uj>.<t>.od.mp    Maple plot of ocular dominance.\n"
//".<ui>_<uj>.drf          Dynamic receptive fields\n\n"
                           
//".<row>.in               Dump of lateral weights for a row, in ASCII.\n"
//".<neuron>.<t>.lat       Dump of lateral weights for a neuron, in ASCII.\n\n"
                           
//".stat.<sel>.<m>.mp      Maple plot of orientation specificity histogram.\n"
//".stat.<sel>.<m>.count   Orientation preference counts.\n"
;






/******************************************************************************/
/* Prototypes for private functions                                           */
/******************************************************************************/

CMD_DECLARE(help);
CMD_DECLARE(make_doc);
char**  command_prompt_completion (char *text, int start, int end);
int     get_line_from_prompt( void );
void    lissom_init_hooks(void);
bool    process_command_line_args(int argc, char **argv);
void    set_filebase(string commandfilename);
void    wrong_usage(const char* filename);
void    read_command_file_if_present(string name);



/******************************************************************************/
/* Main function                                                              */
/******************************************************************************/

int main(int argc, char **argv)
{
  time_t start_time = time(NULL);

  /* Initialize various modules */
  lissom_init_hooks();

  /* Announce program start */
  ipc_notify(IPC_ONE,IPC_SUMMARY,"Execution of %s started %.24s on %s",
             argv[0], ctime(&start_time), getenv("HOST") );

  /* Read and execute commands and files specified on the command line */
  const bool is_interactive = process_command_line_args(argc,argv);
  
  /* Read further commands from terminal prompt, if appropriate */
  if (is_interactive) {
    if (!has_command_file) 
      ipc_init_logfile(filebase.c_str());
    cmdparam_changes_verbose=True;
    cmddefs_exec_batch(&get_line_from_prompt,"prompt");
  }
  
  /* Exit */
  ipc_exit(IPC_EXIT_NORMAL,"Exited normally");
  return 0; /* never reached */
} 



/******************************************************************************/
/* Initialization hook                                                        */
/******************************************************************************/

void lissom_init_hooks(void)
{
  /* Ensure this machine has appropriate types defined */
  if (check_ind_types(False))
    ipc_exit(0,"Need to add definitions to ind_types.c for this architecture.");

  ipc_init();

  /* Register message handlers using IPC routines */
  static Msg::LevelHandler<> ipc_message_handler;
  ipc_message_handler.register_handler( Msg::Verbose,   Msg::ipc_verbose   );
  ipc_message_handler.register_handler( Msg::Notify,    Msg::ipc_notify    );
  ipc_message_handler.register_handler( Msg::Requested, Msg::ipc_requested );
  ipc_message_handler.register_handler( Msg::Warning,   Msg::ipc_warning   );
  ipc_message_handler.register_handler( Msg::Error,     Msg::ipc_error     );
  Msg::LevelHandler<>::set_default_instance(&ipc_message_handler);

  /* Add typical constants */
  blackboard.add_constants();

  /* Turn off buffering so no messages are lost */
  setvbuf( stdout, NULL, _IONBF , 0); 

#ifdef USE_READLINE_LIBRARY
  rl_attempted_completion_function = (CPPFunction *)command_prompt_completion;
#endif
  
  CMD_DOC(help,NULL,0,"%s [<options>]",
          "Try:\n\n"
          
          "   help parameters          for general help using parameters and constants\n"
          "   help parameters list     for a concise list of the available parameters\n"
          "   help parameters doc      for help on all parameters\n"
          "   help constants list      for a concise list of the available constants\n"
          "   help constants doc       for help on all constants\n"

          "   help commands            for general help using commands\n"
          "   help commands list       for a concise list of the available commands\n"
          "   help commands doc        for help on all commands\n"

          "   help usage               for help on the command-line options\n"
          "   help version             for the date and number of this version of LISSOM\n"

          "   help <name>              for help with a specific parameter, constant,\n"
          "                             or command");
  
  
  CMD_DOC(make_doc,NULL,0,"%s [<filename>]",
          "Create a file with the specified name containing all the help information\n"
          "available.  It is currently formatted as an ASCII document.");
  
  /* Call hooks to initialize each source file */ 
  globals_init_hook();
  kernel_init_hook();
  Inputs::global_entry().register_params_and_commands();
  LISSOMBinaryStateSaver::init_hook();
  cmdparam_init_hook();

  /* Redefine help string for cmd_hook to make it specific to LISSOM */
  cmddefs_define_command_doc
    ("hook","%s <hook_location> <iteration_specifier> <command> [<arguments>]",
     "This command allows you to specify that any other command should be\n"
     "executed at a specified iteration or iterations.\n\n"

     "The <command> and its <arguments> may be any valid command and any\n"
     "arguments that it accepts.  Any command arguments are evaluated when the\n"
     "command is run, not when the hook is first defined.\n\n"

     "The <iteration_specifier> should be of the (recursive) form:\n\n"

     "   <start_iteration>[-<end_iteration>[%<step>]][,<iteration_specifier>]\n\n"

     "Each of the first three quantities may be a <term> as defined by the command\n"
     "`set', which means that any compound expressions must be parenthesized.  For\n"
     "example, the <iteration_specifier> can be:\n\n"

     "   a single iteration      (e.g. `1000'),\n"
     "   a range of iterations   (e.g. `1-1000'), \n"
     "   a range with a stepsize (e.g. `1-1000%%10'), or\n"
     "   a list of any of these  (e.g. `1,10,100-200%%100,7,50-52,(tend-2)-tend').\n\n"

     "In the first case, the command is executed only once, at iteration 1000,\n"
     "in the second it is executed 1000 times, once per iteration, in the third,\n"
     "it is executed 100 times, at iterations 10, 20, etc. (all those evenly\n"
     "divisible by 10), and in the last one it is executed at iterations 1,7,\n"
     "10,50,51,52,100,200,19998,19999, and 20000, assuming tend==20000.  Note\n"
     "that the <iteration_specifier> must not contain any spaces.\n\n"

     "The <hook_location> specifies where in the code the hook is checked\n"
     "for (and executed at the appropriate time.)  Currently hooks can be\n"
     "inserted at the following locations within an iteration of the training\n"
     "or testing commands:\n\n"

     " before_input:  At the start of the training iteration, before input,\n"
     "   activation, settling, or learning.  Useful for setting parameters,\n"
     "   loading a saved state, etc.\n\n"

     " after_learning:  At the end of the training iteration, after input,\n"
     "   activation, settling, and learning.  Useful for saving state,\n"
     "   plotting, analyzing the activity, etc.\n\n"

     "At a given hook_location and iteration, all the hooks that apply\n"
     "are executed in the order of their start_iteration and (if those\n"
     "match) the order in which they were defined.\n\n"

     "Hooks can also be defined to execute multiple times within a given\n"
     "specified iteration or iterations(s) using the following hooklist:\n\n"

//     " after_presentation:  After any input has been presented to the\n"
//     "   network subsequent to the original training or testing for an\n"
//     "   iteration.  Useful primarily in conjunction with commands that\n"
//     "   present or modify input or network activation without advancing\n"
//     "   the iteration number, such as input_draw and input_present.  For\n"
//     "   instance, such commands can be used to graph or analyze the\n"
//     "   response to a set of different inputs at periodic times during\n"
//     "   training without disrupting the network or the iteration numbers.\n\n"

     "Examples:\n\n"

     "  hook before_input        501 set exc_rad=9 delta=0.12 beta=0.67\n"
     "  hook before_input       1001 set exc_rad=6 delta=0.15 beta=0.65\n\n"
     
     "These could be part of a training schedule that gradually reduces the\n"
     "excitation radius while increasing the slope of the sigmoid.\n\n"

     "  hook after_learning  1-100%%2 plot\n"
     "  hook after_learning     1000 plot\n\n"
     
     "  hook after_learning    10000 kill_connections 0.0001\n\n"

     "The top two specify 101 iterations at which the input and activity\n"
     "should be plotted.  The next specifies that inhibitory weights smaller\n"
     "than 0.0001 should be pruned at iteration 10000.\n\n"

//   "  hook after_presentation    1 analyze_portions\n"
     "  hook after_learning        1 for f=0 f<PI f=f+PI/18 input_present_object \"\" Input_Gaussian f\n\n"

     "This hook presents a variety of stimuli at iteration 1.");

  /* Parameter used by this file */
  PARAM_A(blackboard,"command_prompt_format",
          string("lissom.t${iteration}.p${presentation}.c${command_num_called}${current_param_set_path}> "),,
          "Command prompt for an interactive session.  The value of this parameter\n"
          "is evaluated as for a string argument to a command, substituting the\n"
          "value of any specified parameters at the time the prompt is printed.\n\n"
          
          "As a special case, the string '${param_set_path}' is globally replaced\n"
          "by the path to the parameter set currently selected, even though there\n"
          "is currently no parameter by that name.\n\n"

          "As another special case, the characters '\\033' are replaced by the\n"
          "escape character.  This allows ANSI color codes to be used in the\n"
          "prompt.  Example:\n\n"
          
          "  command_prompt_format=\"\\033[33;40;1mlissom.t$${iteration}.p$${presentation}.c$${command_num_called}$${current_param_set_path}>\\033[m \"");

  
  cmddefs_exec_str("uninit_network");
}



/******************************************************************************/
/* Private functions                                                          */
/******************************************************************************/

void wrong_usage(const char* filename)
{
  if (AMPARENTPE)
    fprintf(stdout,usage,filename);
  ipc_exit(IPC_EXIT_WRONG_USAGE,"Wrong usage");
}



void read_command_file_if_present(string name)
{
  cmdparam_changes_verbose=network_initialized;
  FILE *file=fopen(name.c_str(),"r");
  if (file) {
    ipc_notify(IPC_ONE,IPC_STD,"Processing command file %s", name.c_str()); 
    fclose(file);
    if (cmddefs_exec_file(name.c_str()))
      ipc_notify(IPC_ONE,IPC_ERROR,"Problem with command file %s",name.c_str());
  }
}


#define nextargis(str) (arglist.nextis(string(str)))

bool process_command_line_args(int argc, char **argv)
{
  CMD_ARG_LIST;
  
  Tristate force_interactive=Uninitialized;
  const string progname=arglist.next(string("lissom"));


  /* Process global and this-directory options files first so that they
     may be overriden by options specified on the command line */
  if (arglist.empty() || !arglist.nextis(string("--no-init-file"))) {
    read_command_file_if_present(string(getenv("HOME"))+"/" RCFILENAME);
    read_command_file_if_present(RCFILENAME);
  }

  /* True if filebase has been set explicitly */
  bool has_filebase=false;
  
  while (!arglist.empty()) {
    /* Allow parameter setting of the form name=val anywhere on command line */
    cmdparams_set(blackboard,arglist,true,false,true);
    
    if (nextargis("--help") || nextargis("-h"))
      fprintf(stdout,usage,progname.c_str());

    else if (nextargis("--batch")) {
      cmdparam_set("interactive","False");
      force_interactive=False;
    }
    else if (nextargis("--interactive")) {
      cmdparam_set("interactive","True");
      force_interactive=True;
    }
    else if (nextargis("--remote"))       cmdparam_set("running_remotely","True");
    else if (nextargis("--display"))      cmdparam_set("display","1");
    else if (nextargis("--verbose"))      ipc_msg_level+=2;
    else if (nextargis("--quiet"))        ipc_msg_level-=2;

    else if (nextargis("--filebase")) {
      if (arglist.empty())
        wrong_usage(progname.c_str());
      else {
        filebase = arglist.next(string(""));
        has_filebase=true;
      }
    }
    
    else if (nextargis("--command") || nextargis("-c")) {
      if (arglist.empty())
        wrong_usage(progname.c_str());
      else {
        ipc_init_logfile(filebase.c_str());
        const string cmd=arglist.next(string(""));
        cmddefs_exec_str(cmd.c_str());
      }
    }
    
    else if (nextargis("--set")) {
      const string param=arglist.next(string(""));
      if (arglist.empty())
        wrong_usage(progname.c_str());
      else {
        const string val=arglist.next(string(""));
        cmdparam_set(param,val);
      }
    }
    
    else if (nextargis("--train")) {
      ipc_init_logfile(filebase.c_str());
      cmddefs_exec_str("training");
      cmdparam_set("interactive","False");
    }
    
    else if (nextargis("--test")) {
      ipc_init_logfile(filebase.c_str());
      cmddefs_exec_str("testing");
      cmdparam_set("interactive","False");
    }
    
    else if (!arglist.empty()) { /* Assumes any other argument is a file to process */
      const string filename=arglist.next(string(""));
      const string start=string(filename,0,2);
      
      if (start == "--") { /* Reserve "--" for options */
        if (nextargis("--file"));
        else
          wrong_usage(progname.c_str());
      }
      
      if (filename=="")
        wrong_usage(progname.c_str());
      else {
        if (!has_command_file) { /* Set file basename to first command file */
          has_command_file=true;
          if (!has_filebase)
            set_filebase(filename.c_str());
          ipc_init_logfile(filebase.c_str());
        }
        /* Suppress reporting of parameters changed in command files until
           .init.param file created */
        cmdparam_changes_verbose=network_initialized; 
        
        /* Execute the file of commands */
        ipc_notify(IPC_ONE,IPC_STD,"Processing command file %s", filename.c_str());
        if (cmddefs_exec_file(filename.c_str()))
          ipc_abort(IPC_EXIT_FILE_PROBLEM,"Problem with command file %s",
                    filename.c_str());
        cmdparam_changes_verbose=True; 
      }
    }
  }

  /* Default to showing interactive prompt if not specified and
     network hasn't been trained */
  if (force_interactive == Uninitialized && !network_initialized)
    cmdparam_set("interactive","True");

  return blackboard.get_with_default("interactive",True);
}
#undef nextargis



void set_filebase(string commandfilename)
{
  int extension = commandfilename.rfind(".param");
  filebase = 
    ((extension<0 || extension>=int(commandfilename.length()))?
     commandfilename :
     commandfilename.replace(extension,commandfilename.length(),""));
}



int get_line_from_prompt( void )
{
  const string param_set_name = (blackboard.path_name()=="" ? "" : "::"+blackboard.path_name());
  const string promptformat   = blackboard.get_with_default("command_prompt_format",string(""));

  /* Hacks: replace current_param_set_path with actual path and
     escape code with escape character */
  unsigned pos;
  string p = promptformat;
  const string param_set_marker="${current_param_set_path}";
  const string escape_marker="\\033";
  while ((pos=p.find(param_set_marker))<p.length())
    p.replace(pos,param_set_marker.length(),param_set_name);
  while ((pos=p.find(escape_marker))<p.length())
    p.replace(pos,escape_marker.length(),"\033");
  
  /* String substitution */
  const string promptstr    = Parse(blackboard,p.c_str()).cmds();

  /* Copied into an array because readline insists on a non-const pointer */
  char prompt[MAX_PROMPT_CHARS];
  SNPRINTF(prompt, MAX_PROMPT_CHARS, "%s",promptstr.c_str());

  char *lineptr=NULL;
#ifdef USE_READLINE_LIBRARY
  lineptr= readline(prompt);
  if (lineptr) {
    if (*lineptr) add_history(lineptr);
    strncpy(cmddefs_line_buffer,lineptr,CMD_MAX_LINE_LENGTH+1);
    free(lineptr);
    lineptr=cmddefs_line_buffer;
  }
  else
    fprintf(stdout,"\n"); /* About to exit */
#else
  fprintf(stdout,prompt);
  lineptr = fgets(cmddefs_line_buffer,CMD_MAX_LINE_LENGTH+1,stdin);
#endif

  return (lineptr==NULL);
}



#ifdef USE_READLINE_LIBRARY
char ** command_prompt_completion (char *text, int start, int end)
{
  (void)end;   /* Unused */
  
  /* First word must be a command; others are usually a param */
  return (start==0 ? 
          completion_matches(text, cmddefs_completion_generator) :
          completion_matches(text, params_completion_generator) );
}
#endif



#define COMPAREARG(arg,string) (argc>(arg) && !strcmp(argv[arg],string))
cmdstat cmd_help( CMD_ARGS )
{
  if (AMPARENTPE) {

    /* Help with parameters */
    if (COMPAREARG(0,"parameters")) {
      if      (COMPAREARG(1,"list"))        params_print_parameters(stdout);
      else if (COMPAREARG(1,"doc"))         params_print_parameters_doc(stdout);
      else                                  fprintf(stdout,param_help_string);
    }
    
    /* Help with constants */
    else if (COMPAREARG(0,"constants")) {
      if      (COMPAREARG(1,"list"))        params_print_constants(stdout);
      else if (COMPAREARG(1,"doc"))         params_print_constants_doc(stdout);
      else                                  fprintf(stdout,param_help_string);
    }

    /* Help with commands */
    else if (COMPAREARG(0,"commands")) {
      if      (COMPAREARG(1,"list"))        cmddefs_print_all(stdout);
      else if (COMPAREARG(1,"doc"))         cmddefs_print_all_doc(stdout);
      else                                  fprintf(stdout,cmd_help_string);
    }

    /* Help with setting */
    else if (COMPAREARG(0,"set")) {
      cmdparams_print_doc(stdout, "set");
      fprintf(stdout,"\nAt present, parameters may be set in any of the following paths:\n(default)\n");
      blackboard.print_children(stdout);
    }

    /* Other general topics */
    else if (COMPAREARG(0,"files"))         fprintf(stdout,file_types_string,"lissom");
    else if (COMPAREARG(0,"usage"))         fprintf(stdout,usage,"lissom");
    else if (COMPAREARG(0,"version")) {
      fprintf(stdout,"This is version %s of LISSOM, compiled on %s at %s.\n",
              lissom_version,__DATE__, __TIME__);
    }

    /* Help with a particular item */
    else if (argc>0 && cmdparams_print_doc(stdout, argv[0]));/* object found, help printed */

    /* Nothing else matched; explain help system itself */
    else
      cmddefs_print_doc(stdout,"help");      
  }
  
  return CMD_NO_ERROR;
}
#undef COMPARE_ARG

#define NEW_SECTION(name) \
 fprintf(file,"\nSECTION: " #name "\n\n")

#define NEW_SUBSECTION(name) \
 fprintf(file,"\nSUBSECTION: " #name "\n\n")

cmdstat cmd_make_doc( CMD_ARGS )
{
  const char *filename=(argc>0 ? PARSE_C(argv[0]) : "USERDOC");
  
  if (AMPARENTPE) {
    FILE *file;
    if ((file=fopen(filename,"w+"))==NULL){
      ipc_notify(IPC_ALL,IPC_ERROR,"Could not open output file %s", filename);
      return CMD_FILE_ERROR;
    }

    fprintf(file,title_string,lissom_version,__DATE__, __TIME__);

    NEW_SECTION(INTRODUCTION);
    fprintf(file,intro_string);

    NEW_SECTION(USAGE);
    fprintf(file,usage,"lissom");

    NEW_SECTION(PARAMETERS);
    fprintf(file,param_help_string);
    fprintf(file,"\nList of valid parameters:\n\n");
    params_print_parameters(file);
    
    NEW_SUBSECTION(PARAMETER DOCUMENTATION);
    params_print_parameters_doc(file);

    NEW_SECTION(CONSTANTS);
    fprintf(file,"\nList of valid constants:\n\n");
    params_print_constants(file);
    
    NEW_SUBSECTION(CONSTANT DOCUMENTATION);
    params_print_constants_doc(file);

    NEW_SECTION(COMMANDS);
    fprintf(file,cmd_help_string);
    fprintf(file,"\nList of valid commands:\n\n");
    cmddefs_print_all(file);
    
    NEW_SUBSECTION(COMMAND DOCUMENTATION);
    cmddefs_print_all_doc(file);

    NEW_SECTION(FILES);
    fprintf(file,file_types_string,"lissom");

    fclose(file);
  }

  ipc_notify(IPC_ONE,IPC_STD,"Created documentation file %s",filename);
  
  return CMD_NO_ERROR;
}
#undef NEW_SECTION
#undef NEW_SUBSECTION

---