diff options
| -rw-r--r-- | tasks-reference/completion/text.xml | 426 | ||||
| -rw-r--r-- | tasks-reference/text.xml | 28 | ||||
| -rw-r--r-- | text.xml | 1 |
3 files changed, 455 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> @@ -39,4 +39,5 @@ section for how to get started. <include href="eclass-writing/"/> <include href="profiles/"/> <include href="keywording/"/> +<include href="tasks-reference/"/> </guide> |