Devel §2 Completion

2.1 Completion API for completion sources

2.1.1 Function ble-complete/cand/yield

# Inside completion sources

ble/complete/cand/yield ACTION CAND DATA

• ACTION specifies the type of the candidates. The value should be one of the pre-defined / user-defined actions.
• CAND specifies the generated candidate.
• DATA specifies additional information on the candidate that will be used by the action. The interpretation depends on the action.

2.1.2 Bleopt complete_menu_style^†

When this option is changed inside the completion sources, this takes an effect only for the current completion. The meaning is the same as the global setting of complete_menu_style.

# Inside completion sources

# Switch to the "desc" view of the completion menu for the current completion
bleopt complete_menu_style=desc

2.2 Completion API for progcomp functions

This section describes the APIs that can be used inside the progcomp functions specified by complete -F func COMMAND or defined as ble/cmdinfo/complete:COMMAND. All the APIs for the completion sources can also be used by the progcomp functions since the progcomp functions are called inside source:argument.

2.2.1 Function compopt^†

Inside the progcomp functions, the builtin command compopt is replaced with a function by ble.sh. Here the options supported by the function compopt are explained.

# Inside progcomp functions

# set an option
compopt -o OPTION

# reset an option
compopt +o OPTION

OPTION is one of the following names. The option name starting with ble/ is an extension by ble.sh.

• bashdefault (unused), default (unused), dirnames, ble/no-default (ble.sh Extension)

  These options control the behavior in the case that the progcomp does not generate any candidates. ble.sh performs fallback completions by default regardless of the Bash compopt options bashdefault and default, so these two options are actually not referenced by ble.sh. [ Note: In Bash, bashdefault and default specify that the Bash/Readline completions should be attented when no candidates are generated. ] dirnames specifies that the directory names should be generated when no candidates are generated. To turn off these default completions, ble/no-default can be specified.

• plusdirs

  This option specifies that the directory names should be generated in addition to the candidates generated by other progcomp specifications.

• filenames

  This option specifies that the generated candidates should be adjusted as filenames.

  • Colors and descriptions in menu-completion is determined based on the file type.
  • In Bash, a slash / is inserted when a unique completion is inserted if the candidate matches with a directory name. In ble.sh, the slash is inserted by default regardless of this option. In ble.sh, this option enables requoting the entire word to make the expanded result shorter: e.g., a\ b\ c\ d may be replaced by 'a b c d'.
  • In Bash, the generated candidates will be properly quoted as filenames. In ble.sh, the candidates generated by progcomp are quoted regardless of this option, but the tilde at the beginning of the completion is not quoted when this option is specified and there is a matching filename.

• nospace, ble/no-mark-directories (ble.sh Extension)

  The option nospace specifies that the space after the unique completion should not be inserted. The option ble/no-mark-directories specifies that the slash after the unique completion should not be inserted.

• noquote

  This option specifies that the generated candidate should not be quoted by ble.sh, but should be directly inserted in the command line.

• nosort

  This option specifies that the order of the generated candidates should be kept.

• ble/prog-trim (internal)

  This option specifies that the trailing spaces of the candidates generated by compgen -C prog should be trimmed.

• ble/filter-by-prefix

  This option specifies that the generated candidates should be filtered by the current word. The idea is similar to COMPREPLY=($(compgen -W '"${COMPREPLY[@]}"' -- "$prefix")) where prefix is the prefix of the current word before the cursor position.

• ble/syntax-raw

  This option specifies that the completion is performed against the raw syntax words, so that the brance expansions and other constructs can be rewritten by the generated candidates. This option takes an effect only when noquote is also specified.