ea8683864c967119b35c3ba6eef387c21cbe5d34
[protos/libecoli.git] / 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