ecoli_editline.h

   1 /* SPDX-License-Identifier: BSD-3-Clause
   2  * Copyright 2018, Olivier MATZ <zer0@droids-corp.org>
   3  */
   4
   5 /**
   6  * @defgroup editline Editline
   7  * @{
   8  *
   9  * @brief Helpers for editline
  10  *
  11  * Helpers that can be used to associate an editline instance with
  12  * an ecoli node tree.
  13  *
  14  * XXX support saved history
  15  * XXX support multiline edition
  16  * XXX set prompt
  17  */
  18
  19 #ifndef ECOLI_EDITLINE_
  20 #define ECOLI_EDITLINE_
  21
  22 #include <histedit.h>
  23
  24 struct ec_editline;
  25 struct ec_node;
  26 struct ec_pnode;
  27 struct ec_comp;
  28
  29 struct ec_editline_help {
  30         char *desc;
  31         char *help;
  32 };
  33
  34 /**
  35  * Default history size.
  36  */
  37 #define EC_EDITLINE_HISTORY_SIZE 128
  38
  39 /**
  40  * Ask the terminal to not send signals (STOP, SUSPEND, XXX). The
  41  * ctrl-c, ctrl-z will be interpreted as standard characters. An
  42  * action can be associated to these characters with:
  43  *
  44  *      static int cb(EditLine *editline, int c) {
  45  *      {
  46  *              see editline documentation for details
  47  *      }
  48  *
  49  *      if (el_set(el, EL_ADDFN, "ed-foobar", "Help string about foobar", cb))
  50  *              handle_error;
  51  *      if (el_set(el, EL_BIND, "^C", "ed-break", NULL))
  52  *              handle_error;
  53  *
  54  * The default behavior (without this flag) is to let the signal pass: ctrl-c
  55  * will stop program and ctrl-z will suspend it.
  56  */
  57 #define EC_EDITLINE_DISABLE_SIGNALS 0x01
  58
  59 /**
  60  * Disable history. The default behavior creates an history with
  61  * EC_EDITLINE_HISTORY_SIZE entries. To change this value, use
  62  * ec_editline_set_history().
  63  */
  64 #define EC_EDITLINE_DISABLE_HISTORY 0x02
  65
  66 /**
  67  * Disable completion. The default behavior is to complete when
  68  * '?' or '<tab>' is hit. You can register your own callback with:
  69  *
  70  *      if (el_set(el, EL_ADDFN, "ed-complete", "Complete buffer", callback))
  71  *              handle_error;
  72  *      if (el_set(el, EL_BIND, "^I", "ed-complete", NULL))
  73  *              handle_error;
  74  *
  75  * The default used callback is ec_editline_complete().
  76  */
  77 #define EC_EDITLINE_DISABLE_COMPLETION 0x04
  78
  79 typedef int (*ec_editline_cmpl_t)(struct ec_editline *editline, int c);
  80
  81 /**
  82  * Create an editline instance with default behavior.
  83  *
  84  * XXX Wrapper to editline's el_init()
  85  *
  86  * It
  87  */
  88 struct ec_editline *
  89 ec_editline(const char *name, FILE *f_in, FILE *f_out, FILE *f_err,
  90         unsigned int flags);
  91
  92 /**
  93  * Free an editline instance allocated with ec_editline().
  94  */
  95 void ec_editline_free(struct ec_editline *editline);
  96
  97 /**
  98  * Return the editline instance attached to the ec_editline object.
  99  */
 100 EditLine *ec_editline_get_el(struct ec_editline *editline);
 101
 102 // XXX public?
 103 const struct ec_node *ec_editline_get_node(struct ec_editline *editline);
 104 void ec_editline_set_node(struct ec_editline *editline,
 105                         const struct ec_node *node);
 106
 107 //XXX get history, get_...
 108
 109 /**
 110  * Change the history size.
 111  *
 112  * The default behavior is to have an history whose size
 113  * is EC_EDITLINE_HISTORY_SIZE. This can be changed with this
 114  * function.
 115  *
 116  * @param editline
 117  *   The pointer to the ec_editline structure.
 118  * @param hist_size
 119  *   The desired size of the history.
 120  * @return
 121  *   0 on success, or -1 on error (errno is set).
 122  */
 123 int ec_editline_set_history(struct ec_editline *editline,
 124         size_t hist_size);
 125
 126 int
 127 ec_editline_print_cols(struct ec_editline *editline,
 128                 char const * const *matches, size_t n);
 129
 130 void ec_editline_free_completions(char **matches, size_t len);
 131 ssize_t
 132 ec_editline_get_completions(const struct ec_comp *cmpl, char ***matches_out);
 133 char *
 134 ec_editline_append_chars(const struct ec_comp *cmpl);
 135
 136 ssize_t
 137 ec_editline_get_helps(const struct ec_editline *editline, const char *line,
 138         const char *full_line, struct ec_editline_help **helps_out);
 139 int
 140 ec_editline_print_helps(struct ec_editline *editline,
 141                         const struct ec_editline_help *helps, size_t n);
 142 void
 143 ec_editline_free_helps(struct ec_editline_help *helps, size_t len);
 144
 145 int
 146 ec_editline_set_prompt(struct ec_editline *editline, const char *prompt);
 147
 148
 149
 150
 151 /**
 152  * Get a line.
 153  *
 154  * The returned line must be freed by the caller using ec_free().
 155  */
 156 char *ec_editline_gets(struct ec_editline *editline);
 157
 158 /**
 159  * Get a line (managing completion) and parse it with passed node
 160  * XXX find a better name?
 161  */
 162 struct ec_pnode *
 163 ec_editline_parse(struct ec_editline *editline, const struct ec_node *node);
 164
 165 int
 166 ec_editline_complete(EditLine *el, int c);
 167
 168 #endif