shellscriptor 0.1.0__py3-none-any.whl

shellscriptor/__init__.py

@@ -0,0 +1,23 @@
+from __future__ import annotations
+from shellscriptor._code import indent, sanitize_code
+from shellscriptor._log import log, log_arg_read, log_arg_write, log_endpoint
+from shellscriptor._output import create_output
+from shellscriptor._script import create_function, create_script
+from shellscriptor._types import (
+    BodySection, FunctionDef, IntegerRangeDef, LogLevel,
+    ParameterDef, ParamType, PathExistenceDef, PathType,
+    ReturnDef, ScriptDef, ScriptType, ValidationDef,
+)
+from shellscriptor._validate import (
+    create_validation_block, validate_enum, validate_integer_range,
+    validate_missing_arg, validate_path_existence, validate_regex, validate_variable,
+)
+__all__ = [
+    "create_script", "create_function", "create_validation_block",
+    "validate_variable", "validate_missing_arg", "validate_enum",
+    "validate_path_existence", "validate_integer_range", "validate_regex",
+    "create_output", "log", "log_endpoint", "log_arg_read", "log_arg_write",
+    "indent", "sanitize_code", "ScriptType", "ParamType", "PathType",
+    "LogLevel", "ScriptDef", "FunctionDef", "ParameterDef", "ValidationDef",
+    "ReturnDef", "BodySection", "PathExistenceDef", "IntegerRangeDef",
+]

shellscriptor/__main__.py

@@ -0,0 +1,142 @@
+"""Command-line interface for shellscriptor.
+
+Usage
+-----
+  shellscriptor <definition-file> [--output <path>] [--type <shell_src|shell_exec>]
+
+*definition-file* must be a YAML or JSON file whose top level is either:
+
+* A **script definition** dict (containing ``"body"``, ``"parameter"``, etc.) —
+  in this case ``--type`` and ``--name`` must also be supplied, or
+* A wrapper object with keys:
+
+  .. code-block:: yaml
+
+     name: my-script
+     type: shell_exec      # or shell_src
+     script:              # ScriptDef
+       interpreter: /bin/bash
+       ...
+
+Examples
+--------
+  shellscriptor my_script.yaml
+  shellscriptor my_script.json --output dist/my_script.sh
+  python -m shellscriptor my_script.yaml --type shell_exec --name deploy
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+
+def _load_definition(path: Path) -> dict:
+    """Load a YAML or JSON definition file."""
+    suffix = path.suffix.lower()
+    text = path.read_text(encoding="utf-8")
+    if suffix in (".yaml", ".yml"):
+        try:
+            import yaml  # type: ignore[import-untyped]
+        except ImportError as exc:
+            print(
+                "PyYAML is required to read YAML files: pip install pyyaml",
+                file=sys.stderr,
+            )
+            raise SystemExit(1) from exc
+        return yaml.safe_load(text)
+    if suffix == ".json":
+        return json.loads(text)
+    # Attempt YAML then JSON as fallback
+    try:
+        import yaml  # type: ignore[import-untyped]
+        return yaml.safe_load(text)
+    except Exception:
+        pass
+    return json.loads(text)
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Entry point for the ``shellscriptor`` command."""
+    parser = argparse.ArgumentParser(
+        prog="shellscriptor",
+        description="Generate a shell script from a YAML/JSON definition file.",
+    )
+    parser.add_argument(
+        "definition",
+        metavar="DEFINITION_FILE",
+        type=Path,
+        help="Path to a YAML or JSON script definition file.",
+    )
+    parser.add_argument(
+        "--output",
+        "-o",
+        metavar="PATH",
+        type=Path,
+        default=None,
+        help="Write generated script to this file (default: stdout).",
+    )
+    parser.add_argument(
+        "--type",
+        "-t",
+        dest="script_type",
+        choices=["shell_src", "shell_exec"],
+        default=None,
+        help=(
+            "Script type override.  Required when the definition file does not "
+            "contain a top-level 'type' key."
+        ),
+    )
+    parser.add_argument(
+        "--name",
+        "-n",
+        dest="name",
+        default=None,
+        help=(
+            "Script name used in log messages.  Defaults to the definition "
+            "file stem."
+        ),
+    )
+    args = parser.parse_args(argv)
+
+    definition_path: Path = args.definition
+    if not definition_path.exists():
+        print(f"Error: file not found: {definition_path}", file=sys.stderr)
+        return 1
+
+    raw = _load_definition(definition_path)
+
+    # Support both wrapper format and bare ScriptDef format
+    if "script" in raw:
+        script_def = raw["script"]
+        script_type = args.script_type or raw.get("type")
+        name = args.name or raw.get("name") or definition_path.stem
+    else:
+        script_def = raw
+        script_type = args.script_type or raw.get("type")
+        name = args.name or definition_path.stem
+
+    if script_type not in ("shell_src", "shell_exec"):
+        print(
+            f"Error: script type must be 'shell_src' or 'shell_exec'; "
+            f"got {script_type!r}. Pass --type to override.",
+            file=sys.stderr,
+        )
+        return 1
+
+    from shellscriptor import create_script
+
+    result = create_script(name=name, data=script_def, script_type=script_type)
+
+    if args.output:
+        args.output.parent.mkdir(parents=True, exist_ok=True)
+        args.output.write_text(result + "\n", encoding="utf-8")
+    else:
+        print(result)
+
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

shellscriptor/_argparse.py

@@ -0,0 +1,213 @@
+from __future__ import annotations
+
+from shellscriptor._code import indent
+from shellscriptor._log import log, log_arg_read
+from shellscriptor._types import ParameterDef, ScriptType
+
+
+def param_name_to_var_name(param_name: str, *, local: bool) -> str:
+    """Convert a parameter name to its shell variable name.
+
+    Hyphens are replaced with underscores.  Global (non-local) variables are
+    uppercased, matching conventional shell style.
+
+    Parameters
+    ----------
+    param_name:
+        The parameter name as given in the definition dict.
+    local:
+        ``True`` for function-local variables (lowercase preserved);
+        ``False`` for script-global variables (uppercased).
+
+    Returns
+    -------
+    The derived shell variable name.
+    """
+    var_name = param_name.replace("-", "_")
+    return var_name if local else var_name.upper()
+
+
+def create_argparse(
+    parameters: dict[str, ParameterDef],
+    *,
+    local: bool,
+    script_type: ScriptType,
+    with_help: bool = False,
+) -> list[str]:
+    """Generate a ``while/case`` argument-parsing block.
+
+    Produces variable initialisation lines followed by a ``while [[ $# -gt 0
+    ]]; do … done`` loop that maps ``--flag`` arguments to shell variables.
+
+    * Boolean flags are set to ``true`` when present and require no value.
+    * String/integer flags consume the next positional argument (``$1``
+      after the dispatch ``shift``).
+    * Array flags accumulate all following non-``--`` arguments.
+
+    Short aliases (single-char ``short`` field) generate an additional
+    ``case`` arm alongside the long form.
+
+    If *with_help* is ``True``, a ``--help``/``-h`` arm is added that calls
+    the caller-supplied ``__usage__`` function.
+
+    Parameters
+    ----------
+    parameters:
+        Mapping of parameter name → :class:`~shellscriptor._types.ParameterDef`.
+    local:
+        Whether to declare variables as ``local``.
+    script_type:
+        Controls whether read-logging calls are emitted.
+    with_help:
+        Emit a ``--help|-h) __usage__;;`` arm when ``True``.  The caller is
+        responsible for ensuring ``__usage__`` is defined before the loop.
+
+    Returns
+    -------
+    List of shell lines (variable declarations + parsing loop).
+    """
+    if not parameters:
+        return []
+    def_lines: list[str] = []
+    case_lines: list[str] = [
+        "while [[ $# -gt 0 ]]; do",
+        indent("case $1 in", 1),
+    ]
+
+    for param_name, param_data in sorted(parameters.items()):
+        var_name = param_name_to_var_name(param_name, local=local)
+        param_type = param_data.type
+        short = param_data.short
+
+        scalar_log = (
+            "" if script_type == "shell_src"
+            else f" {log_arg_read(param_name, var_name)};"
+        )
+        array_log = (
+            "" if script_type == "shell_src"
+            else f" {log_arg_read(param_name, '1')};"
+        )
+
+        if param_type == "boolean":
+            initial_value = '""'
+            argparse_cmd = f"{var_name}=true;{scalar_log}"
+        elif param_type in ("string", "integer"):
+            initial_value = '""'
+            # After the dispatch `shift` the flag is consumed, so $1 is now the value;
+            # a second shift at the end of argparse_cmd consumes it.
+            argparse_cmd = f'{var_name}="$1";{scalar_log} shift'
+        elif param_type == "array":
+            initial_value = "()"
+            argparse_cmd = (
+                f'while [[ $# -gt 0 && ! "$1" =~ ^-- ]]; do '
+                f'{var_name}+=("$1");{array_log} shift; done'
+            )
+        else:
+            raise ValueError(f"Unsupported parameter type: {param_type!r}")
+
+        local_prefix = "local " if local else ""
+        def_lines.append(f"{local_prefix}{var_name}={initial_value}")
+
+        # Build arms: long form, and optionally short form
+        long_arm = f"--{param_name}"
+        short_arm = f"-{short}" if short else None
+        flag_pattern = f"{long_arm}|{short_arm}" if short_arm else long_arm
+
+        case_lines.append(
+            indent(
+                f"{flag_pattern}) shift; {argparse_cmd.removesuffix(';')};;",
+                2,
+            )
+        )
+
+    # Unknown / unexpected catch-alls
+    if with_help:
+        case_lines.append(indent("--help|-h) __usage__;;", 2))
+    _unknown_opt_log = log("Unknown option: '${1}'", "critical")
+    _unexpected_arg_log = log("Unexpected argument: '${1}'", "critical")
+    case_lines.extend(
+        [
+            indent(f"--*) {_unknown_opt_log};;", 2),
+            indent(f"*) {_unexpected_arg_log};;", 2),
+        ]
+    )
+    case_lines.extend([indent("esac", 1), "done"])
+
+    return def_lines + case_lines
+
+
+def create_usage_function(parameters: dict[str, ParameterDef]) -> list[str]:
+    """Generate a ``__usage__`` function that prints a help summary to stderr.
+
+    Only emitted when at least one parameter has a ``"description"`` field.
+
+    Parameters
+    ----------
+    parameters:
+        Mapping of parameter name → :class:`~shellscriptor._types.ParameterDef`.
+
+    Returns
+    -------
+    Lines defining the ``__usage__`` shell function, or an empty list.
+    """
+    if not any(p.description for p in parameters.values()):
+        return []
+    lines: list[str] = ["__usage__() {", indent('echo "Usage:" >&2', 1)]
+    for param_name, param_data in sorted(parameters.items()):
+        desc = param_data.description
+        param_type = param_data.type
+        short = param_data.short
+        flag = f"--{param_name}"
+        if short:
+            flag = f"-{short}, {flag}"
+        lines.append(indent(f'echo "  {flag} ({param_type}): {desc}" >&2', 1))
+    lines.extend([indent("exit 0", 1), "}"])
+    return lines
+
+
+def create_env_var_parse(parameters: dict[str, ParameterDef]) -> list[str]:
+    """Generate a block that reads parameter values from environment variables.
+
+    Used in ``shell_exec`` scripts when they are called with no arguments —
+    the script falls back to reading exported environment variables.
+
+    Parameters
+    ----------
+    parameters:
+        Mapping of parameter name → :class:`~shellscriptor._types.ParameterDef`.
+
+    Returns
+    -------
+    List of shell lines.
+    """
+    lines: list[str] = []
+    for param_name, param_data in sorted(parameters.items()):
+        var_name = param_name_to_var_name(param_name, local=False)
+        param_type = param_data.type
+        if param_type == "array":
+            delimiter = param_data.array_delimiter
+            lines.extend(
+                [
+                    f'if [ "${{{var_name}+defined}}" ]; then',
+                    indent(
+                        log(f"Parse '{param_name}' into array: '${{{var_name}}}'", "info"),
+                        1,
+                    ),
+                    indent(
+                        f'IFS="{delimiter}" read -r -a _tmp_array <<< "${{{var_name}}}"',
+                        1,
+                    ),
+                    indent(f'{var_name}=("${{_tmp_array[@]}}")', 1),
+                    indent(f'for _item in "${{{var_name}[@]}}"; do', 1),
+                    indent(log_arg_read(param_name, "_item"), 2),
+                    indent("done", 1),
+                    indent("unset _item", 1),
+                    indent("unset _tmp_array", 1),
+                    "fi",
+                ]
+            )
+        else:
+            lines.append(
+                f'[ "${{{var_name}+defined}}" ] && {log_arg_read(param_name, var_name)}'
+            )
+    return lines

shellscriptor/_code.py

@@ -0,0 +1,76 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, overload
+
+if TYPE_CHECKING:
+    pass
+
+
+@overload
+def indent(code: str, level: int) -> str: ...
+@overload
+def indent(code: list[str], level: int) -> list[str]: ...
+def indent(code: str | list[str], level: int = 0) -> str | list[str]:
+    """Indent each line of shell code by *level* steps (2 spaces each).
+
+    Parameters
+    ----------
+    code:
+        A single string or a list of lines to indent.
+    level:
+        Number of indentation levels.  Each level adds 2 spaces.
+
+    Returns
+    -------
+    The same type as *code* was passed in, with indentation applied.
+    """
+    if not level:
+        return code
+    prefix = " " * level * 2
+    input_is_str = isinstance(code, str)
+    lines = code.splitlines() if input_is_str else code
+    indented = [f"{prefix}{line}" for line in lines]
+    return "\n".join(indented) if input_is_str else indented
+
+
+def sanitize_code(
+    code: str | list[str],
+    remove_comments: bool = True,
+    remove_empty_lines: bool = True,
+    remove_trailing_whitespace: bool = True,
+    indent_level: int = 0,
+) -> list[str]:
+    """Sanitize shell code by stripping noise and optionally indenting.
+
+    Parameters
+    ----------
+    code:
+        Shell code as a single string or list of lines.
+    remove_comments:
+        Drop lines whose first non-whitespace character is ``#``.
+    remove_empty_lines:
+        Drop blank (or whitespace-only) lines.
+    remove_trailing_whitespace:
+        Strip trailing whitespace from each line.
+    indent_level:
+        Indentation levels to add to each surviving line.
+
+    Returns
+    -------
+    List of sanitized lines.
+    """
+    if isinstance(code, str):
+        code = code.splitlines()
+    prefix = " " * indent_level * 2
+    out: list[str] = []
+    for line in code or []:
+        if remove_comments and line.lstrip().startswith("#"):
+            continue
+        if remove_empty_lines and not line.strip():
+            continue
+        if remove_trailing_whitespace:
+            line = line.rstrip()
+        if indent_level:
+            line = f"{prefix}{line}"
+        out.append(line)
+    return out

shellscriptor/_log.py

@@ -0,0 +1,125 @@
+from __future__ import annotations
+
+from typing import Literal
+
+from shellscriptor._code import indent
+from shellscriptor._types import LogLevel, ScriptType
+
+
+_EMOJI: dict[LogLevel, str] = {
+    "info": "ℹ️",
+    "warn": "⚠️",
+    "error": "❌",
+    "critical": "⛔",
+}
+
+
+def log(
+    msg: str,
+    level: LogLevel | None = None,
+    code: int = 1,
+    indent_level: int = 0,
+) -> str:
+    """Generate a shell command that logs *msg* to stderr and optionally exits.
+
+    Parameters
+    ----------
+    msg:
+        Message text.  May contain shell variable references (e.g. ``$VAR``).
+    level:
+        Severity.  ``"error"`` appends ``return <code>``; ``"critical"``
+        appends ``exit <code>``; other levels only print.
+    code:
+        Exit / return code appended when *level* is ``"error"`` or
+        ``"critical"``.
+    indent_level:
+        Number of indentation levels (2 spaces each) to prepend.
+
+    Returns
+    -------
+    A single-line shell command string.
+
+    Examples
+    --------
+    >>> log("Done.", level="info")
+    'echo "ℹ️ Done." >&2'
+    >>> log("Missing arg.", level="critical")
+    'echo "⛔ Missing arg." >&2; exit 1'
+    """
+    prefix = f"{_EMOJI[level]} " if level else ""
+    echo = f'echo "{prefix}{msg}" >&2'
+    if level == "error":
+        cmd = f"{echo}; return {code}"
+    elif level == "critical":
+        cmd = f"{echo}; exit {code}"
+    else:
+        cmd = echo
+    return indent(cmd, indent_level)
+
+
+def log_endpoint(
+    name: str,
+    typ: Literal["function", "script"],
+    stage: Literal["entry", "exit"],
+) -> str:
+    """Generate a log line marking entry into or exit from a function/script.
+
+    Parameters
+    ----------
+    name:
+        Name of the function or script.
+    typ:
+        ``"function"`` or ``"script"``.
+    stage:
+        ``"entry"`` or ``"exit"``.
+
+    Returns
+    -------
+    A shell ``echo`` command string.
+    """
+    emoji = {"entry": "↪️", "exit": "↩️"}
+    return log(f"{emoji[stage]} {typ.capitalize()} {stage}: {name}")
+
+
+def log_arg_read(param_name: str, var_name: str) -> str:
+    """Generate a log line announcing that argument *param_name* was read.
+
+    Parameters
+    ----------
+    param_name:
+        Logical parameter name (used in the message text).
+    var_name:
+        Shell variable name whose value will be interpolated.
+
+    Returns
+    -------
+    A shell ``echo`` command string.
+
+    Examples
+    --------
+    >>> log_arg_read("my-param", "MY_PARAM")
+    "echo \"📩 Read argument 'my-param': '${MY_PARAM}'\" >&2"
+    """
+    return log(f"📩 Read argument '{param_name}': '${{{var_name}}}'")
+
+
+def log_arg_write(param_name: str, var_name: str) -> str:
+    """Generate a log line announcing that output *param_name* was written.
+
+    Parameters
+    ----------
+    param_name:
+        Logical output name (used in the message text).
+    var_name:
+        Shell variable name whose value will be interpolated.
+
+    Returns
+    -------
+    A shell ``echo`` command string.
+
+    Examples
+    --------
+    >>> log_arg_write("result", "RESULT")
+    "echo \"📤 Write output 'result': '${RESULT}'\" >&2"
+    """
+    return log(f"📤 Write output '{param_name}': '${{{var_name}}}'")

shellscriptor/_output.py

@@ -0,0 +1,72 @@
+from __future__ import annotations
+
+from shellscriptor._code import indent
+from shellscriptor._log import log_arg_write
+from shellscriptor._types import ReturnDef, ScriptType
+
+_TOP_SEP = "\\0"
+_SUB_SEP = "\\x1F"
+
+
+def create_output(
+    returns: list[ReturnDef] | None,
+    script_type: ScriptType,
+) -> list[str]:
+    """Generate shell code that writes return values to stdout.
+
+    Encoding scheme (consistent with ``mapfile``/``read`` callers):
+
+    * **Single scalar** — ``echo "$VAR"``; caller uses ``val=$(fn)``.
+    * **Single array** — ``printf '%s\\0' "${VAR[@]}"``;  caller uses
+      ``mapfile -d '' -t arr < <(fn)``.
+    * **Multiple values** — each value is separated by ``\\0`` at the top
+      level.  Array values within a multi-return are internally delimited
+      by ``\\x1F`` so the caller can split them after unpacking.
+
+    Parameters
+    ----------
+    returns:
+        List of :class:`~shellscriptor._types.ReturnDef` dicts, or ``None``.
+    script_type:
+        Controls whether write-logging calls are emitted.
+
+    Returns
+    -------
+    List of shell lines.
+    """
+    if not returns:
+        return []
+
+    def _output_array(label: str, var: str, sep: str) -> list[str]:
+        lines = [f'for elem in "${{{var}[@]}}"; do']
+        if script_type == "shell_exec":
+            lines.append(indent(log_arg_write(label, var), 1))
+        lines.extend([indent(f"printf '%s{sep}' \"$elem\"", 1), "done"])
+        return lines
+
+    lines: list[str] = []
+    n = len(returns)
+
+    if n == 1:
+        ret = returns[0]
+        rtype, rvar, rlabel = ret.type, ret.variable, ret.name
+        if rtype != "array":
+            if script_type == "shell_exec":
+                lines.append(log_arg_write(rlabel, rvar))
+            lines.append(f'echo "${{{rvar}}}"')
+        else:
+            lines.extend(_output_array(rlabel, rvar, _TOP_SEP))
+        return lines
+
+    # Multiple returns: top-level NUL, arrays use SUB_SEP internally
+    for ret in returns:
+        rtype, rvar, rlabel = ret.type, ret.variable, ret.name
+        if rtype == "array":
+            lines.extend(_output_array(rlabel, rvar, _SUB_SEP))
+            lines.append(f"printf '{_TOP_SEP}'")
+        else:
+            if script_type == "shell_exec":
+                lines.append(log_arg_write(rlabel, rvar))
+            lines.append(f"printf '%s{_TOP_SEP}' \"${{{rvar}}}\"")
+
+    return lines