Natural Language Syntax

EventFlow uses natural language patterns that read like English. This page covers all syntax patterns.

Actors (@)

Actors are referenced with @ inline, always lowercase:

@customer clicks checkout
@sales_manager approves the order
@system sends notification
@payment_gateway processes the card

Events (:)

Events are referenced with : inline:

on :checkout from @customer (api)
on :payment_success from @payment
emit :order_confirmed to @customer

States (#)

States are referenced with # inline:

order moves to #checkout
payment enters #processing
document transitions to #approved
ticket becomes #closed

State Transition Keywords

All of these are equivalent - use what reads best:

Keyword	Example
moves to	order moves to #paid
transitions to	order transitions to #approved
enters	payment enters #processing
becomes	ticket becomes #closed
changes to	status changes to #active

Guards (?)

Guards are conditions that start with ? at the beginning of the line:

? cart is not empty
  proceed to checkout

Multiple Guards (AND)

Multiple ? lines require ALL conditions to pass:

? payment is authorized
? shipping is valid
? inventory is available
  complete the order

OR Guards

Use ?? for OR conditions:

? user is admin
?? user has manager role
  show admin panel

Combined Logic

? cart is valid
? user is logged in
?? user is guest with email
  allow checkout

Reads as: (cart is valid AND user is logged in) OR user is guest with email

Default Case

Use otherwise or empty ?:

? status is pending
  process request
? status is approved
  send notification
otherwise
  log error

Or with empty ?:

? status is pending
  process request
?
  handle other cases

Assertions (=)

Assertions start with = and appear in expect: blocks:

expect:
  = order is in #processing
  = $total equals 1250
  = @customer received confirmation
  = payment was processed

Data Tables

Use tables for structured data:

cart contains:
  | product     | quantity | price |
  | Laptop      | 1        | 1200  |
  | Mouse       | 2        | 25    |
  | Keyboard    | 1        | 75    |

@customer enters shipping:
  | field   | value           |
  | street  | "123 Main St"   |
  | city    | "Springfield"   |
  | zip     | "62701"         |

Comments

// single line comment

/*
  multi-line
  comment
*/

@customer clicks checkout  // inline comment

Event Patterns

Receiving Events

// Public API endpoint
on :checkout from @customer (api)
  ...

// Internal event
on :payment_success from @payment
  ...

// From any sender
on :status_update
  ...

Sending Events

// Basic emit
emit :payment_request to @payment

// With data
emit :payment_request to @payment
  with $order_id, $total

// With structured data
emit :order_details to @warehouse
  with:
    | field     | value       |
    | order_id  | $order_id   |
    | items     | $items      |
    | priority  | "high"      |

Context Patterns

Setting Values

$total becomes 100
$name becomes "John"
$is_active becomes true
$items becomes empty

With Type Annotations

$total: number becomes 100
$name: string becomes "John"
$is_active: boolean becomes true
$items: array becomes empty

Arithmetic

$total increases by 25
$total decreases by 10
$count increases by 1

Collections

$items adds "Laptop"
$items adds $new_item
$items removes "Mouse"
$items clears

Reading Values

? $total is greater than 100
? $items contains "Laptop"
? $count equals 0
? $name is not empty

Comparison Operators

Pattern	Meaning
equals	Equal to
is	Equal to
is not	Not equal to
is greater than	Greater than
is less than	Less than
is at least	Greater than or equal
is at most	Less than or equal
contains	Array/string contains
is empty	Empty array/string
is not empty	Non-empty

State Checks

? order is in #pending
? order is not in #cancelled
? payment has entered #processing

Time-Based Patterns

? created more than 24 hours ago
? updated within last 1 hour
? days since purchase < 7

Natural Language Flexibility

EventFlow is designed to be flexible. These are equivalent:

// All valid for state transitions
order moves to #paid
order transitions to #paid
order enters #paid
order becomes #paid

// All valid for comparisons
? $total equals 100
? $total is 100
? $total is equal to 100

The goal is readability - use what sounds most natural for your context.