Loading...
Searching...
No Matches
Editline

Helpers for editline. More...

## Macros

#define | EC_EDITLINE_HISTORY_SIZE 128
| Default history size.

## Typedefs

typedef int(* | ec_editline_check_exit_cb_t) (void *opaque)
| Type of callback invoked by ec_editline_interact() to check if loop should exit (when the function return true), or continue (when the function return false).

## Enumerations

enum | ec_editline_init_flags { EC_EDITLINE_DISABLE_SIGNALS = 1 << 0 , EC_EDITLINE_DISABLE_HISTORY = 1 << 1 , EC_EDITLINE_DISABLE_COMPLETION = 1 << 2 , EC_EDITLINE_DEFAULT_SIGHANDLER = 1 << 3 }
| Flags passed at ec_editline initialization. More...

## Functions

struct ec_editline * | ec_editline (const char *prog, FILE *f_in, FILE *f_out, FILE *f_err, enum ec_editline_init_flags flags)
| Create an editline instance with default behavior.
void | ec_editline_free (struct ec_editline *editline)
| Free an editline structure allocated with ec_editline().
struct editline * | ec_editline_get_el (struct ec_editline *editline)
| Return the wrapped editline instance attached to the ec_editline structure.
int | ec_editline_term_size (const struct ec_editline *editline, unsigned int *width, unsigned int *height)
| Get terminal width and height.
int | ec_editline_set_node (struct ec_editline *editline, const struct ec_node *node)
| Attach an ecoli node to the editline structure.
const struct ec_node * | ec_editline_get_node (const struct ec_editline *editline)
| Return the ecoli node attached to the editline structure.
int | ec_editline_set_history (struct ec_editline *editline, size_t hist_size, const char *hist_file)
| Change the history size.
int | ec_editline_set_prompt (struct ec_editline *editline, const char *prompt)
| Set editline prompt.
int | ec_editline_set_prompt_esc (struct ec_editline *editline, const char *prompt, char delim)
| Set editline escaped prompt.
char * | ec_editline_curline (const struct ec_editline *editline, bool trim_after_cursor)
| Get the current edited line.
char * | ec_editline_gets (struct ec_editline *editline)
| Get a line interactively (with completion).
struct ec_pnode * | ec_editline_parse (struct ec_editline *editline)
| Get a line interactively (with completion), and parse it.
int | ec_editline_interact (struct ec_editline *editline, ec_editline_check_exit_cb_t check_exit_cb, void *opaque)
| Interact with the user until exit.
int | ec_editline_complete (struct editline *el, int c)
| Default completion callback used by editline.

## Detailed Description

Helpers for editline.

Helpers that can be used to associate an editline instance with an ecoli node tree.

## Macro Definition Documentation

## EC_EDITLINE_HISTORY_SIZE

#define EC_EDITLINE_HISTORY_SIZE 128

Default history size.

Definition at line 31 of file editline.h.

## Typedef Documentation

## ec_editline_check_exit_cb_t

typedef int(* ec_editline_check_exit_cb_t) (void *opaque)

Type of callback invoked by ec_editline_interact() to check if loop should exit (when the function return true), or continue (when the function return false).

Definition at line 94 of file editline.h.

## Enumeration Type Documentation

## ec_editline_init_flags

enum ec_editline_init_flags

Flags passed at ec_editline initialization.

Enumerator

EC_EDITLINE_DISABLE_SIGNALS

Ask the terminal to not send signals (STOP, SUSPEND, ...).

The ctrl-c, ctrl-z will be interpreted as standard characters. An action can be associated with these characters with:

static int cb(EditLine *editline, int c) {
{
see editline documentation for details
}
if (el_set(el, EL_ADDFN, "ed-foobar", "Help string about foobar", cb))
handle_error;
if (el_set(el, EL_BIND, "^C", "ed-break", NULL))
handle_error;

The default behavior (without this flag) is to let the signal pass: ctrl-c will stop program and ctrl-z will suspend it.

EC_EDITLINE_DISABLE_HISTORY | Disable history. The default behavior creates a history with EC_EDITLINE_HISTORY_SIZE entries. To change this value, use ec_editline_set_history().
EC_EDITLINE_DISABLE_COMPLETION | Disable completion. The default behavior is to complete when ? or <tab> is hit. You can register your own callback with: if (el_set(el, EL_ADDFN, "ed-complete", "Complete buffer", callback)) handle_error; if (el_set(el, EL_BIND, "^I", "ed-complete", NULL)) handle_error; The default used callback is ec_editline_complete().
EC_EDITLINE_DEFAULT_SIGHANDLER | Use editline own signal handler for the following signals when reading command input: SIGCONT, SIGHUP, SIGINT, SIGQUIT, SIGSTOP, SIGTERM, SIGTSTP, and SIGWINCH. Otherwise, the current signal handlers will be used.

Definition at line 36 of file editline.h.

## Function Documentation

## ec_editline()

struct ec_editline * ec_editline | ( | const char * | prog,
|  | FILE * | f_in,
|  | FILE * | f_out,
|  | FILE * | f_err,
|  | enum ec_editline_init_flags | flags )

Create an editline instance with default behavior.

It allocates and initializes an ec_editline structure, calls editline's el_init(), and does the editline configuration according to given flags.

After that, the user must call ec_editline_set_node() to attach the grammar to the editline.

Parameters

  prog | The name of the invoking program, used when reading the editrc(5) file to determine which settings to use.
  f_in | The input stream to use.
  f_out | The output stream to use.
  f_err | The error stream to use.
  flags | Flags to customize initialization. See ec_editline_init_flags.

Returns
  The allocated ec_editline structure, or NULL on error.

Examples
  extension-editline/main.c, parse-yaml/parse-yaml.c, pool-editline/main.c, and simple-editline/main.c.

## ec_editline_free()

void ec_editline_free | ( | struct ec_editline * | editline | ) |

Free an editline structure allocated with ec_editline().

Parameters

  editline | The pointer to the ec_editline structure to free.

Examples
  extension-editline/main.c, parse-yaml/parse-yaml.c, pool-editline/main.c, and simple-editline/main.c.

## ec_editline_get_el()

struct editline * ec_editline_get_el | ( | struct ec_editline * | editline | ) |

Return the wrapped editline instance attached to the ec_editline structure.

Parameters

  editline | The pointer to the ec_editline structure.

## ec_editline_term_size()

int ec_editline_term_size | ( | const struct ec_editline * | editline,
|  | unsigned int * | width,
|  | unsigned int * | height )

Get terminal width and height.

Parameters

  editline | The pointer to the ec_editline structure.
  width | The pointer where the number of columns is stored on success.
  height | The pointer where the number of rows is stored on success.

Returns
  0 on success, or -1 on error (in this case the value pointed by width and height are not modified).

## ec_editline_set_node()

int ec_editline_set_node | ( | struct ec_editline * | editline,
|  | const struct ec_node * | node )

Attach an ecoli node to the editline structure.

This node must be an sh_lex node, with its grammar subtree. It will be used for completion and contextual help. The contextual help description is attached as a string to nodes using a node attribute EC_EDITLINE_HELP_ATTR.

Parameters

  editline | The pointer to the ec_editline structure.
  node | The pointer to the sh_lex ec_node to use as grammar.

Returns
  0 on success, or -1 on error. errno is set to EINVAL if the node is not of type sh_lex.

Examples
  extension-editline/main.c, parse-yaml/parse-yaml.c, pool-editline/main.c, and simple-editline/main.c.

## ec_editline_get_node()

const struct ec_node * ec_editline_get_node | ( | const struct ec_editline * | editline | ) |

Return the ecoli node attached to the editline structure.

Parameters

  editline | The pointer to the ec_editline structure.

Returns
  The pointer to the ec_node.

## ec_editline_set_history()

int ec_editline_set_history | ( | struct ec_editline * | editline,
|  | size_t | hist_size,
|  | const char * | hist_file )

Change the history size.

The default behavior is to have a history whose size is EC_EDITLINE_HISTORY_SIZE. This can be changed with this function.

Parameters

  editline | The pointer to the ec_editline structure.
  hist_size | The desired size of the history.
  hist_file | Optional file path to load and write the history to.

Returns
  0 on success, or -1 on error (errno is set).

## ec_editline_set_prompt()

int ec_editline_set_prompt | ( | struct ec_editline * | editline,
|  | const char * | prompt )

Set editline prompt.

Parameters

  editline | The pointer to the ec_editline structure.
  prompt | The prompt string to use.

Returns
  0 on success, or -1 on error.

Examples
  extension-editline/main.c, pool-editline/main.c, and simple-editline/main.c.

## ec_editline_set_prompt_esc()

int ec_editline_set_prompt_esc | ( | struct ec_editline * | editline,
|  | const char * | prompt,
|  | char | delim )

Set editline escaped prompt.

From el_set(3):

If the start/stop delim character is found in the prompt, the character itself is not printed, but characters after it are printed directly to the terminal without affecting the state of the current line. A subsequent second start/stop literal character ends this behavior. This is typically used to embed literal escape sequences that change the color/style of the terminal in the prompt. Note that the literal escape character cannot be the last character in the prompt, as the escape sequence is attached to the next character in the prompt.

Parameters

  editline | The pointer to the ec_editline structure.
  prompt | The prompt string to use.
  delim | The start/stop literal prompt character.

Returns
  0 on success, or -1 on error.

## ec_editline_curline()

char * ec_editline_curline | ( | const struct ec_editline * | editline,
|  | bool | trim_after_cursor )

Get the current edited line.

Parameters

  editline | The pointer to the ec_editline structure.
  trim_after_cursor | If true, remove all characters starting from cursor (included).

Returns
  An allocated string containing the current line. It must be freed by the user. Return NULL on error.

## ec_editline_gets()

char * ec_editline_gets | ( | struct ec_editline * | editline | ) |

Get a line interactively (with completion).

Wrapper to libedit el_gets(). It returns the edited line without its "\n", and adds it to the history.

Parameters

  editline | The pointer to the ec_editline structure.

Returns
  An allocated string containing the edited line, that must be freed by the caller using free().

## ec_editline_parse()

struct ec_pnode * ec_editline_parse | ( | struct ec_editline * | editline | ) |

Get a line interactively (with completion), and parse it.

Similar to ec_editline_gets(), except that the string result is parsed using the grammar node on success.

Parameters

  editline | The pointer to the ec_editline structure.

Returns
  An allocated ec_pnode containing the parse result. It must be freed by the caller using ec_pnode_free(). Return NULL on error.

Examples
  parse-yaml/parse-yaml.c.

## ec_editline_interact()

int ec_editline_interact | ( | struct ec_editline * | editline,
|  | ec_editline_check_exit_cb_t | check_exit_cb,
|  | void * | opaque )

Interact with the user until exit.

Run the command line, parsing and completing commands on demand. When a command is parsed successfully, invoke the callback attached to the grammar node as a EC_INTERACT_CB_ATTR attribute. The callback type must be ec_interact_command_cb_t.

On EOF, or if check_exit() function returns true, exit from the interactive loop.

Parameters

  editline | The pointer to the ec_editline structure.
  check_exit_cb | Optional function pointer executed before each loop iteration to check if loop should be exited (when the function return true).
  opaque | User pointer, passed as-is to check_exit_cb().

Returns
  0 if interactive loop exited gracefully, or -1 on error.

Examples
  extension-editline/main.c, pool-editline/main.c, and simple-editline/main.c.

## ec_editline_complete()

int ec_editline_complete | ( | struct editline * | el,
|  | int | c )

Default completion callback used by editline.

It displays the list of completions with TAB, and a contextual help with '?'.

Parameters

  el | The pointer to libedit Editline structure.
  c | The character used to complete.

Returns
  An editline error code: CC_REFRESH, CC_ERROR, or CC_REDISPLAY.