pyfect-dev 0.1.0__py3-none-any.whl

pyfect/cli/completions/_descriptor.py

@@ -0,0 +1,182 @@
+"""What a completion script describes (Effect's ``Completions`` descriptor
+types and internal ``completions/descriptor``): each command's visible
+flags, arguments and subcommands, read off a ``Command``."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from dataclasses import dataclass, field, replace
+from typing import Any, Literal
+
+from pyfect.cli._command import Command
+from pyfect.cli.param import ARGUMENT, FLAG, Param, Single
+from pyfect.cli.primitive import PathType
+
+
+@dataclass(frozen=True, slots=True)
+class Choice:
+    values: tuple[str, ...]
+
+
+@dataclass(frozen=True, slots=True)
+class PathKind:
+    path_type: PathType
+
+
+type ScalarTag = Literal["Boolean", "String", "Int", "Finite", "Date"]
+type FlagType = ScalarTag | Choice | PathKind
+type ArgumentType = Literal["String", "Int", "Finite", "Date"] | Choice | PathKind
+
+
+@dataclass(frozen=True, slots=True)
+class FlagDescriptor:
+    name: str
+    aliases: tuple[str, ...]
+    description: str | None
+    type: FlagType
+    optional_value: bool = False
+    negation: str | Literal[False] | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class ArgumentDescriptor:
+    name: str
+    description: str | None
+    required: bool
+    variadic: bool
+    type: ArgumentType
+
+
+@dataclass(frozen=True, slots=True)
+class CommandDescriptor:
+    name: str
+    description: str | None
+    flags: tuple[FlagDescriptor, ...] = ()
+    arguments: tuple[ArgumentDescriptor, ...] = ()
+    subcommands: tuple[CommandDescriptor, ...] = field(default=())
+
+
+_FILE_TAGS = ("FileText", "FileParse", "FileSchema")
+
+
+def _value_type(single: Single[Any]) -> Choice | PathKind | ScalarTag:  # noqa: PLR0911 - one return per tag
+    primitive = single.primitive
+    match primitive.tag:
+        case "Boolean":
+            return "Boolean"
+        case "Int":
+            return "Int"
+        case "Finite":
+            return "Finite"
+        case "Date":
+            return "Date"
+        case "Choice":
+            return Choice(primitive.choice_keys or ())
+        case "Path":
+            return PathKind(primitive.path_type or "either")
+        case tag if tag in _FILE_TAGS:
+            return PathKind("file")
+        case _:
+            return "String"
+
+
+def _argument_type(single: Single[Any]) -> ArgumentType:
+    kind = _value_type(single)
+    return "String" if kind == "Boolean" else kind
+
+
+def from_command(
+    command: Command[Any, Any, Any, Any], inherited: Sequence[Param[Any]] = ()
+) -> CommandDescriptor:
+    """The descriptor of ``command`` and its listed subcommands; local
+    flags come first, then the shared flags of its ancestors."""
+    state = command.state
+    own = state.config.flags
+    flags: list[FlagDescriptor] = []
+    seen: set[str] = set()
+    for index, flag in enumerate((*own, *inherited)):
+        for single in flag.singles():
+            if single.kind != FLAG or single.hidden:
+                continue
+            if index >= len(own) and single.name in seen:
+                continue
+            seen.add(single.name)
+            flags.append(
+                FlagDescriptor(
+                    name=single.name,
+                    aliases=single.aliases,
+                    description=single.description,
+                    type=_value_type(single),
+                    optional_value=single.optional_value is not None,
+                    negation=single.negation,
+                )
+            )
+    arguments: list[ArgumentDescriptor] = []
+    for arg in state.config.arguments:
+        metadata = arg.metadata()
+        for single in arg.singles():
+            if single.kind != ARGUMENT:
+                continue
+            arguments.append(
+                ArgumentDescriptor(
+                    name=single.name,
+                    description=single.description,
+                    required=not metadata.is_optional,
+                    variadic=metadata.is_variadic,
+                    type=_argument_type(single),
+                )
+            )
+    shared = (*inherited, *state.context_config.flags)
+    subcommands: list[CommandDescriptor] = []
+    for group in command.subcommands:
+        for sub in group.commands:
+            if sub.unlisted:
+                continue
+            descriptor = from_command(sub, shared)
+            subcommands.append(descriptor)
+            if sub.alias and sub.alias != sub.name:
+                subcommands.append(replace(descriptor, name=sub.alias))
+    return CommandDescriptor(
+        name=command.name,
+        description=(
+            command.description if command.short_description is None else command.short_description
+        ),
+        flags=tuple(flags),
+        arguments=tuple(arguments),
+        subcommands=tuple(subcommands),
+    )
+
+
+def takes_separate_value(flag: FlagDescriptor) -> bool:
+    return flag.type != "Boolean" and not flag.optional_value
+
+
+def negated_name(flag: FlagDescriptor) -> str | None:
+    if flag.type != "Boolean" or flag.negation is False:
+        return None
+    return flag.negation if flag.negation is not None else f"no-{flag.name}"
+
+
+def long_forms(flag: FlagDescriptor) -> list[str]:
+    """``--name``, each alias with its dashes, and the negation."""
+    forms = [f"--{flag.name}"]
+    forms += [f"-{alias}" if len(alias) == 1 else f"--{alias}" for alias in flag.aliases]
+    negation = negated_name(flag)
+    if negation is not None:
+        forms.append(f"--{negation}")
+    return forms
+
+
+__all__ = [
+    "ArgumentDescriptor",
+    "ArgumentType",
+    "Choice",
+    "CommandDescriptor",
+    "FlagDescriptor",
+    "FlagType",
+    "PathKind",
+    "from_command",
+    "long_forms",
+    "negated_name",
+    "takes_separate_value",
+]

pyfect/cli/completions/bash.py

@@ -0,0 +1,300 @@
+"""Bash completion scripts (Effect's internal ``completions/bash``). The
+script runs on Bash 3.2 and works without the bash-completion package."""
+
+from __future__ import annotations
+
+import re
+
+from pyfect.cli.completions._descriptor import (
+    ArgumentType,
+    Choice,
+    CommandDescriptor,
+    FlagDescriptor,
+    FlagType,
+    PathKind,
+    long_forms,
+    takes_separate_value,
+)
+
+# The static parts, as Effect writes them.
+INIT_COMPLETION_FALLBACK = (
+    "if ! type _init_completion &>/dev/null; then\n"
+    "  _init_completion()\n"
+    "  {\n"
+    "    COMPREPLY=()\n"
+    '    local _i _j=0 _piece _line="$COMP_LINE"\n'
+    '    words=("${COMP_WORDS[0]}")\n'
+    "    cword=0\n"
+    '    _line="${_line#*"${COMP_WORDS[0]}"}"\n'
+    "    for ((_i = 1; _i < ${#COMP_WORDS[@]}; _i++)); do\n"
+    '      _piece="${COMP_WORDS[_i]}"\n'
+    '      if [[ "$_line" == [[:blank:]]* ]]; then\n'
+    "        ((_j++))\n"
+    '        words[_j]="$_piece"\n'
+    "      else\n"
+    '        words[_j]="${words[_j]}$_piece"\n'
+    "      fi\n"
+    "      ((_i == COMP_CWORD)) && cword=$_j\n"
+    '      _line="${_line#*"$_piece"}"\n'
+    "    done\n"
+    '    cur="${words[cword]}"\n'
+    '    prev=""\n'
+    '    ((cword > 0)) && prev="${words[cword-1]}"\n'
+    "    return 0\n"
+    "  }\n"
+    "fi\n"
+    "\n"
+)
+
+CHOICES_HELPER_NAME = "_x--choices"
+CHOICES_HELPER = (
+    "_x--choices()\n"
+    "{\n"
+    '  local _cur="$1" _word="$2"; shift 2\n'
+    "\n"
+    '  local _head="${_cur%"$_word"}"\n'
+    '  local _open=""\n'
+    '  case "$_head" in\n'
+    "    *\\') _open=\"'\" ;;\n"
+    "    *\\\") _open='\"' ;;\n"
+    "  esac\n"
+    "\n"
+    '  local _prefix="$_cur" _committed="$_head"\n'
+    "  _prefix=${_prefix//\\\\/}; _prefix=${_prefix//\\\"/}; _prefix=${_prefix//\\'/}\n"
+    '  _committed=${_committed//\\\\/}; _committed=${_committed//\\"/};'
+    " _committed=${_committed//\\'/}\n"
+    "\n"
+    "  COMPREPLY=()\n"
+    "  local _choice _rest _match\n"
+    '  for _choice in "$@"; do\n'
+    '    [[ "$_choice" == "$_prefix"* ]] || continue\n'
+    '    _rest="${_choice#"$_committed"}"\n'
+    '    case "$_open" in\n'
+    '      "\'")\n'
+    '        if [[ "$_head" == "\'" ]]; then\n'
+    "          _match=${_rest//\\'/\\'\\\\\\'\\'}\n"
+    "        else\n"
+    '          [[ "$_rest" == *\\\'* ]] && continue\n'
+    '          _match="$_rest"\n'
+    "        fi\n"
+    "        ;;\n"
+    "      '\"')\n"
+    '        _match="${_rest//\\\\/\\\\\\\\}"\n'
+    '        _match="${_match//\\$/\\\\$}"\n'
+    '        _match="${_match//\\`/\\\\\\`}"\n'
+    '        _match="${_match//\\"/\\\\\\"}"\n'
+    "        ;;\n"
+    "      *)\n"
+    "        printf -v _match '%q' \"$_rest\"\n"
+    '        [[ -z "$_head" && "$_match" == \'~\'* ]] && _match="\\\\$_match"\n'
+    "        ;;\n"
+    "    esac\n"
+    '    [[ -n "$_open" && "$_match" == *"$_open" ]] && _match+="$_open"\n'
+    '    COMPREPLY+=("$_match")\n'
+    "  done\n"
+    "}\n"
+)
+
+
+def _escape(text: str) -> str:
+    return text.replace("'", "'\\''")
+
+
+def _sanitize(text: str) -> str:
+    return re.sub(r"[^a-zA-Z0-9_]", "_", text)
+
+
+def _flag_group_declarations(flags: tuple[FlagDescriptor, ...], lines: list[str]) -> None:
+    if not flags:
+        return
+    groups = [long_forms(flag) for flag in flags]
+    lines.append("  local " + " ".join(f'_used_{index}=""' for index in range(len(groups))))
+    lines.append("  for ((i = 1; i < cword; i++)); do")
+    lines.append('    case "${words[i]%%=*}" in')
+    for index, forms in enumerate(groups):
+        lines.append(f"      {'|'.join(forms)}) _used_{index}=1 ;;")
+    lines.append("    esac")
+    lines.append("  done")
+    lines.append('  local _filtered_flags=""')
+    for index, forms in enumerate(groups):
+        lines.append(f'  [[ -n "$_used_{index}" ]] || _filtered_flags+=" {" ".join(forms)}"')
+    lines.append("")
+
+
+def _choice_completion(helper: str, values: tuple[str, ...]) -> str:
+    quoted = " ".join(f"'{_escape(value)}'" for value in values)
+    return f'{helper} "$cur" "$_comp_word" {quoted}'
+
+
+def _path_completion(kind: PathKind) -> str:
+    if kind.path_type == "directory":
+        return 'COMPREPLY=( $(compgen -d -- "$cur") )'
+    return 'COMPREPLY=( $(compgen -f -- "$cur") )'
+
+
+def _value_completion(kind: FlagType | ArgumentType, helper: str) -> str | None:
+    if isinstance(kind, Choice):
+        return _choice_completion(helper, kind.values)
+    if isinstance(kind, PathKind):
+        return _path_completion(kind)
+    return None
+
+
+def _function_name(path: list[str]) -> str:
+    return "_" + "_".join(_sanitize(part) for part in path)
+
+
+def _skip_cases(flag: FlagDescriptor, lines: list[str]) -> None:
+    forms = long_forms(flag)
+    lines.append(f"      {'|'.join(forms)}) _skip_next=1 ;;")
+    lines.append(f"      {'|'.join(f'{form}=*' for form in forms)}) ;;")
+
+
+def _skip_loop_head(lines: list[str]) -> None:
+    lines.append("  for ((i = _command_index + 1; i < cword; i++)); do")
+    lines.append("    if (( _skip_next )); then")
+    lines.append("      _skip_next=0")
+    lines.append("      continue")
+    lines.append("    fi")
+
+
+def _flag_values(descriptor: CommandDescriptor, helper: str, lines: list[str]) -> None:
+    with_values = [flag for flag in descriptor.flags if takes_separate_value(flag)]
+    if not with_values:
+        return
+    lines.append("  # Flag value completions")
+    lines.append('  case "$prev" in')
+    for flag in with_values:
+        names = [f"--{flag.name}"] + [
+            f"-{alias}" if len(alias) == 1 else f"--{alias}" for alias in flag.aliases
+        ]
+        completion = _value_completion(flag.type, helper)
+        if completion:
+            lines.append(f"    {'|'.join(names)})")
+            lines.append(f"      {completion}")
+            lines.append("      return")
+            lines.append("      ;;")
+    lines.append("  esac")
+    lines.append("")
+
+
+def _subcommand_dispatch(descriptor: CommandDescriptor, path: list[str], lines: list[str]) -> None:
+    if not descriptor.subcommands:
+        return
+    lines.append("  # Subcommand dispatch")
+    lines.append("  local cmd _skip_next=0")
+    _skip_loop_head(lines)
+    lines.append('    case "${words[i]}" in')
+    for flag in descriptor.flags:
+        if takes_separate_value(flag):
+            _skip_cases(flag, lines)
+    for sub in descriptor.subcommands:
+        lines.append(f"      {sub.name})")
+        lines.append(f'        {_function_name([*path, sub.name])} "$i"')
+        lines.append("        return")
+        lines.append("        ;;")
+    lines.append("    esac")
+    lines.append("  done")
+    lines.append("")
+
+
+def _positionals(descriptor: CommandDescriptor, helper: str, lines: list[str]) -> None:
+    completions = [
+        (index, argument, completion)
+        for index, argument in enumerate(descriptor.arguments)
+        if (completion := _value_completion(argument.type, helper)) is not None
+    ]
+    if not completions:
+        if descriptor.subcommands:
+            names = " ".join(sub.name for sub in descriptor.subcommands)
+            lines.append(f"  COMPREPLY=( $(compgen -W '{names}' -- \"$cur\") )")
+        return
+    lines.append("  # Positional argument completions")
+    lines.append("  local _position=0 _skip_next=0 _end_of_options=0")
+    _skip_loop_head(lines)
+    lines.append("    if (( _end_of_options )); then")
+    lines.append("      ((_position += 1))")
+    lines.append("      continue")
+    lines.append("    fi")
+    lines.append('    case "${words[i]}" in')
+    lines.append("      --) _end_of_options=1 ;;")
+    for flag in descriptor.flags:
+        if takes_separate_value(flag):
+            _skip_cases(flag, lines)
+        else:
+            lines.append(f"      {'|'.join(long_forms(flag))}) ;;")
+    lines.append("      -*) ;;")
+    lines.append("      *) ((_position += 1)) ;;")
+    lines.append("    esac")
+    lines.append("  done")
+    lines.append('  case "$_position" in')
+    for index, argument, completion in completions:
+        if argument.variadic:
+            continue
+        lines.append(f"    {index})")
+        lines.append(f"      {completion}")
+        lines.append("      return")
+        lines.append("      ;;")
+    lines.append("  esac")
+    variadic = next((entry for entry in completions if entry[1].variadic), None)
+    if variadic is not None:
+        lines.append(f"  if (( _position >= {variadic[0]} )); then")
+        lines.append(f"    {variadic[2]}")
+        lines.append("    return")
+        lines.append("  fi")
+
+
+def _function(
+    descriptor: CommandDescriptor, parent: list[str], lines: list[str], helper: str
+) -> None:
+    path = [*parent, descriptor.name]
+    lines.append(f"{_function_name(path)}()")
+    lines.append("{")
+    lines.append("  local cur prev words cword i")
+    lines.append("  local _command_index=0" if not parent else '  local _command_index="$1"')
+    lines.append('  _init_completion -n "$COMP_WORDBREAKS" || return')
+    if not parent:
+        lines.append('  local _comp_word="$2"')
+    lines.append("")
+    _flag_values(descriptor, helper, lines)
+    _subcommand_dispatch(descriptor, path, lines)
+    _flag_group_declarations(descriptor.flags, lines)
+    if descriptor.flags or descriptor.subcommands:
+        lines.append("  # Complete flags (filtered) and subcommands")
+        lines.append('  if [[ "$cur" == -* ]]; then')
+        if descriptor.flags:
+            lines.append('    COMPREPLY=( $(compgen -W "$_filtered_flags" -- "$cur") )')
+        lines.append("    return")
+        lines.append("  fi")
+        lines.append("")
+    _positionals(descriptor, helper, lines)
+    lines.append("}")
+    lines.append("")
+    for sub in descriptor.subcommands:
+        _function(sub, path, lines, helper)
+
+
+def generate(executable: str, descriptor: CommandDescriptor) -> str:
+    safe = _sanitize(executable)
+    helper = f"_{safe}--choices"
+    name = _escape(executable)
+    lines = [
+        f"###-begin-{name}-completions-###",
+        "#",
+        "# Static completion script for Bash",
+        "#",
+        "# Installation:",
+        f"#   {name} --completions bash >> ~/.bashrc",
+        "#",
+        "",
+    ]
+    lines += INIT_COMPLETION_FALLBACK.split("\n")[:-1]
+    lines += CHOICES_HELPER.replace(CHOICES_HELPER_NAME, helper).split("\n")[:-1]
+    lines.append("")
+    _function(descriptor, [], lines, helper)
+    lines.append(f"complete -F _{safe} {name}")
+    lines.append(f"###-end-{name}-completions-###")
+    return "\n".join(lines)
+
+
+__all__ = ["CHOICES_HELPER", "CHOICES_HELPER_NAME", "INIT_COMPLETION_FALLBACK", "generate"]

pyfect/cli/completions/fish.py

@@ -0,0 +1,164 @@
+"""Fish completion scripts (Effect's internal ``completions/fish``): one
+``complete`` line per subcommand, flag and typed argument, scoped by the
+subcommand path."""
+
+from __future__ import annotations
+
+import re
+
+from pyfect.cli.completions._descriptor import (
+    ArgumentType,
+    Choice,
+    CommandDescriptor,
+    FlagDescriptor,
+    FlagType,
+    PathKind,
+    negated_name,
+    takes_separate_value,
+)
+
+_UNSAFE_CHOICE = re.compile(r"[^A-Za-z0-9_.,/@%+-]")
+
+
+def _escape(text: str) -> str:
+    return text.replace("\\", "\\\\").replace("'", "\\'")
+
+
+def _escape_choice(text: str) -> str:
+    return _escape(_UNSAFE_CHOICE.sub(lambda match: "\\" + match.group(), text))
+
+
+def _subcommand_condition(parent: list[str], children: list[str]) -> str:
+    if not parent:
+        return "__fish_use_subcommand" if children else ""
+    condition = "; and ".join(f"__fish_seen_subcommand_from {name}" for name in parent)
+    if children:
+        return f"{condition}; and not __fish_seen_subcommand_from {' '.join(children)}"
+    return condition
+
+
+def _contains_opt(flag: FlagDescriptor) -> str:
+    args = [f"-s {alias}" for alias in flag.aliases if len(alias) == 1]
+    args.append(flag.name)
+    args += [alias for alias in flag.aliases if len(alias) > 1]
+    negation = negated_name(flag)
+    if negation is not None:
+        args.append(negation)
+    return f"not __fish_contains_opt {' '.join(args)}"
+
+
+def _value_flag_dedup(flag: FlagDescriptor) -> str:
+    forms = [f"--{flag.name}"]
+    forms += [f"-{alias}" if len(alias) == 1 else f"--{alias}" for alias in flag.aliases]
+    return (
+        f"begin; {_contains_opt(flag)}; or contains -- (commandline -poc)[-1] "
+        f"{' '.join(forms)}; end"
+    )
+
+
+def _choice_args(choice: Choice) -> str:
+    return f"-r -f -a '{' '.join(_escape_choice(value) for value in choice.values)}'"
+
+
+def _flag_value_args(kind: FlagType) -> str | None:
+    match kind:
+        case "Boolean":
+            return None
+        case Choice():
+            return _choice_args(kind)
+        case PathKind():
+            return "-r -F"
+        case _:
+            return "-r -f"
+
+
+def _argument_value_args(kind: ArgumentType) -> str | None:
+    match kind:
+        case Choice():
+            return _choice_args(kind)
+        case PathKind():
+            return "-r -F"
+        case _:
+            return None
+
+
+def _flag_args(flag: FlagDescriptor) -> list[str]:
+    args = [f"-l {flag.name}"]
+    args += [f"-s {alias}" if len(alias) == 1 else f"-l {alias}" for alias in flag.aliases]
+    if flag.description:
+        args.append(f"-d '{_escape(flag.description)}'")
+    value = _flag_value_args(flag.type) if takes_separate_value(flag) else None
+    if value:
+        args.append(value)
+    return args
+
+
+def _line(executable: str, *parts: str) -> str:
+    return " ".join([f"complete -c {executable}", *(part for part in parts if part)])
+
+
+def _disable(flag: FlagDescriptor) -> str:
+    return f"-d '{_escape(f'Disable {flag.name}')}'" if flag.description else ""
+
+
+def _bare_flags(
+    executable: str, descriptor: CommandDescriptor, condition: str, lines: list[str]
+) -> None:
+    not_dash = 'not string match -q -- "-*" (commandline -ct)'
+    base = f"{condition}; and {not_dash}" if condition else not_dash
+    for flag in descriptor.flags:
+        bare = f"-n '{base}; and {_contains_opt(flag)}'"
+        description = f"-d '{_escape(flag.description)}'" if flag.description else ""
+        lines.append(_line(executable, bare, f"-f -a '--{flag.name}'", description))
+        negation = negated_name(flag)
+        if negation is not None:
+            lines.append(_line(executable, bare, f"-f -a '--{negation}'", _disable(flag)))
+
+
+def _completions(
+    executable: str, descriptor: CommandDescriptor, parent: list[str], lines: list[str]
+) -> None:
+    condition = _subcommand_condition(parent, [sub.name for sub in descriptor.subcommands])
+    condition_arg = f"-n '{condition}'" if condition else ""
+    if not any(isinstance(argument.type, PathKind) for argument in descriptor.arguments):
+        lines.append(_line(executable, condition_arg, "-f"))
+    for sub in descriptor.subcommands:
+        description = f"-d '{_escape(sub.description)}'" if sub.description else ""
+        lines.append(_line(executable, condition_arg, f"-f -a '{_escape(sub.name)}'", description))
+    for flag in descriptor.flags:
+        dedup = _value_flag_dedup(flag) if takes_separate_value(flag) else _contains_opt(flag)
+        flag_condition = f"{condition}; and {dedup}" if condition else dedup
+        flag_condition_arg = f"-n '{flag_condition}'"
+        lines.append(_line(executable, flag_condition_arg, *_flag_args(flag)))
+        negation = negated_name(flag)
+        if negation is not None:
+            lines.append(_line(executable, flag_condition_arg, f"-l {negation}", _disable(flag)))
+    if descriptor.flags:
+        _bare_flags(executable, descriptor, condition, lines)
+    for argument in descriptor.arguments:
+        value = _argument_value_args(argument.type)
+        if value:
+            description = f"-d '{_escape(argument.description)}'" if argument.description else ""
+            lines.append(_line(executable, condition_arg, value, description))
+    for sub in descriptor.subcommands:
+        _completions(executable, sub, [*parent, sub.name], lines)
+
+
+def generate(executable: str, descriptor: CommandDescriptor) -> str:
+    lines = [
+        f"###-begin-{executable}-completions-###",
+        "#",
+        "# Static completion script for Fish",
+        "#",
+        "# Installation:",
+        f"#   {executable} --completions fish > ~/.config/fish/completions/{executable}.fish",
+        "#",
+        "",
+    ]
+    _completions(executable, descriptor, [], lines)
+    lines.append("")
+    lines.append(f"###-end-{executable}-completions-###")
+    return "\n".join(lines)
+
+
+__all__ = ["generate"]