--- name: "editline.lukem" section: "3" platform: "linux" package: "lukemftp" version: "1.5-8" release: "Debian 3.1 (Sarge)" platforms: ["linux"] url: "https://new.carta.tech/editline.lukem" --- # editline.lukem(3) line editor and history functions ## NAME **editline**, **el\_init**, **el\_end**, **el\_reset**, **el\_gets**, **el\_getc**, **el\_push**, **el\_parse**, **el\_set**, **el\_source**, **el\_resize**, **el\_line**, **el\_insertstr**, **el\_deletestr**, **history\_init**, **history\_end**, **history** – line editor and history functions ## LIBRARY library “libedit” ## SYNOPSIS **#include \** *EditLine* *\**\ **el\_init**(*const char \*prog*, *FILE \*fin*, *FILE \*fout*, *FILE \*ferr*); *void*\ **el\_end**(*EditLine \*e*); *void*\ **el\_reset**(*EditLine \*e*); *const* *char* *\**\ **el\_gets**(*EditLine \*e*, *int \*count*); *int*\ **el\_getc**(*EditLine \*e*, *char \*ch*); *void*\ **el\_push**(*EditLine \*e*, *const char \*str*); *int*\ **el\_parse**(*EditLine \*e*, *int argc*, *char \*argv\[\]*); *int*\ **el\_set**(*EditLine \*e*, *int op*, *...*); *int*\ **el\_get**(*EditLine \*e*, *int op*, *void \*result*); *int*\ **el\_source**(*EditLine \*e*, *const char \*file*); *void*\ **el\_resize**(*EditLine \*e*); *const* *LineInfo* *\**\ **el\_line**(*EditLine \*e*); *int*\ **el\_insertstr**(*EditLine \*e*, *const char \*str*); *void*\ **el\_deletestr**(*EditLine \*e*, *int count*); *History* *\**\ **history\_init**(); *void*\ **history\_end**(*History \*h*); *int*\ **history**(*History \*h*, *HistEvent \*ev*, *int op*, *...*); ## DESCRIPTION The **editline** library provides generic line editing and history functions, similar to those found in [sh(1)](/sh/1.md). These functions are available in the **libedit** library (which needs the **libtermcap** library). Programs should be linked with **-ledit** **-ltermcap**. ## LINE EDITING FUNCTIONS The line editing functions use a common data structure, *EditLine*, which is created by **el\_init**() and freed by **el\_end**(). The following functions are available: - **el\_init**() Initialise the line editor, and return a data structure to be used by all other line editing functions. *prog* is the name of the invoking program, used when reading the [editrc(5)](/editrc/5.md) file to determine which settings to use. *fin*, *fout* and *ferr* are the input, output, and error streams (respectively) to use. In this documentation, references to “the tty” are actually to this input/output stream combination. - **el\_end**() Clean up and finish with *e*, assumed to have been created with **el\_init**(). - **el\_reset**() Reset the tty and the parser. This should be called after an error which may have upset the tty's state. - **el\_gets**() Read a line from the tty. *count* is modified to contain the number of characters read. Returns the line read if successful, or NULL if no characters were read or if an error occurred. - **el\_getc**() Read a character from the tty. *ch* is modified to contain the character read. Returns the number of characters read if successful, -1 otherwise. - **el\_push**() Pushes *str* back onto the input stream. This is used by the macro expansion mechanism. Refer to the description of **bind** **-s** in [editrc(5)](/editrc/5.md) for more information. - **el\_parse**() Parses the *argv* array (which is *argc* elements in size) to execute builtin **editline** commands. If the command is prefixed with “prog:” then **el\_parse**() will only execute the command if “prog” matches the *prog* argument supplied to **el\_init**(). The return value is -1 if the command is unknown, 0 if there was no error or “prog” didn't match, or 1 if the command returned an error. Refer to [editrc(5)](/editrc/5.md) for more information. - **el\_set**() Set **editline** parameters. *op* determines which parameter to set, and each operation has its own parameter list. The following values for *op* are supported, along with the required argument list: - EL\_PROMPT, *char \*(\*f)(EditLine \*)* Define prompt printing function as *f*, which is to return a string that contains the prompt. - EL\_RPROMPT, *char \*(\*f)(EditLine \*)* Define right side prompt printing function as *f*, which is to return a string that contains the prompt. - EL\_TERMINAL, *const char \*type* Define terminal type of the tty to be *type*, or to TERM if *type* is NULL. - EL\_EDITOR, *const char \*mode* Set editing mode to *mode*, which must be one of “emacs” or “vi”. - EL\_SIGNAL, *int flag* If *flag* is non-zero, **editline** will install its 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. - EL\_BIND, *const char \**, *...*, NULL Perform the **bind** builtin command. Refer to [editrc(5)](/editrc/5.md) for more information. - EL\_ECHOTC, *const char \**, *...*, NULL Perform the **echotc** builtin command. Refer to [editrc(5)](/editrc/5.md) for more information. - EL\_SETTC, *const char \**, *...*, NULL Perform the **settc** builtin command. Refer to [editrc(5)](/editrc/5.md) for more information. - EL\_SETTY, *const char \**, *...*, NULL Perform the **setty** builtin command. Refer to [editrc(5)](/editrc/5.md) for more information. - EL\_TELLTC, *const char \**, *...*, NULL Perform the **telltc** builtin command. Refer to [editrc(5)](/editrc/5.md) for more information. - EL\_ADDFN, *const char \*name*, *const char \*help*, *unsigned char (\*func)(EditLine \*e, int ch)* Add a user defined function, **func**(), referred to as *name* which is invoked when a key which is bound to *name* is entered. *help* is a description of *name*. At invocation time, *ch* is the key which caused the invocation. The return value of **func**() should be one of: - CC\_NORM Add a normal character. - CC\_NEWLINE End of line was entered. - CC\_EOF EOF was entered. - CC\_ARGHACK Expecting further command input as arguments, do nothing visually. - CC\_REFRESH Refresh display. - CC\_REFRESH\_BEEP Refresh display, and beep. - CC\_CURSOR Cursor moved, so update and perform CC\_REFRESH. - CC\_REDISPLAY Redisplay entire input line. This is useful if a key binding outputs extra information. - CC\_ERROR An error occurred. Beep, and flush tty. - CC\_FATAL Fatal error, reset tty to known state. - EL\_HIST, *History \*(\*func)(History \*, int op, ...)*, *const char \*ptr* Defines which history function to use, which is usually **history**(). *ptr* should be the value returned by **history\_init**(). - EL\_EDITMODE, *int flag* If *flag* is non-zero, editing is enabled (the default). Note that this is only an indication, and does not affect the operation of . At this time, it is the caller's responsibility to check this (using **el\_get**()) to determine if editing should be enabled or not. - **el\_get**() Get **editline** parameters. *op* determines which parameter to retrieve into *result*. The following values for *op* are supported, along with actual type of *result*: - EL\_PROMPT, *char \*(\*f)(EditLine \*)* Return a pointer to the function that displays the prompt. - EL\_RPROMPT, *char \*(\*f)(EditLine \*)* Return a pointer to the function that displays the rightside prompt. - EL\_EDITOR, *const char \** Return the name of the editor, which will be one of “emacs” or “vi”. - EL\_SIGNAL, *int \** Return non-zero if **editline** has installed private signal handlers (see **el\_get**() above). - EL\_EDITMODE, *int \** Return non-zero if editing is enabled. - **el\_source**() Initialise **editline** by reading the contents of *file*. **el\_parse**() is called for each line in *file*. If *file* is NULL, try *$PWD/.editrc* then *$HOME/.editrc*. Refer to [editrc(5)](/editrc/5.md) for details on the format of *file*. - **el\_resize**() Must be called if the terminal size changes. If EL\_SIGNAL has been set with **el\_set**(), then this is done automatically. Otherwise, it's the responsibility of the application to call **el\_resize**() on the appropriate occasions. - **el\_line**() Return the editing information for the current line in a *LineInfo* structure, which is defined as follows: ``` typedef struct lineinfo { const char *buffer; /* address of buffer */ const char *cursor; /* address of cursor */ const char *lastchar; /* address of last character */ } LineInfo; ``` - **el\_insertstr**() Insert *str* into the line at the cursor. Returns -1 if *str* is empty or won't fit, and 0 otherwise. - **el\_deletestr**() Delete *num* characters before the cursor. ## HISTORY LIST FUNCTIONS The history functions use a common data structure, *History*, which is created by **history\_init**() and freed by **history\_end**(). The following functions are available: - **history\_init**() Initialise the history list, and return a data structure to be used by all other history list functions. - **history\_end**() Clean up and finish with *h*, assumed to have been created with **history\_init**(). - **history**() Perform operation *op* on the history list, with optional arguments as needed by the operation. *ev* is changed accordingly to operation. The following values for *op* are supported, along with the required argument list: - H\_SETSIZE, *int size* Set size of history to *size* elements. - H\_GETSIZE Get number of events currently in history. - H\_END Cleans up and finishes with *h*, assumed to be created with **history\_init**(). - H\_CLEAR Clear the history. - H\_FUNC, *void \*ptr*, *history\_gfun\_t first*, *history\_gfun\_t next*, *history\_gfun\_t last*, *history\_gfun\_t prev*, *history\_gfun\_t curr*, *history\_sfun\_t set*, *history\_vfun\_t clear*, *history\_efun\_t enter*, *history\_efun\_t add* Define functions to perform various history operations. *ptr* is the argument given to a function when it's invoked. - H\_FIRST Return the first element in the history. - H\_LAST Return the last element in the history. - H\_PREV Return the previous element in the history. - H\_NEXT Return the next element in the history. - H\_CURR Return the current element in the history. - H\_SET Set the cursor to point to the requested element. - H\_ADD, *const char \*str* Append *str* to the current element of the history, or create an element with - H\_APPEND, *const char \*str* Append *str* to the last new element of the history. - H\_ENTER, *const char \*str* Add *str* as a new element to the history, and, if necessary, removing the oldest entry to keep the list to the created size. - H\_PREV\_STR, *const char \*str* Return the closest previous event that starts with *str*. - H\_NEXT\_STR, *const char \*str* Return the closest next event that starts with *str*. - H\_PREV\_EVENT, *int e* Return the previous event numbered *e*. - H\_NEXT\_EVENT, *int e* Return the next event numbered *e*. - H\_LOAD, *const char \*file* Load the history list stored in *file*. - H\_SAVE, *const char \*file* Save the history list to *file*. **history**() returns 0 if the operation *op* succeeds. Otherwise, -1 is returned and *ev* is updated to contain more details about the error. ## SEE ALSO [editrc(5)](/editrc/5.md), [sh(1)](/sh/1.md), [signal(3)](/signal/3.md), [termcap(3)](/termcap/3.md) ## HISTORY The **editline** library first appeared in 4.4BSD. CC\_REDISPLAY appeared in NetBSD 1.3. CC\_REFRESH\_BEEP, EL\_EDITMODE and the readline emulation appeared in NetBSD 1.4. EL\_RPROMPT appeared in NetBSD 1.5. ## AUTHORS The **editline** library was written by Christos Zoulas. Luke Mewburn wrote this manual and implemented CC\_REDISPLAY, CC\_REFRESH\_BEEP, EL\_EDITMODE, and EL\_RPROMPT. Jaromir Dolecek implemented the readline emulation. ## BUGS The tokenization functions are not publically defined in **\** At this time, it is the responsibility of the caller to check the result of the EL\_EDITMODE operation of **el\_get**() (after an **el\_source**() or **el\_parse**()) to determine if **editline** should be used for further input. I.e., EL\_EDITMODE is purely an indication of the result of the most recent [editrc(5)](/editrc/5.md) **edit** command.