[ 日本語 | English ] ≫ Manual [§1 Intro | §2 Color | §3 Bind | §4 Edit | §5 Emacs | §6 Vim | §7 Comp | §8 Misc | Index]

The settings for completion need to be performed through the hook complete_load or the callback for ble-import core-complete. The following is an example to use the complete_load hook to configure bleopt complete_auto_delay:

# blerc

function my/complete-load-hook {
  bleopt complete_auto_delay=300
}

blehook/eval-after-load complete my/complete-load-hook
# ble-0.3 and before
# ble/array#push _ble_complete_load_hook my/complete-load-hook

The following is an example to use the ble-import callback (ble >= 0.4):

# blerc

function my/set-up-completion {
  bleopt complete_auto_delay=300
}

ble-import core-complete -C 'my/set-up-completion'

widget: complete $opts

OPTIONS

  $opts   a colon separated list of fields

    insert_common
    insert_all
    insert_braces
    insert_unique
    toggle_menu
    enter_menu
    show_menu
    context=CONTEXT
    backward
    no-empty
    no-bell

By default, completion can be trigger by C-i or TAB. When the menu of candidates are already shown, it enters the menu completion mode (described later). The first step of the process of the completion is to generate possible candidates. Initially the programmable completion from the setting by Bash builtin complete are checked, and if it is not available the candidate generator built in ble.sh is used instead. If there are no possible candidates, ambiguous candidate generation is performed. The next step is to insert the candidates.

• When insert_common is specified or no other insertion method is specified, ble.sh inserts the longest common prefix among possible candidates and the existing text. In addition, when the possible candidate is unique, the unique candidate is inserted, and the completion is finished. When there are multiple possible candidates, a menu of the possible candidates is shown.
• When insert_all is specified, all the candidates are inserted in the command line, and the completion is finished.
• When insert_braces is specified, all the candidates are inserted with a compact form by contracting common parts by brace expansions, and the completion is finished.
• When toggle_menu is specified, the completion menu is shown if it is not shown. The completion menu is hidden if it is shown.
• When enter_menu is specified, the completion menu is shown with the first item being selected, and ble.sh enters the menu completion mode. If backward is specified, the last item is selected instead of the first item. If insert_unique is specified and the generated candidate is unique, intead of entering the menu, the unique candidate is inserted, and the completion is finished.
• When show_menu is specified, the completion menu is just shown.

When the completion is finished, suffixes and closing quotations are inserted to each inserted candidate if needed.

When M-? is pressed in Emacs editing mode (or when the widget complete receives show_menu as an argument), the menu of possible completions is shown instead of inserting a common prefix. When C-TAB is used (or when the widget complete receives enter_menu as an argument), the menu completion is started instead of inserting a common prefix.

When M-/, M-~, M-$, M-@ or M-! is pressed in Emacs editing mode (or when the widget receives a context argument, context=filename, context=username, context=variable, context=hostname or context=command), possible completions for filenames, users, variables, hostnames or commands are generated, respectively. When C-x /, C-x ~, C-x $, C-x @ or C-x ! is pressed in Emacs editing mode, (or when the widget receives show_menu as an additional argument to the context argument), the corresponding completions are show in a menu instead of inserting a common prefix. When C-x /, C-x ~, C-x $, C-x @, C-x ! is pressed in Vim editing mode, (or when the widget receives enter_menu as an additional argument to the context argument), the menu completion is started with the corresponding completions instead of inserting a common prefix.

widget: menu-complete $opts

This is the alias to the widget complete enter_menu:insert_unique:$opts. Please refer to the description on the widget complete.

# default
bleopt complete_ambiguous=1

If this has a non-empty value, completions ambiguously matching to the current text are generated. If this has the empty value, ambiguous completion is disabled.

# default
bleopt complete_contract_function_names=1

If this has a non-empty value, function names are split by / just like the file paths, and first fragment is used for completions. If this has the empty value, the whole function names are used for completions.

# default
bleopt complete_polling_cycle=50     # ble-0.3
bleopt complete_stdin_frequency=50   # ble-0.2 (obsoleted in ble-0.3)

In ble.sh, the completion is canceled when there is a user input during the completion generation to respond the user's input. This setting controls the interval of user input checks in the unit of the number of processed completions.

# default
bleopt complete_limit=

This options gives a hint on the maximum acceptable size of any data structure generated during the completion process, beyond which the completion may be prematurely aborted to avoid excessive processing time. When its value is empty, the size checks are disabled. This setting is particularly intended for the normal (TAB) completion. For auto-completion, please also see complete_limit_auto below.

# default
bleopt complete_limit_auto=2000

This option is the same as complete_limit but is used for auto-complete. When its value is empty, the setting of complete_limit is used.

# default
bleopt complete_limit_auto_menu=100

This option is the same as complete_limit but is used for auto-complete. When its value is empty, the setting of complete_limit is used.

# default
bleopt complete_timeout_auto=5000

This setting controls the timeout for the pathname expansions performed in auto-complete. When the word contains a glob pattern that takes a long time to evaluate the pathname expansion, auto-complete based on the filename is canceled based on the timeout setting. The value specifies the timeout duration in milliseconds. When the value is empty, the timeout is disabled.

# default
bleopt complete_timeout_compvar=200

This setting controls the timeout for the pathname expansions to prepare COMP_WORDS and COMP_LINE for progcomp. When the word contains a glob pattern that takes a long time to evaluate, the pathname expansion is canceled, and a noglob expansion is used to construct COMP_WORDS and COMP_LINE. The value specifies ## the timeout duration in milliseconds. When the value is empty, the timeout is disabled.

# default
bleopt complete_allow_reduction=     # ble-0.4

When the generated completion does not contain the already existing text, The non-empty value of this setting allows the rewrite of the existing text. When this setting has the empty value, it allows the rewrite only when the possible completion is unique.

# default
bleopt complete_requote_threshold=0

This option specifies the threshold to simplify the quotation type of the inserted word. When this option evaluates to a negative value, the simplification of the quotation is disabled. Otherwise, when the number of characters will be reduced by at least the specified value, the quotation is simplified. The default is 0, which means that the quotation is simplified unless the number of characters increases by the simplification.

# bashrc

# default
shopt -u no_empty_cmd_completion

When this Bash setting is enabled, the command name generation using the empty text is disabled.

# bashrc

# default
shopt -s force_fignore

When this Bash setting is enabled, all kinds of generated completions, not restricted in pathnames, are filtered by the shell variable FIGNORE. The completions that have one of the suffixes specified in the colon-separated value of FIGNORE will be removed.

# bashrc

# default
bind 'set completion-ignore-case off'

When this Readline setting is enabled, the cases of alphabets are ignored on completion generation.

# bashrc

# default
bleopt complete_skip_matched=on    # ble-0.4 and later
bind 'set skip-completed-text on'
bind 'set skip-completed-text off' # ble-0.3

When a non-empty value is specified, the matching text on the right of the cursor is removed on the insertion of the completion. This setting is synchronized with the readline variable skip-completed-text.

# bashrc

# default
bind 'set visible-stats off'

When this Readline setting is turned on, suffixes are added to the filename completions in the menu. The characters @, / and * are added to symbolic links, directories and executables, respectively.

# bashrc

# default
bind 'set mark-directories on'

When this Readline setting is turned on, the suffix / is inserted after the insertion of directory names.

# bashrc

# default
bind 'set mark-symlinked-directories on'

When this Readline setting is turned on, the suffix / is inserted after symbolic links pointing to directories.

# bashrc

# default
bind 'set match-hidden-files on'

When this Readline setting is turned on, the filenames starting with . is also generated as possible completions.

# bashrc

# default
bind 'set menu-complete-display-prefix off'

When filenames of the form dir/file* is shown in the menu, the part of the directory name dir/ is omitted by default. When this Readline setting is turned on, the directory name of filename completions are not omitted.

# default
bleopt complete_source_sabbrev_ignore=

This specifies a colon-separated list of glob patterns of sabbrev names ignored in generating the sabbrev completion candidates.

# default
bleopt complete_source_sabbrev_opts=

This is a colon-separated list of options. When the field no-empty-completion is specified, the sabbrev completion candidates are not generated when the word to complete is empty.

When the menu is shown, C-i or TAB leads to the menu completion mode. The dedicated key bindings (such as C-TAB, and C-x /, C-x ~, C-x $, C-x @ and C-x ! in Vim editing-mode) can also be used to enter the menu completion mode. In the menu completion mode, the following bindings are available.

# default
bleopt complete_menu_complete=1

If a non-empty value is set, C-i and TAB (or the widget complete) triggers the menu completion mode when the menu is shown. If this has the empty value, a normal completion is tried again instead of entering the menu completion.

# default
bleopt complete_menu_complete_opts=insert-selection

This setting controls the detailed behavior of menu-complete with a colon-separated list of options: When the option insert-selection is specified, the currently selected menu item is temporarily inserted in the command line. When hidden is specified, insert-selection is automatically enabled. In addition, the completion menu is by default hidden in the menu-complete mode so that only the temporary insertion in the command line is shown.

# default
bleopt complete_menu_style=align-nowrap

This setting controls the style of the menu. When the value dense is specified, all the possible completions are shown separated by single spaces. The completion can be broken into two lines at the end of lines. The value dense-nowrap is the version with word wrapping, i.e., it inserts newlines before the completion that does not fit into the line. When the value align is specified, completions are aligned in rows by inserting proper amount of spaces. The value align-nowrap is the version with word wrapping. When the value linewise is specified, each line show one completion. When the value desc-text is specified, each line show one completion with a description. Control characters in descriptions are replaced with some visible representation. When the value desc is specified, each line show one completion with a description that contains control characters and escape sequences.

# default
bleopt complete_menu_maxlines=-1

When this value is evaluated to be a positive integer, the maximal line number of the menu is limited to that value.

# default
bleopt menu_align_max=20      # ble-0.4
bleopt complete_menu_align=20 # ble-0.3 (obsoleted in ble-0.4)

This setting is used when blesh option complete_menu_style has the value align or align-wrap. This specifies the maximal unit width of the alignment.

# default
bleopt menu_align_min=4

This setting is used when blesh option complete_menu_style has the value align or align-wrap. This specifies the minimal unit width of the alignment.

# default
bleopt menu_prefix=
bleopt menu_align_prefix=
bleopt menu_desc_prefix=
bleopt menu_linewise_prefix=
bleopt menu_dense_prefix=

# Example
bleopt menu_align_prefix='\e[1m%d:\e[m '
bleopt menu_desc_prefix='\e[1m%d.\e[m '
bleopt menu_dense_prefix='\e[1;32m>\e[m '
bleopt menu_linewise_prefix='\e[1;36m%d:\e[m '

These settings can be used to specify the prefix of the menu items. menu_prefix specifies the default prefix for any menu-style. menu_{align,desc,linewise,dense}_prefix specify the prefixes in the respective menu-styles. The value is specified by a printf format, where the first argument is the index of the candidate. The ANSI escape sequences can also be used.

# default
bleopt menu_desc_multicolumn_width=65

# Example: disable multicolumn
bleopt menu_desc_multicolumn_width=

This setting specifies the minimum column width for the multicolumn description for complete_menu_style=desc. When the empty value is specified, the multicolumn mode is disabled.

# bashrc

# default
bleopt complete_menu_color=on
bind 'set colored-stats on'

When a non-empty value is specified, the highlighting of the menu items is enabled. This setting is synchronized with the readline variable colored-stats.

# bashrc

# default
bleopt complete_menu_color_match=on
bind 'set colored-completion-prefix on'

When a non-empty value is specified, the part of the menu items matching with the already input text is highlighted. This setting is synchronized with the readline variable colored-completion-prefix.

# default
ble-face menu_desc_default=none

This face specifies the default graphic style of texts in the menu descriptions.

# default
ble-face menu_desc_type=ref:syntax_delimiter

This face specifies the graphic style of type indicators of the form (type) in the menu descriptions, which represents the type of the menu item.

# default
ble-face menu_desc_quote=ref:syntax_quoted

This face specifies the graphic style of quoted strings in the menu descriptions.

# default
ble-face menu_complete_match=bold

This face specifies the additional graphic style for the candidate parts matching the filtering text.

# default
ble-face menu_complete_selected=reverse

This face specifies the additional graphic style for the selected candidate.

The face for the menu items generated based on CDPATH.

# default
ble-face cmdinfo_cd_cdpath='fg=26,bg=155'

In Bash 4.0 and later, auto completion is enabled to suggest a possible completion automatically.

# default
bleopt complete_auto_complete=1

When this has a non-empty value, auto completion is enabled. When this has the empty value, auto completion is disabled.

# default
bleopt complete_auto_delay=1

The delay to start auto completion after the user made the last input. The unit is millisecond.

# default
bleopt complete_auto_history=1

When this has a non-empty value, auto completions are generated from the history. The history entries containing the current text as a prefix are generated as a completion.

# default
bleopt complete_auto_wordbreaks=$' \t\n'

This setting is used to identify the words used in M-right (auto_complete/insert-word). This specifies a set of the characters that breaks the completion into words.

# default
bleopt complete_auto_complete_opts=

This setting controls the detailed behavior of auto-complete with a colon-separated list of options:

• When the option suppress-after-complete is specified, auto-complete is enabled after TAB completions. Otherwise, auto-complete is disabled after TAB completions.

# default
bleopt complete_auto_menu=

This setting controls the delay of auto-menu. When a non-empty string is set, auto-menu is enabled. The string is evaluated as an arithmetic expression to give the delay in milliseconds. ble.sh will automatically show the menu of completions after the idle time (for which user input does not arrive) reaches the delay.

# default
ble-face auto_complete='bg=254,fg=238'

This face is used to show the suggested strings by auto completion.

In Bash 4.0 and later, menu filter is enabled. When the menu is shown, the completions shown in the menu are dynamically filtered according to the newly input texts.

# default
bleopt complete_menu_filter=1

When this setting has a non-empty value, menu filtering is enabled. When this setting has the empty value, menu filtering is disabled.

# default
ble-face menu_filter_fixed=bold

This face is used to show a fixed part of menu filtering.

# default
ble-face menu_filter_input='fg=16,bg=229'

This face is used to show a range of the input text which is used for menu filtering.

The sabbrev expansion provides the feature like zsh-abbreviations. The sabbrev expansion can be performed by SP (widget magic-space) or M-', C-x ' (Emacs), C-] in Vim editing mode (widget sabbrev-expand).

# hook:complete_load

ble-sabbrev [-wmil] [KEY=VALUE|KEY=]...

The function ble-sabbrev is used to define sabbrev expansions. In each argument, the left hand side of the left most = is regarded as KEY and the right hand side is regarded as VALUE. This registers an expansion from a word KEY to VALUE. When VALUE is omitted, the sabbrev expansion assigned to KEY is removed.

• Word sabbrev: When the option -w is specified or no other types are specified, KEY matches a word before the current position.
• Dynamic sabbrev: When the option -m is specified, the right hand side is regarded as COMMAND. On the expansion, COMMAND is executed as a shell command and the completion is started by the generated completions. The command COMMAND can store the generated completions in the array COMPREPLY or use the function ble/complete/cand/yield to register them.
• Inline sabbrev: When the option -i is specified, KEY can match any length of substring ending at the current position.
• Line sabbrev: When the option -l is specified, KEY matches the current line before the current position.
• Suffix sabrev: When the option -s is specified, KEY matches a filename extension of the command name that does not match any existing command names. KEY does not include the dot . that separates the extension in the filename. VALUE is inserted before the command name during the expansion. This emulates the behavior of Zsh's suffix aliases.

# hook:complete_load

# Example
ble-sabbrev L='| less'
ble-sabbrev '\date'='date +%F'

The sabbrev expansion may also be used to approximate Zsh's named directories. Although Bash does not expands ~named_dir (with named_dir not being a user name) in the tilde expansions, ble.sh expands ~named_dir in the command line on pressing SP or / when the sabbrev expansion ~name_dir is defined.

# hook:complete_load

# Example
ble-sabbrev "~mybin=$HOME/bin"
ble-sabbrev "~local=$HOME/.local"

The dabbrev expansion searches a completion that matches with the current word as a prefix from the words in history separated by spaces or the characters in COMP_WORDBREAKS. The key sequence C-x C-r starts the dabbrev expansion mode.

In dabbrev expansion mode, the following bindings are available.

[ 日本語 | English ] ≫ Manual [§1 Intro | §2 Color | §3 Bind | §4 Edit | §5 Emacs | §6 Vim | §7 Comp | §8 Misc | Index]