complete.h File Reference

Prototypes for functions related to tab-completion. More...

#include <wchar.h>
#include "util.h"

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures

struct completion_t

Defines

#define SHARED   0

Header guard.

#define NO_FILES   1

Do not use file completion.

#define NO_COMMON   2

Require a parameter after completion.

#define EXCLUSIVE   3

Only use the argument list specifies with completion after option.

#define PATH   1

Command is a path.

#define COMMAND   0

Command is not a path.

#define COMPLETE_SEP   L'\004'

Separator between completion and description.

#define COMPLETE_SEP_STR   L"\004"

Separator between completion and description.

#define COMPLETE_ITEM_SEP   L'\uf500'

Separator between completion items in fish_pager.

#define PROG_COMPLETE_SEP   L'\t'

Character that separates the completion and description on programmable completions.

#define COMPLETE_NO_SPACE   1

Do not insert space afterwards if this is the only completion.

#define COMPLETE_NO_CASE   2

This compeltion is case insensitive.

#define COMPLETE_WHOLE_ARGUMENT   4

This compeltion is the whole argument, not just the remainder.

#define COMPLETE_AUTO_SPACE   8

This completion may or may not want a space at the end - guess by checking the last character of the completion.

#define COMPLETE_DONT_ESCAPE   16

This completion should be inserted as-is, without escaping.

Functions

void complete_add (const wchar_t *cmd, int cmd_type, wchar_t short_opt, const wchar_t *long_opt, int long_mode, int result_mode, const wchar_t *condition, const wchar_t *comp, const wchar_t *desc, int flags)

Add a completion.

void complete_set_authoritative (const wchar_t *cmd, int cmd_type, int authoritative)

Sets whether the completion list for this command is complete.

void complete_remove (const wchar_t *cmd, int cmd_type, wchar_t short_opt, const wchar_t *long_opt)

Remove a previously defined completion.

void complete (const wchar_t *cmd, array_list_t *out)

Find all completions of the command cmd, insert them into out.

void complete_print (string_buffer_t *out)

Print a list of all current completions into the string_buffer_t.

int complete_is_valid_option (const wchar_t *str, const wchar_t *opt, array_list_t *errors)

Tests if the specified option is defined for the specified command.

int complete_is_valid_argument (const wchar_t *str, const wchar_t *opt, const wchar_t *arg)

Tests if the specified argument is valid for the specified option and command.

void complete_load (const wchar_t *cmd, int reload)

Load command-specific completions for the specified command.

void completion_allocate (array_list_t *context, const wchar_t *comp, const wchar_t *desc, int flags)

Create a new completion entry.

Detailed Description

Prototypes for functions related to tab-completion.

These functions are used for storing and retrieving tab-completion data, as well as for performing tab-completion.

Define Documentation

#define COMPLETE_ITEM_SEP L'\uf500'

Separator between completion items in fish_pager.

This is used for completion grouping, e.g. when putting completions with the same descriptions on the same line.

#define COMPLETE_NO_CASE 2

This compeltion is case insensitive.

Warning: The contents of the completion_t structure is actually different if this flag is set! Specifically, the completion string contains the _entire_ completion token, not only the current

Referenced by builtin_complete(), complete_cmd(), complete_param(), complete_variable(), completion_insert(), handle_completions(), run_pager(), try_complete_user(), wildcard_complete_internal(), and wildcard_expand().

#define COMPLETE_NO_SPACE 1

Do not insert space afterwards if this is the only completion.

(The default is to try insert a space)

Referenced by completion_allocate(), completion_insert(), handle_completions(), try_complete_user(), and wildcard_completion_allocate().

#define COMPLETE_WHOLE_ARGUMENT 4

This compeltion is the whole argument, not just the remainder.

This flag must never be set on completions returned from the complete() function. It is strictly for internal use in the completion code.

#define EXCLUSIVE 3

Only use the argument list specifies with completion after option.

This is the same as (NO_FILES & NO_COMMON)

Referenced by builtin_complete().

#define SHARED 0

Header guard.

Use all completions

Referenced by builtin_complete().

Function Documentation

void complete	(	const wchar_t *	cmd,
		array_list_t *	out
	)

Find all completions of the command cmd, insert them into out.

The caller must free the variables returned in out. The results are returned in the array_list_t 'out', in the format of wide character strings, with each element consisting of a suggested completion and a description of what kind of object this completion represents, separated by a separator of type COMPLETE_SEP.

Values returned by this function should be freed by the caller.

If we are completing a variable name or a tilde expansion user name, we do that and return. No need for any other competions.

References al_get_count(), buff, CHECK, complete_cmd(), complete_init(), complete_param(), complete_param_expand(), condition_cache_clear(), end_loop, parse_util_cmdsubst_extent(), parse_util_token_extent(), parser_keywords_is_subcommand(), TOK_ACCEPT_UNFINISHED, TOK_BACKGROUND, tok_destroy(), TOK_END, TOK_ERROR, tok_get_pos(), tok_has_next(), tok_init(), tok_last(), tok_last_type(), tok_next(), TOK_PIPE, TOK_STRING, try_complete_user(), try_complete_variable(), unescape(), and UNESCAPE_INCOMPLETE.

Referenced by builtin_complete(), builtin_read(), perf_complete(), and read_i().

void complete_add	(	const wchar_t *	cmd,
		int	cmd_type,
		wchar_t	short_opt,
		const wchar_t *	long_opt,
		int	long_mode,
		int	result_mode,
		const wchar_t *	condition,
		const wchar_t *	comp,
		const wchar_t *	desc,
		int	flags
	)

Add a completion.

All supplied values are copied, they should be freed by or otherwise disposed by the caller.

Examples:

The command 'gcc -o' requires that a file follows it, so the NO_COMMON option is suitable. This can be done using the following line:

complete -c gcc -s o -r

The command 'grep -d' required that one of the strings 'read', 'skip' or 'recurse' is used. As such, it is suitable to specify that a completion requires one of them. This can be done using the following line:

complete -c grep -s d -x -a "read skip recurse"

Parameters:

	cmd	Command to complete.
	cmd_type	If cmd_type is PATH, cmd will be interpreted as the absolute path of the program (optionally containing wildcards), otherwise it will be interpreted as the command name.
	short_opt	The single character name of an option. (-a is a short option, --all and -funroll are long options)
	long_opt	The multi character name of an option. (-a is a short option, --all and -funroll are long options)
	long_mode	Whether to use old style, single dash long options.
	result_mode	Whether to search further completions when this completion has been succesfully matched. If result_mode is SHARED, any other completions may also be used. If result_mode is NO_FILES, file completion should not be used, but other completions may be used. If result_mode is NO_COMMON, on option may follow it - only a parameter. If result_mode is EXCLUSIVE, no option may follow it, and file completion is not performed.
	comp	A space separated list of completions which may contain subshells.
	desc	A description of the completion.
	condition	a command to be run to check it this completion should be used. If `condition` is empty, the completion is always used.
	flags	A set of completion flags

References CHECK, complete_entry_opt::comp, complete_get_exact_entry(), complete_entry_opt::condition, complete_entry_opt::desc, complete_entry::first_option, complete_entry_opt::flags, halloc(), halloc_wcsdup(), complete_entry_opt::long_opt, complete_entry_opt::next, NO_COMMON, complete_entry_opt::old_mode, complete_entry_opt::result_mode, complete_entry_opt::short_opt, and complete_entry::short_opt_str.

Referenced by builtin_complete_add2().

void complete_load	(	const wchar_t *	cmd,
		int	reload
	)

Load command-specific completions for the specified command.

This is done automatically whenever completing any given command, so there is no need to call this except in the case of completions with internal dependencies.

Parameters:

	cmd	the command for which to load command-specific completions
	reload	should the commands completions be reloaded, even if they where previously loaded. (This is set to true on actual completions, so that changed completion are updated in running shells)

References CHECK, complete_load_handler(), and parse_util_load().

Referenced by complete_is_valid_option(), and complete_param().

void complete_print ( string_buffer_t * out )

Print a list of all current completions into the string_buffer_t.

Parameters:

out

The string_buffer_t to write completions to

References append_switch(), C_, CHECK, complete_entry::cmd, complete_entry::cmd_type, complete_entry_opt::comp, complete_entry_opt::condition, complete_entry_opt::desc, complete_entry::first_option, complete_entry_opt::long_opt, complete_entry_opt::next, complete_entry::next, complete_entry_opt::old_mode, complete_entry_opt::result_mode, sb_printf(), and complete_entry_opt::short_opt.

Referenced by builtin_complete().

void complete_set_authoritative	(	const wchar_t *	cmd,
		int	cmd_type,
		int	authoritative
	)

Sets whether the completion list for this command is complete.

If true, any options not matching one of the provided options will be flagged as an error by syntax highlighting.

References complete_entry::authoritative, CHECK, and complete_get_exact_entry().

Referenced by builtin_complete_add().

void completion_allocate	(	array_list_t *	context,
		const wchar_t *	comp,
		const wchar_t *	desc,
		int	flags
	)

Create a new completion entry.

Parameters:

	context	The halloc context to use for allocating new memory
	comp	The completion string
	desc	The description of the completion
	flags	completion flags

References al_push(), COMPLETE_AUTO_SPACE, COMPLETE_NO_SPACE, halloc(), and halloc_wcsdup().

Referenced by complete_param(), complete_variable(), expand_pid(), find_process(), try_complete_user(), and wildcard_complete_internal().


Data Structures
struct	completion_t
Defines
#define	SHARED 0
	Header guard.
#define	NO_FILES 1
	Do not use file completion.
#define	NO_COMMON 2
	Require a parameter after completion.
#define	EXCLUSIVE 3
	Only use the argument list specifies with completion after option.
#define	PATH 1
	Command is a path.
#define	COMMAND 0
	Command is not a path.
#define	COMPLETE_SEP L'\004'
	Separator between completion and description.
#define	COMPLETE_SEP_STR L"\004"
	Separator between completion and description.
#define	COMPLETE_ITEM_SEP L'\uf500'
	Separator between completion items in fish_pager.
#define	PROG_COMPLETE_SEP L'\t'
	Character that separates the completion and description on programmable completions.
#define	COMPLETE_NO_SPACE 1
	Do not insert space afterwards if this is the only completion.
#define	COMPLETE_NO_CASE 2
	This compeltion is case insensitive.
#define	COMPLETE_WHOLE_ARGUMENT 4
	This compeltion is the whole argument, not just the remainder.
#define	COMPLETE_AUTO_SPACE 8
	This completion may or may not want a space at the end - guess by checking the last character of the completion.
#define	COMPLETE_DONT_ESCAPE 16
	This completion should be inserted as-is, without escaping.
Functions
void	complete_add (const wchar_t cmd, int cmd_type, wchar_t short_opt, const wchar_t long_opt, int long_mode, int result_mode, const wchar_t condition, const wchar_t comp, const wchar_t *desc, int flags)
	Add a completion.
void	complete_set_authoritative (const wchar_t *cmd, int cmd_type, int authoritative)
	Sets whether the completion list for this command is complete.
void	complete_remove (const wchar_t cmd, int cmd_type, wchar_t short_opt, const wchar_t long_opt)
	Remove a previously defined completion.
void	complete (const wchar_t cmd, array_list_t out)
	Find all completions of the command cmd, insert them into out.
void	complete_print (string_buffer_t *out)
	Print a list of all current completions into the string_buffer_t.
int	complete_is_valid_option (const wchar_t str, const wchar_t opt, array_list_t *errors)
	Tests if the specified option is defined for the specified command.
int	complete_is_valid_argument (const wchar_t str, const wchar_t opt, const wchar_t *arg)
	Tests if the specified argument is valid for the specified option and command.
void	complete_load (const wchar_t *cmd, int reload)
	Load command-specific completions for the specified command.
void	completion_allocate (array_list_t context, const wchar_t comp, const wchar_t *desc, int flags)
	Create a new completion entry.