libtecla.h

BCAST Implementation for NS2

/*.......................................................................
 * Return the last signal that was caught by the most recent call to
 * gl_get_line(), or -1 if no signals were caught. This is useful if
 * gl_get_line() returns errno=EINTR and you need to find out what signal
 * caused it to abort.
 *
 * Input:
 *  gl           GetLine *  The resource object of gl_get_line().
 * Output:
 *  return           int    The last signal caught by the most recent
 *                          call to gl_get_line(), or -1 if no signals
 *                          were caught.
 */
int gl_last_signal(const GetLine *gl);

/*.......................................................................
 * This function is designed to be called by CPL_MATCH_FN() callback
 * functions. It adds one possible completion of the token that is being
 * completed to an array of completions. If the completion needs any
 * special quoting to be valid when displayed in the input line, this
 * quoting must be included in the string.
 *
 * Input:
 *  cpl      WordCompletion *  The argument of the same name that was passed
 *                             to the calling CPL_MATCH_FN() callback function.
 *  line         const char *  The input line, as received by the callback
 *                             function.
 *  word_start          int    The index within line[] of the start of the
 *                             word that is being completed. If an empty
 *                             string is being completed, set this to be
 *                             the same as word_end.
 *  word_end            int    The index within line[] of the character which
 *                             follows the incomplete word, as received by the
 *                             callback function.
 *  suffix       const char *  The appropriately quoted string that could
 *                             be appended to the incomplete token to complete
 *                             it. A copy of this string will be allocated
 *                             internally.
 *  type_suffix  const char *  When listing multiple completions, gl_get_line()
 *                             appends this string to the completion to indicate
 *                             its type to the user. If not pertinent pass "".
 *                             Otherwise pass a literal or static string.
 *  cont_suffix  const char *  If this turns out to be the only completion,
 *                             gl_get_line() will append this string as
 *                             a continuation. For example, the builtin
 *                             file-completion callback registers a directory
 *                             separator here for directory matches, and a
 *                             space otherwise. If the match were a function
 *                             name you might want to append an open
 *                             parenthesis, etc.. If not relevant pass "".
 *                             Otherwise pass a literal or static string.
 * Output:
 *  return              int    0 - OK.
 *                             1 - Error.
 */
int cpl_add_completion(WordCompletion *cpl, const char *line,
		       int word_start, int word_end, const char *suffix,
		       const char *type_suffix, const char *cont_suffix);

/*
 * Each possible completion string is recorded in an array element of
 * the following type.
 */
typedef struct {
  char *completion;        /* The matching completion string */
  char *suffix;            /* The pointer into completion[] at which the */
                           /*  string was extended. */
  const char *type_suffix; /* A suffix to be added when listing completions */
                           /*  to indicate the type of the completion. */
} CplMatch;

/*
 * Completions are returned in a container of the following form.
 */
typedef struct {
  char *suffix;            /* The common initial part of all of the */
                           /*  completion suffixes. */
  const char *cont_suffix; /* Optional continuation string to be appended to */
                           /*  the sole completion when nmatch==1. */
  CplMatch *matches;       /* The array of possible completion strings, */
                           /*  sorted into lexical order. */
  int nmatch;              /* The number of elements in matches[] */
} CplMatches;

/*.......................................................................
 * Given an input line and the point at which completion is to be
 * attempted, return an array of possible completions.
 *
 * Input:
 *  cpl    WordCompletion *  The word-completion resource object.
 *  line       const char *  The current input line.
 *  word_end          int    The index of the character in line[] which
 *                           follows the end of the token that is being
 *                           completed.
 *  data             void *  Anonymous 'data' to be passed to match_fn().
 *  match_fn   CplMatchFn *  The function that will identify the prefix
 *                           to be completed from the input line, and
 *                           record completion suffixes.
 * Output:
 *  return     CplMatches *  The container of the array of possible
 *                           completions. The returned pointer refers
 *                           to a container owned by the parent Completion
 *                           object, and its contents thus potentially
 *                           change on every call to cpl_matches().
 */
CplMatches *cpl_complete_word(WordCompletion *cpl, const char *line,
			      int word_end, void *data, 
			      CplMatchFn *match_fn);

/*.......................................................................
 * Print out an array of matching completions.
 *
 * Input:
 *  result  CplMatches *   The container of the sorted array of
 *                         completions.
 *  fp            FILE *   The output stream to write to.
 *  term_width     int     The width of the terminal.
 * Output:
 *  return         int     0 - OK.
 *                         1 - Error.
 */
int cpl_list_completions(CplMatches *result, FILE *fp, int term_width);

/*.......................................................................
 * Return a description of the error that occurred on the last call to
 * cpl_complete_word() or cpl_add_completion().
 *
 * Input:
 *  cpl   WordCompletion *  The string-completion resource object.
 * Output:
 *  return    const char *  The description of the last error.
 */
const char *cpl_last_error(WordCompletion *cpl);

/*
 * PathCache objects encapsulate the resources needed to record
 * files of interest from comma-separated lists of directories.
 */
typedef struct PathCache PathCache;

/*.......................................................................
 * Create an object who's function is to maintain a cache of filenames
 * found within a list of directories, and provide quick lookup and
 * completion of selected files in this cache.
 *
 * Output:
 *  return     PathCache *  The new, initially empty cache, or NULL
 *                          on error.
 */
PathCache *new_PathCache(void);

/*.......................................................................
 * Delete a given cache of files, returning the resources that it
 * was using to the system.
 *
 * Input:
 *  pc      PathCache *  The cache to be deleted (can be NULL).
 * Output:
 *  return  PathCache *  The deleted object (ie. allways NULL).
 */
PathCache *del_PathCache(PathCache *pc);

/*.......................................................................
 * Return a description of the last path-caching error that occurred.
 *
 * Input:
 *  pc     PathCache *   The filename cache that suffered the error.
 * Output:
 *  return      char *   The description of the last error.
 */
const char *pca_last_error(PathCache *pc);

/*.......................................................................
 * Build the list of files of interest contained in a given
 * colon-separated list of directories.
 *
 * Input:
 *  pc         PathCache *  The cache in which to store the names of
 *                          the files that are found in the list of
 *                          directories.
 *  path      const char *  A colon-separated list of directory
 *                          paths. Under UNIX, when searching for
 *                          executables, this should be the return
 *                          value of getenv("PATH").
 * Output:
 *  return           int    0 - OK.
 *                          1 - An error occurred.
 */
int pca_scan_path(PathCache *pc, const char *path);

/*.......................................................................
 * If you want subsequent calls to pca_lookup_file() and
 * pca_path_completions() to only return the filenames of certain
 * types of files, for example executables, or filenames ending in
 * ".ps", call this function to register a file-selection callback
 * function. This callback function takes the full pathname of a file,
 * plus application-specific data, and returns 1 if the file is of
 * interest, and zero otherwise.
 *
 * Input:
 *  pc         PathCache *  The filename cache.
 *  check_fn  CplCheckFn *  The function to call to see if the name of
 *                          a given file should be included in the
 *                          cache. This determines what type of files
 *                          will reside in the cache. To revert to
 *                          selecting all files, regardless of type,
 *                          pass 0 here.
 *  data            void *  You can pass a pointer to anything you
 *                          like here, including NULL. It will be
 *                          passed to your check_fn() callback
 *                          function, for its private use.
 */
void pca_set_check_fn(PathCache *pc, CplCheckFn *check_fn, void *data);

/*.......................................................................
 * Given the simple name of a file, search the cached list of files
 * in the order in which they where found in the list of directories
 * previously presented to pca_scan_path(), and return the pathname
 * of the first file which has this name.
 *
 * Input:
 *  pc     PathCache *  The cached list of files.
 *  name  const char *  The name of the file to lookup.
 *  name_len     int    The length of the filename substring at the
 *                      beginning of name[], or -1 to assume that the
 *                      filename occupies the whole of the string.
 *  literal      int    If this argument is zero, lone backslashes
 *                      in name[] are ignored during comparison
 *                      with filenames in the cache, under the
 *                      assumption that they were in the input line
 *                      soley to escape the special significance of
 *                      characters like spaces. To have them treated
 *                      as normal characters, give this argument a
 *                      non-zero value, such as 1.
 * Output:
 *  return      char *  The pathname of the first matching file,
 *                      or NULL if not found. Note that the returned
 *                      pointer points to memory owned by *pc, and
 *                      will become invalid on the next call.
 */
char *pca_lookup_file(PathCache *pc, const char *name, int name_len,
		      int literal);

/*
 * Objects of the following type can be used to change the default
 * behavior of the pca_path_completions() callback function.
 */
typedef struct PcaPathConf PcaPathConf;

/*
 * pca_path_completions() is a completion callback function for use directly
 * with cpl_complete_word() or gl_customize_completions(), or indirectly
 * from your own completion callback function. It requires that a PcaPathConf
 * object be passed via its 'void *data' argument (see below).
 */
CPL_MATCH_FN(pca_path_completions);

/*.......................................................................
 * Allocate and initialize a pca_path_completions() configuration object.
 *
 * Input:
 *  pc         PathCache *  The filename cache in which to look for
 *                          file name completions.
 * Output:
 *  return   PcaPathConf *  The new configuration structure, or NULL
 *                          on error.
 */
PcaPathConf *new_PcaPathConf(PathCache *pc);

/*.......................................................................
 * Deallocate memory, previously allocated by new_PcaPathConf().
 *
 * Input:
 *  ppc     PcaPathConf *  Any pointer previously returned by
 *                         new_PcaPathConf() [NULL is allowed].
 * Output:
 *  return  PcaPathConf *  The deleted structure (always NULL).
 */
PcaPathConf *del_PcaPathConf(PcaPathConf *ppc);

/*
 * If backslashes in the prefix being passed to pca_path_completions()
 * should be treated as literal characters, call the following function
 * with literal=1. Otherwise the default is to treat them as escape
 * characters which remove the special meanings of spaces etc..
 */
void ppc_literal_escapes(PcaPathConf *ppc, int literal);

/*
 * Before calling pca_path_completions, call this function if you know
 * the index at which the filename prefix starts in the input line.
 * Otherwise by default, or if you specify start_index to be -1, the
 * filename is taken to start after the first unescaped space preceding
 * the cursor, or the start of the line, whichever comes first.
 */
void ppc_file_start(PcaPathConf *ppc, int start_index);

#ifdef __cplusplus
}
#endif

#endif