Loading...
Searching...
No Matches
Interactive command line

Helpers for interactive command line (editline, readline, ...). More...

## Data Structures

struct | ec_interact_help
| A structure describing a contextual help. More...

## Macros

#define | EC_INTERACT_HELP_ATTR "_help"
| The key of the node attribute storing the contextual help.
#define | EC_INTERACT_CB_ATTR "_cb"
| The key of the node attribute storing the command callback.
#define | EC_INTERACT_DESC_ATTR "_desc"
| The key of the node attribute storing the short description.

## Typedefs

typedef int(* | ec_interact_command_cb_t) (const struct ec_pnode *)
| Type of callback attached with EC_INTERACT_CB_ATTR attribute.

## Functions

ssize_t | ec_interact_get_completions (const struct ec_comp *cmpl, char ***matches_out, enum ec_comp_type type_mask)
| Get completion matches as an array of strings.
void | ec_interact_free_completions (char **matches, size_t n)
| Free the array of completion matches.
int | ec_interact_print_cols (FILE *out, unsigned int width, char const *const *matches, size_t n)
| Print completion matches as columns.
char * | ec_interact_append_chars (const struct ec_comp *cmpl)
| Get characters to append to the line for a completion.
ssize_t | ec_interact_get_helps (const struct ec_node *node, const char *line, struct ec_interact_help **helps_out)
| Get contextual helps from the current line.
int | ec_interact_print_helps (FILE *out, unsigned int width, const struct ec_interact_help *helps, size_t n)
| Print helps generated with ec_interact_get_helps().
void | ec_interact_free_helps (struct ec_interact_help *helps, size_t n)
| Free contextual helps.
ssize_t | ec_interact_get_error_helps (const struct ec_node *node, const char *line, struct ec_interact_help **helps_out, size_t *char_idx)
| Get suggestions after a parsing error for the current line.
int | ec_interact_print_error_helps (FILE *out, unsigned int width, const char *line, const struct ec_interact_help *helps, size_t n, size_t char_idx)
| Print suggestions generated with ec_interact_get_error_helps().
int | ec_interact_set_help (struct ec_node *node, const char *help)
| Set help on a grammar node.
int | ec_interact_set_callback (struct ec_node *node, ec_interact_command_cb_t cb)
| Set callback function on a grammar node.
int | ec_interact_set_desc (struct ec_node *node, const char *desc)
| Set short description of a grammar node.
ec_interact_command_cb_t | ec_interact_get_callback (struct ec_pnode *parse)
| Get callback attached to a parse tree.

## Detailed Description

Helpers for interactive command line (editline, readline, ...).

## Macro Definition Documentation

## EC_INTERACT_HELP_ATTR

#define EC_INTERACT_HELP_ATTR "_help"

The key of the node attribute storing the contextual help.

Definition at line 34 of file interact.h.

## EC_INTERACT_CB_ATTR

#define EC_INTERACT_CB_ATTR "_cb"

The key of the node attribute storing the command callback.

Definition at line 39 of file interact.h.

## EC_INTERACT_DESC_ATTR

#define EC_INTERACT_DESC_ATTR "_desc"

The key of the node attribute storing the short description.

Definition at line 44 of file interact.h.

## Typedef Documentation

## ec_interact_command_cb_t

typedef int(* ec_interact_command_cb_t) (const struct ec_pnode *)

Type of callback attached with EC_INTERACT_CB_ATTR attribute.

Examples
  pool-editline/main.c.

Definition at line 49 of file interact.h.

## Function Documentation

## ec_interact_get_completions()

ssize_t ec_interact_get_completions | ( | const struct ec_comp * | cmpl,
|  | char *** | matches_out,
|  | enum ec_comp_type | type_mask )

Get completion matches as an array of strings.

Parameters

  cmpl | The completions, as returned by ec_complete().
  matches_out | The pointer where the matches array will be returned.
  type_mask | The mask of completion types to return (e.g., EC_COMP_FULL | EC_COMP_PARTIAL).

Returns
  The size of the array on success (>= 0), or -1 on error.

## ec_interact_free_completions()

void ec_interact_free_completions | ( | char ** | matches,
|  | size_t | n )

Free the array of completion matches.

Parameters

  matches | The array of matches.
  n | The size of the array.

## ec_interact_print_cols()

int ec_interact_print_cols | ( | FILE * | out,
|  | unsigned int | width,
|  | char const *const * | matches,
|  | size_t | n )

Print completion matches as columns.

Parameters

  out | The pointer to the output stream.
  width | The number of columns on terminal.
  matches | The string array of matches to display.
  n | The size of the array.

Returns
  0 on success, or -1 on error.

## ec_interact_append_chars()

char * ec_interact_append_chars | ( | const struct ec_comp * | cmpl | ) |

Get characters to append to the line for a completion.

Parameters

  cmpl | The completion object containing all the completion items.

Returns
  An allocated string to be appended to the current line (must be freed by the caller using free()). This string can be empty if there is no completion or if completions start with a different letter. Return NULL on error.

## ec_interact_get_helps()

ssize_t ec_interact_get_helps | ( | const struct ec_node * | node,
|  | const char * | line,
|  | struct ec_interact_help ** | helps_out )

Get contextual helps from the current line.

Parameters

  node | The pointer to the sh_lex grammar node.
  line | The line from which to get help.
  helps_out | The pointer where the helps array will be returned.

Returns
  The size of the array on success (>= 0), or -1 on error.

## ec_interact_print_helps()

int ec_interact_print_helps | ( | FILE * | out,
|  | unsigned int | width,
|  | const struct ec_interact_help * | helps,
|  | size_t | n )

Print helps generated with ec_interact_get_helps().

Parameters

  out | The pointer to the output stream.
  width | The number of columns on terminal.
  helps | The helps array returned by ec_interact_get_helps().
  n | The array size returned by ec_interact_get_helps().

Returns
  0 on success, or -1 on error.

## ec_interact_free_helps()

void ec_interact_free_helps | ( | struct ec_interact_help * | helps,
|  | size_t | n )

Free contextual helps.

Free helps generated with ec_interact_get_helps() or ec_interact_get_error_helps().

Parameters

  helps | The helps array.
  n | The array size.

## ec_interact_get_error_helps()

ssize_t ec_interact_get_error_helps | ( | const struct ec_node * | node,
|  | const char * | line,
|  | struct ec_interact_help ** | helps_out,
|  | size_t * | char_idx )

Get suggestions after a parsing error for the current line.

Parameters

  node | The pointer to the sh_lex grammar node.
  line | The line from which to get error help.
  helps_out | The pointer where the helps array will be returned.
  char_idx | A pointer to an integer where the index of the error in the line string is returned.

Returns
  The size of the array on success (>= 0), or -1 on error.

## ec_interact_print_error_helps()

int ec_interact_print_error_helps | ( | FILE * | out,
|  | unsigned int | width,
|  | const char * | line,
|  | const struct ec_interact_help * | helps,
|  | size_t | n,
|  | size_t | char_idx )

Print suggestions generated with ec_interact_get_error_helps().

Parameters

  out | The pointer to the output stream.
  width | The number of columns on terminal.
  line | The line used to generate the error helps.
  helps | The helps array returned by ec_interact_get_helps().
  n | The array size returned by ec_interact_get_helps().
  char_idx | The index of the error in the line string.

Returns
  0 on success, or -1 on error.

## ec_interact_set_help()

int ec_interact_set_help | ( | struct ec_node * | node,
|  | const char * | help )

Set help on a grammar node.

Set the node attribute EC_INTERACT_HELP_ATTR on the node, containing the given string. It is used by the ec_interact functions to display contextual helps on completion or parsing error.

Parameters

  node | The ec_node on which to add the help attribute.
  help | The help string.

Returns
  0 on success, or -1 on error.

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

## ec_interact_set_callback()

int ec_interact_set_callback | ( | struct ec_node * | node,
|  | ec_interact_command_cb_t | cb )

Set callback function on a grammar node.

Set the node attribute EC_INTERACT_CB_ATTR on the node, containing the pointer to a function invoked on successful parsing.

Parameters

  node | The ec_node on which to add the callback attribute.
  cb | The callback function pointer.

Returns
  0 on success, or -1 on error.

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

## ec_interact_set_desc()

int ec_interact_set_desc | ( | struct ec_node * | node,
|  | const char * | desc )

Set short description of a grammar node.

Set the node attribute EC_INTERACT_DESC_ATTR on the node, containing the given string. It is used by the ec_interact functions to display the short description of the contextual help, overriding the value provided by ec_node_desc().

Parameters

  node | The ec_node on which to add the desc attribute.
  desc | The short description string.

Returns
  0 on success, or -1 on error.

Examples
  pool-editline/main.c.

## ec_interact_get_callback()

ec_interact_command_cb_t ec_interact_get_callback | ( | struct ec_pnode * | parse | ) |

Get callback attached to a parse tree.

This function browses the parse tree and try to find an attribute EC_INTERACT_CB_ATTR attached to a grammar node referenced in the tree. Return the value of this attribute, which is a function pointer.

Parameters

  parse | The parsed tree.

Returns
  The function pointer used as command callback.