Completion

Basic word completion. More...

Typedefs
typedef struct ic_completion_env_s	ic_completion_env_t
	A completion environment. More...
typedef void()	ic_completer_fun_t(ic_completion_env_t *cenv, const char *prefix)
	A completion callback that is called by isocline when tab is pressed. More...
typedef bool()	ic_is_char_class_fun_t(const char *s, long len)
	Function that returns whether a (utf8) character (of length len) is in a certain character class. More...

Functions
void	ic_set_default_completer (ic_completer_fun_t *completer, void *arg)
	Set the default completion handler. More...
bool	ic_add_completion (ic_completion_env_t *cenv, const char *completion)
	In a completion callback (usually from ic_complete_word()), use this function to add a completion. More...
bool	ic_add_completion_ex (ic_completion_env_t *cenv, const char *completion, const char *display, const char *help)
	In a completion callback (usually from ic_complete_word()), use this function to add a completion. More...
bool	ic_add_completions (ic_completion_env_t *cenv, const char *prefix, const char **completions)
	In a completion callback (usually from ic_complete_word()), use this function to add completions. More...
void	ic_complete_filename (ic_completion_env_t *cenv, const char *prefix, char dir_separator, const char *roots, const char *extensions)
	Complete a filename. More...
void	ic_complete_word (ic_completion_env_t *cenv, const char *prefix, ic_completer_fun_t *fun, ic_is_char_class_fun_t *is_word_char)
	Complete a word (i.e. More...
void	ic_complete_qword (ic_completion_env_t *cenv, const char *prefix, ic_completer_fun_t *fun, ic_is_char_class_fun_t *is_word_char)
	Complete a quoted word. More...
void	ic_complete_qword_ex (ic_completion_env_t *cenv, const char *prefix, ic_completer_fun_t fun, ic_is_char_class_fun_t *is_word_char, char escape_char, const char *quote_chars)
	Complete a word. More...

Detailed Description

Basic word completion.

Typedef Documentation

ic_completer_fun_t

typedef void() ic_completer_fun_t(ic_completion_env_t *cenv, const char *prefix)

A completion callback that is called by isocline when tab is pressed.

It is passed a completion environment (containing the current input and the current cursor position), the current input up-to the cursor (prefix) and the user given argument when the callback was set. When using completion transformers, like ic_complete_quoted_word the prefix contains the the word to be completed without escape characters or quotes.

ic_completion_env_t

typedef struct ic_completion_env_s ic_completion_env_t

A completion environment.

ic_is_char_class_fun_t

typedef bool() ic_is_char_class_fun_t(const char *s, long len)

Function that returns whether a (utf8) character (of length len) is in a certain character class.

See also

ic_char_is_separator() etc.

Function Documentation

ic_add_completion()

bool ic_add_completion	(	ic_completion_env_t *	cenv,
		const char *	completion
	)

In a completion callback (usually from ic_complete_word()), use this function to add a completion.

(the completion string is copied by isocline and do not need to be preserved or allocated).

Returns true if the callback should continue trying to find more possible completions. If false is returned, the callback should try to return and not add more completions (for improved latency).

ic_add_completion_ex()

bool ic_add_completion_ex	(	ic_completion_env_t *	cenv,
		const char *	completion,
		const char *	display,
		const char *	help
	)

In a completion callback (usually from ic_complete_word()), use this function to add a completion.

The display is used to display the completion in the completion menu, and help is displayed for hints for example. Both can be NULL for the default. (all are copied by isocline and do not need to be preserved or allocated).

Returns true if the callback should continue trying to find more possible completions. If false is returned, the callback should try to return and not add more completions (for improved latency).

ic_add_completions()

bool ic_add_completions	(	ic_completion_env_t *	cenv,
		const char *	prefix,
		const char **	completions
	)

In a completion callback (usually from ic_complete_word()), use this function to add completions.

The completions array should be terminated with a NULL element, and all elements are added as completions if they start with prefix.

Returns true if the callback should continue trying to find more possible completions. If false is returned, the callback should try to return and not add more completions (for improved latency).

ic_complete_filename()

void ic_complete_filename	(	ic_completion_env_t *	cenv,
		const char *	prefix,
		char	dir_separator,
		const char *	roots,
		const char *	extensions
	)

Complete a filename.

Complete a filename given a semi-colon separated list of root directories roots and semi-colon separated list of possible extensions (excluding directories). If roots is NULL, the current directory is the root ("."). If extensions is NULL, any extension will match. Each root directory should not end with a directory separator. If a directory is completed, the dir_separator is added at the end if it is not 0. Usually the dir_separator is / but it can be set to \\ on Windows systems. For example:

/ho         --> /home/
/home/.ba   --> /home/.bashrc

(This already uses ic_complete_quoted_word() so do not call it from inside a word handler).

ic_complete_qword()

void ic_complete_qword	(	ic_completion_env_t *	cenv,
		const char *	prefix,
		ic_completer_fun_t *	fun,
		ic_is_char_class_fun_t *	is_word_char
	)

Complete a quoted word.

Calls the user provided function fun to complete while taking care of quotes and escape characters. Almost all user provided completers should use this function. The prefix passed to fun is modified to be unquoted and unescaped, and any results from ic_add_completion are automatically quoted and escaped again. For example, completing hello world, the fun always just completes hel or hello w to hello world, but depending on user input, it will complete as:

hel        -->  hello\ world
hello\ w   -->  hello\ world
hello w    -->                   # no completion, the word is just 'w'>
"hel       -->  "hello world" 
"hello w   -->  "hello world"

with proper quotes and escapes. If is_word_char is NULL, the default &ic_char_is_nonseparator is used.

See also

ic_complete_quoted_word() to customize the word boundary, quotes etc.

ic_complete_qword_ex()

void ic_complete_qword_ex	(	ic_completion_env_t *	cenv,
		const char *	prefix,
		ic_completer_fun_t	fun,
		ic_is_char_class_fun_t *	is_word_char,
		char	escape_char,
		const char *	quote_chars
	)

Complete a word.

Calls the user provided function fun to complete while taking care of quotes and escape characters. Almost all user provided completers should use this function. The is_word_char is a set of characters that are part of a "word". Use NULL for the default (&ic_char_is_nonseparator). The escape_char is the escaping character, usually \ but use 0 to not have escape characters. The quote_chars define the quotes, use NULL for the default ‘"\’\""quotes. @see ic_complete_word() which uses the default values fornon_word_chars,quote_charsand` for escape characters.

ic_complete_word()

void ic_complete_word	(	ic_completion_env_t *	cenv,
		const char *	prefix,
		ic_completer_fun_t *	fun,
		ic_is_char_class_fun_t *	is_word_char
	)

Complete a word (i.e.

token). Calls the user provided function fun to complete on the current word. Almost all user provided completers should use this function. If is_word_char is NULL, the default &ic_char_is_nonseparator is used. The prefix passed to fun is modified to only contain the current word, and any results from ic_add_completion are automatically adjusted to replace that part. For example, on the input "hello w", a the user fun only gets w and can just complete with "world" resulting in "hello world" without needing to consider delete_before etc.

See also

ic_complete_qword() for completing quoted and escaped tokens.

ic_set_default_completer()

void ic_set_default_completer	(	ic_completer_fun_t *	completer,
		void *	arg
	)

Set the default completion handler.

Parameters

completer	The completion function
arg	Argument passed to the completer. There can only be one default completion function, setting it again disables the previous one. The initial completer use ic_complete_filename.