docopt-completion 0.1.0__tar.gz

docopt_completion-0.1.0/PKG-INFO

@@ -0,0 +1,31 @@
+Metadata-Version: 2.4
+Name: docopt-completion
+Version: 0.1.0
+Summary: A completion for the docopt language
+License: MIT
+Author: Anders Ingemann
+Author-email: anders@ingemann.de
+Requires-Python: >=3.11.0,<4.0
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Dist: docopt (>=0.6.2,<0.7.0)
+Requires-Dist: docopt-parser (>=0.0.1,<0.0.2)
+Requires-Dist: pyyaml (>=6.0,<7.0)
+Requires-Dist: termcolor (>=1.1.0,<2.0.0)
+Project-URL: Homepage, https://github.com/andsens/docopt.completion
+Project-URL: Repository, https://github.com/andsens/docopt.completion
+Description-Content-Type: text/markdown
+
+docopt.completion
+=================
+
+A completion script generator for [docopt](http://docopt.org/) compatible help texts.
+
+The full documentation is available on [GitHub](https://github.com/andsens/docopt.completion#docoptcompletion).
+

docopt_completion-0.1.0/docopt_completion/__init__.py

@@ -0,0 +1,11 @@
+"""
+docopt.completion - A completion script generator for docopt compatible help texts.
+"""
+
+__version__: str
+try:
+  from .version import __version__  # type: ignore
+except ImportError:
+  __version__ = '0.0.0-dev'
+
+__all__ = []

docopt_completion-0.1.0/docopt_completion/__main__.py

@@ -0,0 +1,108 @@
+#!/usr/bin/env python3
+import logging
+import os
+import sys
+import typing as T
+import docopt
+import termcolor
+import yaml
+import docopt_parser as P
+from docopt_completion import __doc__ as pkg_doc, \
+  __name__ as root_name, __version__
+from docopt_completion import intermediate, tables, bash, zsh, register
+
+log = logging.getLogger(root_name)
+
+__doc__: str = T.cast(str, pkg_doc) + """
+Usage:
+  docopt-completion intermediate [FILE]
+  docopt-completion bash [FILE]
+  docopt-completion zsh [FILE]
+  docopt-completion register [--dir=DIR] (bash|zsh) COMMAND
+  docopt-completion -h
+  docopt-completion --version
+
+Reads a docopt help text on stdin, except for register. FILE is an intermediate
+with annotations.
+
+Commands:
+  intermediate  Write the YAML intermediate to stdout, or update FILE in place
+                keeping its annotations
+  bash          Write a bash completion script to stdout
+  zsh           Write a zsh completion script to stdout, for a file named _<prog>
+                in $fpath or to be sourced after compinit
+  register      Write the completion for COMMAND from its --help, which
+                regenerates itself when COMMAND changes. Without --dir the
+                script goes where bash-completion loads it from, or to
+                ${XDG_DATA_HOME:-~/.local/share}/zsh/site-functions for zsh
+
+Options:
+  --help -h  Show this help screen
+  --version  Show the docopt.completion version
+"""
+Params = T.TypedDict('Params', {
+  'intermediate': bool, 'bash': bool, 'zsh': bool, 'register': bool,
+  'FILE': 'str | None', '--dir': 'str | None', 'COMMAND': 'str | None',
+})
+
+def docopt_completion(params: Params):
+  try:
+    if params['register']:
+      shell = 'bash' if params['bash'] else 'zsh'
+      directory = params['--dir'] or register.default_dir(shell, os.environ)
+      path = register.register(shell, T.cast(str, params['COMMAND']), directory)
+      log.info(f'Wrote {path}')
+      if shell == 'zsh':
+        log.info(f'Add {directory} to $fpath before compinit if it isn\'t there already')
+      return
+    text = sys.stdin.read()
+    previous = None
+    if params['FILE'] is not None and os.path.exists(params['FILE']):
+      with open(params['FILE']) as handle:
+        previous = yaml.safe_load(handle)
+    result, orphans = intermediate.generate(text, previous)
+    for key in orphans:
+      log.warning(f'{key} no longer matches anything in the usage, dropping it')
+    if params['bash']:
+      sys.stdout.write(bash.generate(result['prog'], tables.compile(result)))
+    elif params['zsh']:
+      sys.stdout.write(zsh.generate(result['prog'], tables.compile(result)))
+    else:
+      output = yaml.safe_dump(result, sort_keys=False, default_flow_style=None, allow_unicode=True)
+      if params['FILE'] is None:
+        sys.stdout.write(output)
+      else:
+        with open(params['FILE'], 'w') as handle:
+          handle.write(output)
+  except P.DocoptError as error:
+    log.error(str(error))
+    sys.exit(error.exit_code)
+
+
+def setup_logging():
+  level_colors = {
+    logging.ERROR: 'red',
+    logging.WARN: 'yellow',
+  }
+
+  class ColorFormatter(logging.Formatter):
+
+    def format(self, record: logging.LogRecord):
+      record.msg = termcolor.colored(str(record.msg), level_colors.get(record.levelno, None))
+      return super().format(record)
+
+  stderr = logging.StreamHandler(sys.stderr)
+  if os.isatty(2):
+    stderr.setFormatter(ColorFormatter())
+  log.setLevel(level=logging.INFO)
+  log.addHandler(stderr)
+
+
+def main():
+  setup_logging()
+  params = T.cast(Params, docopt.docopt(__doc__, version=__version__))
+  docopt_completion(params)
+
+
+if __name__ == '__main__':
+  main()

docopt_completion-0.1.0/docopt_completion/bash.py

@@ -0,0 +1,43 @@
+import re
+import shlex
+from docopt_completion import tables as Tb, script
+
+compgen = {
+  'files': 'compopt -o filenames; mapfile -t -O "${#values[@]}" values < <(compgen -f -- "$2")',
+  'dirs': 'compopt -o filenames; mapfile -t -O "${#values[@]}" values < <(compgen -d -- "$2")',
+  'hosts': 'mapfile -t -O "${#values[@]}" values < <(compgen -A hostname -- "$2")',
+  'users': 'mapfile -t -O "${#values[@]}" values < <(compgen -u -- "$2")',
+  'groups': 'mapfile -t -O "${#values[@]}" values < <(compgen -g -- "$2")',
+  'commands': 'mapfile -t -O "${#values[@]}" values < <(compgen -c -- "$2")',
+  'signals': 'mapfile -t -O "${#values[@]}" values < <(compgen -A signal -- "$2")',
+  'processes': 'mapfile -t -O "${#values[@]}" values < <(compgen -W "$(ps -e -o pid=)" -- "$2")',
+}
+
+
+def source_code(source: Tb.Source) -> str:
+  if isinstance(source, str):
+    return compgen[source]
+  if 'words' in source:
+    words = ' '.join(shlex.quote(str(word)) for word in source['words'])
+    return f'local candidates=({words}); for w in "${{candidates[@]}}"; do [[ $w = "$2"* ]] && values+=("$w"); done'
+  return f'while IFS= read -r w; do [[ $w = "$2"* ]] && values+=("$w"); done < <({source["command"]})'
+
+
+def generate(prog: str, compiled: Tb.Tables, refresh: "script.Refresh | None" = None) -> str:
+  function = '_docopt_' + re.sub(r'[^A-Za-z0-9_]', '_', prog)
+  code = ''
+  if refresh is not None:
+    binary, path, regenerate = (script.quote(refresh[0]), script.quote(refresh[1]), shlex.join(refresh[2]))
+    code = f'''# Regenerate this script when {prog} changed since
+local bin
+if [[ -z ${{_docopt_refreshed-}} ]] && bin=$(type -P {shlex.quote(prog)}) && bin=$(realpath -- "$bin") \\
+  && [[ $bin != {binary} || $bin -nt {path} || $bin -ot {path} ]]; then
+  local _docopt_refreshed=1
+  if {regenerate} >/dev/null 2>&1; then
+    # shellcheck disable=SC1090
+    source {path}
+    {function} "$@"
+    return
+  fi
+fi'''
+  return script.render('bash.sh', prog, function, compiled, source_code, 0, False, code)

docopt_completion-0.1.0/docopt_completion/bash.sh

@@ -0,0 +1,138 @@
+# bash completion for "PROG", generated by docopt-completion
+
+FN() {
+  "REFRESH"
+  "TABLES"
+  # Rejoin what COMP_WORDBREAKS split (--opt=value, host:port): pieces with no whitespace between them
+  local line=${COMP_LINE:0:COMP_POINT} words=() i w
+  line=${line#*"${COMP_WORDS[0]}"}
+  for ((i=1; i<=COMP_CWORD; i++)); do
+    w=${COMP_WORDS[i]}
+    if [[ -n $w && $line = "$w"* && ${#words[@]} -gt 0 ]]; then
+      words[${#words[@]}-1]+=$w
+    else
+      words+=("$w")
+    fi
+    line=${line#*"$w"}
+  done
+  local cur=${words[${#words[@]}-1]} piece=${COMP_WORDS[COMP_CWORD]}
+  # Readline replaces only what follows the last word break, strip the rest from the replies
+  for ((i=0; i<${#piece}; i++)); do
+    [[ $COMP_WORDBREAKS = *"${piece:i:1}"* ]] || break
+  done
+  [[ $i -eq ${#piece} ]] && piece=''
+  local strip=$((${#cur} - ${#piece}))
+  unset 'words[${#words[@]}-1]'
+
+  local state=0 expect=-1 positional=false used=' ' word opt pos
+  for word in "${words[@]}"; do
+    if [[ $state = -1 ]]; then
+      return 0
+    elif [[ $expect != -1 ]]; then
+      expect=-1
+    elif ! $positional && [[ $word = -- ]]; then
+      positional=true
+      state=${st_sep[state]}
+    elif ! $positional && [[ $word = --* ]]; then
+      if HELPERS_find "${word%%=*}" true; then
+        used+="$opt "
+        [[ ${opt_arg[opt]} = 1 && $word != *=* ]] && expect=$opt
+      fi
+    elif ! $positional && [[ $word = -?* ]]; then
+      for ((pos=1; pos<${#word}; pos++)); do
+        if HELPERS_find "-${word:pos:1}" false; then
+          used+="$opt "
+          if [[ ${opt_arg[opt]} = 1 ]]; then
+            [[ $pos -eq $((${#word}-1)) ]] && expect=$opt
+            break
+          fi
+        fi
+      done
+    else
+      pos=${st_other[state]}
+      for i in "${!cmd_state[@]}"; do
+        if [[ ${cmd_state[i]} = "$state" && ${cmd_name[i]} = "$word" ]]; then
+          pos=${cmd_next[i]}
+          break
+        fi
+      done
+      state=$pos
+    fi
+  done
+  [[ $state = -1 ]] && return 0
+
+  local items=() values=() src=-1 prefix=''
+  if [[ $expect != -1 ]]; then
+    src=${opt_src[expect]}
+  elif ! $positional && [[ $cur = --*=* ]]; then
+    HELPERS_find "${cur%%=*}" true && [[ ${opt_arg[opt]} = 1 ]] || return 0
+    src=${opt_src[opt]}
+    prefix=${cur%%=*}=
+  else
+    local options=() commands=()
+    if ! $positional; then
+      for i in ${st_opts[state]}; do
+        # shellcheck disable=SC2206
+        [[ $used = *" $i "* && ${opt_rep[i]} = 0 ]] || options+=(${opt_names[i]})
+      done
+    fi
+    for i in "${!cmd_state[@]}"; do
+      [[ ${cmd_state[i]} = "$state" ]] && commands+=("${cmd_name[i]}")
+    done
+    if ! $positional && [[ $cur = -* ]]; then
+      items=("${options[@]}")
+    elif [[ ${#commands[@]} -eq 0 && ${st_other[state]} = -1 ]]; then
+      items=("${options[@]}")
+    else
+      items=("${commands[@]}")
+      src=${st_src[state]}
+    fi
+  fi
+  for w in "${items[@]}"; do
+    [[ $w = "$cur"* ]] && COMPREPLY+=("${w:strip}")
+  done
+  [[ $src = -1 ]] && return 0
+  HELPERS_source "$src" "${cur#"$prefix"}"
+  for w in "${values[@]}"; do
+    w=$prefix$w
+    COMPREPLY+=("${w:strip}")
+  done
+}
+
+# Sets $opt to the option named $1, matching long options by prefix when $2 is true
+HELPERS_find() {
+  local i n matches=() first=''
+  for i in "${!opt_names[@]}"; do
+    for n in ${opt_names[i]}; do
+      [[ $n = "$1" ]] && matches+=("$i")
+    done
+  done
+  if [[ ${#matches[@]} -eq 0 && $2 = true ]]; then
+    for i in "${!opt_names[@]}"; do
+      n=${opt_names[i]%% *}
+      if [[ $n = "$1"* ]]; then
+        [[ -n $first && $first != "$n" ]] && return 1
+        first=$n
+        matches+=("$i")
+      fi
+    done
+  fi
+  [[ ${#matches[@]} -gt 0 ]] || return 1
+  opt=${matches[0]}
+  for i in "${matches[@]}"; do
+    if [[ " ${st_opts[state]} " = *" $i "* ]]; then
+      opt=$i
+      return 0
+    fi
+  done
+}
+
+# Adds the candidates of source set $1 that start with $2 to $values
+HELPERS_source() {
+  local w
+  case $1 in
+    "SOURCES"
+  esac
+}
+
+complete -F FN "PROG"

docopt_completion-0.1.0/docopt_completion/intermediate.py

@@ -0,0 +1,136 @@
+"""
+The intermediate: a YAML document describing what to complete, generated from a docopt help text.
+
+`usage` mirrors the usage section as nested groups whose leaves are keys into `nodes`.
+`nodes` holds what was parsed (type, short, argument, default) and the annotations
+(`description`, `complete`), which the user may edit and which survive regeneration.
+
+A node key is the leaf's identifier (`<x>`, `--speed`, `move`). Adding a key that is qualified
+by the commands preceding the leaf (`shoot <x>`) or by its occurrence (`<x>#2`) splits that
+occurrence off into its own node on the next regeneration.
+"""
+import re
+import typing as T
+import docopt_parser as P
+
+Usage = T.Union[str, T.Dict[str, T.List["Usage"]]]
+Node = T.Dict[str, T.Any]
+Intermediate = T.Dict[str, T.Any]
+
+annotations = ('description', 'complete')
+
+group_names: T.Dict[type, str] = {
+  P.Choice: 'choice', P.Sequence: 'sequence', P.Optional: 'optional', P.Repeatable: 'repeatable',
+}
+leaf_types: T.Dict[type, str] = {
+  P.Command: 'command', P.Argument: 'argument', P.ArgumentSeparator: 'separator', P.Option: 'option',
+}
+
+# Last word of a placeholder name -> builtin completion source
+placeholder_sources = {
+  'file': 'files', 'path': 'files',
+  'dir': 'dirs', 'directory': 'dirs',
+  'host': 'hosts', 'hostname': 'hosts',
+  'user': 'users',
+  'group': 'groups',
+  'cmd': 'commands', 'command': 'commands',
+  'signal': 'signals', 'sig': 'signals',
+  'pid': 'processes',
+}
+
+
+def generate(text: str, previous: "Intermediate | None" = None) -> T.Tuple[Intermediate, T.List[str]]:
+  """
+  Returns the intermediate for `text` and the keys of `previous` that no longer match a node.
+  Annotations in `previous` are kept, missing ones are filled with defaults.
+  """
+  root = P.parse(text)
+  prog = P.get_prog(text).elm
+  old_nodes: T.Dict[str, Node] = previous['nodes'] if previous else {}
+  nodes: T.Dict[str, Node] = {}
+  occurrences: T.Dict[str, int] = {}
+
+  def resolve_key(ident: str, commands: T.List[str]) -> str:
+    occurrences[ident] = occurrences.get(ident, 0) + 1
+    if (key := f'{ident}#{occurrences[ident]}') in old_nodes:
+      return key
+    best, best_len = ident, 0
+    for key in old_nodes:
+      *qualifiers, last = key.split(' ')
+      if last == ident and len(qualifiers) > best_len and is_subsequence(qualifiers, commands):
+        best, best_len = key, len(qualifiers)
+    return best
+
+  def walk(node: P.Node, commands: T.List[str]) -> Usage:
+    if isinstance(node, P.Group):
+      items: T.List[Usage] = []
+      preceding = list(commands)
+      for item in node.items:
+        items.append(walk(item, commands if isinstance(node, P.Choice) else preceding))
+        if isinstance(item, P.Command):
+          preceding.append(item.ident)
+      return {group_names[type(node)]: items}
+    leaf = T.cast(P.Leaf, node)
+    ident = leaf.definition.ident if isinstance(leaf, P.Option) else leaf.ident
+    key = resolve_key(ident, commands)
+    if key not in nodes:
+      nodes[key] = node_entry(leaf, old_nodes.get(key))
+    return key
+
+  usage = walk(root, [])
+  return {'prog': prog, 'usage': usage, 'nodes': nodes}, [key for key in old_nodes if key not in nodes]
+
+
+def node_entry(leaf: P.Leaf, old: "Node | None") -> Node:
+  entry: Node = {'type': leaf_types[type(leaf)]}
+  defaults: Node = {}
+  if isinstance(leaf, P.Option):
+    definition = leaf.definition
+    if definition.short_alias and definition.short_alias != definition.ident:
+      entry['short'] = definition.short_alias
+    if leaf.doc:
+      description = re.sub(r'\s+', ' ', re.sub(r'\[default: [^]]*\]', '', leaf.doc))
+      defaults['description'] = re.sub(r' ([.,;:])', r'\1', description).strip()
+    if leaf.argname:
+      entry['argument'] = leaf.argname.elm
+      default = leaf.default
+      words = default if isinstance(default, list) else [default] if isinstance(default, str) else []
+      if words:
+        entry['default'] = list(words)
+      defaults['complete'] = complete_default(leaf.argname.elm, words)
+  elif isinstance(leaf, P.Argument):
+    defaults['complete'] = complete_default(leaf.ident, [])
+  for key in annotations:
+    if old is not None and key in old:
+      entry[key] = old[key]
+    elif key in defaults:
+      entry[key] = defaults[key]
+  return entry
+
+
+def complete_default(placeholder: str, default: T.List[str]) -> T.Any:
+  sources: T.List[T.Any] = []
+  if default:
+    sources.append({'words': default})
+  if (source := placeholder_sources.get(placeholder_word(placeholder))) is not None:
+    sources.append(source)
+  if not sources:
+    return 'none'
+  return sources[0] if len(sources) == 1 else sources
+
+
+def placeholder_word(placeholder: str) -> str:
+  """The last word of a placeholder, lowercased and singular: <config-files> -> file"""
+  words = [w for w in re.split(r'[^A-Za-z0-9]+|(?<=[a-z])(?=[A-Z])', placeholder) if w]
+  word = words[-1].lower() if words else ''
+  if word not in placeholder_sources:
+    if word.endswith('ies') and word[:-3] + 'y' in placeholder_sources:
+      return word[:-3] + 'y'
+    if word.endswith('s') and word[:-1] in placeholder_sources:
+      return word[:-1]
+  return word
+
+
+def is_subsequence(needle: T.List[str], haystack: T.List[str]) -> bool:
+  it = iter(haystack)
+  return all(item in it for item in needle)

docopt_completion-0.1.0/docopt_completion/register.py

@@ -0,0 +1,51 @@
+"""
+Completion for a docopt program that has none, generated from its `--help`. The script regenerates
+itself when the program's resolved path or modification time changes.
+"""
+import os
+import shutil
+import subprocess
+import typing as T
+import docopt_parser as P
+from docopt_completion import intermediate, tables, bash, zsh
+
+
+class NotDocoptError(P.DocoptError):
+  pass
+
+
+def default_dir(shell: str, env: T.Mapping[str, str]) -> str:
+  """Where bash-completion lazy-loads user completions from; zsh has no such place"""
+  data = env.get('XDG_DATA_HOME') or os.path.join(env['HOME'], '.local', 'share')
+  if shell == 'bash':
+    user_dir = env.get('BASH_COMPLETION_USER_DIR', '').split(':')[0] or os.path.join(data, 'bash-completion')
+    return os.path.join(user_dir, 'completions')
+  return os.path.join(data, 'zsh', 'site-functions')
+
+
+def register(shell: str, command: str, directory: str) -> str:
+  """Writes the completion script for `command` to `directory` and returns its path"""
+  found = shutil.which(command)
+  if found is None:
+    raise P.DocoptError(f'{command} not found')
+  binary = os.path.realpath(found)
+  try:
+    text = subprocess.run([found, '--help'], capture_output=True, text=True, timeout=10, check=True).stdout
+  except (subprocess.CalledProcessError, subprocess.TimeoutExpired) as error:
+    raise P.DocoptError(f'`{command} --help` failed: {error}') from error
+  result, _ = intermediate.generate(text)
+  for key, node in T.cast(T.Dict[str, T.Dict[str, T.Any]], result['nodes']).items():
+    if node['type'] == 'argument' and intermediate.placeholder_word(key) in ('option', 'options'):
+      raise NotDocoptError(f'The help of {command} looks GNU style ({key}), not docopt')
+  compiled = tables.compile(result)
+  name = os.path.basename(command)
+  path = os.path.join(directory, f'{name}.bash' if shell == 'bash' else f'_{name}')
+  refresh = (binary, path, ['docopt-completion', 'register', f'--dir={directory}', shell, command])
+  code = (bash if shell == 'bash' else zsh).generate(name, compiled, refresh)
+  os.makedirs(directory, exist_ok=True)
+  with open(path, 'w') as handle:
+    handle.write(code)
+  # The script carries the binary's mtime, a mismatch means the binary changed
+  stat = os.stat(binary)
+  os.utime(path, ns=(stat.st_atime_ns, stat.st_mtime_ns))
+  return path

docopt_completion-0.1.0/docopt_completion/script.py

@@ -0,0 +1,76 @@
+import os
+import re
+import shlex
+import typing as T
+from docopt_completion import tables as Tb
+
+# The resolved binary, the path of the script and the command that regenerates it
+Refresh = T.Tuple[str, str, T.List[str]]
+
+
+def quote(value: str) -> str:
+  """Always quoted, unlike shlex.quote: unquoted on the right of [[ x = y ]] is a pattern"""
+  return "'" + value.replace("'", "'\\''") + "'"
+
+
+def render(template: str, prog: str, function: str, compiled: Tb.Tables,
+           source_code: T.Callable[[Tb.Source], str], base: int, descriptions: bool, refresh: str = '') -> str:
+  """
+  Fill a shell template with the tables as arrays. Indexes start at `base`, `base - 1` is none.
+  `function` is the completion function, its helpers are prefixed with `_docopt_<prog>`.
+  `refresh` is code to run first in the completion function.
+  """
+  source_sets: T.List[T.List[Tb.Source]] = []
+
+  def source_set(sources: T.List[Tb.Source]) -> int:
+    if not sources:
+      return base - 1
+    if sources not in source_sets:
+      source_sets.append(sources)
+    return source_sets.index(sources) + base
+
+  def index(value: "int | None") -> int:
+    return base - 1 if value is None else value + base
+
+  def array(name: str, values: T.Iterable[T.Any]) -> str:
+    return f'local -a {name}=(' + ' '.join(shlex.quote(str(value)) for value in values) + ')'
+
+  options = compiled.options
+  states = compiled.states
+  transitions = [(i, name, target, description) for i, state in enumerate(states)
+                 for name, (target, description) in state.commands.items()]
+  table_lines = [
+    array('opt_names', (' '.join(o.names) for o in options)),
+    array('opt_arg', (int(o.argument) for o in options)),
+    array('opt_rep', (int(o.repeatable) for o in options)),
+    array('opt_src', (source_set(o.complete) for o in options)),
+    array('cmd_state', (index(t[0]) for t in transitions)),
+    array('cmd_name', (t[1] for t in transitions)),
+    array('cmd_next', (index(t[2]) for t in transitions)),
+    array('st_sep', (index(s.separator) for s in states)),
+    array('st_other', (index(s.other) for s in states)),
+    array('st_src', (source_set(s.complete) for s in states)),
+    array('st_opts', (' '.join(str(index(o)) for o in s.options) for s in states)),
+  ]
+  if descriptions:
+    table_lines += [
+      array('opt_desc', (o.description or '' for o in options)),
+      array('cmd_desc', (t[3] or '' for t in transitions)),
+    ]
+  source_lines: T.List[str] = []
+  for i, sources in enumerate(source_sets):
+    source_lines.append(f'{i + base})')
+    source_lines += [f'  {source_code(source)}' for source in sources]
+    source_lines.append('  ;;')
+
+  with open(os.path.join(os.path.dirname(__file__), template)) as handle:
+    code = handle.read()
+  return (
+    code
+    .replace('HELPERS', '_docopt_' + re.sub(r'[^A-Za-z0-9_]', '_', prog))
+    .replace('FN', function)
+    .replace('"PROG"', shlex.quote(prog))
+    .replace('"TABLES"', '\n  '.join(table_lines))
+    .replace('"SOURCES"', '\n    '.join(source_lines))
+    .replace('  "REFRESH"\n', ''.join(f'  {line}\n' for line in refresh.splitlines()))
+  )

docopt_completion-0.1.0/docopt_completion/tables.py

@@ -0,0 +1,273 @@
+"""
+Match tables compiled from the intermediate, the input for the shell generators.
+
+The positional leaves (commands, arguments, `--`) form an automaton that is compiled to a DFA
+over the command names, `--` and any other word. Options take no part in the ordering, docopt
+matches them anywhere. Instead every state lists the options that lie on some path through it.
+
+`complete()` is the reference for what the shell runtimes do with the tables.
+"""
+import typing as T
+from dataclasses import dataclass, field
+from docopt_parser import DocoptError
+
+Source = T.Union[str, T.Dict[str, T.Any]]
+builtin_sources = ('files', 'dirs', 'hosts', 'users', 'groups', 'commands', 'signals', 'processes')
+
+@dataclass
+class Option:
+  names: T.List[str]
+  argument: bool
+  repeatable: bool
+  description: "str | None"
+  complete: T.List[Source]
+
+@dataclass
+class State:
+  # command name -> (next state, description)
+  commands: T.Dict[str, T.Tuple[int, "str | None"]] = field(default_factory=dict[str, T.Tuple[int, "str | None"]])
+  # next state for `--` and for any other word
+  separator: "int | None" = None
+  other: "int | None" = None
+  # completion sources of the arguments that `other` consumes
+  complete: T.List[Source] = field(default_factory=list[Source])
+  # indexes into Tables.options
+  options: T.List[int] = field(default_factory=list[int])
+
+@dataclass
+class Tables:
+  options: T.List[Option]
+  states: T.List[State]
+
+
+def ident(key: str) -> str:
+  """`shoot <x>#2` -> `<x>`"""
+  return key.split(' ')[-1].split('#')[0]
+
+
+def sources(key: str, complete: T.Any) -> T.List[Source]:
+  items = T.cast(T.List[T.Any], complete if isinstance(complete, list) else [complete])
+  result: T.List[Source] = []
+  for item in items:
+    if item == 'none':
+      continue
+    if item in builtin_sources:
+      result.append(T.cast(str, item))
+      continue
+    if isinstance(item, dict):
+      source = T.cast(T.Dict[str, T.Any], item)
+      if len(source) == 1 and (isinstance(source.get('words'), list) or isinstance(source.get('command'), str)):
+        result.append(source)
+        continue
+    raise DocoptError(f'{key}: unknown completion source {item!r}')
+  return result
+
+
+Label = T.Tuple[str, str]  # (node type, key)
+# An NFA state and the options passed on the way to it
+Item = T.Tuple[int, T.FrozenSet[str]]
+
+def compile(intermediate: T.Dict[str, T.Any]) -> Tables:
+  nodes: T.Dict[str, T.Dict[str, T.Any]] = intermediate['nodes']
+  edges: T.List[T.List[T.Tuple["Label | None", int]]] = []
+  repeatable_options: T.Set[str] = set()
+
+  def new_state() -> int:
+    edges.append([])
+    return len(edges) - 1
+
+  def build(usage: T.Any, start: int, repeated: bool = False) -> int:
+    if isinstance(usage, str):
+      end = new_state()
+      edges[start].append(((nodes[usage]['type'], usage), end))
+      if repeated and nodes[usage]['type'] == 'option':
+        repeatable_options.add(usage)
+      return end
+    [(kind, items)] = T.cast(T.Dict[str, T.List[T.Any]], usage).items()
+    if kind == 'choice':
+      end = new_state()
+      for item in items:
+        edges[build(item, start, repeated)].append((None, end))
+      return end
+    if kind == 'optional':
+      # docopt makes every item of [a b] optional on its own
+      for item in items:
+        end = new_state()
+        edges[start].append((None, end))
+        edges[build(item, start, repeated)].append((None, end))
+        start = end
+      return start
+    if kind == 'repeatable':
+      loop = new_state()
+      edges[start].append((None, loop))
+      end = build({'sequence': items}, loop, True)
+      edges[end].append((None, loop))
+      return end
+    for item in items:
+      start = build(item, start, repeated)
+    return start
+
+  start = new_state()
+  accept = build(intermediate['usage'], start)
+
+  # States reachable from each state
+  reach: T.List[T.Set[int]] = []
+  for state in range(len(edges)):
+    seen = {state}
+    todo = [state]
+    while todo:
+      for _, target in edges[todo.pop()]:
+        if target not in seen:
+          seen.add(target)
+          todo.append(target)
+    reach.append(seen)
+  option_edges = [
+    (source, label[1], target) for source in range(len(edges))
+    for label, target in edges[source] if label is not None and label[0] == 'option'
+  ]
+
+  def after(state: int) -> T.Set[str]:
+    """Options on some path from `state` to the end"""
+    return {key for source, key, target in option_edges if source in reach[state] and accept in reach[target]}
+
+  def closure(items: T.Iterable["Item"]) -> T.FrozenSet["Item"]:
+    passed_by: T.Dict[int, T.FrozenSet[str]] = {}
+    todo = list(items)
+    while todo:
+      state, passed = todo.pop()
+      if state in passed_by and passed <= passed_by[state]:
+        continue
+      passed_by[state] = passed = passed_by.get(state, frozenset()) | passed
+      for label, target in edges[state]:
+        if label is None:
+          todo.append((target, passed))
+        elif label[0] == 'option':
+          todo.append((target, passed | {label[1]}))
+    return frozenset(passed_by.items())
+
+  option_keys = [key for key, node in nodes.items() if node['type'] == 'option']
+  options = [
+    Option(
+      names=[ident(key)] + ([nodes[key]['short']] if 'short' in nodes[key] else []),
+      argument='argument' in nodes[key],
+      repeatable=key in repeatable_options,
+      description=nodes[key].get('description'),
+      complete=sources(key, nodes[key].get('complete', 'none')),
+    ) for key in option_keys
+  ]
+
+  dfa: T.Dict[T.FrozenSet[Item], int] = {}
+  states: T.List[State] = []
+
+  def dfa_state(items: T.FrozenSet[Item]) -> "int | None":
+    if not items:
+      return None
+    if items in dfa:
+      return dfa[items]
+    index = dfa[items] = len(states)
+    state = State()
+    states.append(state)
+    outgoing = [
+      (label, (target, passed)) for s, passed in items
+      for label, target in edges[s] if label is not None and label[0] != 'option'
+    ]
+    arguments = {target for (kind, _), target in outgoing if kind == 'argument'}
+    for (kind, key), _ in outgoing:
+      if kind == 'command':
+        name = ident(key)
+        targets = {t for (k, other_key), t in outgoing if k == 'command' and ident(other_key) == name}
+        next_state = T.cast(int, dfa_state(closure(targets | arguments)))
+        description = state.commands.get(name, (0, None))[1] or nodes[key].get('description')
+        state.commands[name] = (next_state, description)
+      elif kind == 'argument':
+        for source in sources(key, nodes[key].get('complete', 'none')):
+          if source not in state.complete:
+            state.complete.append(source)
+    separators = {target for (kind, _), target in outgoing if kind == 'separator'}
+    state.separator = dfa_state(closure(separators | arguments))
+    state.other = dfa_state(closure(arguments))
+    in_scope = set[str]().union(*(passed | after(s) for s, passed in items))
+    state.options = [i for i, key in enumerate(option_keys) if key in in_scope]
+    return index
+
+  dfa_state(closure([(start, frozenset())]))
+  return Tables(options, states)
+
+
+@dataclass
+class Completion:
+  # Literal candidates with their descriptions
+  words: T.List[T.Tuple[str, "str | None"]] = field(default_factory=list[T.Tuple[str, "str | None"]])
+  # Sources for the shell to expand
+  sources: T.List[Source] = field(default_factory=list[Source])
+  # Prepended to every candidate, e.g. `--speed=`
+  prefix: str = ''
+
+
+def complete(tables: Tables, words: T.List[str], cur: str) -> Completion:
+  """Candidates for `cur` after `words` (without the program name). Not filtered by `cur`."""
+  state: "int | None" = 0
+  used: T.Set[int] = set()
+  expect: "Option | None" = None
+  positional_only = False
+
+  def find(name: str, prefix: bool) -> "int | None":
+    in_scope = tables.states[state].options if state is not None else []
+    matches = [i for i, o in enumerate(tables.options) if name in o.names]
+    if not matches and prefix:
+      matches = [i for i, o in enumerate(tables.options) if any(n.startswith(name) for n in o.names[:1])]
+      if len({tables.options[i].names[0] for i in matches}) > 1:
+        return None
+    return next((i for i in matches if i in in_scope), next(iter(matches), None))
+
+  for word in words:
+    if state is None:
+      return Completion()
+    if expect is not None:
+      expect = None
+    elif not positional_only and word == '--':
+      positional_only = True
+      state = tables.states[state].separator
+    elif not positional_only and word.startswith('--'):
+      name, eq, _ = word.partition('=')
+      if (i := find(name, True)) is not None:
+        used.add(i)
+        if tables.options[i].argument and not eq:
+          expect = tables.options[i]
+    elif not positional_only and word.startswith('-') and word != '-':
+      for pos in range(1, len(word)):
+        if (i := find('-' + word[pos], False)) is not None:
+          used.add(i)
+          if tables.options[i].argument:
+            if pos == len(word) - 1:
+              expect = tables.options[i]
+            break
+    else:
+      current = tables.states[state]
+      state = current.commands[word][0] if word in current.commands else current.other
+
+  if state is None:
+    return Completion()
+  if expect is not None:
+    return Completion(sources=expect.complete)
+  if not positional_only and cur.startswith('--') and '=' in cur:
+    name = cur.partition('=')[0]
+    if (i := find(name, True)) is not None and tables.options[i].argument:
+      return Completion(sources=tables.options[i].complete, prefix=name + '=')
+    return Completion()
+  current = tables.states[state]
+  options = Completion(words=[
+    (name, tables.options[i].description)
+    for i in current.options if i not in used or tables.options[i].repeatable
+    for name in tables.options[i].names
+  ])
+  if positional_only:
+    options = Completion()
+  if cur.startswith('-') and not positional_only:
+    return options
+  if not current.commands and current.other is None:
+    return options
+  return Completion(
+    words=[(name, description) for name, (_, description) in current.commands.items()],
+    sources=current.complete,
+  )

docopt_completion-0.1.0/docopt_completion/zsh.py

@@ -0,0 +1,40 @@
+import shlex
+from docopt_completion import tables as Tb, script
+
+compsys = {
+  'files': '_files',
+  'dirs': '_files -/',
+  'hosts': '_hosts',
+  'users': '_users',
+  'groups': '_groups',
+  'commands': '_command_names -e',
+  'signals': '_signals',
+  'processes': '_pids',
+}
+
+
+def source_code(source: Tb.Source) -> str:
+  if isinstance(source, str):
+    return f'{compsys[source]} && ret=0'
+  if 'words' in source:
+    return 'compadd -- ' + ' '.join(shlex.quote(str(word)) for word in source['words']) + ' && ret=0'
+  return f'compadd -- ${{(f)"$({source["command"]})"}} && ret=0'
+
+
+def generate(prog: str, compiled: Tb.Tables, refresh: "script.Refresh | None" = None) -> str:
+  # Named like the file compinit autoloads (_<prog>), so that the first run replaces the autoload stub
+  function = '_' + prog
+  code = ''
+  if refresh is not None:
+    binary, path, regenerate = (script.quote(refresh[0]), script.quote(refresh[1]), shlex.join(refresh[2]))
+    code = f'''# Regenerate this script when {prog} changed since
+local bin=${{commands[{prog}]:A}}
+if [[ -z $_docopt_refreshed && -n $bin && ( $bin != {binary} || $bin -nt {path} || $bin -ot {path} ) ]]; then
+  local _docopt_refreshed=1
+  if {regenerate} >/dev/null 2>&1; then
+    source {path}
+    {function} "$@"
+    return
+  fi
+fi'''
+  return script.render('zsh.sh', prog, function, compiled, source_code, 1, True, code)

docopt_completion-0.1.0/docopt_completion/zsh.sh

@@ -0,0 +1,119 @@
+#compdef "PROG"
+# zsh completion for "PROG", generated by docopt-completion
+
+FN() {
+  "REFRESH"
+  "TABLES"
+  local state=1 expect=0 positional=0 word opt pos i n
+  local -a used
+  for word in "${(@Q)words[2,CURRENT-1]}"; do
+    if (( ! state )); then
+      return 1
+    elif (( expect )); then
+      expect=0
+    elif (( ! positional )) && [[ $word = -- ]]; then
+      positional=1
+      state=$st_sep[state]
+    elif (( ! positional )) && [[ $word = --* ]]; then
+      if HELPERS_find "${word%%=*}" 1; then
+        used+=($opt)
+        (( opt_arg[opt] )) && [[ $word != *=* ]] && expect=$opt
+      fi
+    elif (( ! positional )) && [[ $word = -?* ]]; then
+      for (( pos=2; pos<=$#word; pos++ )); do
+        if HELPERS_find "-$word[pos]" 0; then
+          used+=($opt)
+          if (( opt_arg[opt] )); then
+            (( pos == $#word )) && expect=$opt
+            break
+          fi
+        fi
+      done
+    else
+      pos=$st_other[state]
+      for (( i=1; i<=$#cmd_state; i++ )); do
+        if (( cmd_state[i] == state )) && [[ $cmd_name[i] = "$word" ]]; then
+          pos=$cmd_next[i]
+          break
+        fi
+      done
+      state=$pos
+    fi
+  done
+  (( state )) || return 1
+
+  if (( expect )); then
+    HELPERS_source $opt_src[expect]
+    return
+  elif (( ! positional )) && [[ $PREFIX = --*=* ]]; then
+    HELPERS_find "${PREFIX%%=*}" 1 && (( opt_arg[opt] )) || return 1
+    compset -P '*='
+    HELPERS_source $opt_src[opt]
+    return
+  fi
+  local -a options commands
+  if (( ! positional )); then
+    for i in ${=st_opts[state]}; do
+      (( $used[(Ie)$i] && ! opt_rep[i] )) && continue
+      for n in ${=opt_names[i]}; do
+        options+=("${n//:/\\:}${opt_desc[i]:+:$opt_desc[i]}")
+      done
+    done
+  fi
+  for (( i=1; i<=$#cmd_state; i++ )); do
+    (( cmd_state[i] == state )) && commands+=("${cmd_name[i]//:/\\:}${cmd_desc[i]:+:$cmd_desc[i]}")
+  done
+  if (( ! positional )) && [[ $PREFIX = -* ]] || (( ! $#commands && ! st_other[state] )); then
+    (( $#options )) && _describe -t options option options
+    return
+  fi
+  local ret=1
+  (( $#commands )) && _describe -t commands command commands && ret=0
+  HELPERS_source $st_src[state] && ret=0
+  return ret
+}
+
+# Sets $opt to the option named $1, matching long options by prefix when $2 is 1
+HELPERS_find() {
+  local i n first
+  local -a matches
+  for (( i=1; i<=$#opt_names; i++ )); do
+    for n in ${=opt_names[i]}; do
+      [[ $n = "$1" ]] && matches+=($i)
+    done
+  done
+  if (( ! $#matches && $2 )); then
+    for (( i=1; i<=$#opt_names; i++ )); do
+      n=${${=opt_names[i]}[1]}
+      if [[ $n = "$1"* ]]; then
+        [[ -n $first && $first != "$n" ]] && return 1
+        first=$n
+        matches+=($i)
+      fi
+    done
+  fi
+  (( $#matches )) || return 1
+  opt=$matches[1]
+  for i in $matches; do
+    if (( ${${=st_opts[state]}[(Ie)$i]} )); then
+      opt=$i
+      return 0
+    fi
+  done
+  return 0
+}
+
+# Adds the candidates of source set $1
+HELPERS_source() {
+  local ret=1
+  case $1 in
+    "SOURCES"
+  esac
+  return ret
+}
+
+if [[ $zsh_eval_context[-1] = loadautofunc ]]; then
+  FN "$@"
+else
+  compdef FN "PROG"
+fi

docopt_completion-0.1.0/docs/README.pypi.md

@@ -0,0 +1,6 @@
+docopt.completion
+=================
+
+A completion script generator for [docopt](http://docopt.org/) compatible help texts.
+
+The full documentation is available on [GitHub](https://github.com/andsens/docopt.completion#docoptcompletion).

docopt_completion-0.1.0/pyproject.toml

@@ -0,0 +1,51 @@
+[tool.poetry]
+name = "docopt-completion"
+description = "A completion for the docopt language"
+version = "0.1.0"
+authors = ["Anders Ingemann <anders@ingemann.de>"]
+license = "MIT"
+readme = "docs/README.pypi.md"
+homepage = "https://github.com/andsens/docopt.completion"
+repository = "https://github.com/andsens/docopt.completion"
+classifiers = [
+  "Topic :: Software Development :: Libraries :: Python Modules",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.11",
+  "License :: OSI Approved :: MIT License",
+]
+packages = [
+  { include = "docopt_completion" },
+  { include = "docopt_completion/py.typed" },
+]
+
+[tool.flake8]
+max-line-length = 120
+ignore = "E111,E114,E121,W503,E302,E303,E305"
+
+[tool.poetry.dependencies]
+python = ">=3.11.0,<4.0"
+docopt = "^0.6.2"
+termcolor = "^1.1.0"
+pyyaml = "^6.0"
+docopt-parser = "^0.0.1"
+
+[tool.poetry.dev-dependencies]
+flake8 = "^6.0.0"
+flake8-pyproject = "^1.1.0.post0"
+pytest = "^7.1.1"
+pyright = "^1.1.238"
+types-docopt = "^0.6.11"
+
+[tool.poetry.scripts]
+docopt-completion = "docopt_completion.__main__:main"
+
+[tool.pyright]
+include = ["docopt_completion", "tests"]
+typeCheckingMode = "strict"
+exclude = [ ".venv" ]
+venvPath = "."
+venv = ".venv"
+
+[build-system]
+requires = ["poetry_core>=1.0.0"]
+build-backend = "poetry.core.masonry.api"