info rlman

2.6.3 Completion Variables

Variable: rl_compentry_func_t * rl_completion_entry_function: A pointer to the generator function for rl_completion_matches(). NULL means to use rl_filename_completion_function(), the default filename completer.

Variable: rl_completion_func_t * rl_attempted_completion_function: A pointer to an alternative function to create matches. The function is called with text, start, and end. start and end are indices in rl_line_buffer defining the boundaries of text, which is a character string. If this function exists and returns NULL, or if this variable is set to NULL, then rl_complete() will call the value of rl_completion_entry_function to generate matches, otherwise the array of strings returned will be used. If this function sets the rl_attempted_completion_over variable to a non-zero value, Readline will not perform its default completion even if this function returns no matches.

Variable: rl_quote_func_t * rl_filename_quoting_function: A pointer to a function that will quote a filename in an application-specific fashion. This is called if filename completion is being attempted and one of the characters in rl_filename_quote_characters appears in a completed filename. The function is called with text, match_type, and quote_pointer. The text is the filename to be quoted. The match_type is either SINGLE_MATCH, if there is only one completion match, or MULT_MATCH. Some functions use this to decide whether or not to insert a closing quote character. The quote_pointer is a pointer to any opening quote character the user typed. Some functions choose to reset this character.

Variable: rl_dequote_func_t * rl_filename_dequoting_function: A pointer to a function that will remove application-specific quoting characters from a filename before completion is attempted, so those characters do not interfere with matching the text against names in the filesystem. It is called with text, the text of the word to be dequoted, and quote_char, which is the quoting character that delimits the filename (usually ‘'’ or ‘"’). If quote_char is zero, the filename was not in an embedded string.

Variable: rl_linebuf_func_t * rl_char_is_quoted_p: A pointer to a function to call that determines whether or not a specific character in the line buffer is quoted, according to whatever quoting mechanism the program calling Readline uses. The function is called with two arguments: text, the text of the line, and index, the index of the character in the line. It is used to decide whether a character found in rl_completer_word_break_characters should be used to break words for the completer.

Variable: rl_compignore_func_t * rl_ignore_some_completions_function: This function, if defined, is called by the completer when real filename completion is done, after all the matching names have been generated. It is passed a NULL terminated array of matches. The first element (matches[0]) is the maximal substring common to all matches. This function can re-arrange the list of matches as required, but each element deleted from the array must be freed.

Variable: rl_icppfunc_t * rl_directory_completion_hook: This function, if defined, is allowed to modify the directory portion of filenames Readline completes. It could be used to expand symbolic links or shell variables in pathnames. It is called with the address of a string (the current directory name) as an argument, and may modify that string. If the string is replaced with a new string, the old value should be freed. Any modified directory name should have a trailing slash. The modified value will be used as part of the completion, replacing the directory portion of the pathname the user typed. At the least, even if no other expansion is performed, this function should remove any quote characters from the directory name, because its result will be passed directly to opendir(). The directory completion hook returns an integer that should be non-zero if the function modifies its directory argument. The function should not modify the directory argument if it returns 0.

Variable: rl_dequote_func_t * rl_filename_rewrite_hook: If non-zero, this is the address of a function called when reading directory entries from the filesystem for completion and comparing them to the partial word to be completed. The function should perform any necesary application or system-specific conversion on the filename, such as converting between character sets or converting from a filesystem format to a character input format. The function takes two arguments: fname, the filename to be converted, and fnlen, its length in bytes. It must either return its first argument (if no conversion takes place) or the converted filename in newly-allocated memory. The converted form is used to compare against the word to be completed, and, if it matches, is added to the list of matches. Readline will free the allocated string.

Variable: rl_compdisp_func_t * rl_completion_display_matches_hook: If non-zero, then this is the address of a function to call when completing a word would normally display the list of possible matches. This function is called in lieu of Readline displaying the list. It takes three arguments: (char **matches, int num_matches, int max_length) where matches is the array of matching strings, num_matches is the number of strings in that array, and max_length is the length of the longest string in that array. Readline provides a convenience function, rl_display_match_list, that takes care of doing the display to Readline’s output stream. That function may be called from this hook.

Variable: const char * rl_basic_word_break_characters: The basic list of characters that signal a break between words for the completer routine. The default value of this variable is the characters which break words for completion in Bash: " \t\n\"\\'`@$><=;|&{(".

Variable: const char * rl_basic_quote_characters: A list of quote characters which can cause a word break.

Variable: const char * rl_completer_word_break_characters: The list of characters that signal a break between words for rl_complete_internal(). The default list is the value of rl_basic_word_break_characters.

Variable: rl_cpvfunc_t * rl_completion_word_break_hook: If non-zero, this is the address of a function to call when Readline is deciding where to separate words for word completion. It should return a character string like rl_completer_word_break_characters to be used to perform the current completion. The function may choose to set rl_completer_word_break_characters itself. If the function returns NULL, rl_completer_word_break_characters is used.

Variable: const char * rl_completer_quote_characters: A list of characters which can be used to quote a substring of the line. Completion occurs on the entire substring, and within the substring rl_completer_word_break_characters are treated as any other character, unless they also appear within this list.

Variable: const char * rl_filename_quote_characters: A list of characters that cause a filename to be quoted by the completer when they appear in a completed filename. The default is the null string.

Variable: const char * rl_special_prefixes: The list of characters that are word break characters, but should be left in text when it is passed to the completion function. Programs can use this to help determine what kind of completing to do. For instance, Bash sets this variable to "$@" so that it can complete shell variables and hostnames.

Variable: int rl_completion_query_items: Up to this many items will be displayed in response to a possible-completions call. After that, readline asks the user if she is sure she wants to see them all. The default value is 100. A negative value indicates that Readline should never ask the user.

Variable: int rl_completion_append_character: When a single completion alternative matches at the end of the command line, this character is appended to the inserted completion text. The default is a space character (‘ ’). Setting this to the null character (‘\0’) prevents anything being appended automatically. This can be changed in application-specific completion functions to provide the “most sensible word separator character” according to an application-specific command line syntax specification.

Variable: int rl_completion_suppress_append: If non-zero, rl_completion_append_character is not appended to matches at the end of the command line, as described above. It is set to 0 before any application-specific completion function is called, and may only be changed within such a function.

Variable: int rl_completion_quote_character: When Readline is completing quoted text, as delimited by one of the characters in rl_completer_quote_characters, it sets this variable to the quoting character found. This is set before any application-specific completion function is called.

Variable: int rl_completion_suppress_quote: If non-zero, Readline does not append a matching quote character when performing completion on a quoted string. It is set to 0 before any application-specific completion function is called, and may only be changed within such a function.

Variable: int rl_completion_found_quote: When Readline is completing quoted text, it sets this variable to a non-zero value if the word being completed contains or is delimited by any quoting characters, including backslashes. This is set before any application-specific completion function is called.

Variable: int rl_completion_mark_symlink_dirs: If non-zero, a slash will be appended to completed filenames that are symbolic links to directory names, subject to the value of the user-settable mark-directories variable. This variable exists so that application-specific completion functions can override the user’s global preference (set via the mark-symlinked-directories Readline variable) if appropriate. This variable is set to the user’s preference before any application-specific completion function is called, so unless that function modifies the value, the user’s preferences are honored.

Variable: int rl_ignore_completion_duplicates: If non-zero, then duplicates in the matches are removed. The default is 1.

Variable: int rl_filename_completion_desired: Non-zero means that the results of the matches are to be treated as filenames. This is always zero when completion is attempted, and can only be changed within an application-specific completion function. If it is set to a non-zero value by such a function, directory names have a slash appended and Readline attempts to quote completed filenames if they contain any characters in rl_filename_quote_characters and rl_filename_quoting_desired is set to a non-zero value.

Variable: int rl_filename_quoting_desired: Non-zero means that the results of the matches are to be quoted using double quotes (or an application-specific quoting mechanism) if the completed filename contains any characters in rl_filename_quote_chars. This is always non-zero when completion is attempted, and can only be changed within an application-specific completion function. The quoting is effected via a call to the function pointed to by rl_filename_quoting_function.

Variable: int rl_attempted_completion_over: If an application-specific completion function assigned to rl_attempted_completion_function sets this variable to a non-zero value, Readline will not perform its default filename completion even if the application’s completion function returns no matches. It should be set only by an application’s completion function.

Variable: int rl_sort_completion_matches: If an application sets this variable to 0, Readline will not sort the list of completions (which implies that it cannot remove any duplicate completions). The default value is 1, which means that Readline will sort the completions and, depending on the value of rl_ignore_completion_duplicates, will attempt to remove duplicate matches.

Variable: int rl_completion_type: Set to a character describing the type of completion Readline is currently attempting; see the description of rl_complete_internal() (see section Completion Functions) for the list of characters. This is set to the appropriate value before any application-specific completion function is called, allowing such functions to present the same interface as rl_complete().

Variable: int rl_completion_invoking_key: Set to the final character in the key sequence that invoked one of the completion functions that call rl_complete_internal(). This is set to the appropriate value before any application-specific completion function is called.

Variable: int rl_inhibit_completion: If this variable is non-zero, completion is inhibited. The completion character will be inserted as any other bound to self-insert.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]