interactive.h File Reference

Detailed Description

Interactive sessions based on the GNU readline library.

This API is used by para_client(1), para_audioc(1) and para_play(1). The API is twofold: The first part consists of structures and functions which implement interactive line editing. The second part implements programmable completion. All functions declared here are defined in interactive.c. All function and structure names start with "i9e", which is short for "interactive".

To start an interactive editing session, programs define and initialize an instance of struct i9e_client_info and pass a pointer to this instance to i9e_open() in order to register the interactive task to the scheduler. These users set the poll function of the scheduler to i9e_poll() and employ i9e_log() as the log function.

The completion functions are run when para_client(1) or para_audioc(1) are started in completion mode, or when the tab key is pressed during an interactive session.

Functions
int	i9e_open (struct i9e_client_info *ici, struct sched *s)
void	i9e_attach_to_stdout (struct btr_node *producer)
void	i9e_print_status_bar (char *buf, unsigned len)
void	i9e_close (void)
void	i9e_signal_dispatch (int sig_num)
__printf_2_3 void	i9e_log (int ll, const char *fmt,...)
int	i9e_poll (struct pollfd *fds, nfds_t nfds, int timeout)
int	i9e_extract_completions (const char *word, char *const *string_list, char ***result)
char **	i9e_complete_commands (const char *word, const struct i9e_completer *completers)
void	i9e_complete_option (char *const *opts, struct i9e_completion_info *ci, struct i9e_completion_result *cr)
unsigned	i9e_get_nonopt_argnum (char *const *opts, struct i9e_completion_info *ci)
int	i9e_cword_is_option_arg (char *const *opts, struct i9e_completion_info *ci)
int	i9e_print_completions (const struct i9e_completer *completers)
int	i9e_get_error (void)
void	i9e_ll_completer (struct i9e_completion_info *ci, struct i9e_completion_result *cr)

Data Structures
struct	i9e_completion_info
struct	i9e_completion_result
struct	i9e_completer
struct	i9e_client_info

Macros
#define	I9E_DUMMY_COMPLETER(name)

Function Documentation

i9e_open()

int i9e_open	(	struct i9e_client_info *	ici,
		struct sched *	s
	)

Register the i9e task and initialize readline.

Parameters

ici	The i9e configuration parameters set by the caller.
s	The scheduler instance to add the i9e task to.

The i9e client info structure must be allocated and initialized by the caller before this function is called.

Returns

Standard.

i9e_attach_to_stdout()

void i9e_attach_to_stdout

(

struct btr_node *

producer

)

Prepare writing to stdout.

Parameters

producer

The buffer tree node which produces output.

The i9e subsystem maintains a buffer tree node which may be attached to another node which generates output (a "producer"). When attached, the i9e buffer tree node copies the buffers generated by the producer to stdout. This function attaches the i9e input queue to an output queue of producer.

i9e_print_status_bar()

void i9e_print_status_bar	(	char *	buf,
		unsigned	len
	)

Print the current status to stderr.

Parameters

buf	The text to print.
len	The number of bytes in the buffer.

This clears the bottom line, moves to the beginning of the line and prints the given text. If the length of this text exceeds the width of the terminal, the text is shortened by leaving out a part in the middle.

i9e_close()

void i9e_close

(

void

)

Reset the terminal and save the in-memory command line history.

This should be called before the caller exits.

i9e_signal_dispatch()

void i9e_signal_dispatch

(

int

sig_num

)

Tell i9e that the caller received a signal.

Parameters

sig_num

The number of the signal received.

i9e_log()

__printf_2_3 void i9e_log	(	int	ll,
		const char *	fmt,
			...
	)

The log function of the i9e subsystem.

Parameters

ll	Severity log level.
fmt	Printf-like format string.

This clears the bottom line of the terminal if necessary and writes the formatted string to fd[2], where fd[] is the array provided earlier in i9e_open().

i9e_poll()

int i9e_poll	(	struct pollfd *	fds,
		nfds_t	nfds,
		int	timeout
	)

Wrapper for poll(2) which handles EINTR and returns paraslash error codes.

Parameters

fds	See poll(2).
nfds	See poll(2).
timeout	See poll(2).

Returns

See poll(2).

The only difference between this function and xpoll() is that i9e_poll() returns zero if the system call was interrupted while xpoll() restarts the system call in this case.

i9e_extract_completions()

int i9e_extract_completions	(	const char *	word,
		char *const *	string_list,
		char ***	result
	)

Return the possible completions for a given word.

Parameters

word	The word to complete.
string_list	All possible words in this context.
result	String list is returned here.

This function never fails. If no completion was found, a string list of length zero is returned. In any case, the result must be freed by the caller using free_argv().

This function is independent of readline and may be called before i9e_open().

Returns

The number of possible completions.

Referenced by i9e_complete_option(), and i9e_ll_completer().

i9e_complete_commands()

char** i9e_complete_commands	(	const char *	word,
		const struct i9e_completer *	completers
	)

Return the list of partially matching words.

Parameters

word	The command to complete.
completers	The array containing all command names.

This is similar to i9e_extract_completions(), but completes on the command names in the completers array.

Returns

See i9e_extract_completions().

i9e_complete_option()

void i9e_complete_option	(	char *const *	opts,
		struct i9e_completion_info *	ci,
		struct i9e_completion_result *	cr
	)

Complete according to the given options.

Parameters

opts	All available options.
ci	Information which was passed to the completer.
cr	Result pointer.

This helper returns the possible tab-completions of an option. The array of all possible options is passed as the first argument. Flags, i.e. options without an argument, are expected as strings such as "-X" while options which require an argument are expected to be of the form "-X=", i.e., contain a trailing "=".

If the word can be uniquely completed to a flag option, an additional space character is appended to the output. For non-flag options no space character is appended.

i9e_get_nonopt_argnum()

unsigned i9e_get_nonopt_argnum	(	char *const *	opts,
		struct i9e_completion_info *	ci
	)

Return the number of non-option arguments encountered so far.

This counts the number of arguments up to the current word which are neither options nor arguments to options.

Parameters

opts	NULL terminated array of short and long options, may be NULL.
ci	Provided by i9e in completion context.

For convenience, NULL can be passed as the option array pointer to indicate that the subcommand has no options. In this case the function returns the word number stored in the completion info structure.

Returns

Zero means that the cursor is positioned at the first non-option argument.

i9e_cword_is_option_arg()

int i9e_cword_is_option_arg	(	char *const *	opts,
		struct i9e_completion_info *	ci
	)

Find out whether the current word is an argument to an option.

This handles both the –opt=arg and –opt arg syntax to specify option arguments.

Parameters

opts	NULL-terminated array of short and long options.
ci	Provided by i9e in completion context.

Returns

If the current word is an option argument, the function returns the index into the option array which corresponds to the matching option. Otherwise, -1 is returned.

i9e_print_completions()

int i9e_print_completions

(

const struct i9e_completer *

completers

)

Print possible completions to stdout.

Parameters

completers

The array of completion functions.

At the end of the output a line starting with "-o=", followed by the (possibly empty) list of completion options is printed. Currently, the only two completion options are "nospace" and "filenames". The former indicates that no space should be appended even for a unique match while the latter indicates that usual filename completion should be performed in addition to the previously printed options.

Returns

Standard.

i9e_get_error()

int i9e_get_error

(

void

)

Return the error state of the i9e task.

This is mainly useful for other tasks to tell whether the i9e task is still running.

Returns

A negative return value of zero means the i9e task terminated. Only in this case it is safe to call i9e_close().

i9e_ll_completer()

void i9e_ll_completer	(	struct i9e_completion_info *	ci,
		struct i9e_completion_result *	cr
	)

Complete on severity strings.

Parameters

ci	See struct i9e_completer.
cr	See struct i9e_completer.

This is used by para_client and para_audioc which need the same completion primitive for the ll server/audiod command. Both define their own completer which is implemented as a trivial wrapper that calls this function.

Macro Definition Documentation

I9E_DUMMY_COMPLETER

#define I9E_DUMMY_COMPLETER

(

name

)

Define a completer which does nothing.

Parameters

name	Determines the name of the function to be defined.