aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
Diffstat (limited to 'tasks-reference')
-rw-r--r--tasks-reference/completion/text.xml426
-rw-r--r--tasks-reference/text.xml28
2 files changed, 454 insertions, 0 deletions
diff --git a/tasks-reference/completion/text.xml b/tasks-reference/completion/text.xml
new file mode 100644
index 0000000..71a410f
--- /dev/null
+++ b/tasks-reference/completion/text.xml
@@ -0,0 +1,426 @@
+<?xml version="1.0"?>
+<guide self="tasks-reference/completion/">
+<chapter>
+<title>Completion Files</title>
+<body>
+
+<p>
+Since v2.05a, <c>bash</c> has offered intelligent programmable completion. Writing
+such completions for your own programs/things you maintain is relatively easy
+provided you know bash already. See `bash-completion.eclass Reference`_ for how
+to install completion files.
+</p>
+
+<section>
+<title>Completion-Related Internal Bash Variables</title>
+<body>
+
+<p>
+Most of these variables lose their special properties when unset, even if they
+are subsequently reset.
+</p>
+
+<table>
+ <tr>
+ <th>
+ Variable
+ </th>
+ <th>
+ Purpose
+ </th>
+ </tr>
+ <tr>
+ <ti>
+ <c>COMP_CWORD</c>
+ </ti>
+ <ti>
+ An index into <c>${COMP_WORDS}</c> of the word containing the
+ current cursor position.
+ </ti>
+ </tr>
+ <tr>
+ <ti>
+ <c>COMP_LINE</c>
+ </ti>
+ <ti>
+ The current command line.
+ </ti>
+ </tr>
+ <tr>
+ <ti>
+ <c>COMP_POINT</c>
+ </ti>
+ <ti>
+ The index of the current cursor position relative to the
+ beginning of the current command. If the current cursor
+ position is at the end of the current command, the value
+ of this variable is equal to <c>${#COMP_LINE}</c>.
+ </ti>
+ </tr>
+ <tr>
+ <ti>
+ <c>COMP_WORDBREAKS</c>
+ </ti>
+ <ti>
+ The set of characters that the Readline library treats as
+ word separators when performing word completion.
+ </ti>
+ </tr>
+ <tr>
+ <ti>
+ <c>COMP_WORDS</c>
+ </ti>
+ <ti>
+ An array variable consisting of the individual words in
+ the current command line, <c>${COMP_LINE}</c>.
+ </ti>
+ </tr>
+ <tr>
+ <ti>
+ <c>COMPREPLY</c>
+ </ti>
+ <ti>
+ An array variable from which bash reads the possible
+ completions generated by a completion function.
+ </ti>
+ </tr>
+</table>
+
+</body>
+</section>
+
+<section>
+<title>Completion-Related Bash Builtins</title>
+<body>
+
+<p>
+See `bash-1`_ for a full description of these builtins and their options.
+</p>
+
+<table>
+ <tr>
+ <th>
+ Builtin
+ </th>
+ <th>
+ Usage
+ </th>
+ </tr>
+ <tr>
+ <ti>
+ <c>compgen</c>
+ </ti>
+ <ti>
+ <c>compgen [-abcdefgjksuv] [-o option] [-A action] [-G globpat]
+ [-W wordlist] [-P prefix] [-S suffix] [-X filterpat]
+ [-F function] [-C command] [word]</c>
+ Display the possible completions depending on the options.
+ Intended to be used from within a shell function generating
+ possible completions. If the optional WORD argument is supplied,
+ matches against WORD are generated.
+ </ti>
+ </tr>
+ <tr>
+ <ti>
+ <c>complete</c>
+ </ti>
+ <ti>
+ <c>complete [-abcdefgjksuv] [-pr] [-o option] [-A action]
+ [-G globpat] [-W wordlist] [-P prefix] [-S suffix]
+ [-X filterpat] [-F function] [-C command] [name ...]</c>
+ For each NAME, specify how arguments are to be completed.
+ If the -p option is supplied, or if no options are supplied,
+ existing completion specifications are printed in a way that
+ allows them to be reused as input. The -r option removes a
+ completion specification for each NAME, or, if no NAMEs are
+ supplied, all completion specifications.
+ </ti>
+ </tr>
+</table>
+
+<p>
+For extremely simple cases, a simple <c>complete</c> statement is all that is
+needed. For example, minimal <c>cd</c> completion (minimal as in no support for
+<c>${CDPATH}</c>) would be as simple as:
+</p>
+
+<codesample lang="ebuild">
+complete -o nospace -d cd
+</codesample>
+
+</body>
+</section>
+
+<section>
+<title>Anatomy of a Completion Function</title>
+<body>
+
+<p>
+Nearly all completion functions will start out the same way. For these cases,
+the following can be used as a template for creating new completion functions:
+</p>
+
+<codesample lang="ebuild">
+_foo() {
+ local cur prev opts
+ COMPREPLY=()
+ cur="${COMP_WORDS[COMP_CWORD]}"
+ prev="${COMP_WORDS[COMP_CWORD-1]}"
+ opts=""
+
+ if [[ ${cur} == -* || ${COMP_CWORD} -eq 1 ]] ; then
+ COMPREPLY=( $(compgen -W "${opts}" -- ${cur}) )
+ return 0
+ fi
+
+ case "${prev}" in
+ # ...
+ esac
+}
+complete -F _foo foo
+</codesample>
+
+<table>
+ <tr>
+ <th>
+ Line
+ </th>
+ <th>
+ Explanation
+ </th>
+ </tr>
+ <tr>
+ <ti>
+ 1
+ </ti>
+ <ti>
+ The convention for completion function names is usually _NAME, where NAME
+ is the name of the application/function you are writing the completion
+ function for. If NAME contains a '-', it should be replaced with a '_'.
+ Hence bash-completion-config would be _bash_completion_config(). Failing
+ to do so can cause weird bugs if bash is invoked in POSIX-mode while a
+ function name containing a '-' is in the environment (POSIX sh does not
+ allow a '-' in function names).
+ </ti>
+ </tr>
+ <tr>
+ <ti>
+ 3
+ </ti>
+ <ti>
+ Resets the <c>${COMPREPLY}</c> array, as it may be set from a previous
+ invocation.
+ </ti>
+ </tr>
+ <tr>
+ <ti>
+ 4
+ </ti>
+ <ti>
+ Sets the local variable, <c>${cur}</c> to the current word of the command line.
+ If the current command line, <c>${COMP_LINE}</c> is say 'foo --fil', <c>${cur}</c>
+ would be equal to '--fil'. If <c>${COMP_LINE}</c> is equal to 'foo --file '
+ (note the space at the end), <c>${cur}</c> is null.
+ </ti>
+ </tr>
+ <tr>
+ <ti>
+ 5
+ </ti>
+ <ti>
+ Sets the local variable, <c>${prev}</c> to the previous word of the command
+ line. <c>${prev}</c> is the word before <c>${cur}</c>.
+ </ti>
+ </tr>
+ <tr>
+ <ti>
+ 6
+ </ti>
+ <ti>
+ Sets the local variable, <c>${opts}</c>. In a real completion function, this
+ variable would be set to all the options that <c>foo</c> recognizes.
+ </ti>
+ </tr>
+ <tr>
+ <ti>
+ 8
+ </ti>
+ <ti>
+ Tests whether or not the current word is equivalent to -* (an option) or if
+ we're completing on the first word (ie. <c>${COMP_CWORD}</c> == 1).
+ </ti>
+ </tr>
+ <tr>
+ <ti>
+ 9
+ </ti>
+ <ti>
+ If the test returns true, show the available options, <c>${opts}</c>. The -W
+ option to <c>compgen</c> tells bash to complete on the word list (string or
+ something that evaluates to a string). In the majority of cases, you'll
+ pass <c>'-- ${cur}'</c> to <c>compgen</c> telling it to only return those
+ completions that match <c>${cur}</c>.
+ </ti>
+ </tr>
+ <tr>
+ <ti>
+ 13
+ </ti>
+ <ti>
+ Most of the time, you'll want to perform a certain action if <c>${prev}</c> is
+ equal to a certain option. For example, if <c>foo</c> has a --file option
+ (and -f for short) that takes any kind file, you could do:
+ <codesample lang="ebuild">
+case "${prev}" in
+ -f|--file)
+ COMPREPLY=( $(compgen -f ? ${cur}) )
+ ;;
+esac
+ </codesample>
+ </ti>
+ </tr>
+ <tr>
+ <ti>
+ 17
+ </ti>
+ <ti>
+ Tells bash to use the <c>_foo</c> function to generate any completions for
+ the <c>foo</c> application/function.
+ </ti>
+ </tr>
+</table>
+
+</body>
+</section>
+
+<section>
+<title>Real-World Example</title>
+<body>
+
+<p>
+For this document, I will take you through a real-world example and write a
+real completion function for <c>revdep-rebuild</c> (might even be available in
+<c>gentoo-bashcomp</c> by the time you read this :]).
+</p>
+
+<codesample lang="ebuild">
+_revdep_rebuild() {
+ local cur prev opts
+ COMPREPLY=()
+ cur="${COMP_WORDS[COMP_CWORD]}"
+ prev="${COMP_WORDS[COMP_CWORD-1]}"
+ opts="-X --package-names --soname --soname-regexp -q --quiet"
+
+ if [[ ${cur} == -* || ${COMP_CWORD} -eq 1 ]] || \
+ [[ ${prev} == @(-q|--quiet) ]] ; then
+ COMPREPLY=( $(compgen -W "${opts}" -- ${cur}) )
+ return 0
+ fi
+
+ case "${prev}" in
+ -X|--package-names)
+ _pkgname -I ${cur}
+ ;;
+ --soname)
+ local sonames=$(for x in /lib/*.so?(.)* /usr/lib*/*.so\?(.)* ; do \
+ echo ${x##*/} ; \
+ done)
+ COMPREPLY=( $(compgen -W "${sonames}" -- ${cur}) )
+ ;;
+ --soname-regexp)
+ COMPREPLY=()
+ ;;
+ *)
+ if [[ ${COMP_LINE} == *" "@(-X|--package-names)* ]] ; then
+ _pkgname -I ${cur}
+ COMPREPLY=(${COMPREPLY[@]} $(compgen -W "${opts}"))
+ else
+ COMPREPLY=($(compgen -W "${opts} -- ${cur}"))
+ fi
+ ;;
+ esac
+}
+complete -F _revdep_rebuild revdep-rebuild
+</codesample>
+
+<p>
+Lines 1-12 are pretty much the same as in the previous section.
+</p>
+
+<table>
+ <tr>
+ <th>
+ Line
+ </th>
+ <th>
+ Explanation
+ </th>
+ </tr>
+ <tr>
+ <ti>
+ 15
+ </ti>
+ <ti>
+ If <c>${prev}</c> is equal to -X|--package-names, call _pkgname (a function
+ defined by <c>gentoo-bashcomp</c> that completes on package names - it sets
+ <c>${COMPREPLY}</c>, so we don't worry about that here).
+ </ti>
+ </tr>
+ <tr>
+ <ti>
+ 18
+ </ti>
+ <ti>
+ If <c>${prev}</c> is equal to --soname, generate a list of all shared libs
+ in /lib and /usr/lib*. Pass that list to <c>compgen</c> to generate a list
+ of possible completions that match <c>${cur}</c>.
+ </ti>
+ </tr>
+ <tr>
+ <ti>
+ 24
+ </ti>
+ <ti>
+ Obviously we cannot complete on any regexp's so if <c>${prev}</c> is equal
+ to --soname-regexp, do nothing.
+ </ti>
+ </tr>
+ <tr>
+ <ti>
+ 27
+ </ti>
+ <ti>
+ For anything else (any options not specified in the case statement above
+ OR any argument to one of the options specified in the case statement)
+ perform the tests. Since --package-names can take multiple package
+ names, we want to continue to complete on package names until another
+ recognized option is encountered (ie. is <c>${prev}</c>).
+ </ti>
+ </tr>
+ <tr>
+ <ti>
+ 30
+ </ti>
+ <ti>
+ Since _pkgname sets <c>${COMPREPLY}</c> and we want to add to that list,
+ we have to use the COMPREPLY=(${COMPREPLY[@] ... ) construct.
+ </ti>
+ </tr>
+ <tr>
+ <ti>
+ 37
+ </ti>
+ <ti>
+ Tell bash to use _revdep_rebuild to generate all possible completions
+ for revdep-rebuild.
+ </ti>
+ </tr>
+</table>
+
+</body>
+</section>
+
+</body>
+</chapter>
+</guide>
+
diff --git a/tasks-reference/text.xml b/tasks-reference/text.xml
new file mode 100644
index 0000000..06dbb51
--- /dev/null
+++ b/tasks-reference/text.xml
@@ -0,0 +1,28 @@
+<?xml version="1.0"?>
+<guide self="tasks-reference/">
+<chapter>
+<title>Tasks Reference</title>
+
+<body>
+<p>
+This section covers various common tasks which may are used by many different
+ebuilds.
+</p>
+</body>
+
+<section>
+<title>Contents</title>
+<body>
+<contentsTree/>
+</body>
+</section>
+</chapter>
+
+<include href="completion/"/>
+<!--
+<include href="environment/"/>
+<include href="init-scripts/"/>
+<include href="pam/"/>
+<include href="perl-modules/"/>
+-->
+</guide>