Line Editor. More...

Collaboration diagram for EdLine Editor:

Data Structures
struct	_EDITHISTORY
	Line input history. More...
struct	_EDLINE
	Edit line information structure. More...
Defines
#define	EDIT_MAX_HISTORY 16
	Maximum number of history entries.
Typedefs
typedef struct _EDITHISTORY	EDITHISTORY
	Line input history.
typedef int(*	EDLINEGET )(void *)
	Input routine type.
typedef int(*	EDLINEPUT )(void *, int)
	Output routine type.
typedef int(*	EDLINEMAP )(int, int *)
	Character mapping routine type.
typedef struct _EDLINE	EDLINE
	Edit line information structure.
Functions
void	EdLineRegisterInput (EDLINE el, EDLINEGET get, void param)
	Register an input routine.
void	EdLineRegisterOutput (EDLINE el, EDLINEPUT put, void param)
	Register an output routine.
int	EdLineKeyMap (int key, int *seq)
	Default key mapping routine.
void	EdLineRegisterKeymap (EDLINE *el, EDLINEMAP map)
	Register a key mapping routine.
EDLINE *	EdLineOpen (uint16_t mode)
	Open a line editor.
void	EdLineClose (EDLINE *el)
	Close a line editor.
int	EdLineRead (EDLINE el, char buf, int siz)
	Read a line.
EDITHISTORY *	EditHistoryCreate (int siz)
	Create an editor history table.
void	EditHistoryDestroy (EDITHISTORY *hist)
	Create an editor history table.
void	EditHistorySet (EDITHISTORY hist, int idx, char buf)
	Replace the specified history table entry.
int	EditHistoryGet (EDITHISTORY hist, int idx, char buf, int siz)
	Retrieve the specified history table entry.
void	EditHistoryInsert (EDITHISTORY hist, int idx, char buf)
	Insert a new history table entry at the specified position.
int	EdLineKeyMapVt100 (int key, int *seq)
	Optional VT100 key mapping routine.
Edit mode flags
Used when calling EdLineOpen to enable specific line editor features.
#define	EDIT_MODE_ECHO 0x0001
	Enables echoing of input characters.
#define	EDIT_MODE_BINARY 0x0002
	Enables binary mode (currently unused).
#define	EDIT_MODE_HISTORY 0x0004
	Enables input line history.
Line editor input commands
Special keys which are interpreted by the editor as commands.
#define	EDIT_KEY_IGNORE 0x00
	No operation. Default is Ctrl-@.
#define	EDIT_KEY_HOME 0x01
	Move cursor to line begin. Default is Ctrl-A.
#define	EDIT_KEY_LEFT 0x02
	Move cursor left. Default is Ctrl-B.
#define	EDIT_KEY_END 0x05
	Move cursor to line end. Default is Ctrl-E.
#define	EDIT_KEY_RIGHT 0x06
	Move cursor right. Default is Ctrl-F.
#define	EDIT_KEY_REMOVE 0x08
	Delete left character. Default is Ctrl-H.
#define	EDIT_KEY_ENTER 0x0a
	Confirm input. Default is Ctrl-J.
#define	EDIT_KEY_UP 0x12
	History upwards. Default is Ctrl-R.
#define	EDIT_KEY_DOWN 0x16
	History downwards. Default is Ctrl-V.
#define	EDIT_KEY_RESTORE 0x1b
	Restore default. Default is ESC.
Line editor output commands
Special characters used by the editor to update the output.
#define	EDIT_CHAR_SPACE ' '
	Clear character right.
#define	EDIT_CHAR_BACKSPACE '\b'
	Move cursor left.
#define	EDIT_CHAR_ALARM '\a'
	Invoke audible alarm.
#define	EDIT_STR_EOL "\r\n"
	Terminate input.

Detailed Description

Line Editor.

Define Documentation

#define EDIT_MODE_ECHO 0x0001

Enables echoing of input characters.

Examples:: caltime/caltime.c.

Referenced by EdLineRead(), LuaThread(), and main().

#define EDIT_MODE_BINARY 0x0002

Enables binary mode (currently unused).

#define EDIT_MODE_HISTORY 0x0004

Enables input line history.

Referenced by EdLineOpen(), EdLineRead(), and LuaThread().

#define EDIT_KEY_IGNORE 0x00

No operation. Default is Ctrl-@.

Referenced by EdLineKeyMap(), and EdLineKeyMapVt100().

#define EDIT_KEY_HOME 0x01

Move cursor to line begin. Default is Ctrl-A.

Referenced by EdLineRead().

#define EDIT_KEY_LEFT 0x02

Move cursor left. Default is Ctrl-B.

Referenced by EdLineKeyMapVt100(), and EdLineRead().

#define EDIT_KEY_END 0x05

Move cursor to line end. Default is Ctrl-E.

Referenced by EdLineRead().

#define EDIT_KEY_RIGHT 0x06

Move cursor right. Default is Ctrl-F.

Referenced by EdLineKeyMapVt100(), and EdLineRead().

#define EDIT_KEY_REMOVE 0x08

Delete left character. Default is Ctrl-H.

Referenced by EdLineRead().

#define EDIT_KEY_ENTER 0x0a

Confirm input. Default is Ctrl-J.

Referenced by EdLineKeyMap(), and EdLineRead().

#define EDIT_KEY_UP 0x12

History upwards. Default is Ctrl-R.

Referenced by EdLineKeyMapVt100(), and EdLineRead().

#define EDIT_KEY_DOWN 0x16

History downwards. Default is Ctrl-V.

Referenced by EdLineKeyMapVt100(), and EdLineRead().

#define EDIT_KEY_RESTORE 0x1b

Restore default. Default is ESC.

Referenced by EdLineRead().

#define EDIT_CHAR_SPACE ' '

Clear character right.

Referenced by EdLineRead().

#define EDIT_CHAR_BACKSPACE '\b'

Move cursor left.

Referenced by EdLineRead().

#define EDIT_CHAR_ALARM '\a'

Invoke audible alarm.

Referenced by EdLineRead().

#define EDIT_STR_EOL "\r\n"

Terminate input.

Referenced by EdLineRead().

#define EDIT_MAX_HISTORY 16

Maximum number of history entries.

The first entry with index 0 is used to restore the default value.

Referenced by EdLineOpen().

Typedef Documentation

typedef struct _EDITHISTORY EDITHISTORY

Line input history.

typedef int(* EDLINEGET)(void *)

Input routine type.

typedef int(* EDLINEPUT)(void *, int)

Output routine type.

typedef int(* EDLINEMAP)(int, int *)

Character mapping routine type.

typedef struct _EDLINE EDLINE

Edit line information structure.

Function Documentation

void EdLineRegisterInput	(	EDLINE *	el,
		EDLINEGET	get,
		void *	param
	)

Register an input routine.

Applications may use this function to replace the default character input routine.

Parameters:

el	Pointer to an EDLINE structure, obtained by a previous call to EdLineOpen.
get	Pointer to the new input routine. If NULL, then the default routine is restored.
param	Optional parameter, which is passed to the input routine.

References _EDLINE::el_get, and _EDLINE::el_iparm.

Referenced by EdLineOpen().

void EdLineRegisterOutput	(	EDLINE *	el,
		EDLINEPUT	put,
		void *	param
	)

Register an output routine.

Applications may use this function to replace the default character output routine.

Parameters:

el	Pointer to an EDLINE structure, obtained by a previous call to EdLineOpen.
put	Pointer to the new output routine. If NULL, then the default routine is restored.
param	Optional parameter, which is passed to the output routine.

References _EDLINE::el_oparm, and _EDLINE::el_put.

Referenced by EdLineOpen().

int EdLineKeyMap	(	int	key,
		int *	seq
	)

Default key mapping routine.

Replaces carriage returns and linefeeds by EDIT_KEY_ENTER. Linefeeds immediately following carriage returns are ignored. May be replaced by calling EdLineRegisterKeymap().

This routine may be called by other key mapping routines.

Parameters:

key	Input character to remap.
seq	Pointer to an integer, which is used by the key mapping routine to store the current state. Note, that its value must be preserved by the caller between calls to EdLineRead.

Returns:: The mapped character. If EDIT_KEY_IGNORE is returned the caller must ignore this character.

References EDIT_KEY_ENTER, and EDIT_KEY_IGNORE.

Referenced by EdLineKeyMapVt100(), and EdLineRegisterKeymap().

void EdLineRegisterKeymap	(	EDLINE *	el,
		EDLINEMAP	map
	)

Register a key mapping routine.

Parameters:

el	Pointer to an EDLINE structure, obtained by a previous call to EdLineOpen.
map	Pointer to the new mapping routine. If NULL, then the default routine is restored.

References EdLineKeyMap(), and _EDLINE::el_map.

Referenced by EdLineOpen(), and LuaThread().

Here is the call graph for this function:

EDLINE* EdLineOpen ( uint16_t mode )

Open a line editor.

Parameters:

mode	Mode flags, may contain any combination of EDIT_MODE_ECHO enables echoing of input characters. EDIT_MODE_BINARY enables binary mode (currently unused). EDIT_MODE_HISTORY enables input line history.

Returns:: Pointer to a new EDLINE structure.

References calloc, EDIT_MAX_HISTORY, EDIT_MODE_HISTORY, EditHistoryCreate(), EdLineRegisterInput(), EdLineRegisterKeymap(), EdLineRegisterOutput(), _EDLINE::el_hist, _EDLINE::el_mode, NULL, stdin, and stdout.

Referenced by LuaThread(), and main().

Here is the call graph for this function:

void EdLineClose ( EDLINE * el )

Close a line editor.

Releases all occupied memory.

Parameters:

el	Pointer to an EDLINE structure, obtained by a previous call to EdLineOpen.

References EditHistoryDestroy(), _EDLINE::el_hist, and free().

Referenced by LuaThread().

Here is the call graph for this function:

int EdLineRead	(	EDLINE *	el,
		char *	buf,
		int	siz
	)

Read a line.

This functions offers some editing capabilities and is typically used for text input by human users.

Line editing can be done by entering any of the following control characters:

EDIT_KEY_RESTORE Restores initial default line (default ESC)
EDIT_KEY_REMOVE Deletes character on the left of the cursor (default CTRL-H)
EDIT_KEY_HOME Moves cursor to the beginning of the line (default Ctrl-A).
EDIT_KEY_END Moves cursor to the beginning of the line (default CTRL-E)
EDIT_KEY_LEFT Moves cursor one character to the left (default CTRL-B)
EDIT_KEY_RIGHT Moves cursor one character to the right (default CTRL-F)
EDIT_KEY_UP Walks up the list of previously entered lines (default CTRL-R)
EDIT_KEY_DOWN Walks down the list of previously entered lines (default CTRL-V)

Note, that these commands may be modified by the currently registered remapping routine.

Parameters:

el	Pointer to an EDLINE structure, obtained by a previous call to EdLineOpen.
buf	Pointer to the buffer that receives the text line. If it contains a string on entry, this will be used as the default value.
siz	Number of bytes available in the buffer. The maximum length of the text string is 1 less, so the string is always properly terminated.

Returns:: Number of characters or -1 on errors.

Todo:: Hidden entry for password input.

References EDIT_CHAR_ALARM, EDIT_CHAR_BACKSPACE, EDIT_CHAR_SPACE, EDIT_KEY_DOWN, EDIT_KEY_END, EDIT_KEY_ENTER, EDIT_KEY_HOME, EDIT_KEY_LEFT, EDIT_KEY_REMOVE, EDIT_KEY_RESTORE, EDIT_KEY_RIGHT, EDIT_KEY_UP, EDIT_MODE_ECHO, EDIT_MODE_HISTORY, EDIT_STR_EOL, EditHistoryGet(), EditHistoryInsert(), EditHistorySet(), _EDLINE::el_get, _EDLINE::el_hist, _EDLINE::el_iparm, _EDLINE::el_map, _EDLINE::el_mode, _EDLINE::el_oparm, _EDLINE::el_put, _EDLINE::el_seq, EOF, NULL, and strlen().

Here is the call graph for this function:

EDITHISTORY* EditHistoryCreate ( int siz )

Create an editor history table.

Parameters:

siz	Maximum number of history entries.

Returns:: Pointer to an EDITHISTORY structure on success. A NULL pointer is returned in case of an error.

References calloc, free(), _EDITHISTORY::hist_siz, _EDITHISTORY::hist_tab, malloc(), and NULL.

Referenced by EdLineOpen().

Here is the call graph for this function:

void EditHistoryDestroy ( EDITHISTORY * hist )

Create an editor history table.

Releases occupied memory.

Parameters:

hist	Pointer to an EDITHISTORY structure, obtained by a previous call to EditHistoryCreate.

References free(), _EDITHISTORY::hist_siz, and _EDITHISTORY::hist_tab.

Referenced by EdLineClose().

Here is the call graph for this function:

void EditHistorySet	(	EDITHISTORY *	hist,
		int	idx,
		char *	buf
	)

Replace the specified history table entry.

Parameters:

idx	Index in to the history table.
buf	Pointer to the string that will replace the existing one.
hist	Pointer to an EDITHISTORY structure, obtained by a previous call to EditHistoryCreate.

References free(), _EDITHISTORY::hist_tab, NULL, and strdup().

Referenced by EdLineRead().

Here is the call graph for this function:

int EditHistoryGet	(	EDITHISTORY *	hist,
		int	idx,
		char *	buf,
		int	siz
	)

Retrieve the specified history table entry.

Parameters:

idx	Index in to the history table.
hist	Pointer to an EDITHISTORY structure, obtained by a previous call to EditHistoryCreate.

References _EDITHISTORY::hist_tab, memcpy(), rc, and strlen().

Referenced by EdLineRead().

Here is the call graph for this function:

void EditHistoryInsert	(	EDITHISTORY *	hist,
		int	idx,
		char *	buf
	)

Insert a new history table entry at the specified position.

All following entries are moved up by 1. If the table is full, then the top most entry will be removed.

Parameters:

idx	Index in to the history table.
buf	Pointer to the new string. If it doesn't differ from the existing entry, than nothing will be changed.
hist	Pointer to an EDITHISTORY structure, obtained by a previous call to EditHistoryCreate.

References free(), _EDITHISTORY::hist_siz, _EDITHISTORY::hist_tab, strcmp(), and strdup().

Referenced by EdLineRead().

Here is the call graph for this function:

int EdLineKeyMapVt100	(	int	key,
		int *	seq
	)

Optional VT100 key mapping routine.

Pass this function to EdLineRegisterKeymap to enable VT100 key mapping.

This routine has been tested with the TeraTerm terminal emulator after loading the keymap contained in ibmkeyb.cnf. It allows to use the arrow keys for moving the cursor and walking through the history. This should work with most other VT100 emulations as well.

The following command sequences are remapped:

ESC [ A remapped to EDIT_KEY_UP.
ESC [ B remapped to EDIT_KEY_DOWN.
ESC [ C remapped to EDIT_KEY_RIGHT.
ESC [ D remapped to EDIT_KEY_LEFT.

Internally calls EdLineKeyMap to handle carriage return and linefeed.

Parameters:

key	Input character to remap.
seq	Pointer to an integer, which is used by the key mapping routine to store the current state. Note, that its value must be preserved by the caller between calls to EdLineRead.

Returns:: The mapped character. If EDIT_KEY_IGNORE is returned the caller must ignore this character.

References EDIT_KEY_DOWN, EDIT_KEY_IGNORE, EDIT_KEY_LEFT, EDIT_KEY_RIGHT, EDIT_KEY_UP, and EdLineKeyMap().

Referenced by LuaThread().

Here is the call graph for this function:

Data Structures

Defines

Typedefs

Functions

Edit mode flags

Line editor input commands

Line editor output commands

Detailed Description

Define Documentation

Typedef Documentation

Function Documentation