From 0bc58b66a4850cdb8458a86c3d9a2fc81de82aa3 Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Sun, 28 Apr 2024 11:14:42 +0200 Subject: Adding upstream version 1:2.11. Signed-off-by: Daniel Baumann --- doc/Makefile.am | 8 +++ doc/bash_completion.txt | 66 ++++++++++++++++++++++++ doc/bashrc | 1 + doc/inputrc | 1 + doc/main.txt | 18 +++++++ doc/makeHtml.sh | 4 ++ doc/styleguide.txt | 134 ++++++++++++++++++++++++++++++++++++++++++++++++ doc/testing.txt | 112 ++++++++++++++++++++++++++++++++++++++++ 8 files changed, 344 insertions(+) create mode 100644 doc/Makefile.am create mode 100644 doc/bash_completion.txt create mode 120000 doc/bashrc create mode 120000 doc/inputrc create mode 100644 doc/main.txt create mode 100755 doc/makeHtml.sh create mode 100644 doc/styleguide.txt create mode 100644 doc/testing.txt (limited to 'doc') diff --git a/doc/Makefile.am b/doc/Makefile.am new file mode 100644 index 0000000..6930b9c --- /dev/null +++ b/doc/Makefile.am @@ -0,0 +1,8 @@ +EXTRA_DIST = \ + bash_completion.txt \ + bashrc \ + inputrc \ + main.txt \ + makeHtml.sh \ + styleguide.txt \ + testing.txt diff --git a/doc/bash_completion.txt b/doc/bash_completion.txt new file mode 100644 index 0000000..e67f98b --- /dev/null +++ b/doc/bash_completion.txt @@ -0,0 +1,66 @@ +Bash completion +=============== + +Configuration files +------------------- + +*$BASH_COMPLETION_USER_FILE*:: + Sourced late by bash_completion, pretty much after everything else. + Use this file for example to load additional completions, and to remove + and override ones installed by bash_completion. Defaults to + `~/.bash_completion` if unset or null. + +*$XDG_CONFIG_HOME/bash_completion*:: + Sourced by the bash_completion.sh profile.d script. This file is + suitable for definitions of all `COMP_*` environment variables + below. If `$XDG_CONFIG_HOME` is unset or null, `~/.config` is + used instead of it. + +Environment variables +--------------------- + +*BASH_COMPLETION_COMPAT_DIR*:: + Directory for pre-dynamic loading era (pre-2.0) backwards compatibility + completion files that are loaded eagerly from `bash_completion` when it is + loaded. If unset or null, the default compatibility directory to use is + `/etc/bash_completion.d`. + +*COMP_CONFIGURE_HINTS*:: + If set and not null, `configure` completion will return the entire option + string (e.g. `--this-option=DESCRIPTION`) so one can see what kind of data + is required and then simply delete the descriptive text and add one's own + data. If unset or null (default), `configure` completion will strip + everything after the '=' when returning completions. + +*COMP_CVS_REMOTE*:: + If set and not null, `cvs commit` completion will try to complete on + remotely checked-out files. This requires passwordless access to the + remote repository. Default is unset. + +*COMP_FILEDIR_FALLBACK*:: + If set and not null, completions that look for filenames based on their + "extensions" will fall back to suggesting all files if there are none + matching the sought ones. + +*COMP_IWLIST_SCAN*:: + If set and not null, `iwconfig` completion will try to complete on + available wireless networks identifiers. Default is unset. + +*COMP_KNOWN_HOSTS_WITH_HOSTFILE*:: + If set and not null (default), known hosts completion will complement + hostnames from ssh's known_hosts files with hostnames taken from the file + specified by the HOSTFILE shell variable (compgen -A hostname). If null, + known hosts completion will omit hostnames from HOSTFILE. Omitting + hostnames from HOSTFILE is useful if HOSTFILE contains many entries for + local web development or ad-blocking. + +*COMP_KNOWN_HOSTS_WITH_AVAHI*:: + If set and not null, known hosts completion will try to use `avahi-browse` + for additional completions. This may be a slow operation in some setups. + Default is unset. + +*COMP_TAR_INTERNAL_PATHS*:: + If set and not null *before* sourcing bash_completion, `tar` completion + will do correct path completion for tar file contents. If unset or null, + `tar' completion will do correct completion for paths to tar files. See + also README. diff --git a/doc/bashrc b/doc/bashrc new file mode 120000 index 0000000..e22ec0e --- /dev/null +++ b/doc/bashrc @@ -0,0 +1 @@ +../test/config/bashrc \ No newline at end of file diff --git a/doc/inputrc b/doc/inputrc new file mode 120000 index 0000000..b6f22e6 --- /dev/null +++ b/doc/inputrc @@ -0,0 +1 @@ +../test/config/inputrc \ No newline at end of file diff --git a/doc/main.txt b/doc/main.txt new file mode 100644 index 0000000..d8a3076 --- /dev/null +++ b/doc/main.txt @@ -0,0 +1,18 @@ +Bash-completion +=============== +Freddy Vulto (FVu) +v1.0, Mar 2009 + +Preface +======= +Bash completion extends bashs standard completion behavior to achieve +complex command lines with just a few keystrokes. This project was +conceived to produce programmable completion routines for the most +common Linux/UNIX commands, reducing the amount of typing sysadmins +and programmers need to do on a daily basis. + +// include::intro.txt[] +include::bash_completion.txt[] + +include::styleguide.txt[] +include::testing.txt[] diff --git a/doc/makeHtml.sh b/doc/makeHtml.sh new file mode 100755 index 0000000..79780eb --- /dev/null +++ b/doc/makeHtml.sh @@ -0,0 +1,4 @@ +#!/bin/bash -eu + +[ -d html~ ] || mkdir html~ +a2x -D html~ -d book -f xhtml --asciidoc-opts="--unsafe" main.txt diff --git a/doc/styleguide.txt b/doc/styleguide.txt new file mode 100644 index 0000000..2251e77 --- /dev/null +++ b/doc/styleguide.txt @@ -0,0 +1,134 @@ +Coding Style Guide +================== + +Introduction +------------ +This document attempts to explain the basic styles and patterns that +are used in the bash completion. New code should try to conform to +these standards so that it is as easy to maintain as existing code. +Of course every rule has an exception, but it's important to know +the rules nonetheless! + +This is particularly directed at people new to the bash completion +codebase, who are in the process of getting their code reviewed. +Before getting a review, please read over this document and make +sure your code conforms to the recommendations here. + +Indentation +----------- +Indent step should be 4 spaces, no tabs. + +Globbing in case labels +----------------------- + +Avoid "fancy" globbing in case labels, just use traditional style when +possible. For example, do "--foo|--bar)" instead of "--@(foo|bar))". +Rationale: the former is easier to read, often easier to grep, and +doesn't confuse editors as bad as the latter, and is concise enough. + +[[ ]] vs [ ] +---------------- + +Always use [[ ]] instead of [ ]. Rationale: the former is less error +prone, more featureful, and slightly faster. + +Line wrapping +------------- + +Try to wrap lines at 79 characters. Never go past this limit, unless +you absolutely need to (example: a long sed regular expression, or the +like). This also holds true for the documentation and the testsuite. +Other files, like ChangeLog, or COPYING, are exempt from this rule. + +$(...) vs \`...` +---------------- + +When you need to do some code substitution in your completion script, +you *MUST* use the $(...) construct, rather than the \`...`. The former +is preferable because anyone, with any keyboard layout, is able to +type it. Backticks aren't always available, without doing strange +key combinations. + +-o filenames +------------ + +As a rule of thumb, do not use "complete -o filenames". Doing it makes +it take effect for all completions from the affected function, which +may break things if some completions from the function must not be +escaped as filenames. Instead, use "compopt -o filenames" to turn on +"-o filenames" behavior dynamically when returning completions that +need that kind of processing (e.g. file and command names). The +_filedir and _filedir_xspec helpers do this automatically whenever +they return some completions. + +[[ ${COMPREPLY-} == *= ]] && compopt -o nospace +------------------------------------------------ + +The above is functionally a shorthand for: +---- +if [[ ${#COMPREPLY[@]} -eq 1 && ${COMPREPLY[0]} == *= ]]; then + compopt -o nospace +fi +---- +It is used to ensure that long options' name won't get a space +appended after the equal sign. Calling compopt -o nospace makes sense +in case completion actually occurs: when only one completion is +available in COMPREPLY. + +$split && return +---------------- + +Should be used in completions using the -s flag of _init_completion, +or other similar cases where _split_longopt has been invoked, after +$prev has been managed but before $cur is considered. If $cur of the +form --foo=bar was split into $prev=--foo and $cur=bar and the $prev +block did not process the option argument completion, it makes sense +to return immediately after the $prev block because --foo obviously +takes an argument and the remainder of the completion function is +unlikely to provide meaningful results for the required argument. +Think of this as a catch-all for unknown options requiring an +argument. + +Note that even when using this, options that are known to require an +argument but for which we don't have argument completion should be +explicitly handled (non-completed) in the $prev handling block because +--foo=bar options can often be written without the equals sign, and in +that case the long option splitting does not occur. + +Use arithmetic evaluation +------------------------- + +When dealing with numeric data, take advantage of arithmetic evaluation. +In essence, use (( ... )) whenever it can replace [[ ... ]] because the +syntax is more readable; no need for $-prefixes, numeric comparison etc +operators are more familiar and easier on the eye. + +Array subscript access +---------------------- + +Array subscripts are arithmetic expressions, take advantage of that. +E.g. write ${foo[bar]}, not ${foo[$bar]}, and similarly ${foo[bar+1]} +vs ${foo[((bar+1))]} or ${foo[$((bar+1))]}, ${foo[--i]} vs ${foo[((--i))]}. + +Loop variable names +------------------- + +Use i, j, k for loop-local indices; n and m for lengths; some other descriptive +name typically based on array name but in singular when looping over actual +values. If an index or value is to be accessed later on instead of being just +locally for looping, use a more descriptive and specific name for it. + +///////////////////////////////////////// +case/esac vs if +--------------- + +quoting +------- + +awk vs cut for simple cases +--------------------------- + +variable and function naming +---------------------------- + +///////////////////////////////////////// diff --git a/doc/testing.txt b/doc/testing.txt new file mode 100644 index 0000000..3ec7c97 --- /dev/null +++ b/doc/testing.txt @@ -0,0 +1,112 @@ +Automated testing +================= + +Introduction +------------ +The bash-completion package contains an automated test suite. Running the +tests should help verifying that bash-completion works as expected. The tests +are also very helpful in uncovering software regressions at an early stage. + +The test suite is written in Python, using https://pytest.org/[pytest] +and https://pexpect.readthedocs.io/[pexpect]. + + +Coding Style Guide +------------------ + +For the Python part, all of it is formatted using +https://github.com/ambv/black[Black], and we also run +https://flake8.pycqa.org/[Flake8] on it. + + +Installing dependencies +----------------------- + +Installing dependencies should be easy using your local package manager or +`pip`. Python 3.4 or newer is required, and the rest of the Python package +dependencies are specified in the `test/requirements.txt` file. If using `pip`, +this file can be fed directly to it, e.g. like: +------------------------------------ +pip install -r test/requirements.txt +------------------------------------ + + +Debian/Ubuntu +~~~~~~~~~~~~~ + +On Debian/Ubuntu you can use `apt-get`: +------------- +sudo apt-get install python3-pytest python3-pexpect +------------- +This should also install the necessary dependencies. Only Debian testing +(buster) and Ubuntu 18.10 (cosmic) and later have an appropriate version +of pytest in the repositories. + +Fedora/RHEL/CentOS +~~~~~~~~~~~~~~~~~~ + +On Fedora and RHEL/CentOS (with EPEL) you can try `yum` or `dnf`: +------------- +sudo yum install python3-pytest python3-pexpect +------------- +This should also install the necessary dependencies. At time of writing, only +Fedora 29 comes with recent enough pytest. + + + +Structure +--------- + +Tests are in the `t/` subdirectory, with `t/test_\*.py` being completion +tests, and `t/unit/test_unit_\*.py` unit tests. + + +Running the tests +----------------- + +Tests are run by calling `pytest` on the desired test directories or +individual files, for example in the project root directory: +----------------------- +pytest test/t +----------------------- + +See `test/docker/docker-script.sh` for how and what we run and test in CI. + + +Specifying bash binary +~~~~~~~~~~~~~~~~~~~~~~ + +The test suite standard uses `bash` as found in PATH. Export the +`bashcomp_bash` environment variable with a path to another bash executable if +you want to test against something else. + + +Maintenance +----------- + + +Adding a completion test +~~~~~~~~~~~~~~~~~~~~~~~~ + +You can run `cd test && ./generate cmd` to add a test for the `cmd` +command. Additional arguments will be passed to the first generated test case. +This will add the `test/t/test_cmd.py` file with a very basic test, and add it +to `test/t/Makefile.am`. Add additional tests to the generated file. + +Rationale +--------- + + +Naming conventions +~~~~~~~~~~~~~~~~~~ + +Test suite or testsuite +^^^^^^^^^^^^^^^^^^^^^^^ +The primary Wikipedia page is called +https://en.wikipedia.org/wiki/Test_suite[test suite] and not testsuite, so +that's what this document sticks to. + +script/generate +^^^^^^^^^^^^^^^ +The name and location of this code generation script come from Ruby on Rails' +https://en.wikibooks.org/wiki/Ruby_on_Rails/Tools/Generators[script/generate]. -- cgit v1.2.3