interactive.h

   1 /*
   2  * Copyright (C) 2011 Andre Noll <maan@tuebingen.mpg.de>
   3  *
   4  * Licensed under the GPL v2. For licencing details see COPYING.
   5  */
   6
   7 /** \file interactive.h Public API for interactive sessions. */
   8
   9 /* Interactive is hard to spell, lets' write i9e. */
  10
  11 /** Structure passed as input to the completers. */
  12 struct i9e_completion_info {
  13         char *buffer; /**< The full line. */
  14         char *word; /**< The word the cursor is in. */
  15         int point; /**< Cursor position. */
  16         char **argv; /**< Vector of words in \a buffer. */
  17         int argc; /**< Number of elements(words) in argv. */
  18         int word_num; /**< The cursor is on this word. */
  19 };
  20
  21 /** Completion information returned by the completers. */
  22 struct i9e_completion_result {
  23         /** NULL-terminated array of possible completions. */
  24         char **matches;
  25         /** Whether standard filename completion should be performed. */
  26         bool filename_completion_desired;
  27         /** Suppress adding a space character after the completed word. */
  28         bool dont_append_space;
  29 };
  30
  31 /**
  32  * Define a completer which does nothing.
  33  *
  34  * \param name Determines the name of the function to be defined.
  35  */
  36 #define I9E_DUMMY_COMPLETER(name) void name ## _completer( \
  37                 __a_unused struct i9e_completion_info *ciname, \
  38                 struct i9e_completion_result *result) {result->matches = NULL;}
  39
  40 /**
  41  * A completer is simply a function pointer and name of the command for which
  42  * it performs completion.
  43  */
  44 struct i9e_completer {
  45         /** The command for which this completer provides completion. */
  46         const char *name;
  47         /** The completer returns all possible completions via the second parameter. */
  48         void (*completer)(struct i9e_completion_info *, struct i9e_completion_result *);
  49 };
  50
  51 /**
  52  * The i9e configuration settings of the client.
  53  *
  54  * A structure of this type must be allocated and filled in by the client
  55  * before it is passed to the i9e subsystem via \ref i9e_open().
  56  */
  57 struct i9e_client_info {
  58         /** Threshold for i9e_log(). */
  59         int loglevel;
  60         /** Complete input lines are passed to this callback function. */
  61         int (*line_handler)(char *line);
  62         /** In single key mode, this callback is executed instead. */
  63         int (*key_handler)(int key);
  64         /** The array of valid key sequences for libreadline. */
  65         char **bound_keyseqs;
  66         /** File descriptors to use for input/output/log. */
  67         int fds[3];
  68         /** Text of the current prompt. */
  69         char *prompt;
  70         /** Where to store the readline history. */
  71         char *history_file;
  72         /**
  73          * The array of completers, one per command. This is used for
  74          * completing the first word (the command) and for calling the right
  75          * completer if the cursor is not on the first word.
  76          */
  77         struct i9e_completer *completers;
  78         /**
  79          * If non-NULL, this node is attached immediately to the stdout btr
  80          * node of the i9e subsystem.
  81          */
  82         struct btr_node *producer;
  83 };
  84
  85 int i9e_open(struct i9e_client_info *ici, struct sched *s);
  86 void i9e_attach_to_stdout(struct btr_node *producer);
  87 void ie9_print_status_bar(char *buf, unsigned len);
  88 void i9e_close(void);
  89 void i9e_signal_dispatch(int sig_num);
  90 __printf_2_3 void i9e_log(int ll, const char* fmt,...);
  91 int i9e_select(int n, fd_set *readfds, fd_set *writefds,
  92                 struct timeval *timeout_tv);
  93 int i9e_extract_completions(const char *word, char **string_list,
  94                 char ***result);
  95 char **i9e_complete_commands(const char *word, struct i9e_completer *completers);
  96 void i9e_complete_option(char **opts, struct i9e_completion_info *ci,
  97                 struct i9e_completion_result *cr);
  98 int i9e_print_completions(struct i9e_completer *completers);
  99 int i9e_get_error(void);