Editline

Helpers for editline. More...

Data Structures
struct	ec_editline_help

Macros
#define	EC_EDITLINE_HISTORY_SIZE   128
#define	EC_EDITLINE_HELP_ATTR   "_help"
#define	EC_EDITLINE_CB_ATTR   "_cb"
#define	EC_EDITLINE_DESC_ATTR   "_desc"

Typedefs
typedef int(*	ec_editline_command_cb_t) (const struct ec_pnode *)
typedef int(*	ec_editline_check_exit_cb_t) (void *opaque)

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 }

Functions
struct ec_editline *	ec_editline (const char *prog, FILE *f_in, FILE *f_out, FILE *f_err, enum ec_editline_init_flags flags)
void	ec_editline_free (struct ec_editline *editline)
EditLine *	ec_editline_get_el (struct ec_editline *editline)
int	ec_editline_term_size (const struct ec_editline *editline, unsigned int *width, unsigned int *height)
int	ec_editline_set_node (struct ec_editline *editline, const struct ec_node *node)
const struct ec_node *	ec_editline_get_node (const struct ec_editline *editline)
int	ec_editline_set_history (struct ec_editline *editline, size_t hist_size, const char *hist_file)
ssize_t	ec_editline_get_completions (const struct ec_comp *cmpl, char ***matches_out)
void	ec_editline_free_completions (char **matches, size_t n)
int	ec_editline_print_cols (struct ec_editline *editline, char const *const *matches, size_t n)
char *	ec_editline_append_chars (const struct ec_comp *cmpl)
ssize_t	ec_editline_get_helps (const struct ec_editline *editline, const char *line, struct ec_editline_help **helps_out)
int	ec_editline_print_helps (const struct ec_editline *editline, const struct ec_editline_help *helps, size_t n)
void	ec_editline_free_helps (struct ec_editline_help *helps, size_t n)
ssize_t	ec_editline_get_error_helps (const struct ec_editline *editline, struct ec_editline_help **helps_out, size_t *char_idx)
int	ec_editline_print_error_helps (const struct ec_editline *editline, const struct ec_editline_help *helps, size_t n, size_t char_idx)
int	ec_editline_set_prompt (struct ec_editline *editline, const char *prompt)
int	ec_editline_set_prompt_esc (struct ec_editline *editline, const char *prompt, char delim)
char *	ec_editline_curline (const struct ec_editline *editline, bool trim_after_cursor)
char *	ec_editline_gets (struct ec_editline *editline)
struct ec_pnode *	ec_editline_parse (struct ec_editline *editline)
int	ec_editline_interact (struct ec_editline *el, ec_editline_check_exit_cb_t check_exit_cb, void *opaque)
int	ec_editline_complete (EditLine *el, int c)
int	ec_editline_set_help (struct ec_node *node, const char *help)
int	ec_editline_set_callback (struct ec_node *node, ec_editline_command_cb_t cb)
int	ec_editline_set_desc (struct ec_node *node, const char *desc)

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 37 of file editline.h.

EC_EDITLINE_HELP_ATTR

#define EC_EDITLINE_HELP_ATTR   "_help"

The key of the node attribute storing the contextual help.

Definition at line 42 of file editline.h.

EC_EDITLINE_CB_ATTR

#define EC_EDITLINE_CB_ATTR   "_cb"

The key of the node attribute storing the command callback.

Definition at line 47 of file editline.h.

EC_EDITLINE_DESC_ATTR

#define EC_EDITLINE_DESC_ATTR   "_desc"

The key of the node attribute storing the short description.

Definition at line 52 of file editline.h.

Typedef Documentation

ec_editline_command_cb_t

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

Type of callback invoked by ec_editline_interact() on successful parsing.

Definition at line 109 of file editline.h.

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 116 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 to 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 an 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 57 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.

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.

ec_editline_get_el()

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. @params width The pointer where the number of columns is stored on success. @params 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.

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 an 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_get_completions()

ssize_t ec_editline_get_completions	(	const struct ec_comp *	cmpl,
		char ***	matches_out )

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.

Returns

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

ec_editline_free_completions()

void ec_editline_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_editline_print_cols()

int ec_editline_print_cols	(	struct ec_editline *	editline,
		char const *const *	matches,
		size_t	n )

Print completion matches as columns.

Parameters

editline	The pointer to the ec_editline structure.
matches	The string array of matches to display.
n	The size of the array.

Returns

0 on success, or -1 on error.

ec_editline_append_chars()

char * ec_editline_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()). Return NULL on error.

ec_editline_get_helps()

ssize_t ec_editline_get_helps	(	const struct ec_editline *	editline,
		const char *	line,
		struct ec_editline_help **	helps_out )

Get contextual helps from the current line.

Parameters

editline	The pointer to the ec_editline structure.
line	The line from which to get help. If NULL, use the line currently being edited.
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_editline_print_helps()

int ec_editline_print_helps	(	const struct ec_editline *	editline,
		const struct ec_editline_help *	helps,
		size_t	n )

Print helps generated with ec_editline_get_helps().

Parameters

editline	The pointer to the ec_editline structure.
helps	The helps array returned by ec_editline_get_helps().
n	The array size returned by ec_editline_get_helps().

Returns

0 on success, or -1 on error.

ec_editline_free_helps()

void ec_editline_free_helps	(	struct ec_editline_help *	helps,
		size_t	n )

Free contextual helps.

Free helps generated with ec_editline_get_helps() or ec_editline_get_error_helps().

Parameters

helps	The helps array.
n	The array size.

ec_editline_get_error_helps()

ssize_t ec_editline_get_error_helps	(	const struct ec_editline *	editline,
		struct ec_editline_help **	helps_out,
		size_t *	char_idx )

Get suggestions after a parsing error for the current line.

Parameters

editline	The pointer to the ec_editline structure.
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_editline_print_error_helps()

int ec_editline_print_error_helps	(	const struct ec_editline *	editline,
		const struct ec_editline_help *	helps,
		size_t	n,
		size_t	char_idx )

Print suggestions generated with ec_editline_get_error_helps().

Parameters

editline	The pointer to the ec_editline structure.
helps	The helps array returned by ec_editline_get_helps().
n	The array size returned by ec_editline_get_helps().
char_idx	The index of the error in the line string.

Returns

0 on success, or -1 on error.

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.

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 using using ec_pnode_free(). Return NULL on error.

ec_editline_interact()

int ec_editline_interact	(	struct ec_editline *	el,
		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 "cb" attribute. The callback type must be ec_editline_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.

ec_editline_complete()

int ec_editline_complete	(	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.

ec_editline_set_help()

int ec_editline_set_help	(	struct ec_node *	node,
		const char *	help )

Set help on a grammar node.

Set the node attribute EC_EDITLINE_HELP_ATTR on the node, containing the given string. It is used by the ec_editline 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.

ec_editline_set_callback()

int ec_editline_set_callback	(	struct ec_node *	node,
		ec_editline_command_cb_t	cb )

Set callback function on a grammar node.

Set the node attribute EC_EDITLINE_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.

ec_editline_set_desc()

int ec_editline_set_desc	(	struct ec_node *	node,
		const char *	desc )

Set short description of a grammar node.

Set the node attribute EC_EDITLINE_DESC_ATTR on the node, containing the given string. It is used by the ec_editline 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.