keycut ¤

def as_colored_text(document: Document) -> str:
    """Render shortcut entries with terminal colors for fields and matches.

    Args:
        document: Shortcut entries to render. Position fields, when present,
            mark the text to highlight.

    Returns:
        Formatted text, or an empty string for an empty document.
    """
    str_list = []
    for item in document:
        s = []
        category = item.get("category", None)
        if category:
            s.append("Category: ")
            category_pos = item.get("category_pos", None)
            if category_pos:
                s.extend(_color_match(category, category_pos, CATEGORY_COLOR))
                s.append("\n")
            else:
                s.append(f"{_color(category, CATEGORY_COLOR)}\n")
        action = item["action"].rstrip("\n")
        action_pos = item.get("action_pos", None)
        s.append("  Action: ")
        if action_pos:
            s.extend(_color_match(action, action_pos, ACTION_COLOR))
            s.append("\n")
        else:
            s.append(f"{_color(action, ACTION_COLOR)}\n")
        s.append("    Keys: ")
        s_key = []
        keys = item["keys"]
        for key in keys:
            key_pos = item.get("keys_pos", {}).get(key)
            if key_pos:
                s_key.append("".join(_color_match(key, key_pos, KEY_COLOR)))
            else:
                s_key.append(f"{_color(key, KEY_COLOR)}")
        s.append(", ".join(s_key))
        s.append("\n")
        str_list.append("".join(s))
    return "\n".join(str_list) if str_list else ""

def as_text(document: Document) -> str:
    """Render shortcut entries as plain text.

    Args:
        document: Shortcut entries to render.

    Returns:
        Formatted text, or an empty string for an empty document.
    """
    str_list = []
    for item in document:
        category = item.get("category", None)
        if category:
            str_list.append(f"Category: {category}\nAction: {item['action'].rstrip()}\nKeys: {item['keys']}\n")
        else:
            str_list.append(f"Action: {item['action'].rstrip()}\nKeys: {item['keys']}\n")
    return "\n".join(str_list) if str_list else ""

def as_yaml(document: Document) -> str:
    """Serialize shortcut entries as YAML.

    Args:
        document: Shortcut entries to serialize.

    Returns:
        YAML text.
    """
    return yaml.dump(document)

def check(name: str, path: Path = DIRECTORY) -> tuple[Path, bool]:
    """Get the path to a shortcut file and check whether it exists.

    Args:
        name: Application name without the `.yml` suffix.
        path: Directory containing the shortcut file.

    Returns:
        The file path and whether it is a file.
    """
    file = path.joinpath(name).with_suffix(".yml")
    return file, file.is_file()

def from_yaml(app: str, command_line: str | None = None) -> Document | None:
    """Load an application's shortcuts from YAML.

    Args:
        app: Application name used to locate the YAML file.
        command_line: Command line used to find a fallback file when the
            application's file is missing.

    Returns:
        Shortcut entries, or `None` if no fallback file matches.
    """
    file, exist = check(app)
    if not exist and command_line is not None:
        file = grep(command_line)
        if not file:
            return None
    with Path(file).open() as f:
        doc = yaml.safe_load(f)
    if isinstance(doc, dict):
        document = [dict(category=key, **v) for key, value in doc.items() for v in value]
    else:
        document = [dict(category="", **value) for value in doc]
    return document

def get_parser() -> argparse.ArgumentParser:
    """Return the CLI argument parser.

    Returns:
        An argparse parser.
    """
    parser = argparse.ArgumentParser(prog="keycut")
    parser.add_argument("-V", "--version", action="version", version=f"%(prog)s {debug._get_version()}")
    parser.add_argument("--debug-info", action=_DebugInfo, help="Print debug information.")
    return parser

def grep(cmdline: str) -> Path | None:
    """Find a shortcut file whose suffix appears in a command line.

    Args:
        cmdline: Command line to search, ignoring case.

    Returns:
        The matching file path, or `None` if no file matches.
    """
    cmdline = cmdline.lower()
    for file in DIRECTORY.iterdir():
        app = file.suffix.lower()
        if app in cmdline:
            return DIRECTORY / file
    return None

def in_action(document: Document, pattern: str) -> Document:
    """Return shortcuts whose action matches a case-insensitive regex.

    Args:
        document: Shortcut entries to search.
        pattern: Regular expression to match.

    Returns:
        Matching shortcut entries.
    """
    return _search(document, pattern, key="action")

def in_category(document: Document, pattern: str) -> Document:
    """Return shortcuts whose category matches a case-insensitive regex.

    Args:
        document: Shortcut entries to search.
        pattern: Regular expression to match.

    Returns:
        Matching shortcut entries.
    """
    return _search(document, pattern, key="category")

def in_keys(document: Document, pattern: str) -> Document:
    """Return shortcuts whose keys field matches a case-insensitive regex.

    Args:
        document: Shortcut entries to search.
        pattern: Regular expression to match.

    Returns:
        Matching shortcut entries.
    """
    return _search(document, pattern, key="keys")

def main(args: list[str] | None = None) -> int:
    """Run the main program.

    This function is executed when you type `keycut` or `python -m keycut`.

    Parameters:
        args: Arguments passed from the command line.

    Returns:
        An exit code.
    """
    parser = get_parser()
    opts = parser.parse_args(args=args)
    print(opts)
    return 0

def print_err(message: str) -> None:
    """Write a message to standard error.

    Args:
        message: Text to write without an added newline.
    """
    sys.stderr.write(message)

def reload(document: Document) -> None:
    """Print shortcut entries with terminal colors.

    Args:
        document: Shortcut entries to print.
    """
    text = render.as_colored_text(document)
    print(text)  # noqa: T201

def search(document: Document, pattern: str) -> Document:
    """Search shortcut actions, categories, and keys with a case-insensitive regex.

    Matching entries gain position fields for highlighting. If nothing matches,
    return the original document.

    Args:
        document: Shortcut entries to search.
        pattern: Regular expression to match.

    Returns:
        Matching shortcut entries, or the original document if none match.
    """
    return _search(document, pattern)

def word_in_action(document: Document, pattern: str) -> Document:
    """Return shortcuts with a whole-word match in their action.

    Args:
        document: Shortcut entries to search.
        pattern: Case-insensitive regular expression to match as a whole word.

    Returns:
        Matching shortcut entries.
    """
    return _search(document, pattern, key="action", word=True)

def word_in_category(document: Document, pattern: str) -> Document:
    """Return shortcuts with a whole-word match in their category.

    Args:
        document: Shortcut entries to search.
        pattern: Case-insensitive regular expression to match as a whole word.

    Returns:
        Matching shortcut entries.
    """
    return _search(document, pattern, key="category", word=True)

def word_in_keys(document: Document, pattern: str) -> Document:
    """Return shortcuts with a whole-word match in their keys field.

    Args:
        document: Shortcut entries to search.
        pattern: Case-insensitive regular expression to match as a whole word.

    Returns:
        Matching shortcut entries.
    """
    return _search(document, pattern, key="keys", word=True)

def word_search(document: Document, pattern: str) -> Document:
    """Search all shortcut fields for whole-word matches.

    Matching entries gain position fields for highlighting. If nothing matches,
    return the original document.

    Args:
        document: Shortcut entries to search.
        pattern: Case-insensitive regular expression to match as a whole word.

    Returns:
        Matching shortcut entries, or the original document if none match.
    """
    return _search(document, pattern, word=True)