Bash 3's completion doesn't split words by characters in
COMP_WORDBREAKS. In particular it doesn't split at "=" signs. Now
_gst_launch_parse handles both bash 3 and 4 format of COMP_WORDS.
Note that "${cur%%=*}" means cur's value with the longest possible match
of "=*" deleted from the end; "${cur#*=}" means cur's value with the
shortest possible match of "*=" deleted from the beginning. See
http://www.gnu.org/software/bash/manual/html_node/Shell-Parameter-Expansion.html
Regardless of the version of bash running the unit tests, I can test for
both behaviours because the unit test populates COMP_WORDS manually. So
this tests the bash 3 behaviour:
test_gst_inspect_completion --gst-debug-level=4
and this tests the bash 4 behaviour:
test_gst_inspect_completion --gst-debug-level = 4
Compatible with bash 3.2; doesn't require the bash-completion package at
all (though the easiest way to install this script is still to install
bash-completion, and then drop this script into /etc/bash_completion.d).
Note that bash 3 doesn't break COMP_WORDS according to characters in
COMP_WORDBREAKS, so "property=val" looks like a single word, so this
won't complete property values (on bash 3). Similarly,
"--gst-debug-level=<TAB>" won't complete properly (on bash 3), but
"--gst-debug-level <TAB>" will.
For that reason, I now offer "--gst-debug-level" etc as completions
instead of "--gst-debug-level=".
Functions "_init_completion" and "_parse_help" were provided by the
bash-completion package >= 2.0; now I roll my own equivalent of
"_parse_help", and instead of "_init_completion" I use
"_get_comp_words_by_ref" which is available from bash-completion 1.2
onwards. If the bash-completion package isn't available at all I use
bash's raw facilities, at the expense of not completing properly when
the cursor is in the middle of a word.
The builtin "compopt" doesn't exist in bash 3; those users will just
have to live with the inconvenience of "property=" completing to
"property= " with a trailing space. Property values aren't completed
properly anyway on bash 3 (see above).
"[[ -v var ]]" to test whether a variable is set, also doesn't exist in
bash 3. Neither does ";;&" to fall through in a "case" statement.
In the unit tests:
* On my system (OS X), "#!/bin/bash" is bash 3.2, whereas
"#!/usr/bin/env bash" is the 4.2 version I built myself.
* I have to initialise array variables like "expected=()", or bash 3
treats "+=" as appending to an array already populated with one empty
string.
Completes options like "--gst-debug-level" and the values of some of
those options; completes gst-launch pipeline element names, property
names, and even property values (for enum or boolean properties only).
Doesn't complete all caps specifications, nor element names specified
earlier in the pipeline with "name=...".
The GStreamer version number is hard-coded into the completion script:
This patch is off the master branch and has the version hard-coded as
"1.0"; it needs to be updated if backported to the 0.10 branch. You
could always create a "gstreamer-completion.in" that has the appropriate
version inserted by "configure", but I'd rather not do that. The
hard-coded version is consistent with the previous implementation of
gstreamer-completion, which had the registry path hard-coded as
~/.gstreamer-1.0/registry.xml.
Note that GStreamer 0.10 installs "gst-inspect" and "gst-inspect-0.10".
"gst-inspect --help" only prints 4 flags (--help, --print, --gst-mm,
gst-list-mm) whereas "gst-inspect-0.10 --help-all" prints the full list
of flags. The same applies to "gst-launch" and "gst-launch-0.10".
GStreamer 1.0 only installs "gst-inspect-1.0", not "gst-inspect".
Requires bash 4; only tested with bash 4.2. Requires "bash-completion"
(which you install with your system's package manager).
Put this in /etc/bash_completion.d/ or in `pkg-config
--variable=compatdir bash-completion`, where it will be loaded at the
beginning of every new terminal session;
or in `pgk-config --variable=completionsdir bash-completion`, renamed to
match the name of the command it completes (e.g. "gst-launch-1.0", with
an additional symlink named "gst-inspect-1.0"), where it will be
autoloaded when needed.
test-gstreamer-completion.sh is (for now) in tests/misc -- it might be
worth creating "tests/check/tools", with all the necessary automake
boilerplate, and moving test-gstreamer-completion.sh there, and have it
run automatically with "make check".
IF YOU'RE NEW TO BASH COMPLETION SCRIPTS
----------------------------------------
"complete -F _gst_launch gst-launch-1.0" means that bash will run the
function "_gst_launch" to generate possible completions for the command
"gst-launch-1.0".
"_gst_launch" must return the possible completions in the array variable
COMPREPLY. (Note on bash syntax: "V=(a b c)" assigns three elements to
the array "V").
"compgen" prints a list of possible completions to standard output. Try
it:
compgen -W "abc1 abc2 def" -- "a"
compgen -f -- "/"
The last argument is the word currently being completed; compgen uses it
to filter out the non-matching completions. We put "--" first, in case
the word currently being completed starts with "-" or "--", so that it
isn't treated as a flag to compgen.
For the documentation of COMP_WORDS, COMP_CWORD, etc see
http://www.gnu.org/software/bash/manual/html_node/Bash-Variables.html#index-COMP_005fCWORD-180
See also:
* http://www.gnu.org/software/bash/manual/html_node/Programmable-Completion.html
* http://www.gnu.org/software/bash/manual/html_node/Programmable-Completion-Builtins.html
The bash-completion package provides the helper function
"_init_completion" which populates variables "cur", "prev", and "words".
See
http://anonscm.debian.org/gitweb/?p=bash-completion/bash-completion.git;a=blob;f=bash_completion;h=870811b4;hb=HEAD#l634
Note that by default, bash appends a space to the completed word. When
the completion is "property=" we don't want a trailing space; calling
"compopt -o nospace" modifies the currently-executing completion
accordingly. See
http://www.gnu.org/software/bash/manual/html_node/Programmable-Completion-Builtins.html#index-compopt
