"""Fish completion script generator. Generates static fish completion scripts using `complete -c COMMAND` statements. Completions auto-load from ~/.config/fish/completions/PROGNAME.fish. """ import re from typing import TYPE_CHECKING from cyclopts.completion._base import ( CompletionAction, CompletionData, clean_choice_text, extract_completion_data, get_completion_action, strip_markup, ) if TYPE_CHECKING: from cyclopts import App def generate_completion_script(app: "App", prog_name: str) -> str: """Generate fish completion script. Parameters ---------- app : App The Cyclopts application to generate completion for. prog_name : str Program name for completion (alphanumeric with hyphens/underscores). Returns ------- str Complete fish completion script. Raises ------ ValueError If prog_name contains invalid characters. """ if not prog_name or not re.match(r"^[a-zA-Z0-9_-]+$", prog_name): raise ValueError(f"Invalid prog_name: {prog_name!r}. Must be alphanumeric with hyphens/underscores.") completion_data = extract_completion_data(app) lines = [ f"# Fish completion for {prog_name}", "# Generated by Cyclopts", "", ] has_nested_commands = any(len(path) > 0 for path in completion_data.keys()) if has_nested_commands: lines.extend(_generate_helper_functions(prog_name, completion_data)) lines.append("") help_flags = tuple(app.help_flags) if app.help_flags else () version_flags = tuple(app.version_flags) if app.version_flags else () lines.extend(_generate_completions(completion_data, prog_name, help_flags, version_flags)) return "\n".join(lines) + "\n" def _escape_fish_string(text: str) -> str: r"""Escape single quotes for fish strings.""" return text.replace("'", r"'\''") def _escape_fish_description(text: str) -> str: """Escape description text for fish.""" text = text.replace("\n", " ") text = text.replace("\r", " ") return _escape_fish_string(text) def _generate_helper_functions( prog_name: str, completion_data: dict[tuple[str, ...], CompletionData], ) -> list[str]: """Generate helper function for command path detection. Parameters ---------- prog_name : str Program name. completion_data : dict Completion data used to identify options that take values. Returns ------- list[str] Lines defining the helper function. """ options_with_values = set() for data in completion_data.values(): for argument in data.arguments: if not argument.is_flag() and argument.parameter.name: for name in argument.parameter.name: if name.startswith("-"): options_with_values.add(name) func_name = f"__fish_{prog_name}_using_command" lines = [ "# Helper function to check exact command path sequence", f"function {func_name}", " set -l cmd (commandline -opc)", " set -l subcommands", ] if options_with_values: escaped_opts = " ".join(_escape_fish_string(opt) for opt in sorted(options_with_values)) lines.append(f" set -l options_with_values '{escaped_opts}'") else: lines.append(" set -l options_with_values ''") lines.extend( [ " set -l skip_next 0", " # Extract non-option words (commands) from command line", " for i in (seq 2 (count $cmd))", " set -l word $cmd[$i]", " if test $skip_next -eq 1", " set skip_next 0", " continue", " end", " if string match -qr -- '^-' $word", " # Check if this option takes a value (exact match)", ' if string match -q -- "* $word *" " $options_with_values "', " set skip_next 1", " end", " else", " # Non-option word is a command", " set -a subcommands $word", " end", " end", " # Check if subcommand sequence matches expected path", " if test (count $subcommands) -ne (count $argv)", " return 1", " end", " for i in (seq 1 (count $argv))", " if test $subcommands[$i] != $argv[$i]", " return 1", " end", " end", " return 0", "end", ] ) return lines def _map_completion_action_to_fish(action: CompletionAction) -> str: """Map completion action to fish flags. Parameters ---------- action : CompletionAction Completion action type. Returns ------- str Fish completion flags ("-r -F" for files, "-r -a '(...)'" for directories, "" otherwise). """ if action == CompletionAction.FILES: return "-r -F" if action == CompletionAction.DIRECTORIES: return "-r -a '(__fish_complete_directories)'" return "" def _generate_completions( completion_data: dict[tuple[str, ...], CompletionData], prog_name: str, help_flags: tuple[str, ...], version_flags: tuple[str, ...], ) -> list[str]: """Generate all fish completion commands. Parameters ---------- completion_data : dict Extracted completion data. prog_name : str Program name. help_flags : tuple[str, ...] Help flags. version_flags : tuple[str, ...] Version flags. Returns ------- list[str] Completion command lines. """ lines = [] for command_path, _data in sorted(completion_data.items()): lines.extend( _generate_completions_for_path( completion_data, command_path, prog_name, help_flags, version_flags, ) ) if command_path != max(completion_data.keys(), key=len): lines.append("") return lines def _generate_completions_for_path( completion_data: dict[tuple[str, ...], CompletionData], command_path: tuple[str, ...], prog_name: str, help_flags: tuple[str, ...], version_flags: tuple[str, ...], ) -> list[str]: """Generate completions for a specific command path. Parameters ---------- completion_data : dict Extracted completion data. command_path : tuple[str, ...] Command path. prog_name : str Program name. help_flags : tuple[str, ...] Help flags. version_flags : tuple[str, ...] Version flags. Returns ------- list[str] Completion command lines. """ if command_path not in completion_data: return [] data = completion_data[command_path] lines = [] condition = _get_condition_for_path(command_path, prog_name) lines.extend(_generate_subcommand_completions(data, command_path, prog_name, condition)) keyword_args = [arg for arg in data.arguments if not arg.is_positional_only() and arg.show] if keyword_args or help_flags or version_flags: lines.extend(_generate_option_section_header(command_path)) lines.extend(_generate_help_version_completions(prog_name, condition, help_flags, version_flags)) lines.extend(_generate_keyword_arg_completions(keyword_args, prog_name, condition, data.help_format)) lines.extend(_generate_command_option_completions(data.commands, prog_name, condition, data.help_format)) return lines def _generate_subcommand_completions( data: CompletionData, command_path: tuple[str, ...], prog_name: str, condition: str, ) -> list[str]: """Generate completions for subcommands. Parameters ---------- data : CompletionData Completion data. command_path : tuple[str, ...] Command path. prog_name : str Program name. condition : str Fish condition. Returns ------- list[str] Completion command lines. """ commands = [ name for registered_command in data.commands for name in registered_command.names if not name.startswith("-") ] if not commands: return [] lines = [] if command_path: lines.append(f"# Subcommands for: {' '.join(command_path)}") else: lines.append("# Root-level commands") for registered_command in data.commands: for cmd_name in registered_command.names: if cmd_name.startswith("-"): continue desc = _get_description_from_app(registered_command.app, data.help_format) escaped_desc = _escape_fish_description(desc) escaped_cmd = _escape_fish_string(cmd_name) lines.append(f"complete -c {prog_name} {condition} -a '{escaped_cmd}' -d '{escaped_desc}'") return lines def _generate_option_section_header(command_path: tuple[str, ...]) -> list[str]: """Generate section header comment for options. Parameters ---------- command_path : tuple[str, ...] Command path. Returns ------- list[str] Comment line. """ if command_path: return [f"# Options for: {' '.join(command_path)}"] return ["# Root-level options"] def _generate_help_version_completions( prog_name: str, condition: str, help_flags: tuple[str, ...], version_flags: tuple[str, ...], ) -> list[str]: """Generate completions for help and version flags. Parameters ---------- prog_name : str Program name. condition : str Fish condition. help_flags : tuple[str, ...] Help flags. version_flags : tuple[str, ...] Version flags. Returns ------- list[str] Completion command lines. """ lines = [] for flag in help_flags: if flag.startswith("--"): long_name = flag[2:] lines.append(f"complete -c {prog_name} {condition} -l {long_name} -d 'Display this message and exit.'") elif flag.startswith("-") and len(flag) == 2: short_name = flag[1] lines.append(f"complete -c {prog_name} {condition} -s {short_name} -d 'Display this message and exit.'") for flag in version_flags: if flag.startswith("--"): long_name = flag[2:] lines.append(f"complete -c {prog_name} {condition} -l {long_name} -d 'Display application version.'") elif flag.startswith("-") and len(flag) == 2: short_name = flag[1] lines.append(f"complete -c {prog_name} {condition} -s {short_name} -d 'Display application version.'") return lines def _generate_keyword_arg_completions( keyword_args: list, prog_name: str, condition: str, help_format: str, ) -> list[str]: """Generate completions for keyword arguments. Parameters ---------- keyword_args : list Keyword arguments. prog_name : str Program name. condition : str Fish condition. help_format : str Help text format. Returns ------- list[str] Completion command lines. """ lines = [] for argument in keyword_args: desc = strip_markup(argument.parameter.help or "", format=help_format) escaped_desc = _escape_fish_description(desc) is_flag = argument.is_flag() choices = argument.get_choices(force=True) action = get_completion_action(argument.hint) for name in argument.parameter.name or []: if not name.startswith("-"): continue if name.startswith("--"): long_name = name[2:] line_parts = [f"complete -c {prog_name} {condition} -l {long_name}"] elif len(name) == 2: short_name = name[1] line_parts = [f"complete -c {prog_name} {condition} -s {short_name}"] else: continue if is_flag: line_parts.append(f"-d '{escaped_desc}'") elif choices: escaped_choices = [_escape_fish_string(clean_choice_text(c)) for c in choices] choices_str = " ".join(escaped_choices) line_parts.append(f"-x -a '{choices_str}' -d '{escaped_desc}'") else: action_flags = _map_completion_action_to_fish(action) if action_flags: line_parts.append(f"{action_flags} -d '{escaped_desc}'") else: line_parts.append(f"-r -d '{escaped_desc}'") lines.append(" ".join(line_parts)) for name in argument.negatives: if not name.startswith("-"): continue if name.startswith("--"): long_name = name[2:] lines.append(f"complete -c {prog_name} {condition} -l {long_name} -d '{escaped_desc}'") elif len(name) == 2: short_name = name[1] lines.append(f"complete -c {prog_name} {condition} -s {short_name} -d '{escaped_desc}'") return lines def _generate_command_option_completions( commands: list, prog_name: str, condition: str, help_format: str, ) -> list[str]: """Generate completions for commands that look like options. Parameters ---------- commands : list List of RegisteredCommand tuples. prog_name : str Program name. condition : str Fish condition. help_format : str Help text format. Returns ------- list[str] Completion command lines. """ lines = [] for registered_command in commands: for cmd_name in registered_command.names: if not cmd_name.startswith("-"): continue desc = _get_description_from_app(registered_command.app, help_format) escaped_desc = _escape_fish_description(desc) if cmd_name.startswith("--"): long_name = cmd_name[2:] lines.append(f"complete -c {prog_name} {condition} -l {long_name} -d '{escaped_desc}'") elif len(cmd_name) == 2: short_name = cmd_name[1] lines.append(f"complete -c {prog_name} {condition} -s {short_name} -d '{escaped_desc}'") return lines def _get_condition_for_path(command_path: tuple[str, ...], prog_name: str) -> str: """Generate fish condition string for a command path. Parameters ---------- command_path : tuple[str, ...] Command path (empty for root). prog_name : str Program name. Returns ------- str Fish condition flag. """ if not command_path: return "-n __fish_use_subcommand" func_name = f"__fish_{prog_name}_using_command" escaped_commands = " ".join(_escape_fish_string(cmd) for cmd in command_path) return f"-n '{func_name} {escaped_commands}'" def _get_description_from_app(cmd_app: "App", help_format: str) -> str: """Extract description from App. Parameters ---------- cmd_app : App Command app. help_format : str Help text format. Returns ------- str Description text. """ from cyclopts.help.help import docstring_parse if not cmd_app.help: return "" try: parsed = docstring_parse(cmd_app.help, "plaintext") text = parsed.short_description or "" except Exception: text = str(cmd_app.help) return strip_markup(text, format=help_format)