libtecla.h

BCAST Implementation for NS2

 * Input:
 *  gl      GetLine *  The resource object of gl_get_line().
 *  bufsize  size_t    The number of bytes in the history buffer, or 0
 *                     to delete the buffer completely.
 * Output:
 *  return      int    0 - OK.
 *                     1 - Insufficient memory (the previous buffer
 *                         will have been retained). No error message
 *                         will be displayed.
 */
int gl_resize_history(GetLine *gl, size_t bufsize);

/*.......................................................................
 * Set an upper limit to the number of lines that can be recorded in the
 * history list, or remove a previously specified limit.
 *
 * Input:
 *  gl      GetLine *  The resource object of gl_get_line().
 *  max_lines   int    The maximum number of lines to allow, or -1 to
 *                     cancel a previous limit and allow as many lines
 *                     as will fit in the current history buffer size.
 */
void gl_limit_history(GetLine *gl, int max_lines);

/*.......................................................................
 * Discard either all historical lines, or just those associated with the
 * current history group.
 *
 * Input:
 *  gl      GetLine *  The resource object of gl_get_line().
 *  all_groups  int    If true, clear all of the history. If false,
 *                     clear only the stored lines associated with the
 *                     currently selected history group.
 */
void gl_clear_history(GetLine *gl, int all_groups);

/*.......................................................................
 * Temporarily enable or disable the gl_get_line() history mechanism.
 *
 * Input:
 *  gl      GetLine *  The resource object of gl_get_line().
 *  enable      int    If true, turn on the history mechanism. If
 *                     false, disable it.
 */
void gl_toggle_history(GetLine *gl, int enable);

/*
 * Objects of the following type are returned by gl_terminal_size().
 */
typedef struct {
  int nline;        /* The terminal has nline lines */
  int ncolumn;      /* The terminal has ncolumn columns */
} GlTerminalSize;

/*.......................................................................
 * Update if necessary, and return the current size of the terminal.
 *
 * Input:
 *  gl            GetLine *  The resource object of gl_get_line().
 *  def_ncolumn       int    If the number of columns in the terminal
 *                           can't be determined, substitute this number.
 *  def_nline         int    If the number of lines in the terminal can't
 *                           be determined, substitute this number.
 * Output:
 *  return GlTerminalSize    The current terminal size.
 */
GlTerminalSize gl_terminal_size(GetLine *gl, int def_ncolumn, int def_nline);

/*
 * The gl_lookup_history() function returns information in an
 * argument of the following type.
 */
typedef struct {
  const char *line;    /* The requested history line */
  unsigned group;      /* The history group to which the */
                       /*  line belongs. */
  time_t timestamp;    /* The date and time at which the */
                       /*  line was originally entered. */
} GlHistoryLine;

/*.......................................................................
 * Lookup a history line by its sequential number of entry in the
 * history buffer.
 *
 * Input:
 *  gl            GetLine *  The resource object of gl_get_line().
 *  id      unsigned long    The identification number of the line to
 *                           be returned, where 0 denotes the first line
 *                           that was entered in the history list, and
 *                           each subsequently added line has a number
 *                           one greater than the previous one. For
 *                           the range of lines currently in the list,
 *                           see the gl_range_of_history() function.
 * Input/Output:
 *  line    GlHistoryLine *  A pointer to the variable in which to
 *                           return the details of the line.
 * Output:
 *  return            int    0 - The line is no longer in the history
 *                               list, and *line has not been changed.
 *                           1 - The requested line can be found in
 *                               *line. Note that the string in
 *                               line->line is part of the history
 *                               buffer and will change, so a private
 *                               copy should be made if you wish to
 *                               use it after subsequent calls to any
 *                               functions that take gl as an argument.
 */
int gl_lookup_history(GetLine *gl, unsigned long id, GlHistoryLine *line);

/*
 * The gl_state_of_history() function returns information in an argument
 * of the following type.
 */
typedef struct {
  int enabled;     /* True if history is enabled */
  unsigned group;  /* The current history group */
  int max_lines;   /* The current upper limit on the number of lines */
                   /*  in the history list, or -1 if unlimited. */
} GlHistoryState;

/*.......................................................................
 * Query the state of the history list. Note that any of the input/output
 * pointers can be specified as NULL.
 *
 * Input:
 *  gl            GetLine *  The resource object of gl_get_line().
 * Input/Output:
 *  state  GlHistoryState *  A pointer to the variable in which to record
 *                           the return values.
 */
void gl_state_of_history(GetLine *gl, GlHistoryState *state);

/*
 * The gl_range_of_history() function returns information in an argument
 * of the following type.
 */
typedef struct {
  unsigned long oldest;  /* The sequential entry number of the oldest */
                         /*  line in the history list. */
  unsigned long newest;  /* The sequential entry number of the newest */
                         /*  line in the history list. */
  int nlines;            /* The number of lines in the history list */
} GlHistoryRange;

/*.......................................................................
 * Query the number and range of lines in the history buffer.
 *
 * Input:
 *  gl            GetLine *  The resource object of gl_get_line().
 *  range  GlHistoryRange *  A pointer to the variable in which to record
 *                           the return values. If range->nline=0, the
 *                           range of lines will be given as 0-0.
 */
void gl_range_of_history(GetLine *gl, GlHistoryRange *range);

/*
 * The gl_size_of_history() function returns information in an argument
 * of the following type.
 */
typedef struct {
  size_t size;      /* The size of the history buffer (bytes) */
  size_t used;      /* The number of bytes of the history buffer */
                    /*  that are currently occupied. */
} GlHistorySize;

/*.......................................................................
 * Return the size of the history buffer and the amount of the
 * buffer that is currently in use.
 *
 * Input:
 *  gl         GetLine *  The resource object of gl_get_line().
 * Input/Output:
 *  GlHistorySize size *  A pointer to the variable in which to return
 *                        the results.
 */
void gl_size_of_history(GetLine *gl, GlHistorySize *size);

/*.......................................................................
 * Specify whether text that users type should be displayed or hidden.
 * In the latter case, only the prompt is displayed, and the final
 * input line is not archived in the history list.
 *
 * Input:
 *  gl         GetLine *  The input-line history maintenance object.
 *  enable         int     0 - Disable echoing.
 *                         1 - Enable echoing.
 *                        -1 - Just query the mode without changing it.
 * Output:
 *  return         int    The echoing disposition that was in effect
 *                        before this function was called:
 *                         0 - Echoing was disabled.
 *                         1 - Echoing was enabled.
 */
int gl_echo_mode(GetLine *gl, int enable);

/*.......................................................................
 * This function can be called from gl_get_line() callbacks to have
 * the prompt changed when they return. It has no effect if gl_get_line()
 * is not currently being invoked.
 *
 * Input:
 *  gl         GetLine *  The resource object of gl_get_line().
 *  prompt  const char *  The new prompt.
 */
void gl_replace_prompt(GetLine *gl, const char *prompt);

/*
 * Enumerate the available prompt formatting styles.
 */
typedef enum {
  GL_LITERAL_PROMPT,   /* Display the prompt string literally */
  GL_FORMAT_PROMPT     /* The prompt string can contain any of the */
                       /* following formatting directives: */
                       /*   %B  -  Display subsequent characters */
                       /*          with a bold font. */
                       /*   %b  -  Stop displaying characters */
                       /*          with the bold font. */
                       /*   %U  -  Underline subsequent characters. */
                       /*   %u  -  Stop underlining characters. */
                       /*   %S  -  Highlight subsequent characters */
                       /*          (also known as standout mode). */
                       /*   %s  -  Stop highlighting characters */
                       /*   %%  -  Display a single % character. */
} GlPromptStyle;

/*.......................................................................
 * Specify whether to heed text attribute directives within prompt
 * strings.
 *
 * Input:
 *  gl           GetLine *  The resource object of gl_get_line().
 *  style  GlPromptStyle    The style of prompt (see the definition of
 *                          GlPromptStyle in libtecla.h for details).
 */
void gl_prompt_style(GetLine *gl, GlPromptStyle style);

/*.......................................................................
 * Remove a signal from the list of signals that gl_get_line() traps.
 *
 * Input:
 *  gl           GetLine *  The resource object of gl_get_line().
 *  signo            int    The number of the signal to be ignored.
 * Output:
 *  return           int    0 - OK.
 *                          1 - Error.
 */
int gl_ignore_signal(GetLine *gl, int signo);

/*
 * A bitwise union of the following enumerators is passed to
 * gl_trap_signal() to specify the environment in which the
 * application's signal handler is to be called.
 */
typedef enum {
  GLS_RESTORE_SIG=1,  /* Restore the caller's signal environment */
                      /* while handling the signal. */
  GLS_RESTORE_TTY=2,  /* Restore the caller's terminal settings */
                      /* while handling the signal. */
  GLS_RESTORE_LINE=4, /* Move the cursor to the start of the next line */
  GLS_REDRAW_LINE=8,  /* Redraw the input line when the signal handler */
                      /*  returns. */
  GLS_UNBLOCK_SIG=16, /* Normally a signal who's delivery is found to */
                      /*  be blocked by the calling application is not */
                      /*  trapped by gl_get_line(). Including this flag */
                      /*  causes it to be temporarily unblocked and */
                      /*  trapped while gl_get_line() is executing. */
  GLS_DONT_FORWARD=32,/* Don't forward the signal to the signal handler */
                      /*  of the calling program. */
  GLS_RESTORE_ENV = GLS_RESTORE_SIG | GLS_RESTORE_TTY | GLS_REDRAW_LINE,
  GLS_SUSPEND_INPUT = GLS_RESTORE_ENV | GLS_RESTORE_LINE
} GlSignalFlags;

/*
 * The following enumerators are passed to gl_trap_signal() to tell
 * it what to do after the application's signal handler has been called.
 */
typedef enum {
  GLS_RETURN,      /* Return the line as though the user had pressed the */
                   /*  return key. */
  GLS_ABORT,       /* Cause gl_get_line() to return NULL */
  GLS_CONTINUE     /* After handling the signal, resume command line editing */
} GlAfterSignal;

/*.......................................................................
 * Tell gl_get_line() how to respond to a given signal. This can be used
 * both to override the default responses to signals that gl_get_line()
 * normally catches and to add new signals to the list that are to be
 * caught.
 *
 * Input:
 *  gl           GetLine *  The resource object of gl_get_line().
 *  signo            int    The number of the signal to be caught.
 *  flags       unsigned    A bitwise union of GlSignalFlags enumerators.
 *  after  GlAfterSignal    What to do after the application's signal
 *                          handler has been called.
 *  errno_value      int    The value to set errno to.
 * Output:
 *  return           int    0 - OK.
 *                          1 - Insufficient memory to record the
 *                              new signal disposition.
 */
int gl_trap_signal(GetLine *gl, int signo, unsigned flags,
		   GlAfterSignal after, int errno_value);