if-empty

NAME

if-empty - check if a value is empty, whitespace-only, or null

SYNOPSIS

state-name:
  tool: if-empty
  arguments:
    value: <expression>
  goto:
    true: <empty-state>
    false: <not-empty-state>

DESCRIPTION

The if-empty tool evaluates whether a value is considered “empty” and returns "true" or "false" for use with goto branching. This provides cleaner conditional logic compared to using switch with equality expressions.

A value is considered empty if it is:

An empty string ("")
Whitespace-only (" ")
The literal string "null" (common from JSON extraction)
An actual null value

The value is trimmed before evaluation to handle captured outputs with trailing newlines.

ARGUMENTS

Argument	Required	Default	Description
`value`	Yes	-	The value to check for emptiness

EXIT CODES

Code	Meaning
`0`	Success (outputs “true” or “false”)
`1`	Missing required argument

OUTPUT

The tool outputs "true" if the value is empty, or "false" if it has content. This output is used for goto routing.

EXAMPLES

Basic Empty Check

check-input:
  tool: if-empty
  arguments:
    value: "{{ user_input }}"
  goto:
    true: prompt-for-input
    false: process-input

Check Command Output

get-branch:
  tool: bash
  arguments:
    command: git branch --show-current
  output: var(branch)
  next: check-branch

check-branch:
  tool: if-empty
  arguments:
    value: "{{ branch }}"
  goto:
    true: not-in-repo
    false: on-branch

Validate JSON Field

extract-email:
  tool: bash
  arguments:
    command: "jq -r '.email' config.json"
  output: var(email)
  next: check-email

check-email:
  tool: if-empty
  arguments:
    value: "{{ email }}"
  goto:
    true: email-missing
    false: email-found

Guard Against Missing Config

load-api-key:
  tool: bash
  arguments:
    command: 'echo "$API_KEY"'
  output: var(api_key)
  next: validate-key

validate-key:
  tool: if-empty
  arguments:
    value: "{{ api_key }}"
  goto:
    true: request-api-key
    false: proceed-with-api

COMMON PATTERNS

Optional Variable Default

check-optional:
  tool: if-empty
  arguments:
    value: "{{ optional_param }}"
  goto:
    true: use-default
    false: use-provided

use-default:
  tool: bash
  arguments:
    command: echo "default_value"
  output: var(optional_param)
  next: continue-workflow

Pre-flight Validation

validate-inputs:
  tool: if-empty
  arguments:
    value: "{{ required_field }}"
  goto:
    true: validation-failed
    false: check-next-field