libmojave/util/lm_command_util.mli

   1 (*
   2    Command-line Interface Utilities
   3    Copyright (C) 2002 Justin David Smith, Caltech
   4
   5    This library is free software; you can redistribute it and/or
   6    modify it under the terms of the GNU Lesser General Public
   7    License as published by the Free Software Foundation,
   8    version 2.1 of the License.
   9
  10    This library is distributed in the hope that it will be useful,
  11    but WITHOUT ANY WARRANTY; without even the implied warranty of
  12    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  13    Lesser General Public License for more details.
  14
  15    You should have received a copy of the GNU Lesser General Public
  16    License along with this library; if not, write to the Free Software
  17    Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
  18
  19    Additional permission is given to link this library with the
  20    OpenSSL project's "OpenSSL" library, and with the OCaml runtime,
  21    and you may distribute the linked executables.  See the file
  22    LICENSE.libmojave for more details.
  23  *)
  24
  25
  26 (***  Command Processing (Extract Commands)  ***)
  27
  28
  29 (* get_next_argument args
  30    Return the first argument in an argument list, along with the
  31    tail of the list.  This is NOT List.hd; if the list is empty,
  32    then this returns an empty string for the next argument.  *)
  33 val get_next_argument : string list -> string * string list
  34
  35
  36 (* reconstruct_arguments args
  37    Return a string representing the indicated argument list.  The
  38    arguments are NOT quoted by this function; think of it as a
  39    ``feature'' at this time ;)  *)
  40 val reconstruct_arguments : string list -> string
  41
  42
  43 (***  Prompt Formatting and Display Properties  ***)
  44
  45
  46 (* tcap_set_bold
  47    tcap_clear_attr
  48    Get terminal capabilities for formatting text.  *)
  49 val tcap_set_bold : string option
  50 val tcap_clear_attr : string option
  51
  52
  53 (* xterm_escape_begin
  54    xterm_escape_end
  55    XTerm escape sequences for setting and clearing the title text.  *)
  56 val xterm_escape_begin : string option
  57 val xterm_escape_end : string option
  58
  59
  60 (* bold_text text
  61    Makes the indicated text bold. If no termcap support was available, this
  62    returns the original prompt, unaltered. This is used primarily for prompt
  63    formatting.  *)
  64 val bold_text : string -> string
  65
  66
  67 (* title_text appname text
  68    Format text to be displayed in a title, as in an xterm title.  If the
  69    terminal is not an xterm, then this returns an empty string.  This will
  70    NOT format the text to display anything to the console itself, under
  71    any circumstance.  This may prepend the application name to the text. *)
  72 val title_text : string -> string -> string
  73
  74
  75 (***  Read-Eval-Print Lm_loop  ***)
  76
  77
  78 (* run_status
  79    Used to indicate whether a read-eval-print loop should continue accepting
  80    commands, or if it should terminate.  Once the loop is terminated, an
  81    arbitrary value may be returned.
  82       Continue          Command wants the read-eval-print loop to continue.
  83       Exit value        Command wants loop to exit and return given value.
  84  *)
  85 type 'result run_status =
  86    Continue
  87  | Exit of 'result
  88
  89
  90 (* run_command
  91    Type of command functions that are called by the read-eval-print loop.
  92    'args is the type of the arguments (usually string list), and 'result is
  93    the value returned by commands once they are ready to exit the loop.  *)
  94 type ('args, 'result) run_command = 'args -> 'result run_status
  95
  96
  97 (* command
  98    Type of a single command entry.  This corresponds to a command name, the
  99    function to call when the command is invoked, and the help text for the
 100    command.  *)
 101 type ('args, 'result) command = string * ('args, 'result) run_command * string
 102
 103
 104 (* run_info
 105    Information given to run_loop which determines how the command prompt is
 106    formatted and how help text is presented to the user.  Contains these
 107    fields:
 108       ri_appname        Name of the application (used in title prompt).
 109       ri_curses         If true, the help display can use curses interface.
 110       ri_hack_title     If true, title text will be displayed in prompts.
 111       ri_help_prefix    Text/overview to prepend to any help display.
 112       ri_prompt         Function which, when run, returns text to display on
 113                         each command prompt.  The function is passed a unit
 114                         argument.
 115       ri_commands       List of commands to accept, and their actions.
 116       ri_cmd_quit       Function to call if ^D is struck.
 117       ri_arg_filter     Command to run on the arguments before passing them
 118                         to the command function.  space_filter gives the
 119                         usual string list, split on whitespace.
 120  *)
 121 type ('args, 'result) run_info =
 122    { ri_appname      :  string;
 123      ri_curses       :  bool;
 124      ri_hack_title   :  bool;
 125      ri_help_prefix  :  string;
 126      ri_prompt       :  unit -> string;
 127      ri_commands     :  ('args, 'result) command list;
 128      ri_cmd_quit     :  ('args, 'result) run_command;
 129      ri_arg_filter   :  string -> 'args
 130    }
 131
 132
 133 (* continue f args
 134    Takes f : args -> unit and builds a new function which will run f,
 135    then return Continue.  *)
 136 val continue : ('a -> unit) -> 'a -> 'result run_status
 137
 138
 139 (* space_filter arguments
 140    Process arguments into a list of nonempty strings, which contain
 141    the arguments separated by whitespace.  This is the typical filter
 142    given in the run_info structure.  *)
 143 val space_filter : string -> string list
 144
 145
 146 (* no_filter arguments
 147    Pass the arguments through unaltered.  *)
 148 val no_filter : string -> string
 149
 150
 151 (* read_eval_print run
 152    Read a single command, evaluate it, and print the results.  This
 153    processes at most one command for constructing a test case; call
 154    it from within a loop to accept multiple commands.  *)
 155 val read_eval_print : ('args, 'result) run_info -> 'result run_status
 156
 157
 158 (* run_loop read_eval_print run
 159    Runs the loop for evaluating ri_commands until the user quits and/or
 160    presses ^D.  This catches any exceptions that may have been thrown
 161    by the read-eval-print loop, above.  You must indicate what function
 162    should be called when ^D is pressed, using ri_cmd_quit.  The given
 163    read_eval_print function is used; usually you want Mcc_command_util's
 164    version of read_eval_print.
 165
 166    If the ri_curses flag is true, then the help system is allowed to
 167    use curses interface to display help on the commands.  Any help text
 168    will be preceded by the contents of the string ri_help_prefix; the
 169    rest of the help is extracted from commands.
 170
 171    This function catches EOF, ^C, Unix errors, Failures, and Invalid
 172    argument exceptions.  If you wish to catch other exceptions in a
 173    manner that will not abort the run loop, you should pass in a custom
 174    read_eval_print which catches those exceptions and returns Continue.  *)
 175 val run_loop : (('args, 'result) run_info -> 'result run_status) -> ('args, 'result) run_info -> 'result
 176
 177
 178 (* bad_arguments ()
 179    Helper that indicates the arguments to a command were bad.  *)
 180 val bad_arguments : unit -> unit
 181
 182
 183 (***  Specialised Prompts  ***)
 184
 185
 186 (* yes_no_cancel appname hack_title prompt default
 187    Presents a yes/no/cancel prompt (^D maps to ``cancel'') for the user
 188    to respond to.  Returns None if the user cancels, otherwise returns
 189    Some true if the user responds yes and Some false if the user responds
 190    no.  *)
 191 val yes_no_cancel : string -> bool -> string -> bool option -> bool option
 192
 193
 194 (* yes_no appname hack_title prompt default
 195    Similar to yes_no_cancel, but ``cancel'' gets mapped to ``no''.  *)
 196 val yes_no : string -> bool -> string -> bool -> bool
 197
 198
 199 (* ok_to_overwrite_file appname hack_title filename
 200    If the named file exists, this puts up a prompt if it is okay to
 201    overwrite the named file, which defaults to yes.  No prompt is
 202    displayed if the file doesn't exist.  This returns true if either
 203    the file doesn't exist, or the user says it is okay to overwrite.  *)
 204 val ok_to_overwrite_file : string -> bool -> string -> bool