shellscriptor 0.1.0__py3-none-any.whl

shellscriptor/_validate.py

@@ -0,0 +1,413 @@
+from __future__ import annotations
+
+from typing import Literal
+
+from shellscriptor._argparse import param_name_to_var_name
+from shellscriptor._code import indent
+from shellscriptor._log import log
+from shellscriptor._types import (
+    ParameterDef,
+    PathType,
+    ScriptType,
+    ValidationDef,
+)
+
+
+def create_validation_block(
+    parameters: dict[str, ParameterDef],
+    *,
+    local: bool,
+    script_type: ScriptType,
+) -> list[str]:
+    """Generate validation lines for all parameters.
+
+    Parameters
+    ----------
+    parameters:
+        Mapping of parameter name → :class:`~shellscriptor._types.ParameterDef`.
+    local:
+        Whether variables are function-local.
+    script_type:
+        Controls whether informational log calls are emitted.
+
+    Returns
+    -------
+    List of shell lines covering all parameter validations.
+    """
+    lines: list[str] = []
+    for param_name, param_data in sorted((parameters or {}).items()):
+        lines.extend(
+            validate_variable(
+                var_name=param_name_to_var_name(param_name, local=local),
+                var_type=param_data.type,
+                default=param_data.default,
+                required=param_data.required,
+                validations=param_data.validation,
+                script_type=script_type,
+            )
+        )
+    return lines
+
+
+def validate_variable(
+    var_name: str,
+    var_type: Literal["string", "boolean", "array", "integer"],
+    default: str | list[str] | None,
+    required: bool | None,
+    validations: ValidationDef | None,
+    script_type: ScriptType,
+) -> list[str]:
+    """Generate all validation checks for a single variable.
+
+    Applies, in order:
+
+    1. Missing-argument / default assignment check — **unless** the
+       parameter is explicitly optional (``required=False``) and has no
+       default, in which case the variable is allowed to be empty after
+       argument parsing and the check is skipped entirely.
+       Boolean variables are always normalised to ``"false"`` when unset
+       regardless of ``required``.
+    2. For scalars/integers: enum, path-existence, integer-range, and regex
+       checks directly on the variable.
+    3. For arrays with structural validators (enum / path-existence /
+       integer-range / regex): wraps checks in a ``for elem in …`` loop.
+    4. Custom shell lines verbatim.
+
+    Parameters
+    ----------
+    var_name:
+        Shell variable name.
+    var_type:
+        One of ``"string"``, ``"boolean"``, ``"array"``, ``"integer"``.
+    default:
+        Default value(s).  ``None`` with ``required`` unset or ``True``
+        makes the parameter required.
+    required:
+        Explicit required flag.
+
+        * ``True``  — exit if missing (``default`` is ignored).
+        * ``False`` — optional; if ``default`` is also ``None`` the check
+          is skipped entirely and the variable may remain empty.
+        * ``None``  — inferred: required when ``default is None``, optional
+          otherwise.
+    validations:
+        Optional validation rules applied after the missing-arg check.
+    script_type:
+        Controls whether informational log calls are emitted.
+
+    Returns
+    -------
+    List of shell validation lines.
+    """
+    # Determine effective required flag
+    is_required = required if required is not None else (default is None)
+
+    # Boolean: always normalise "" → "false"; never treated as "skip".
+    # Other types: only emit check when required OR a default is provided.
+    # When required=False and default=None the variable is genuinely optional
+    # (empty after parsing is acceptable) — skip the check.
+    emit_missing_check = var_type == "boolean" or is_required or default is not None
+
+    out: list[str] = []
+    if emit_missing_check:
+        out.append(
+            validate_missing_arg(
+                var_name=var_name,
+                var_type=var_type,
+                default=default if not is_required else None,
+                script_type=script_type,
+            )
+        )
+
+    if var_type == "boolean":
+        return out
+
+    validations = validations or ValidationDef()
+    has_structural = bool(
+        validations.enum
+        or validations.path_existence
+        or validations.integer_range
+        or validations.regex
+    )
+    in_for_loop = has_structural and var_type == "array"
+
+    if in_for_loop:
+        out.append(f'for elem in "${{{var_name}[@]}}"; do')
+
+    check_var = "elem" if in_for_loop else var_name
+    level = 1 if in_for_loop else 0
+
+    if validations.enum:
+        out.extend(indent(validate_enum(var_name=check_var, enum=validations.enum), level))
+    if validations.path_existence:
+        pe = validations.path_existence
+        out.extend(indent(validate_path_existence(var_name=check_var, must_exist=pe.must_exist, path_type=pe.type), level))
+    if validations.integer_range:
+        ir = validations.integer_range
+        out.extend(indent(validate_integer_range(var_name=check_var, min_val=ir.min, max_val=ir.max), level))
+    if validations.regex:
+        out.extend(indent(validate_regex(var_name=check_var, pattern=validations.regex), level))
+
+    if in_for_loop:
+        out.append("done")
+
+    if validations.custom:
+        out.extend(validations.custom)
+
+    return out
+
+
+def validate_missing_arg(
+    var_name: str,
+    var_type: Literal["string", "boolean", "array", "integer"],
+    default: str | list[str] | None,
+    script_type: ScriptType,
+) -> str:
+    """Generate a one-liner that enforces presence or applies a default.
+
+    * When *default* is ``None`` the variable is treated as **required** and
+      the generated code calls ``exit 1`` if the variable is unset or empty.
+    * When *default* is provided, the generated code assigns that value and
+      logs the action (in ``shell_exec`` mode only).
+    * For ``boolean`` variables the default is always ``"false"``; the
+      *default* argument is therefore ignored and this function should be
+      called unconditionally for booleans to normalise ``""`` → ``"false"``.
+
+    Parameters
+    ----------
+    var_name:
+        Shell variable name.
+    var_type:
+        One of ``"string"``, ``"boolean"``, ``"array"``, ``"integer"``.
+    default:
+        Default value, or ``None`` to require the argument.
+    script_type:
+        Controls whether informational log calls are emitted.
+
+    Returns
+    -------
+    A single shell line (one-liner).
+    """
+
+    def _info_default(default_repr: str) -> str:
+        if script_type == "shell_src":
+            return ""
+        msg = f"Argument '{var_name}' set to default value '{default_repr}'."
+        return f"{log(msg, 'info')}; "
+
+    err = log(f"Missing required argument '{var_name}'.", "critical")
+
+    if var_type in ("string", "integer"):
+        check = f'[ -z "${{{var_name}-}}" ]'
+        if default is None:
+            action = err
+        else:
+            action = f'{_info_default(str(default))}{var_name}="{default}"'
+    elif var_type == "boolean":
+        check = f'[ -z "${{{var_name}-}}" ]'
+        action = f"{_info_default('false')}{var_name}=false"
+    elif var_type == "array":
+        check = f'{{ [ "${{{var_name}+isset}}" != "isset" ] || [ ${{#{var_name}[@]}} -eq 0 ]; }}'
+        if default is None:
+            action = err
+        else:
+            default_list: list[str] = (
+                default if isinstance(default, list) else [default]
+            )
+            quoted = " ".join('"' + e + '"' for e in default_list)
+            default_str = f"({quoted})"
+            action = f"{_info_default(default_str)}{var_name}={default_str}"
+    else:
+        raise ValueError(f"Unsupported var_type: {var_type!r}")
+
+    return f"{check} && {{ {action}; }}"
+
+
+def validate_enum(var_name: str, enum: list[str]) -> list[str]:
+    """Generate a ``case`` statement that rejects values not in *enum*.
+
+    The empty string is intentionally excluded from the allowed set; the
+    missing-arg check (which must run first) already handles unset/empty
+    variables.
+
+    Parameters
+    ----------
+    var_name:
+        Shell variable name to check.
+    enum:
+        Allowed values.  Must contain at least one entry.
+
+    Returns
+    -------
+    List of shell lines.
+
+    Raises
+    ------
+    ValueError
+        If *enum* is empty.
+    """
+    if not enum:
+        raise ValueError("validate_enum: 'enum' must contain at least one value")
+    enum_str = "|".join('"' + v + '"' for v in enum)
+    _invalid_msg = f"Invalid value for argument '--{var_name}': '${{{var_name}}}'"
+    return [
+        f'case "${{{var_name}}}" in',
+        indent(f"{enum_str});;", 1),
+        indent(
+            f'*) {log(_invalid_msg, "critical")};;',
+            1,
+        ),
+        "esac",
+    ]
+
+
+def validate_path_existence(
+    var_name: str,
+    must_exist: bool,
+    path_type: PathType | None = None,
+) -> list[str]:
+    """Generate a check that a path exists (or does not exist).
+
+    The check is guarded by ``[ -n "${VAR-}" ]`` so that it is silently
+    skipped when the variable is empty.  This means the missing-arg check
+    (``validate_missing_arg``) must run before this one if a non-empty value
+    is required.
+
+    Parameters
+    ----------
+    var_name:
+        Shell variable holding the path.
+    must_exist:
+        ``True`` → path must exist; ``False`` → path must *not* exist.
+    path_type:
+        Kind of filesystem entry to test, or ``None`` for any entry
+        (uses ``-e``).
+
+    Returns
+    -------
+    A single-element list containing the shell check line.
+    """
+    _op: dict[PathType | None, str] = {
+        None: "e",
+        "dir": "d",
+        "exec": "x",
+        "file": "f",
+        "symlink": "L",
+    }
+    _name: dict[PathType | None, str] = {
+        None: "Path",
+        "dir": "Directory",
+        "exec": "Executable",
+        "file": "File",
+        "symlink": "Symbolic link",
+    }
+    condition = "not found" if must_exist else "already exists"
+    err_msg = (
+        f"{_name[path_type]} argument to parameter '{var_name}' "
+        f"{condition}: '${{{var_name}}}'"
+    )
+    negation = "! " if must_exist else ""
+    cmd = (
+        f'[ -n "${{{var_name}-}}" ] && '
+        f'[ {negation}-{_op[path_type]} "${{{var_name}}}" ] && '
+        f'{{ {log(err_msg, "critical")}; }}'
+    )
+    return [cmd]
+
+
+def validate_integer_range(
+    var_name: str,
+    min_val: int | None,
+    max_val: int | None,
+) -> list[str]:
+    """Generate a check that an integer variable is within [*min_val*, *max_val*].
+
+    Always emits a regex guard to ensure the value is a valid integer (matches
+    ``^-?[0-9]+$``) before comparing bounds.  Either bound may be ``None`` to
+    indicate no bound in that direction.
+
+    Parameters
+    ----------
+    var_name:
+        Shell variable holding the integer string.
+    min_val:
+        Inclusive lower bound, or ``None``.
+    max_val:
+        Inclusive upper bound, or ``None``.
+
+    Returns
+    -------
+    List of shell lines.
+    """
+    lines: list[str] = [
+        f'if ! [[ "${{{var_name}}}" =~ ^-?[0-9]+$ ]]; then',
+        indent(
+            log(
+                f"Argument '{var_name}' is not an integer: '${{{var_name}}}'",
+                "critical",
+            ),
+            1,
+        ),
+        "fi",
+    ]
+    if min_val is not None:
+        lines.extend(
+            [
+                f'if [[ "${{{var_name}}}" -lt {min_val} ]]; then',
+                indent(
+                    log(
+                        f"Argument '{var_name}' must be >= {min_val}, got '${{{var_name}}}'",
+                        "critical",
+                    ),
+                    1,
+                ),
+                "fi",
+            ]
+        )
+    if max_val is not None:
+        lines.extend(
+            [
+                f'if [[ "${{{var_name}}}" -gt {max_val} ]]; then',
+                indent(
+                    log(
+                        f"Argument '{var_name}' must be <= {max_val}, got '${{{var_name}}}'",
+                        "critical",
+                    ),
+                    1,
+                ),
+                "fi",
+            ]
+        )
+    return lines
+
+
+def validate_regex(var_name: str, pattern: str) -> list[str]:
+    """Generate a check that a variable's value matches *pattern*.
+
+    Uses bash's ``[[ … =~ … ]]`` extended regex operator (ERE syntax).
+    The check exits the script with code 1 if the value does not match.
+
+    Parameters
+    ----------
+    var_name:
+        Shell variable to check.
+    pattern:
+        ERE pattern passed directly into ``[[ "${VAR}" =~ … ]]``.
+        Must not contain unescaped shell-special characters that would
+        break the surrounding ``if`` construct.
+
+    Returns
+    -------
+    List of shell lines.
+    """
+    return [
+        f'if ! [[ "${{{var_name}}}" =~ {pattern} ]]; then',
+        indent(
+            log(
+                f"Argument '{var_name}' does not match pattern '{pattern}': '${{{var_name}}}'",
+                "critical",
+            ),
+            1,
+        ),
+        "fi",
+    ]