control

@make_procedure
class AssertBool(Procedure[Void]):
    """Assert that a boolean condition is true, failing with a message if false.

    Used to validate conditions and assumptions during procedure execution.
    If the condition evaluates to false, the procedure will fail with the
    provided error message.

    Attributes:
        condition: The boolean condition that must be true.
        text: Error text shown to the user if the condition is false.
    """

    condition: Input[Bool]
    text: Input[String]

@make_procedure
class DoNothing(Procedure[Void]):
    """Do nothing and return immediately (no-op).

    Useful as a placeholder or default branch in conditional logic where one
    path should perform no action.
    """

@make_procedure
@forward_types(CGType, "true_branch", "false_branch")
class IfThenElse[T: CGType](Procedure[T]):
    """Execute one of two branches based on a boolean condition.

    Executes the true or false branch depending on the condition's result.
    Both branches must return the same type ``T``. This enables dynamic
    workflows that adapt based on user input, data conditions, or environmental
    factors. The ``with cg.when(condition):`` block builds the common one-sided
    case (a ``DoNothing`` false branch); construct this node directly for a
    two-sided branch.

    Attributes:
        condition: Boolean procedure to evaluate.
        true_branch: Procedure to execute if condition is true.
        false_branch: Procedure to execute if condition is false.
    """

    condition: Input[Bool]

    true_branch: Input[T]
    false_branch: Input[T]

@make_procedure
class NullProcedure[T: CGType](Procedure[T]):
    """Return a null/empty value of type ``T``.

    Used as a placeholder that produces no actual data but maintains type
    compatibility. Useful for optional branches or default values.

    Attributes:
        output_type: The CGType this procedure returns. Consumed at
            construction — ``__post_init__`` moves it into the node's return type
            and resets the field to ``None``, so it is never serialized as a
            setting (the type is recoverable from the node's ``return_type``).

    Example:
        ```python
        # A null image, e.g. as a default for an optional image input
        cg.NullProcedure(output_type=cg.Image)
        ```
    """

    output_type: Setting[type[T]]

    def __post_init__(self) -> None:
        """Consume ``output_type`` into ``_return_type`` and clear the setting."""
        object.__setattr__(self, "_return_type", self.output_type)
        object.__setattr__(self, "output_type", None)
        super().__post_init__()

@make_procedure
class ProcedureCompleted(Procedure[Bool]):
    """Report whether a procedure completes successfully, as a boolean.

    Runs ``procedure`` and returns ``true`` when it produces a value, ``false``
    when it fails — without propagating the failure. This turns a value's mere
    presence into a condition: pairing it with ``LoadPath`` asks "is there a value
    at this position?" (the basis of ``path.exists()``), which gates a block with
    ``cg.when(...)`` rather than letting a missing value abort the run.

    Attributes:
        procedure: The procedure whose completion is tested; its value is discarded.
    """

    procedure: Procedure[CGType]