cli.commands

File:: EuljiroBible/cli/commands.py
Author:: Benjamin Jaedon Choi - https://github.com/saintbenjamin
Affiliated Church:: The Eulji-ro Presbyterian Church [대한예수교장로회(통합) 을지로교회]
Address:: The Eulji-ro Presbyterian Church, 24-10, Eulji-ro 20-gil, Jung-gu, Seoul 04549, South Korea
Telephone:: +82-2-2266-3070
E-mail:: euljirochurch [at] G.M.A.I.L. (replace [at] with @ and G.M.A.I.L as you understood.)
License:: MIT License with Attribution Requirement (see LICENSE file for details); Copyright (c) 2025 The Eulji-ro Presbyterian Church.

CLI command handlers for EuljiroBible.

This module contains the top-level command functions used by the CLI entry point:

run_bible_command() for verse lookup and formatted verse output.
run_search_command() for keyword search and result printing.

Design notes:

Argument parsing here is intentionally lightweight. Deep validation and output formatting is delegated to shared core logic (e.g., core.logic.verse_logic).
CLI error messages are expected to be English-only by project convention.
Available Bible versions are determined from the actual JSON files under data/. Alias files are used only to improve display labels and optional CLI shorthand tokens.

Limitations:

CLI display for Right-to-Left (RTL) scripts (Hebrew/Arabic/etc.) depends on the terminal/font environment and may not render ideally. A note is printed when a likely RTL version is detected.

cli.commands.handle_cli_metadata(args)[source]

Handle CLI metadata options for the verse lookup command.

This function checks for single-token metadata options and prints an appropriate message. If a metadata option is handled, the caller should exit early without further parsing.

Supported options:

--help / -h: Print usage and examples.
--version / -v: Print CLI version string.
--about: Print author and license information.

Parameters:: args (List[str]) – Raw CLI arguments for the bible command (excluding the script name).
Returns:: True if a metadata option was handled and the command should exit, otherwise False.
Return type:: bool

cli.commands.handle_search_metadata(args)[source]

Handle CLI metadata options for the keyword search command.

Supported options:

--help / -h: Print usage and examples.
--version / -v: Print CLI version string.
--about: Print author and license information.

Parameters:: args (List[str]) – Raw CLI arguments for the search command.
Returns:: True if a metadata option was handled and the command should exit, otherwise False.
Return type:: bool

cli.commands._print_available_versions(version_catalog)[source]

Print the list of Bible versions currently available to the CLI.

The catalog is derived from the actual Bible JSON files under data/. Each entry is printed using the best available user-facing label:

CLI alias from aliases_version_cli.json when available
GUI/display alias from aliases_version.json as a fallback
Raw version key (filename stem) if no alias metadata exists

Parameters:: version_catalog (List[dict]) – Catalog rows produced by core.utils.utils_version.build_cli_version_catalog().
Returns:: None

cli.commands.show_usage_and_versions(version_catalog)[source]

Print general CLI usage for verse lookup and the currently available versions.

Parameters:: version_catalog (List[dict]) – Ordered catalog of versions that actually exist under data/.
Returns:: None

cli.commands.show_search_usage(version_catalog)[source]

Print CLI usage for keyword search and the currently available versions.

Parameters:: version_catalog (List[dict]) – Ordered catalog of versions that actually exist under data/.
Returns:: None

cli.commands.handle_search_version_only(version, version_label_map, version_catalog)[source]

Handle the case where only the version is specified for keyword search.

This keeps the response search-specific instead of falling back to verse-lookup guidance.

Parameters:

version (str) – Full Bible version key.
version_label_map (dict) – Full version -> CLI label mapping used for user-facing text.
version_catalog (list[dict]) – Ordered catalog of available versions for usage display.

Returns:

None

cli.commands.load_cli_version_catalog()[source]

Build the CLI version catalog from the actual Bible data directory.

This helper centralizes the CLI’s notion of “available versions” so the CLI no longer depends on alias JSON files as the source of truth. Availability is determined by the presence of *.json files under data/.

Returns:

(version_catalog, token_to_version, version_label_map) where:

version_catalog is an ordered list of version entries for display.
token_to_version maps accepted CLI input tokens to full version keys.
version_label_map maps full version keys to the preferred CLI label used in help text and formatted output.

Return type:

Tuple[List[dict], dict, dict]

Note

Alias metadata is used only to improve labels and shorthand tokens. If alias metadata is missing, the raw version key remains usable.

cli.commands.parse_versions_from_args(args, token_to_version)[source]

Parse one or more version tokens from the beginning of CLI arguments.

Parsing strategy:

Scan tokens left-to-right.
For each token, check whether it matches a supported version token.
Stop at the first token that does not match a known version.
Treat the remaining tokens as the Bible reference portion.

Parameters:

args (List[str]) – Raw CLI arguments.
token_to_version (dict) – Mapping of accepted CLI tokens to full version keys.

Returns:

(versions, remaining_args) where:

versions is a list of full version keys resolved from the input.
remaining_args is the remainder of tokens after version parsing.

Return type:

Tuple[List[str], List[str]]

Note

If no version tokens are found, versions will be an empty list.
Callers should validate that case and emit a helpful error.

cli.commands.resolve_search_version(version_token, token_to_version, keywords)[source]

Resolve the full Bible version key used for keyword search.

Keyword search requires exactly one version. This helper:

Validates that version_token exists in the supported token map.
Ensures none of the remaining keyword tokens look like extra version tokens.
Returns the full version key corresponding to version_token.

Parameters:

version_token (str) – CLI token provided by the user.
token_to_version (dict) – Mapping of accepted CLI tokens to full version keys.
keywords (List[str]) – Remaining keyword tokens supplied by the user.

Returns:

Full version key if resolved; otherwise None (after printing an error).

Return type:

str | None

cli.commands.parse_and_validate_reference(remaining)[source]

Join and validate Bible reference tokens.

Expected token shape:

<book> <chapter[:verse[-verse]]>

This function joins the remaining tokens into a single reference string and uses core.utils.bible_parser.parse_reference() for parsing.

Parameters:: remaining (List[str]) – Tokens representing the reference portion.
Returns:: (book, chapter, verse_range) if valid; otherwise None.
Return type:: tuple | None

Side effects:: Prints an [ERROR] message on invalid input.

cli.commands.detect_lang_code_from_aliases(versions, _version_label_map)[source]

Heuristically detect a language code based on selected versions.

This is a CLI-only heuristic primarily used to warn about potential RTL rendering. Detection is based on keywords in the resolved version key.

Note

_version_label_map is intentionally unused, but preserved for signature stability and possible future metadata-based detection.

Parameters:

versions (List[str]) – Full version names selected for output.
_version_label_map (dict) – Reserved for future use.

Returns:

Language code among {"he", "ar", "fa", "ur", "ko"}.

Return type:

str

cli.commands.run_display_logic(versions, book, chapter, verse_range, version_label_map)[source]

Execute the CLI verse display pipeline.

This function:

Loads the selected Bible versions.
Validates that the requested book exists in the first version.
Invokes core.logic.verse_logic.display_verse_logic() in CLI mode, sending formatted output to stdout.

Parameters:

versions (List[str]) – Full version names to load and display.
book (str) – Canonical book key expected by BibleDataLoader.
chapter (int) – Chapter number.
verse_range (Tuple[int, int]) – Verse range (start, end).
version_label_map (dict) – Full version -> CLI label mapping used in formatted output.

Returns:

None

cli.commands.run_keyword_search(full_version, keywords)[source]

Run a keyword search and print results to stdout.

This function loads the specified Bible version through core.utils.bible_keyword_searcher.BibleKeywordSearcher, executes the search, prints each matching verse, then prints per-keyword frequencies and the total result count.

Parameters:

full_version (str) – Full Bible version key.
keywords (List[str]) – Keywords to search. They are joined with spaces before searching.

Returns:

None

cli.commands.handle_version_only(version, version_label_map)[source]

Handle the case where only the version is specified.

This prints the general usage plus the list of available books in that version.

Parameters:

version (str) – Full Bible version key.
version_label_map (dict) – Full version -> CLI label mapping used for user-facing text.

Returns:

None

cli.commands.handle_book_only(version, raw_book)[source]

Handle the case where a version and book are provided, but no chapter/verse.

This prints the chapter count for the requested book.

Parameters:

version (str) – Full Bible version key.
raw_book (str) – User-supplied book token (may be localized or abbreviated).

Returns:

None

cli.commands.run_bible_command(args)[source]

Entry point for the CLI bible command.

Supported invocation patterns:

$ bible                          # show usage and available versions
$ bible NKRV                     # list books available in NKRV
$ bible NKRV John                # show chapter count for John
$ bible NKRV John 3:16           # show a single verse
$ bible NKRV John 3:16-18        # show a verse range
$ bible KJV NIV John 3:16        # show the same reference in multiple versions

Behavior:

Handles metadata flags (--help, --version, --about).
Builds the CLI version catalog from actual Bible data files.
Parses one or more version tokens from the beginning of the argument list.
If only a version is given, prints available books.
If version + book are given, prints chapter count.
If a full reference is provided, prints formatted verse output via shared logic.

Parameters:: args (List[str]) – Command-line arguments excluding the script name and excluding the bible token.
Returns:: None

Note

Version availability is determined by the actual contents of data/.
Alias files affect labels and shorthand parsing only.

cli.commands.run_search_command(args)[source]

Entry point for the CLI search command.

Usage:

bible search <version> <keyword1> [keyword2 ...]

Examples:

bible search NKRV faith
bible search KJV faith grace

Behavior:

Handles metadata flags (--help, --version, --about).
Builds the CLI version catalog from actual Bible data files.
Requires exactly one version token.
Runs keyword search and prints matches and keyword frequencies.

Parameters:: args (List[str]) – Command-line arguments excluding the script name and excluding the search token.
Returns:: None