diff --git a/.gitignore b/.gitignore index 3f59210eca0..36a74a65b22 100644 --- a/.gitignore +++ b/.gitignore @@ -17,7 +17,5 @@ pytestdebug.log /config.status /configure /configure.lineno -/doc/*.xml -/doc/html* /install-sh /missing diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 4c52d8f2a1e..17edec6c688 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -116,23 +116,6 @@ repos: - scan exclude: ^CHANGELOG\.md$ - - repo: local - hooks: - - id: asciidoctor - name: asciidoctor - language: docker_image - entry: asciidoctor/docker-asciidoctor:1.15 asciidoctor - args: - - --out-file - - /dev/null - - --failure-level - - WARN - - --doctype - - book - - doc/main.txt - pass_filenames: false - files: ^doc/.*\.txt$ - - repo: https://github.com/pre-commit/pre-commit-hooks rev: v4.0.1 hooks: diff --git a/doc/Makefile.am b/doc/Makefile.am index d1ba538cf56..8bac9e85bbf 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -1,6 +1,4 @@ EXTRA_DIST = \ - bash_completion.txt \ - main.txt \ - makeHtml.sh \ - styleguide.txt \ - testing.txt + configuration.md \ + styleguide.md \ + testing.md diff --git a/doc/bash_completion.txt b/doc/bash_completion.txt deleted file mode 100644 index 2a5effdbab0..00000000000 --- a/doc/bash_completion.txt +++ /dev/null @@ -1,65 +0,0 @@ -= 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* the `tar` completion, it will do - correct path completion for tar file _contents_. If unset or null, - _paths to_ tar files will be correctly completed. Unfortunately we do not - have a way to make both Just Work properly at the moment. We consider it - more important to have proper completion of paths to tar files than it is - to have completion for their contents, so the default is unset. diff --git a/doc/configuration.md b/doc/configuration.md new file mode 100644 index 00000000000..7f8e2306d02 --- /dev/null +++ b/doc/configuration.md @@ -0,0 +1,75 @@ +# 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*` shell variables below. +If `$XDG_CONFIG_HOME` is unset or null,`~/.config` is +used instead of it. + +## Shell 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_ the `tar` completion, it will do +correct path completion for tar file _contents_. If unset or null, +_paths to_ tar files will be correctly completed. Unfortunately we do not +have a way to make both Just Work properly at the moment. We consider it +more important to have proper completion of paths to tar files than it is +to have completion for their contents, so the default is unset. diff --git a/doc/main.txt b/doc/main.txt deleted file mode 100644 index 4b9a9f2af93..00000000000 --- a/doc/main.txt +++ /dev/null @@ -1,19 +0,0 @@ -= Bash-completion - -Freddy Vulto (FVu) -v1.0, Mar 2009 - -[preface] -= 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 deleted file mode 100755 index 7e4f8921a4b..00000000000 --- a/doc/makeHtml.sh +++ /dev/null @@ -1,4 +0,0 @@ -#!/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.md similarity index 55% rename from doc/styleguide.txt rename to doc/styleguide.md index 9dfa9d40c3a..cd0f63f8db2 100644 --- a/doc/styleguide.txt +++ b/doc/styleguide.md @@ -1,9 +1,9 @@ -= Coding Style Guide +# Coding style guide -== Introduction +## 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 +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! @@ -13,69 +13,71 @@ 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 +## Indentation Indent step should be 4 spaces, no tabs. -== Globbing in case labels +## 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))". +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 [ ] +## `[[ ]]` vs `[ ]` -Always use [[ ]] instead of [ ]. Rationale: the former is less error +Always use `[[ ]]` instead of `[ ]`. Rationale: the former is less error prone, more featureful, and slightly faster. -== Line wrapping +## 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 \`...` +## `$( )` vs backticks When you need to do some code substitution in your completion script, -you *MUST* use the $(...) construct, rather than the \`...`. The former +you _MUST_ use the `$(...)` construct, rather than backticks. 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 +## `-o filenames` -As a rule of thumb, do not use "complete -o filenames". Doing it makes +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 +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 +`_filedir` and `_filedir_xspec` helpers do this automatically whenever they return some completions. -== `[[ ${COMPREPLY-} == *= ]] && compopt -o nospace` +## `[[ ${COMPREPLY-} == *= ]] && compopt -o nospace` The above is functionally a shorthand for: - if [[ ${#COMPREPLY[@]} -eq 1 && ${COMPREPLY[0]} == *= ]]; then - compopt -o nospace - fi +```bash +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 +appended after the equal sign. Calling `compopt -o nospace` makes sense in case completion actually occurs: when only one completion is -available in COMPREPLY. +available in `COMPREPLY`. -== `$split && return` +## `$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 +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 @@ -83,33 +85,35 @@ 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 +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 +## 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 +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 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))]}. +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 +## 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. +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. -== Function names +## Function names -Use the _comp_ prefix for all function names, and _comp_cmd_ for functions +Use the `_comp_` prefix for all function names, and `_comp_cmd_` for functions defined in per command completion files and not anywhere else. Prefixing with an underscore helps keep the functions out of the way for most command name completions (except obviously ones starting with an underscore or ones that have @@ -120,14 +124,6 @@ It is known that a lot of functions in the tree do not follow this practice. This is due to backwards compatibility reasons, but all functions introduced after version 2.11 should follow this name prefix rule. -///////////////////////////////////////// +## Variable naming -== case/esac vs if - -== quoting - -== awk vs cut for simple cases - -== variable naming - -///////////////////////////////////////// +To be written. diff --git a/doc/testing.txt b/doc/testing.md similarity index 56% rename from doc/testing.txt rename to doc/testing.md index 90598506fe9..41f4556c19b 100644 --- a/doc/testing.txt +++ b/doc/testing.md @@ -1,90 +1,81 @@ -= Automated testing +# Automated testing -== Introduction +## Introduction -The bash-completion package contains an automated test suite. Running the -tests should help verifying that bash-completion works as expected. The tests +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]. +The test suite is written in Python, using [pytest](https://pytest.org/) +and [pexpect](https://pexpect.readthedocs.io/). -== Coding Style Guide +## Coding style 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. +[Black](https://github.com/psf/black), and we also run +[Flake8](https://flake8.pycqa.org/) on it. -== Installing dependencies +## Installing dependencies Installing dependencies should be easy using your local package manager or `pip`. Python 3.6 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: ------------------------------------- + +```shell pip install -r test/requirements.txt ------------------------------------- +``` -=== Debian/Ubuntu +### Debian/Ubuntu On Debian/Ubuntu you can use `apt-get`: -------------- + +```shell 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 +### Fedora/RHEL/CentOS On Fedora and RHEL/CentOS (with EPEL) you can try `yum` or `dnf`: -------------- + +```shell 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 +## Structure -Tests are in the `t/` subdirectory, with `t/test_\*.py` being completion -tests, and `t/unit/test_unit_\*.py` unit tests. +Tests are in the `t/` subdirectory, with `t/test_*.py` being completion +tests, and `t/unit/test_unit_*.py` unit tests. -== Running the 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: ------------------------ + +```shell pytest test/t ------------------------ +``` See `test/docker/entrypoint.sh` for how and what we run and test in CI. -=== Specifying bash binary +### Specifying bash binary -The test suite standard uses `bash` as found in PATH. Export the +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 +## Maintenance -=== Adding a completion test +### 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].