include/ecoli_editline.h

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