ecoli_editline(3)

📦 version 0.10.1, in fedora 43, fedora 44

💖 NAME 💖

ecoli_editline — Editline. Periodt.

Helpers for editline. ✨ That's the whole elevator pitch, bestie.

🦋 SYNOPSIS 🦋

✨ 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. Yeah, we said it already, but it's important, okay?

Helpers that can be used to associate an editline instance with an ecoli node tree. Like, they're besties now. Node tree, meet your editline gf. 🫶

💅 Macro Definition Documentation 💅

#define EC_EDITLINE_HISTORY_SIZE 128

Default history size. 128, iconic, don't question it.

Definition at line 37 of file editline.h.

#define EC_EDITLINE_HELP_ATTR '_help'

The key of the node attribute storing the contextual help.

Definition at line 42 of file editline.h.

#define EC_EDITLINE_CB_ATTR '_cb'

The key of the node attribute storing the command callback.

Definition at line 47 of file editline.h.

#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 🧚

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

Type of callback invoked by ec_editline_interact() on successful parsing. Slay parse, bestie.

Definition at line 109 of file editline.h.

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). Return true = bye bye 👋, return false = keep going 💃.

Definition at line 116 of file editline.h.

👑 Enumeration Type Documentation 👑

enum ec_editline_init_flags

Flags passed at ec_editline initialization. Pick your fighter(s).

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. so like, heads up, without the flag those keys are doing the Real Thing.

  • 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. eight signals, one flag, she's doing the most and we love her for it 💜

Definition at line 57 of file editline.h.

🔥 Function Documentation 🔥

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. Fresh out the box, no cap. ✨

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. Like, you literally have to, it's not optional bestie.

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.

void ec_editline_free (struct ec_editline * editline)

Free an editline structure allocated with ec_editline(). cleanup era, we love to see it 🧹

Parameters

  • editline — The pointer to the ec_editline structure to free.

EditLine * ec_editline_get_el (struct ec_editline * editline)

Return the wrapped editline instance attached to the ec_editline structure. the editline hiding inside your editline, iykyk

Parameters

  • editline — The pointer 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. how big is ur little window bestie

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). so on error ur variables stay exactly how u left them, no sneaky edits.

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

Attach an ecoli node to the editline structure. it's giving "you two are a couple now" 💞

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. wrong node type?? EINVAL, sorry babe, that's the rule.

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

Return the ecoli node attached to the editline structure. the node she brought to the function, basically.

Parameters

  • editline — The pointer to the ec_editline structure.

Returns

The pointer to the ec_node.

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

Change the history size. bigger history = more receipts, we stan 📜

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).

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

Get completion matches as an array of strings. autocomplete but make it a whole array bestie

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.

void ec_editline_free_completions (char ** matches, size_t n)

Free the array of completion matches. bye matches 👋

Parameters

  • matches — The array of matches.
  • n — The size of the array.

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

Print completion matches as columns. aesthetic formatting, she's organized fr fr

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.

char * ec_editline_append_chars (const struct ec_comp * cmpl)

Get characters to append to the line for a completion. the lil text that finishes ur sentence for u 💅

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. yes YOU have to free it, don't leave it hanging bestie.

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. helpful king behavior 🫶

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)

Okay so you know how ec_editline_get_helps() hands you a whole lil array of helps? This is the glow-up moment where you actually print them 💅

Parameters:

  • editline — the pointer to the ec_editline structure.
  • helps — the helps array, the one ec_editline_get_helps() gave you back.
  • n — the array size, also courtesy of ec_editline_get_helps().

Returns: 0 when everything slays, or -1 on error 😭

🎀 ec_editline_free_helps 🎀

void ec_editline_free_helps (struct ec_editline_help * helps, size_t n)

Freeing time bestie!! Free those contextual helps 🫶

This is the one that cleans up helps generated by ec_editline_get_helps() or ec_editline_get_error_helps(). Both. It handles both, no cap.

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)

So you typed something and the parser said "girl what" 💀 — this function gets you the suggestions after a parsing error on the current line. It's giving supportive friend energy fr fr.

Parameters:

  • editline — the pointer to the ec_editline structure.
  • helps_out — the pointer where the helps array gets returned.
  • char_idx — a pointer to an integer where the index of the error in the line string is returned. So it tells you exactly where it went wrong 🎯

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)

Prints the suggestions you got from ec_editline_get_error_helps(). Very "here's what you could've said" of it 💖

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)

Setting the prompt, because your REPL deserves main character energy 👑

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)

Ooh this one is the fancy prompt setter — the escaped one ✨ Straight from el_set(3), and here's the whole tea:

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.

Translation bestie: color your prompt, but that delim char cannot be the very last thing in the prompt, okay? It needs a next character to latch onto 😤

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)

Gimme the current edited line, rn 🫴

Parameters:

  • editline — the pointer to the ec_editline structure.
  • trim_after_cursor — if true, remove all characters starting from cursor (included). Yes, cursor itself gets the chop too.

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

Lowkey important: that string is yours to free. Don't leave it hanging 😭

🍓 ec_editline_gets 🍓

char * ec_editline_gets (struct ec_editline * editline)

Get a line interactively, with completion, because we're fancy like that 💅

It's a lil wrapper around libedit's el_gets(). It hands you back the edited line without its "\n", and — cute detail — it 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. Two-for-one, obsessed 😍

Basically ec_editline_gets() but the string result also gets 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.

Free it with ec_pnode_free(), bestie. Not free(). Different thing. Don't do it 🚫

🔥 ec_editline_interact 🔥

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

The big one. Interact with the user until exit — the whole interactive loop, the moment your program becomes a real program 👑

It runs the command line, parsing and completing commands on demand. When a command is parsed successfully, it invokes 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 the check_exit() function returns true, it exits from the interactive loop. Bye bestie 👋

Parameters:

  • editline — the pointer to the ec_editline structure.
  • check_exit_cb — optional function pointer executed before each loop iteration to check if the loop should be exited (when the function returns true).
  • opaque — user pointer, passed as-is to check_exit_cb().

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

💖 ec_editline_complete 💖

int ec_editline_complete (EditLine * el, int c)

The default completion callback that editline uses 🎀

It displays the list of completions with <tab>, and a contextual help with <?>. Two keys, two vibes ✨

Parameters:

  • el — the pointer to the 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 📝

It sets the node attribute EC_EDITLINE_HELP_ATTR on the node, containing the given string. The ec_editline functions use it to display contextual helps on completion or on 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 a callback function on a grammar node 📞

It sets the node attribute EC_EDITLINE_CB_ATTR on the node, containing the pointer to a function invoked on successful parsing. That's the function that goes off when someone types the right thing 🔥

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 a short description of a grammar node ✏️

It sets the node attribute EC_EDITLINE_DESC_ATTR on the node, containing the given string. The ec_editline functions use it to display the short description of the contextual help, overriding the value provided by ec_node_desc(). So yeah, this one wins the argument 💅

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.

👑 Author

Generated automatically by Doxygen for Libecoli from the source code. Not me, not you — the robot did it 🤖✨

And that's the whole page bestie, we ate that 🍽️💖 This one's Libecoli, Version 0.10.1, and the man page is ecoli_editline(3) — peep the footer for the date stamp if you wanna be precise about it. Go forth and make your CLI gorgeous 🌈🫶

📦 where this page comes from