Merge 5359bbf0e7 into 4c84ebad53

Update dget, diana, do-release-upgrade, direnv, clang-format, jest

src/_clang-format

@@ -49,7 +49,7 @@ _arguments \
   '(-n --dry-run)'{-n,--dry-run}'[If set, do not actually make the formatting changes]' \
   '--dump-config[Dump configuration options to stdout and exit]' \
   '--fail-on-incomplete-format[If set, fail with exit code 1 on incomplete format]' \
-  '--fallback-style=[The name of the predefined style used as a fallback]: :'"($styles)" \
+  '--fallback-style=[The name of the predefined style used as a fallback]: :($styles)' \
   '--ferror-limit=[Set the maximum number of clang-format errors to emit before stopping]:limit' \
   '*--files=[Provide a list of files to run clang-format]: :_files' \
   '--fno-color-diagnostics[If set, not to print diagnostics in color]' \
@@ -63,7 +63,7 @@ _arguments \
   '--print-options[Print non default options after command line parsing]' \
   '--qualifier-alignment=[If set, overrides the qualifier alignment style determined by the QualifierAlignment style flag]' \
   '--sort-includes[If set, overrides the include sorting behavior determined by the SortIncludes style flag]' \
-  '--style=[Set coding style]: :'"($styles)" \
+  '--style=[Set coding style]: :($styles)' \
   '--verbose[If set, show the list of processed files]' \
   '(- *)--version[Display the version of this program]' \
   '*: :_files'

src/_dget

@@ -28,7 +28,7 @@
 # Description
 # -----------
 #
-#  Completion script for dget 2.22.2
+#  Completion script for dget 2.25.19
 #
 # ------------------------------------------------------------------------------
 # Authors
@@ -39,11 +39,7 @@
 #
 # ------------------------------------------------------------------------------
 
-_dget() {
-  local context state line expl
-  local -A opt_args
-
-  _arguments -A "-*" \
+_arguments -A "-*" \
   '(- *)'{-h,--help}'[Show help message]' \
   '(- *)'{-v,--version}'[Print license, copyright, and version information and exit]' \
   '(-a --all)'{-a,--all}'[Package is a source package; download all binary packages]' \
@@ -54,13 +50,10 @@ _dget() {
   '(--no-conf -u --allow-unauthenticated)'{-u,--allow-unauthenticated}'[Make no attempt to verify source package signature]' \
   '(--no-conf -x --extract -d --download-only --build)--build[Build package with dpkg-buildpackage after download]' \
   '(--no-conf)--path[Check this directory in addition to the apt archive]:DIR:_files -/' \
-    '(--no-conf --insecure)--insecure[Do not check SSL certificates when downloading]' \
+  '(--no-conf -k --insecure)'{-k,--insecure}'[Do not check SSL certificates when downloading]' \
   '(--no-conf --no-cache)--no-cache[Disable server-side HTTP cache]' \
   "(--no-conf)--no-conf[Don't read devscripts config files]" \
   '(-)*:debian package or URL: _alternative "_deb_packages available" "_urls"'
-}
-
-_dget "$@"
 
 # Local Variables:
 # mode: Shell-Script

src/_diana

@@ -105,14 +105,10 @@ _diana_command_arguments() {
       _describe -t output 'Downloads to preview' GIDs
       ;;
   esac
-
-
 }
 
-_diana() {
-    local -a commands
-
-    commands=(
+_diana_subcommands() {
+  local -a commands=(
     "list:Output the list of active downloads."
     "paused:Output the list of paused downloads."
     "stopped:Output the list of stopped downloads."
@@ -132,19 +128,17 @@ _diana() {
     "clean:Stop seeding completed downloads."
   )
 
-_arguments -C \
-  '1:cmd:->cmds' \
-  '*:: :->args' \
-
-case "$state" in
-  (cmds)
   _describe -t commands 'commands' commands
-  ;;
-  (*)
-    _diana_command_arguments
-  ;;
-esac
 }
 
-_diana
+_arguments \
+  '1:cmd:_diana_subcommands' \
+  '*:: :_diana_command_arguments'
 
+# Local Variables:
+# mode: Shell-Script
+# sh-indentation: 2
+# indent-tabs-mode: nil
+# sh-basic-offset: 2
+# End:
+# vim: ft=zsh sw=2 ts=2 et

src/_direnv

@@ -43,9 +43,11 @@ _direnv_commands() {
     'grant:Grants direnv permission to load the given .envrc or .env file'
     'block:Revokes the authorization of a given .envrc or .env file'
     'deny:Revokes the authorization of a given .envrc or .env file'
+    'disallow:Revokes the authorization of a given .envrc or .env file'
     'revoke:Revokes the authorization of a given .envrc or .env file'
     'edit:Opens PATH_TO_RC or the current .envrc or .env into an $EDITOR and allow the file to be loaded afterwards'
     'exec:Executes a command after loading the first .envrc or .env found in DIR'
+    'export:Loads an .envrc or .env and prints the diff in terms of exports'
     "fetchurl:Fetches a given URL into direnv's CAS"
     'help:shows this help'
     'hook:Used to setup the shell hook'
@@ -82,6 +84,12 @@ _direnv() {
             '2:command:_command_names' \
             && ret=0
           ;;
+        (export)
+          local -a supported_shells=(bash elvish gha gzenv murex tcsh vim zsh fish json pwsh systemd)
+          _arguments \
+            '1:shell:($supported_shells)' \
+            && ret=0
+          ;;
         (hook)
           _arguments \
             '1:shell:(bash zsh fish tcsh elvish)' \

src/_do-release-upgrade

@@ -24,7 +24,7 @@
 # Description
 # -----------
 #
-#  Completion script for do-release-upgrade 23.10.10
+#  Completion script for do-release-upgrade 25.10.7
 #
 # ------------------------------------------------------------------------------
 # Authors
@@ -40,12 +40,10 @@ _arguments \
   '(-d --devel-release)'{-d,--devel-release}'[Upgrade to the development release]' \
   '--data-dir=[Directory that contains the data files]:dir:_files -/' \
   '(-p --proposed)'{-p,--proposed}'[Try upgrading to the latest release using the upgrade from \$distro-proposed]' \
-  '(-m --mode)'{-m,--mode=}'[Run in a special upgrade mode]:mode:(desktop server)' \
   '(-f --frontend)'{-f,--frontend}'[Run the specified frontend]:frontend' \
   '(- *)--check-dist-upgrade-only[Check only if a new distribution release is available]' \
   '--allow-third-party[Try the upgrade with third party mirrors and repositories]' \
-  '(-q --quiet)'{-q,--quiet}'[Quiet mode]' \
-  \*{-e,--env=}'[A comma-separated list of environment variables]'
+  '(-q --quiet)'{-q,--quiet}'[Quiet mode]'
 
 # Local Variables:
 # mode: Shell-Script

src/_drush

@@ -1,191 +0,0 @@
-#compdef drush
-# ------------------------------------------------------------------------------
-# Copyright (c) 2014 Github zsh-users - https://github.com/zsh-users
-# All rights reserved.
-#
-# Redistribution and use in source and binary forms, with or without
-# modification, are permitted provided that the following conditions are met:
-#     * Redistributions of source code must retain the above copyright
-#       notice, this list of conditions and the following disclaimer.
-#     * Redistributions in binary form must reproduce the above copyright
-#       notice, this list of conditions and the following disclaimer in the
-#       documentation and/or other materials provided with the distribution.
-#     * Neither the name of the zsh-users nor the
-#       names of its contributors may be used to endorse or promote products
-#       derived from this software without specific prior written permission.
-#
-# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
-# ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
-# WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
-# DISCLAIMED. IN NO EVENT SHALL ZSH-USERS BE LIABLE FOR ANY
-# DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
-# (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
-# LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
-# ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
-# (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
-# SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
-# ------------------------------------------------------------------------------
-# Description
-# -----------
-#
-#  Completion script for Drush (https://drushcommands.com/).
-#
-# ------------------------------------------------------------------------------
-# Authors
-# -------
-#
-#  * Vasily Kraev (https://github.com/vasilykraev)
-#
-# ------------------------------------------------------------------------------
-
-_drush() {
-  local curcontext='$curcontext' state line cmds ret=1
-  integer NORMARG
-  typeset -A opt_args
-
-  global_args=('--debug' '--verbose' '--yes' '--no' '--simulate' '--root=' '--uri=')
-
-  _arguments -C \
-    '(--*)'{--version,--version}'[Show drush version.]' \
-    '(- *)'{-d,--debug}'[Display even more information, including internal messages.]' \
-    '(- *)'{-v,--verbose}'[Display extra information about the command.]' \
-    '(- *)'{-y,--yes}'[Assume "yes" as answer to all prompts.]' \
-    '(- *)'{-n,--no}'[Assume "no" as answer to all prompts.]' \
-    '(- *)'{-s,--simulate}'[Simulate all relevant actions (don'\''t actually change the system).]' \
-    '(- *)'{-r,--root=}'[Drupal root directory to use (default: current directory).]' \
-    '(- *)'{-l,--uri=}'[URI of the drupal site to use (only needed in multisite environments or when running on an alternate port).]' \
-    '1: :->cmds' \
-    '*::arg:->args' \
-  && ret=0
-
-case $state in
-  cmds)
-    _values 'drush command' \
-      '(archive-dump)'{archive-dump,ard,arb}'[Backup your code, files, and database into a single file.]' \
-      '(archive-restore)'{archive-restore,arr}'[Expand a site archive into a Drupal web site.]' \
-      '(cache-clear)'{cache-clear,cc}'[Clear a specific cache, or all drupal caches.]' \
-      '(core-status)'{core-status,status,st}'[Provides a birds-eye view of the current Drupal installation, if any.]' \
-      '(core-cron)'{core-cron,cron}'[Run all cron hooks in all active modules for specified site.]' \
-      '(core-execute)'{core-execute,exec}'[Execute a shell command. Usually used with a site alias.]' \
-      '(drupal-directory)'{drupal-directory,dd}'[Return the filesystem path for modules/themes and other key folders.]' \
-      'help[Print this help message.]' \
-      'image-flush[Flush all derived images for a given style.]' \
-      '(site-alias)'{site-alias,sa}'[Print an alias record.]' \
-      '(site-install)'{site-install,si}'[Install Drupal along with modules/themes/configuration using the specified install profile.]' \
-      'test-clean[Clean temporary tables and files.]' \
-      'test-run[Run tests. Note that you must use the --uri option.]' \
-      '(updatedb)'{updatedb,updb}'[Apply any database updates required (as with running update.php).]' \
-      '(variable-delete)'{variable-delete,vdel}'[Delete a variable.]' \
-      '(variable-get)'{variable-get,vget}'[Get a list of some or all site variables and values.]' \
-      '(variable-set)'{variable-set,vset}'[Set a variable.]' \
-      '(pm-list)'{pm-list,pml}'[Show a list of available extensions (modules and themes).]' \
-      '(pm-disable)'{pm-disable,dis}'[Disable one or more extensions (modules or themes). Disable dependent extensions as well.]' \
-      '(pm-download)'{pm-download,dl}'[Download projects from drupal.org or other sources.]' \
-      '(pm-enable)'{pm-enable,en}'[Enable one or more extensions (modules or themes). Enable dependent extensions as well.]' \
-      'pm-uninstall[Uninstall one or more modules.]' \
-      'pm-update[Update Drupal core and contrib projects and apply any pending database updates (Same as pm-updatecode + updatedb).]' \
-      '(sql-cli)'{sql-cli,sqlc}'[Open a SQL command-line interface using Drupals credentials.]' \
-      'sql-drop[Drop all tables in a given database.]' \
-      'sql-dump[Exports the Drupal DB as SQL using mysqldump or equivalent.]' \
-      '(sql-query)'{sql-query,sqlq}'[Execute a query against the site database.]' \
-      'sql-sync[Copy and import source database to target database. Transfers via rsync.]' \
-      '(user-login)'{user-login,uli}'[Display a one time login link for the given user account (defaults to uid 1).]' \
-      '(user-password)'{user-password,upwd}'[(Re)Set the password for the user account with the specified name.]' \
-      '(devel-reinstall)'{devel-reinstall,dre}'[Disable, Uninstall, and Install a list of projects. (devel)]' \
-      '(devel-token)'{devel-token,token}'[List available tokens (devel)]' \
-      '(generate-content)'{generate-content,genc}'[Create content. (devel_generate)]' \
-      '(generate-menus)'{generate-menus,genm}'[Create menus and menu items. (devel_generate)]' \
-      '(generate-terms)'{generate-terms,gent}'[Create terms in specified vocabulary. (devel_generate)]' \
-      '(generate-users)'{generate-users,genu}'[Create users. (devel_generate)]' \
-      '(generate-vocabs)'{generate-vocabs,genv}'[Create vocabularies. (devel_generate)]' \
-      '(features-diff)'{features-diff,fd}'[Show the difference between the default and overridden state of a feature.]' \
-      '(features-export)'{features-export,fe}'[Export a feature from your site into a module.]' \
-      '(features-list)'{features-list,fl}'[List all the available features for your site.]' \
-      '(features-revert)'{features-revert,fr}'[Revert a feature module on your site.]' \
-      '(features-revert-all)'{features-revert-all,fra}'[Revert all enabled feature module on your site.]' \
-      '(features-update)'{features-update,fu}'[Update a feature module on your site.]' \
-      '(features-update-all)'{features-update-all,fua}'[Update all feature modules on your site.]' \
-  && ret=0
-    ;;
-  args)
-    case $line[1] in
-      (archive-dump|ard)
-        _arguments \
-          '(--description)--description=[Filter out extensions that are provided by drupal core.]' \
-          '(--destination)--destination=[The full path and filename in which the archive should be stored. If omitted, it will be saved to the drush-backups directory.]' \
-          '(--no-core)--no-core[Exclude Drupal core, so the backup only contains the site specific stuff.]' \
-          '(--pipe)--pipe[Only print the destination of the archive. Useful for scripts that don'\''t pass --destination.]' \
-          '(--tar-options)--tar-options=[Options passed thru to the tar command.]' \
-        && ret=0
-        compadd -a global_args
-      ;;
-      (archive-restore|arr)
-        _arguments \
-          '(--db-prefix)--db-prefix[An optional table prefix to use during restore.]' \
-          '(--db-su)--db-su[Account to use when creating the new database. Optional.]' \
-          '(--db-su-pw)--db-su-pw[Password for the "db-su" account. Optional.]' \
-          '(--db-url)--db-url=[A Drupal 6 style database URL indicating the target for database restore. If not provided, the archived settings.php is used. ]' \
-          '(--destination)--destination[Specify where the Drupal site should be expanded, including the docroot. Defaults to the current working directory.]' \
-          '(--overwrite)--overwrite[Allow drush to overwrite any files in the destination.]' \
-        && ret=0
-        compadd -a global_args
-      ;;
-      (user-password|upwd)
-        _arguments \
-          '--password=:Set the password for the username someuser.' \
-        && ret=0
-      ;;
-      (help)
-        _values 'commands' 'arb' 'archive-dump' 'archive-restore' 'ard' 'arr' 'cache-clear' 'cc' 'core-cron' 'core-execute' 'core-status' 'cron' 'dd' 'devel-reinstall' 'devel-token' 'dis' 'dl' 'dre' 'drupal-directory' 'en' 'exec' 'fd' 'fe' 'features-diff' 'features-export' 'features-list' 'features-revert' 'features-revert-all' 'features-update' 'features-update-all' 'fl' 'fr' 'fra' 'fu' 'fua' 'genc' 'generate-content' 'generate-menus' 'generate-terms' 'generate-users' 'generate-vocabs' 'genm' 'gent' 'genu' 'genv' 'help' 'image-flush' 'pm-disable' 'pm-download' 'pm-enable' 'pm-list' 'pm-uninstall' 'pm-update' 'pml' 'sa' 'si' 'site-alias' 'site-install' 'sql-cli' 'sql-drop' 'sql-dump' 'sql-query' 'sql-sync' 'sqlc' 'sqlq' 'st' 'status' 'test-clean' 'test-run' 'token' 'uli' 'updatedb' 'updb' 'upwd' 'user-login' 'user-password' 'variable-delete' 'variable-get' 'variable-set' 'vdel' 'vget' 'vset'
-      ;;
-      (cc)
-        _values 'options' 'all' 'drush' 'theme-registry' 'menu' 'css-js' 'block'
-      ;;
-      (pm-list|pml)
-        _arguments \
-          '(--core)--core[Filter out extensions that are not in drupal core.]' \
-          '(--no-core)--no-core[Filter out extensions that are provided by drupal core.]' \
-          '(--pipe)--pipe[Returns a whitespace delimited list of the names of the resulting extensions.]' \
-          '(--status)--status=-[Filter by extension status. Choices: enabled, disabled and/or "not installed".]:status:(enabled disabled)' \
-          '(--type)--type=-[Filter by extension type. Choices: module, theme.]:type:(module theme)' \
-        && ret=0
-      ;;
-      (pm-disable|dis)
-        _modules=( $(drush pml --status=enabled --pipe) )
-        if [[ $_modules != "" ]]; then
-          _values 'enabled modules' $_modules
-        fi
-      ;;
-      (pm-enable|en)
-        _arguments -C \
-          '--resolve-dependencies[Attempt to download any missing dependencies. At the moment, only works when the module name is the same as the project name.]' \
-          '--skip[Skip automatic downloading of libraries (c.f. devel).]' && ret=0
-        _modules=( $(drush pml --status="disabled,not installed" --pipe) )
-        if [[ $_modules != "" ]]; then
-          _values -s 'not yet enabled modules' $_modules && ret=0
-        fi
-      ;;
-      (*)
-        _values 'Global options' \
-          {-d,--debug}'[Display even more information, including internal messages.]' \
-          {-v,--verbose}'[Display extra information about the command.]' \
-          {-y,--yes}'[Assume "yes" as answer to all prompts.]' \
-          {-n,--no}'[Assume "no" as answer to all prompts.]' \
-          {-s,--simulate}'[Simulate all relevant actions (don'\''t actually change the system).]' \
-          {-r,--root=}'[Drupal root directory to use (default: current directory).]' \
-          {-l,--uri=}'[URI of the drupal site to use (only needed in multisite environments or when running on an alternate port).]'
-        ;;
-    esac
-    ;;
-esac
-}
-
-_drush '$@'
-
-# Local Variables:
-# mode: Shell-Script
-# sh-indentation: 2
-# indent-tabs-mode: nil
-# sh-basic-offset: 2
-# End:
-# vim: ft=zsh sw=2 ts=2 et

src/_jest

@@ -28,7 +28,7 @@
 # Description
 # -----------
 #
-#  Completion script for Jest 29.7.0 (https://jestjs.io/)
+#  Completion script for Jest 30.1.3 (https://jestjs.io/)
 #
 # ------------------------------------------------------------------------------
 # Authors
@@ -41,112 +41,114 @@
 local curcontext=$curcontext state line ret=1
 declare -A opt_args
 
+local -a notify_modes=("always" "failure" "success" "change" "success-change" "failure-change")
+
 _arguments -C -s \
   '(- : *)'{-h,--help}'[Show help]' \
   '(- : *)'--version'[Show version number]' \
-  --all'[The opposite of `onlyChanged`.]' \
-  --automock'[Automock all files by default.]' \
-  '(-b --bail)'{-b,--bail}'[Exit the test suite immediately after `n` number of failing tests.]' \
-  --cache'[Whether to use the transform cache.]' \
-  --cacheDirectory'[The directory where Jest should store its cached dependency information.]:directories:_dirs' \
-  --changedFilesWithAncestor'[Runs tests related to the current changes and the changes made in the last commit.]' \
-  --changedSince'[Runs tests related to the changes since the provided branch.]:string' \
-  --ci'[Whether to run Jest in continuous integration (CI) mode.]' \
-  --clearCache'[Clears the configured Jest cache directory and then exits.]' \
-  --clearMocks'[Automatically clear mock calls, instances, contexts and results before every test.]' \
-  --collectCoverageFrom'[A glob pattern relative to <rootDir> matching the files that coverage info needs to be collected from.]:string' \
-  '(--color --colors)'{--color,--colors}'[Forces test results output color highlighting (even if stdout is not a TTY).]' \
-  '(-c --config)'{-c,--config}'[The path to a jest config file specifying how to find and execute tests.]:files:_files' \
-  '(--coverage --collectCoverage)'{--coverage,--collectCoverage}'[Indicates that test coverage information should be collected and reported in the output.]' \
-  --coverageDirectory'[The directory where Jest should output its coverage files.]:directories:_dirs' \
-  --coveragePathIgnorePatterns'[An array of regexp pattern strings that are matched against all file paths before executing the test.]:array:' \
-  --coverageProvider'[Select between Babel and V8 to collect coverage]:choices:(babel v8)' \
-  --coverageReporters'[A list of reporter names that Jest uses when writing coverage reports.]:array' \
-  --coverageThreshold'[A JSON string with which will be used to configure minimum threshold enforcement for coverage results]:string' \
-  --debug'[Print debugging info about your jest config.]' \
-  --detectLeaks'[**EXPERIMENTAL**: Detect memory leaks in tests.]' \
-  --detectOpenHandles'[Print out remaining open handles preventing Jest from exiting at the end of a test run.]' \
-  '(--env --testEnvironment)'{--env,--testEnvironment}'[The test environment used for all tests.]:files:_files' \
-  --errorOnDeprecated'[Make calling deprecated APIs throw helpful error messages.]' \
-  '(-e --expand)'{-e,--expand}'[Use this flag to show full diffs instead of a patch.]' \
-  --filter'[Path to a module exporting a filtering function.]:string' \
-  --findRelatedTests'[Find related tests for a list of source files that were passed in as arguments.]' \
-  --forceExit'[Force Jest to exit after all tests have completed running.]' \
-  --globalSetup'[The path to a module that runs before All Tests.]:files:_files' \
-  --globalTeardown'[The path to a module that runs after All Tests.]:files:_files' \
-  --globals'[A JSON string with map of global variables that need to be available in all test environments.]:string' \
-  --haste'[A JSON string with map of variables for the haste module system]:string' \
-  --ignoreProjects'[Ignore the tests of the specified projects.]:array' \
-  --init'[Generate a basic configuration file]' \
-  --injectGlobals'[Should Jest inject global variables or not]' \
-  --json'[Prints the test results in JSON.]' \
-  --lastCommit'[Run all tests affected by file changes in the last commit made.]' \
-  --listTests'[Lists all tests Jest will run given the arguments and exits.]' \
-  --logHeapUsage'[Logs the heap usage after every test.]' \
-  --maxConcurrency'[Specifies the maximum number of tests that are allowed to run concurrently.]:number' \
-  '(-w --maxWorkers)'{-w,--maxWorkers}'[Specifies the maximum number of workers the worker-pool will spawn for running tests.]:string' \
-  --moduleDirectories'[An array of directory names to be searched recursively up from the requiring module'"'"'s location.]:directories:_dirs' \
-  --moduleFileExtensions'[An array of file extensions your modules use.]:array' \
-  --moduleNameMapper'[A JSON string with a map from regular expressions to module names or to arrays of module names that allow to stub out resources]:string' \
-  --modulePathIgnorePatterns'[An array of regexp pattern strings that are matched against all module paths before those paths are to be considered "visible" to the module loader.]:array' \
-  --modulePaths'[An array of absolute paths to additional locations to search when resolving modules.]:directories:_dirs' \
-  --no-cache'[Do not use the transform cache.]' \
-  --no-watchman'[Disable watchman for file crawling.]' \
-  --noStackTrace'[Disables stack trace in test results output]' \
-  --notify'[Activates notifications for test results.]' \
-  --notifyMode'[Specifies when notifications will appear for test results.]:string' \
-  '(-o --onlyChanged)'{-o,--onlyChanged}'[Attempts to identify which tests to run based on which files have changed in the current repository.]' \
-  '(-f --onlyFailures)'{-f,--onlyFailures}'[Run tests that failed in the previous execution.]' \
-  --openHandlesTimeout'[Print a warning about probable open handles if Jest does not exit cleanly after this number of milliseconds.]:number' \
-  --outputFile'[Write test results to a file when the --json option is also specified.]:files:_files' \
-  --passWithNoTests'[Will not fail if no tests are found (for example while using `--testPathPattern`.)]' \
-  --preset'[A preset that is used as a base for Jest'"'"'s configuration.]:string' \
-  --prettierPath'[The path to the "prettier" module used for inline snapshots.]:string' \
-  --projects'[A list of projects that use Jest to run all tests of all projects in a single instance of Jest.]:array' \
-  --randomize'[Shuffle the order of the tests within a file.]' \
-  --reporters'[A list of custom reporters for the test suite.]:array' \
-  --resetMocks'[Automatically reset mock state before every test.]' \
-  --resetModules'[If enabled, the module registry for every test file will be reset before running each individual test.]' \
-  --resolver'[A JSON string which allows the use of a custom resolver.]:string' \
-  --restoreMocks'[Automatically restore mock state and implementation before every test.]' \
-  --rootDir'[The root directory that Jest should scan for tests and modules within.]:directories:_dirs' \
-  --roots'[A list of paths to directories that Jest should use to search for files in.]:array' \
-  '(-i --runInBand)'{-i,--runInBand}'[Run all tests serially in the current process.]' \
-  --runTestsByPath'[Used when provided patterns are exact file paths.]' \
-  --runner'[Allows to use a custom runner instead of Jest'"'"'s default test runner.]:string' \
-  --seed'[Sets a seed value that can be retrieved in a tests file via `jest.getSeed()`.]:number' \
-  --selectProjects'[Run the tests of the specified projects.]:array' \
-  --setupFiles'[A list of paths to modules that run some code to configure or set up the testing environment before each test.]:files:_files' \
-  --setupFilesAfterEnv'[A list of paths to modules that run some code to configure or set up the testing framework before each test]:files:_files' \
-  --shard'[Shard tests and execute only the selected shard]:files:_files' \
-  --showConfig'[Print your jest config and then exits.]' \
-  --showSeed'[Prints the seed value in the test report summary.]' \
-  --silent'[Prevent tests from printing messages through the console.]' \
-  --skipFilter'[Disables the filter provided by --filter.]' \
-  --snapshotSerializers'[A list of paths to snapshot serializer modules Jest should use for snapshot testing.]:files:_files' \
-  --testEnvironmentOptions'[A JSON string with options that will be passed to the `testEnvironment`.]:string' \
-  --testFailureExitCode'[Exit code of `jest` command if the test run failed]:string' \
-  --testLocationInResults'[Add `location` information to the test results]' \
-  --testMatch'[The glob patterns Jest uses to detect test files.]:array' \
-  '(-t --testNamePattern)'{-t,--testNamePattern}'[Run only tests with a name that matches the regex pattern.]:string' \
-  --testPathIgnorePatterns'[An array of regexp pattern strings that are matched against all test paths before executing the test.]:array' \
-  --testPathPattern'[A regexp pattern string that is matched against all tests paths before executing the test.]:array' \
-  --testRegex'[A string or array of string regexp patterns that Jest uses to detect test files.]:array' \
-  --testResultsProcessor'[Allows the use of a custom results processor.]:string' \
-  --testRunner'[Allows to specify a custom test runner.]:string' \
-  --testSequencer'[Allows to specify a custom test sequencer.]:string' \
-  --testTimeout'[This option sets the default timeouts of test cases.]:number' \
-  --transform'[A JSON string which maps from regular expressions to paths to transformers.]:string' \
-  --transformIgnorePatterns'[An array of regexp pattern strings that are matched against all source file paths before transformation.]:array' \
-  --unmockedModulePathPatterns'[An array of regexp pattern strings that are matched against all modules before the module loader will automatically return a mock for them.]:array' \
-  '(-u --updateSnapshot)'{-u,--updateSnapshot}'[Use this flag to re-record snapshots.]' \
-  --useStderr'[Divert all output to stderr.]' \
-  --verbose'[Display individual test results with the test suite hierarchy.]' \
-  --watch'[Watch files for changes and rerun tests related to changed files.]' \
-  --watchAll'[Watch files for changes and rerun all tests.]' \
-  --watchPathIgnorePatterns'[An array of regexp pattern strings that are matched against all paths before trigger test re-run in watch mode.]:array' \
-  --watchman'[Whether to use watchman for file crawling.]' \
-  --workerThreads'[Whether to use worker threads for parallelization.]' \
+  '--all[The opposite of "onlyChanged"]' \
+  '--automock[Automock all files by default]' \
+  '(-b --bail)'{-b,--bail}'[Exit the test suite immediately after "n" number of failing tests]' \
+  '(--cache --no-cache)--cache[Use the transform cache]' \
+  '(--cache --no-cache)--no-cache[Do not use the transform cache]' \
+  '--cacheDirectory[The directory where Jest should store its cached dependency information]:dir:_files -/' \
+  '--changedFilesWithAncestor[Run tests related to the current changes and the changes made in the last commit]' \
+  '--changedSince[Run tests related to the changes since the provided branch]:string' \
+  '--ci[Run Jest in continuous integration (CI) mode]' \
+  '--clearCache[Clear the configured Jest cache directory and then exits]' \
+  '--clearMocks[Automatically clear mock calls, instances, contexts and results before every test]' \
+  '--collectCoverageFrom[A glob pattern for collecting coverage info]:string' \
+  '(--color --colors)'{--color,--colors}'[Force test results output color highlighting (even if stdout is not a TTY)]' \
+  '(-c --config)'{-c,--config}'[The path to a jest config file specifying how to find and execute tests]:files:_files' \
+  '(--coverage --collectCoverage)'{--coverage,--collectCoverage}'[Indicate that test coverage information should be collected and reported in the output]' \
+  '--coverageDirectory[The directory where Jest should output its coverage files]:dir:_files -/' \
+  '--coveragePathIgnorePatterns[An array of regexp pattern strings that are matched against all file paths before executing the test]:array' \
+  '--coverageProvider[Select between Babel and V8 to collect coverage]:choices:(babel v8)' \
+  '--coverageReporters[A list of reporter names that Jest uses when writing coverage reports]:array' \
+  '--coverageThreshold[A JSON string with which will be used to configure minimum threshold enforcement for coverage results]:string' \
+  '--debug[Print debugging info about your jest config]' \
+  '--detectLeaks[**EXPERIMENTAL**: Detect memory leaks in tests]' \
+  '--detectOpenHandles[Print out remaining open handles preventing Jest from exiting at the end of a test run]' \
+  '(--env --testEnvironment)'{--env,--testEnvironment}'[The test environment used for all tests]:files:_files' \
+  '--errorOnDeprecated[Make calling deprecated APIs throw helpful error messages]' \
+  '(-e --expand)'{-e,--expand}'[Use this flag to show full diffs instead of a patch]' \
+  '--filter[Path to a module exporting a filtering function]:string' \
+  '--findRelatedTests[Find related tests for a list of source files that were passed in as arguments]' \
+  '--forceExit[Force Jest to exit after all tests have completed running]' \
+  '--globalSetup[The path to a module that runs before All Tests]:files:_files' \
+  '--globalTeardown[The path to a module that runs after All Tests]:files:_files' \
+  '--globals[A JSON string with map of global variables that need to be available in all test environments]:string' \
+  '--haste[A JSON string with map of variables for the haste module system]:string' \
+  '--ignoreProjects[Ignore the tests of the specified projects]:array' \
+  '--injectGlobals[Should Jest inject global variables or not]' \
+  '--json[Print the test results in JSON]' \
+  '--lastCommit[Run all tests affected by file changes in the last commit made]' \
+  '--listTests[List all tests Jest will run given the arguments and exits]' \
+  '--logHeapUsage[Log the heap usage after every test]' \
+  '--maxConcurrency[Specify the maximum number of tests that are allowed to run concurrently]:number' \
+  '(-w --maxWorkers)'{-w,--maxWorkers}'[Maximum number of workers will spawn for running tests]:string' \
+  "--moduleDirectories[Directories to be searched from the requiring module's location]:dir:_files -/" \
+  '--moduleFileExtensions[An array of file extensions your modules use]:array' \
+  '--moduleNameMapper[A JSON string with a map from regular expressions to module names]:string' \
+  '--modulePathIgnorePatterns[An array of ignore module pattern]:array' \
+  '--modulePaths[An array of absolute paths to search modules]:directories:_files -/' \
+  '--noStackTrace[Disable stack trace in test results output]' \
+  '--notify[Activate notifications for test results]' \
+  '--notifyMode[Specify notification mode for test results]:mode:($notify_modes)' \
+  '(-o --onlyChanged)'{-o,--onlyChanged}'[Attempt to identify which tests to run based on which files have changed in the current repository]' \
+  '(-f --onlyFailures)'{-f,--onlyFailures}'[Run tests that failed in the previous execution]' \
+  '--openHandlesTimeout[Timeout msecs for open handle warnings]:number' \
+  '--outputFile[Output file name of test results]:files:_files' \
+  '--passWithNoTests[Will not fail if no tests are found]' \
+  "--preset[A preset that is used as a base for Jest's configuration]:string" \
+  '--prettierPath[The path to the "prettier" module used for inline snapshots]:string' \
+  '--projects[Projects that use Jest to run all tests of all projects in a single instance]:array' \
+  '--randomize[Shuffle the order of the tests within a file]' \
+  '--reporters[A list of custom reporters for the test suite]:array' \
+  '--resetMocks[Automatically reset mock state before every test]' \
+  '--resetModules[The module registry for every test file will be reset before running each test]' \
+  '--resolver[A JSON string which allows the use of a custom resolver]:string' \
+  '--restoreMocks[Automatically restore mock state and implementation before every test]' \
+  '--rootDir[The root directory that Jest should scan for tests and modules]:dir:_files -/' \
+  '--roots[A list directories that Jest should use to search for files in]:array:_files -/' \
+  '(-i --runInBand)'{-i,--runInBand}'[Run all tests serially in the current process]' \
+  '--runTestsByPath[Used when provided patterns are exact file paths]' \
+  "--runner[Use a custom runner instead of Jest's default test runner]:string" \
+  '--seed[Set a seed value that can be retrieved in a tests file via "jest.getSeed()"]:number' \
+  '--selectProjects[Run the tests of the specified projects]:array' \
+  '--setupFiles[Module paths that configure or set up the testing environment before each test]:files:_files' \
+  '--setupFilesAfterEnv[Module paths that configure or set up the testing framework before each test]:files:_files' \
+  '--shard[Shard tests and execute only the selected shard]:shard' \
+  '--showConfig[Print your jest config and then exits]' \
+  '--showSeed[Print the seed value in the test report summary]' \
+  '--silent[Prevent tests from printing messages through the console]' \
+  '--skipFilter[Disable the filter provided by --filter]' \
+  '--snapshotSerializers[Paths of snapshot serializer modules for snapshot testing]:files:_files' \
+  '--testEnvironmentOptions[Options that will be passed to the "testEnvironment"]:string' \
+  '--testFailureExitCode[Exit code of "jest" command if the test run failed]:string' \
+  '--testLocationInResults[Add "location" information to the test results]' \
+  '--testMatch[The glob patterns Jest uses to detect test files]:array' \
+  '(-t --testNamePattern)'{-t,--testNamePattern}'[Run only tests with a name that matches the regex pattern]:string' \
+  '--testPathIgnorePatterns[Regexp patterns for ignoring tests]:array' \
+  '--testPathPatterns[Regexp patterns for executing tests]:array' \
+  '--testRegex[Regexp patterns that Jest uses to detect test files]:array' \
+  '--testResultsProcessor[Specify a custom results processor]:string' \
+  '--testRunner[Specify a custom test runner]:string' \
+  '--testSequencer[Specify a custom test sequencer]:string' \
+  '--testTimeout[Default timeout of test cases]:number' \
+  '--transform[A JSON string which maps from regular expressions to paths to transformers]:string' \
+  '--transformIgnorePatterns[Ignore regexp patterns for transformation]:array' \
+  '--unmockedModulePathPatterns[Regexp patterns for unmocked modules]:array' \
+  '(-u --updateSnapshot)'{-u,--updateSnapshot}'[Re-record snapshots]' \
+  '--useStderr[Divert all output to stderr]' \
+  '--verbose[Display individual test results with the test suite hierarchy]' \
+  '--waitForUnhandledRejections[Give one event loop turn to handle unhandles rejections]' \
+  '--watch[Watch files for changes and rerun tests related to changed files]' \
+  '--watchAll[Watch files for changes and rerun all tests]' \
+  '--watchPathIgnorePatterns[Ignore patterns of watch path]:array' \
+  '(--watchman --no-watchman)--watchman[Use watchman for file crawling]' \
+  '(--watchman --no-watchman)--no-watchman[Do not use watchman for file crawling]' \
+  '--workerThreads[Use worker threads for parallelization]' \
   '*: :->file' \
   && ret=0
 

zsh-completions-howto.zh.org

@@ -0,0 +1,454 @@
+* 目录
+- [[#介绍][介绍]]
+- [[#开始][开始]]
+  - [[#让zsh知道用哪个函数补全命令][让zsh知道用哪个函数补全命令]]
+  - [[#补全gnu格式命令][补全gnu格式命令]]
+  - [[#从其它命令复制补全][从其它命令复制补全]]
+- [[#编写你自己的补全代码][编写你自己的补全代码]]
+  - [[#工具函数][工具函数]]
+  - [[#用_describe编写简单的补全函数][用_describe编写简单的补全函数]]
+  - [[#用_alternative编写补全函数][用_alternative编写补全函数]]
+  - [[#用_arguments编写补全函数][用_arguments编写补全函数]]
+  - [[#用_regex_arguments和_regex_words编写补全函数][用_regex_arguments和_regex_words编写补全函数]]
+  - [[#用_values_sep_parts和_multi_parts实现复杂补全][用_values、_sep_parts和_multi_parts实现复杂补全]]
+  - [[#用compadd直接添加补全词][用compadd直接添加补全词]]
+- [[#测试与debug][测试与debug]]
+- [[#踩坑了吧-需要小心的东西][踩坑了吧 （需要小心的东西）]]
+- [[#小贴士][小贴士]]
+- [[#其它资源][其它资源]]
+
+> 译注：本文可能有不通顺的地方，或者采用的词汇不是很正确。
+> 如果你有更好的主意，欢迎提交PR。
+
+* 介绍
+Zsh官方的补全函数文档令人费解，而且也没提供多少示例。
+写这份文档的当下我已经在网上找到了其它几份教程，但是那些教程只涉及了补全系统的一小部分。
+这份文档目的在于补全网上其它地方没涵盖的部分，同时附带示例，这样读者就可以学会如何写更高级的补全函数。
+我不会展开每一细节，但给你提供的内容和示例足以从零开始。
+如果你需要了解更多细节，你可以自行查询[[https://zsh.sourceforge.net/Doc/Release/Completion-System.html#Completion-System][官方文档]]。
+
+还请公开你所创作的任何脚本（比如fork这个仓库然后[[id:64bcd501-b0f0-48c7-b8e2-07af708b95ec][pr]]）。
+此外如果你有任何更多补充内容或对此教程的改进，欢迎做贡献。
+* 开始
+** 让zsh知道用哪个函数补全命令
+补全命令用的补全函数储存于名字以下划线“_”起始的文件，这些文件应存于$fpath变量所列出的某目录中。
+你可以将下面的代码写入你的~/.zshrc以在$fpath中新增目录：
+#+BEGIN_SRC sh
+fpath=(~/newdir $fpath)
+#+END_SRC
+一个补全函数文件的第一行长这个样：
+#+BEGIN_SRC sh
+#compdef foobar
+#+END_SRC
+这行代码表示这个文件含有补全foobar命令的代码。
+多数情况下第一行都采用这个格式，但你也可以用同一个文件补全多个不同的函数。
+查阅[[https://zsh.sourceforge.net/Doc/Release/Completion-System.html#Autoloaded-files][官方文档]]以了解更多细节。
+
+你也可以直接使用compdef命令(比如在你的~/.zshrc文件里)来告诉zsh用哪个函数补全命令：
+#+BEGIN_SRC sh
+> compdef _function foobar
+#+END_SRC
+或者对多个命令使用同一种补全：
+#+BEGIN_SRC sh
+> compdef _function foobar goocar hoodar
+#+END_SRC
+如果你想提供参数的话：
+#+BEGIN_SRC sh
+> compdef '_function arg1 arg2' foobar
+#+END_SRC
+查阅[[https://zsh.sourceforge.net/Doc/Release/Completion-System.html#Functions-4][官方文档]]以了解更多细节。
+** 补全gnu格式命令
+很多[[https://www.gnu.org/][gnu]]命令以标准化的方式列出选项描述（使用--help选项时）。
+对于这些命令你可以使用_gnu_generic函数自动创建补全，比如这样：
+#+BEGIN_SRC sh
+> compdef _gnu_generic foobar
+#+END_SRC
+或者对多个不同命令使用_gnu_generic：
+#+BEGIN_SRC sh
+> compdef _gnu_generic foobar goocar hoodar
+#+END_SRC
+你可以把这行代码放进~/.zshrc文件里。
+** 从其它命令复制补全
+如果你想要让一个命令（比如cmd1）和另一个已有补全的命令（比如cmd2)拥有相同的补全，你可以：
+#+BEGIN_SRC sh
+> compdef cmd1=cmd2
+#+END_SRC
+比如当你给一个命令创建了一个助记alias的时候会很有帮助。
+* 编写你自己的补全代码
+你可以通过阅读已有的补全函数来开始入门。
+在我的Linux系统上这些补全函数在/usr/share/zsh/functions/Completion/Unix、
+/usr/share/zsh/functions/Completion/Linux和一些其它子目录下。
+
+你会注意到这些文件频繁使用_arguments函数。
+该函数是一个工具函数，可用于编写简单的补全函数。
+_arguments函数是一个compadd内置函数的包装函数。
+compadd内置函数是一个核心函数，用于向命令行加入补全词，并控制其行为。
+不过，多数情况下你不需要使用compadd，因为有很多更易于使用的工具函数，如_arguments和_describe。
+
+对于非常基础的补全，_describe函数已经够用了。
+
+** 工具函数
+下面是一个工具函数列表，你或许会用到它们。
+工具函数的完整列表及使用方法在[[https://zsh.sourceforge.net/Doc/Release/Completion-System.html#Completion-Functions][此]]可供查阅。
+这些函数的使用示例在下一节给出。
+
+> 译注：从这里开始会出现一些术语，如定义（specification）、描述（description）、动作（action）、词汇（word）等。
+> 初次阅读可能会觉得比较困难，尤其是下面的工具函数表格，稍后教程开始一一讲解并给出示例的时候就好懂多了。
+> 定义指的是对补全规则的定义，如`_describe 定义`。
+> 描述当然指的是对命令行选项和参数的用户友好描述，补全时会显示在屏幕上，如：'-o  输出文件'
+> 词汇指的是如同'word'、'-o'、'--help'、'start'等连续的一小段字符串
+> 动作指的是匹配成功后执行的操作，比如执行某函数生成补全，或直接补全等等。
+> 选项（option）和参数指给命令提供的选项和参数，如`cp -r src dst`中，`-r`为选项，`src`和`dst`为参数。有些选项带参，如`tar -f file ...`中`-f`选项带`file`参数。
+> 候选（candidate）指可能的补全结果，如补全`tar -f`时目录下所有文件会被作为候选，补全`systemctl`时`start`、`stop`、`list-units`等指令会被作为候选。
+> 还请不要感到灰心，读下去就是了。
+
+*** 用于大部分补全的主要工具函数
+| _alternative     | 从其它工具函数或shell代码生成补全候选。                                |
+| _arguments       | 指定如何补全一命令的各选项和参数（命令选项风格为unix风格）。           |
+| _describe        | 创建由带描述的词汇（但不包含动作）组成的简单补全。比_arguments更简单。 |
+| _gnu_generic     | 为带有“--help”选项的命令补全选项。                                     |
+| _regex_arguments | 创建一先用regex表达式匹配命令行参数再执行动作/补全的函数。             |
+*** 对单个词汇进行复杂补全的工具函数
+| _values      | 补全任意词汇（值）及其参数，或逗号分隔的词汇与参数列表。                           |
+| _combination | 补全值的组合，比如域名和用户名的二元组。                                           |
+| _multi_parts | 对词汇的由符号分隔的多个部分分别补全，比如补全路径：/u/i/sy -> /usr/include/sys    |
+| _sep_parts   | 类似_multi_parts但在补全的不同部分中允许不同的分隔符。                             |
+| _sequence    | 包装另一补全函数，并补全由该函数生成的匹配列表。                                   |
+*** 用于补全特定对象种类的函数
+| _path_files     | 补全文件目录。用多个选项控制行为。                                              |
+| _files          | 使用所有选项调用_path_files，除了-g和-/。这些选项取决于file-patterns风格设置。  |
+| _net_interfaces | 补全网络接口名称。                                                              |
+| _users          | 补全用户名                                                                      |
+| _groups         | 补全组名                                                                        |
+| _options        | 补全shell选项名。                                                               |
+| _parameters     | 补全shell参数/变量名（可用模式匹配限制要补全的参数/变量名）。                   |
+*** 处理已缓存的补全的函数
+如果你有大量的补全，你可以将补全保存于一个缓存文件以快速加载。
+| _cache_invalid  | 指明补全缓存是否需要重新构建（rebuild），缓存由标识符指定   |
+| _retrieve_cache | 从缓存文件获取补全信息                          |
+| _store_cache    | 储存缓存于缓存文件，缓存由标识符指定            |
+*** 其它函数
+| _message     | 当无补全可生成时显示帮助信息。                               |
+| _regex_words | 为_regex_arguments命令生成参数。比手写参数更简单。           |
+| _guard       | 检查被补全的词汇，用于_arguments和类似函数的定义的ACTION中。 |
+*** 动作（Actions）
+许多工具函数，如_arguments、_regex_arguments、_alternative和_values，在选项/参数末尾有一个action。
+这个action指定如何补全对应的参数。
+这些action可以是如下形式之一：
+| ( )                               | 需要提供参数但未生成任何匹配                                                          |
+| (ITEM1 ITEM2)                     | 匹配列表                                                                              |
+| ((ITEM1\:'DESC1' ITEM2\:'DESC2')) | 匹配列表，带有描述。引号必须和整个定义所使用的引号不同。                              |
+| ->STRING                          | 将$state设为STRING然后继续（可在调用工具函数后用case语句检查$state的值）              |
+| FUNCTION                          | 生成匹配或完成其它操作的函数的函数名，比如_files或_message                            |
+| {EVAL-STRING}                     | 把字符串当作shell代码执行（evaluate）。可用于带参调用工具函数，如_values或_describe   |
+| =ACTION                           | 在补全命令行中插入占位词汇不改变补全点。                                              |
+
+并非所有的action种类都可用于使用action的工具函数。比如->STRING类不可用于_regex_arguments或_alternative函数。
+** 用_describe编写简单的补全函数
+_describe函数可以用于简单的补全，此类补全的选项/参数的位置与顺序无关紧要。
+你只需用一个数组参数储存这些选项和其描述，然后将数组参数的名作为参数传入_describe。
+下面的示例创建补全候选c和d（注意代码文件名应为_cmd，并且文件存于$fpath所列出的目录之下）。
+#+BEGIN_SRC sh
+#compdef cmd
+local -a subcmds
+subcmds=('c:c命令描述' 'd:d命令描述')
+_describe 'command' subcmds
+#+END_SRC
+
+你可以像下面一样使用由双横杠分隔的列表，但注意实操时会混合匹配结果，所以不应该用于不同种类的补全候选：
+#+BEGIN_SRC sh
+local -a subcmds topics
+subcmds=('c:c命令描述' 'd:d命令的描述')
+topics=('e:e帮助主题的描述' 'f:f帮助主题的描述')
+_describe 'command' subcmds -- topics
+#+END_SRC
+
+如果两个候选有相同的描述，_describe把它们集于一行，并确保描述严格按列对齐。
+_describe函数可用在_alternative、_arguments或_regex_arguments的ACTION中。
+在这种情况下你需要用括号将_describe和参数包起来，比如'TAG:DESCRIPTION:{_describe 'values' options}'
+** 用_alternative编写补全函数
+如同_describe，该函数进行简单补全，其选项/参数的顺序和位置并不重要。
+然而，与_describe的固定匹配不同，_alternative可进一步调用函数生成补全候选。
+此外，_alternative允许混合不同种类的补全候选。
+
+关于参数，该函数接受一列定义（specification），每项定义的形式为“TAG:DESCRIPTION:ACTION”（即“标签:描述:动作”），其中TAG是一个标识补全匹配种类的特殊标签。
+DESCRIPTION以标题（heading）的形式描述补全候选组，而ACTION是先前列出的动作种类之一（除了->STRING和=ACTION之外）。
+例如：
+#+BEGIN_SRC sh
+_alternative 'arguments:自定义参数:(a b c)' 'files:文件名:_files'
+#+END_SRC
+第一个定义增加了补全候选a、b和c，而第二个定义调用_files函数以补全文件目录。
+
+我们可以用反斜杠 \ 将不同定义分成几行并给每个自定义参数加入描述文字：
+#+BEGIN_SRC sh
+_alternative \
+  'args:自定义参数:((a\:"描述a" b\:"描述b" c\:"描述c"))' \
+  'files:文件名:_files'
+#+END_SRC
+
+如果我们想向_files传递参数，我们可以直接写在_files后面：
+#+BEGIN_SRC sh
+_alternative \
+  'args:自定义参数:((a\:"描述a" b\:"描述b" c\:"描述c"))' \
+  'files:文件名:_files -/'
+#+END_SRC
+
+如要用变量展开创建补全列表，必须用双引号将定义括起来，
+如：
+#+BEGIN_SRC sh
+_alternative \
+  "dirs:用户目录:($userdirs)" \
+  "pids:进程ID:($(ps -A o pid=))"
+#+END_SRC
+在此例子中第一个定义加入$userdirs变量中的词汇，第二个定义执行'ps -A o pid='并获取pid表，pid表用作补全候选。
+实操中，我们使用已有的_pids函数，而不是像上面那样手写。
+
+我们可以在ACTION中使用_values等其它工具函数以完成更复杂的补全，如：
+#+BEGIN_SRC sh
+_alternative \
+  "directories:用户目录:($userdirs)" \
+  'options:逗号分隔选项: _values -s , letter a b c'
+#+END_SRC
+该示例补全$userdirs里的项目，以及用逗号分隔的、含有a、b和/或c的列表。
+注意_values前面的空格。空格不可省略，因为_values不能接受标准compadd描述选项。
+
+和_describe一样，_alternative可用作ACTION并作为_arguments或_regex_arguments的一部分。
+** 用_arguments编写补全函数
+只需要调用_arguments函数一次就可以创造出非常智能的补全函数。该函数本身就是用于处理这种带有带参选项的命令的。
+如同_alternative函数，_arguments接受一列定义字符串参数。
+这些定义字符串指定选项和任何对应的选项参数（如：-f 文件名），或命令参数。
+
+简单的选项定义用'-OPT[DESCRIPTION]'（即'-选项[描述]'），比如：
+#+BEGIN_SRC sh
+_arguments '-s[排序后输出]' '--l[更多输出]' '-l[更多输出]'
+#+END_SRC
+选项参数可在选项描述后指定，形式用'-OPT[DESCRIPTION]:MESSAGE:ACTION'（即'-选项[描述]:消息:动作'）,
+其中MESSAGE是待显示的信息，而ACTION可以是前面的动作（Actions）章节提到的任何形式。
+比如：
+#+BEGIN_SRC sh
+_arguments '-f[输入文件]:文件名:_files'
+#+END_SRC
+
+命令参数定义用'N:MESSAGE:ACTION'（即'N:消息:动作'），其中N指定这是第N个命令参数，而MESSAGE和ACTION都和前面的一样。
+如果N被省略，则其仅表示这是（在所有已定义的参数之后的）下一个参数。如果开头（在N后面）用的是双冒号，则参数非必需。
+比如：
+#+BEGIN_SRC sh
+_arguments '-s[排序后输出]' '1:第一个参数:_net_interfaces' '::可选参数:_files' ':下一个参数:(a b c)'
+#+END_SRC
+这里第一个参数是网络接口，下一个可选参数是一个文件名，最后一个参数可以是a、b或c，而-s选项可以在任何位置被补全。
+
+_arguments函数允许所有ACTION形式（在前面的动作(Actions)章节列出）。
+这表示你可以用动作来选择case语句分支，如：
+#+BEGIN_SRC sh
+_arguments '-m[音乐文件]:文件名:->files' '-f[flags]:flag:->flags'
+case "$state" in
+    files)
+        local -a music_files
+        music_files=( Music/**/*.{mp3,wav,flac,ogg} )
+        _multi_parts / music_files
+        ;;
+    flags)
+        _values -s , 'flags' a b c d e
+        ;;
+esac
+#+END_SRC
+在此例子中指向音乐文件的路径被_multi_parts一步步地沿目录下降补全，
+而flags被_values函数按照逗号分隔列表补全。
+
+我已经介绍了_arguments定义的基础部分，你还可以定义互斥选项、重复选项和参数、以+开头的选项等。有关更多细节，查阅[[https://zsh.sourceforge.net/Doc/Release/Completion-System.html#Completion-System][官方文档]]。
+同时你也可以看看本文末尾列出的教程，以及[[https://github.com/vapniks/zsh-completions/tree/master/src][src目录]]下的补全函数。
+** 用_regex_arguments和_regex_words编写补全函数
+如果你的命令行定义比较复杂，有多个可能的参数序列，那你可能需要_regex_arguments函数。
+该函数也适用于有一系列跟着多个参数的关键词的情况。
+
+_regex_arguments创建名字由第一个参数给出的补全函数。
+因此你需要先调用_regex_arguments来创建补全函数，然后再调用该函数，比如：
+#+BEGIN_SRC sh
+_regex_arguments _cmd OTHER_ARGS..
+_cmd "$@"
+#+END_SRC
+
+OTHER_ARGS（即“其它参数”）是一序列用于在命令行上匹配和补全词汇的定义。
+这些序列可被'|'分隔来表示备选词汇序列。
+你可以用任意嵌套深度的括号来指定备选序列，但括号必须带反斜杠前缀，如\( \)，或用引号括起来，如'(' ')'。
+
+比如：
+#+BEGIN_SRC sh
+_regex_arguments _cmd 序列1 '|' 序列2 \( 序列2a '|' 序列2b \)
+_cmd "$@"
+#+END_SRC
+该示例定义一个匹配序列1或序列2后跟着序列2a或序列2b的命令行。这种方式和正则表达式语法类似。
+
+一个序列中的每个定义必须在开头包含一个/ PATTERN/ （即/ 模式/）部分，后跟着可选的':TAG:DESCRIPTION:ACTION'（即':标签:描述:动作'）部分。
+
+每个PATTERN是一个匹配一命令行词汇的正则表达式。这些模式按顺序匹配，直到某个模式不匹配，不匹配的模式将执行对应的ACTION（动作）以进行补全。
+注意，一定要有一个匹配命令自身的模式。
+下面有对PATTERN（模式）更详细的解释。
+
+':TAG:DESCRIPTION:ACTION'的使用方法和_alternative相同，只是开头多了个冒号“:”，并且前面列出的所有ACTION格式都可用。
+
+例如：
+#+BEGIN_SRC sh
+_regex_arguments _cmd /$'[^\0]##\0'/ \( /$'word1(a|b|c)\0'/ ':word:first word:(word1a word1b word1c)' '|'\
+ /$'word11(a|b|c)\0'/ ':word:first word:(word11a word11b word11c)' \( /$'word2(a|b|c)\0'/ ':word:second word:(word2a word2b word2c)'\
+   '|' /$'word22(a|b|c)\0'/ ':word:second word:(word22a word22b word22c)' \) \)
+_cmd "$@"
+#+END_SRC
+TODO 英文原文和例子有出入
+
+在这个例子中第一个词可以是word1（即“词1”，下同）或者word11后紧跟a、b或c，并且如果第一个词含有11，则第二个词可以是word2后紧跟a、b或c，或一个文件名。
+
+如果感觉太复杂，你也可以用更简单的_regex_words函数达到相同效果。
+*** 模式
+你可能注意到了上个例子中的/ PATTERN/和普通的正则表达式不太一样。
+通常使用的是形如$'foo\0'的字符串参数。这是为了让\0表示成null字符，而zsh内部用来分隔词汇的也是null字符。
+如果不在末尾包含\0的话，可能会无法匹配下一个词。如果你要把一个变量的值作为模式的一部分，你可以用双括号包起来，
+这样变量就会展开，然后再在后面加个包含null字符的字符串参数，比如："$somevar"$'\0'（somevar即“某变量”）。
+
+表示模式用的正则表达式语法和正常的正则表达式不太一样，但我也找不到有关的文档。
+不过我还是试图搞清楚了这些特殊字符的意义：
+| *  | 通配符 - 任何数量的字符                              |
+| ?  | 通配符 - 单个字符                                    |
+| #  | 零个或更多的上一个字符（和一般正则表达式里的*一样）  |
+| ## | 一个或更多的上一个字符（和一般正则表达式里的+一样）  |
+*** _regex_words
+_regex_words函数比_regex_arguments更简单易用。
+调用_regex_words后的结果可以存在变量里。
+
+要用_regex_words创建一个定义（specification），你需要提供一个标签，后跟一段描述，后跟一个定义不同词汇的列表。
+这些定义采用'WORD:DESCRIPTION:SPEC'（即'词汇:描述:定义'）的格式，WORD即待补全的词，DESCRIPTION是对应的描述，
+SPEC可以是由_regex_words创建的另一个变量以指定当前词后的下一个词汇，也可以留空以表示没有更多的词。
+比如：
+#+BEGIN_SRC sh
+_regex_words firstword '第一个词' 'word1a:词a:' 'word1b:词b:' 'word1c:词c'
+#+END_SRC
+该函数的返回结果将被存入$reply（reply即“回复”、“回应”）数组里，所以我们需要在$reply变化前将结果存进另一个数组里，如：
+#+BEGIN_SRC sh
+local -a firstword
+_regex_words word 'The first word' 'word1a:a word:' 'word1b:b word:' 'word1c:c word'
+firstword="$reply[@]"
+#+END_SRC
+firstword即“第一个词”。
+然后我们可以把结果用在_regex_arguments里，如：
+#+BEGIN_SRC sh
+_regex_arguments _cmd /$'[^\0]##\0'/ "$firstword[@]"
+_cmd "$@"
+#+END_SRC
+注意到我给命令自身也加了模式。
+
+这里还有个更复杂的词汇，我们调用_regex_words以匹配不同词汇
+#+BEGIN_SRC sh
+local -a firstword firstword2 secondword secondword2
+_regex_words word1 '第二个词' 'woo:鄧族' 'hoo:不关我事'
+secondword=("$reply[@]")
+_regex_words word2 '另一个第二个词' 'yee:汝' 'haa:很搞笑！'
+secondword2=("$reply[@]")
+_regex_words commands '第一个词' 'foo:做foo' 'man:yeah man' 'chu:at chu' # 译注：作者在自嗨，at chu除了比较像at you外没什么特殊意义
+firstword=("$reply[@]")
+_regex_words word4 '另一个第一个词' 'boo:吓死某人:$secondword' 'ga:嘤嘤嘤:$secondword'\
+ 'loo:上厕所:$secondword2'
+firstword2=("$reply[@]")
+
+_regex_arguments _hello /$'[^\0]##\0'/ "${firstword[@]}" "${firstword2[@]}"
+_hello "$@"
+#+END_SRC
+在这个例子中第一个词可以是"foo"、"man"、"chu"、"boo"、"ga"或"loo"。
+如果第一个词是"boo"或"ga"，那下一个词可以是"woo"或"hoo"，
+而如果第一个词是"loo"则第二个词可以是"yee"或"haa"，其它情况下没有第二个词。
+
+_ip函数是_regex_words的一个好用例。
+** 用_values、_sep_parts和_multi_parts实现复杂补全
+_values、_sep_parts和_multi_parts可以单独使用，也可以作为_alternative、_arguments或_regex_arguments定义里的ACTION。可以看看下面的例子。
+查阅[[https://zsh.sourceforge.net/Doc/Release/Completion-System.html#Completion-System][官方文档]]以了解更多信息。
+
+空格分隔的mp3文件列表：
+#+BEGIN_SRC sh
+_values 'mp3文件' ~/*.mp3
+#+END_SRC
+
+逗号分隔的会话id列表：
+#+BEGIN_SRC sh
+_values -s , '会话id' "${(uonzf)$(ps -A o sid=)}"
+#+END_SRC
+
+补全foo@news:woo、foo@news:laa或bar@news:woo等：
+#+BEGIN_SRC sh
+_sep_parts '(foo bar)' @ '(news ftp)' : '(woo laa)'
+#+END_SRC
+
+补全MAC地址，一次补全一个字节：
+#+BEGIN_SRC sh
+_multi_parts : '(00:11:22:33:44:55 00:23:34:45:56:67 00:23:45:56:67:78)'
+#+END_SRC
+
+** 用compadd直接添加补全词
+你可以使用内置的compadd函数增加补全词，以获得更细致的控制。
+这个函数有各种选项控制如何显示补全以及补全时如何替换命令行上的文字。
+阅读[[https://zsh.sourceforge.net/Doc/Release/Completion-System.html#Completion-System][官方文档]]以获得更多细节。
+这里我只给出几个简单的示例。
+
+向补全列表里加入若干词汇：
+#+BEGIN_SRC sh
+compadd foo bar blah
+#+END_SRC
+
+同上但显示注释：
+#+BEGIN_SRC sh
+compadd -X '一些注释' foo bar blah
+#+END_SRC
+
+同上但在补全前自动插入"what_"前缀
+#+BEGIN_SRC sh
+compadd -P what_ foo bar blah
+#+END_SRC
+
+同上但补全后自动插入"_todo"后缀：
+#+BEGIN_SRC sh
+compadd -S _todo foo bar blah
+#+END_SRC
+
+同上但在后缀后打空格时自动移除"_todo"后缀：
+#+BEGIN_SRC sh
+compadd -P _todo -q foo bar blah
+#+END_SRC
+
+向补全数组$wordsarray（wordsarray即“词数组”）加入词汇
+#+BEGIN_SRC sh
+compadd -a wordsarray
+#+END_SRC
+
+* 测试与debug
+重新加载补全函数：
+#+BEGIN_SRC sh
+> unfunction _func
+> autoload -U _func
+#+END_SRC
+
+这些函数会提供有用的信息。
+如果默认按键没有用，你可以尝试Alt+x然后再输入命令名。
+| 函数            | 默认按键           | 作用                                                           |
+|-----------------+--------------------+----------------------------------------------------------------|
+| _complete_help  | Ctrl+x h           | 在当前光标位置补全时显示有关上下文名称、标签和补全函数的信息   |
+| _complete_help  | Alt+2 Ctrl+x h     | 同上但显示更多信息                                             |
+| _complete_debug | Ctrl+x ?           | 执行正常补全，但跟踪补全系统执行的shell命令并存入一个临时文件  |
+* 踩坑了吧 （需要小心的东西）
+记得在补全函数的文件开头加那行#compdef
+
+_arguments或_regex_arguments的定义中要使用正确的引号：
+如果定义中有变量要展开，用双引号，其它情况用单引号，
+并且记得在ITEM（项目）描述处用不同的引号。（译注：见[[#动作Actions][动作（Actions）]]章节）
+
+_arguments、_alternative、_regex_arguments等的定义处要在正确的地方使用正确数量的冒号“:”。
+
+使用_regex_arguments时要记得在开头写匹配命令的模式（不需要加入匹配动作（action））。
+
+记得在_regex_arguments的任何PATTERN（模式）参数后加上null字符$'\0'
+* 小贴士
+有时一个子命令后只会跟一个选项，这时zsh会在tab在子命令后按下时自动补全。如果你想要在补全前先列出选项和描述，
+你可以向ACTION（动作）加入另一个空选项（比如\:），如':TAG:DESCRIPTION:((opt1\:"opt1描述" \:))'
+注意这只对在定义参数中使用ACTION的工具函数（_arguments、_regex_arguments等）有效。
+
+* 其它资源
+[[https://wikimatze.de/writing-zsh-completion-for-padrino/][这]]是个展示_arguments函数的基本使用方法的教程，短小精悍，
+而[[https://web.archive.org/web/20190411104837/http://www.linux-mag.com/id/1106/][这]]是_arguments函数的稍稍更进阶的教程。
+[[https://zsh.sourceforge.net/Doc/Release/Completion-System.html#Completion-System][这]]是zshcompsys手册页（man page）。