Language Overview

This page documents currently implemented language behavior in Hyperphp. For host model rules and tell resolution details, see Model Runtime.

Quick Syntax Map

  • assignment: set ... to ..., put ... into ...
  • includes: use script "..."
  • flow: if, repeat, exit repeat, next repeat
  • handlers: on ... end ..., return
  • errors: try/on error/end try, error
  • tell: tell application "...", nested tell ...
  • queries: every ... whose ..., object specifiers, of chains
  • expressions: arithmetic/comparison/logical/containment/concatenation
  • literals: number, text, boolean, list, record
  • coercion: ... as integer|number|text|boolean|list|record

Assignment and Values

set count to 1
put count + 1 into count

set numbers to {1, 2, 3}
set user to {name: "Ada", active: true}
set asText to count as text

Notes: - set and put both assign to variables, record paths, or tell properties. - Multi-word property phrases normalize to snake case keys (read status -> read_status). - as supports aliases: int/integer, real/number/float/double, text/string, bool/boolean, list/array, record/object.

Control Flow

set total to 0

repeat 5 times
    set total to total + 1
end repeat

repeat while total < 10
    set total to total + 1
end repeat

repeat until total >= 12
    set total to total + 1
end repeat

repeat
    if total >= 20 then
        exit repeat
    end if

    set total to total + 1
    next repeat
end repeat

Also supported: - repeat with item in someList - if ... then ... else ... end if

Handlers and Calls

on add(a, b)
    return a + b
end add

set resultValue to add(40, 2)

Call style: - add(1, 2) - add 1, 2

Inside tell, command calls dispatch to the current model object if no script handler matches.

Error Handling

try
    error {message: "bad request", code: "APP_400"}
on error err
    return err.code
end try

Supported forms: - error - error "message" - error {message: "...", code: "..."}

on error err binding includes: - err.message - err.code - err.line, err.column - err.stack.calls - err.stack.tell

Tell Blocks and Object Addressing

tell application "mail"
    set firstSubject to subject of first message of inbox
    set unread to every message of inbox whose read status is false

    repeat with m in unread
        tell m
            set read status to true
        end tell
    end repeat
end tell

Addressing features: - every <kind> whose <predicate> - every <kind> of <expr> whose <predicate> - first/last <kind> - <kind> 2 - <kind> 1 thru 3 - of chains (subject of first message of inbox) - possessive chains (event's sender's name, its subject, my cached_value)

Operators

  • arithmetic: +, -, *, /, div, mod
  • logical: and, or, not
  • comparison: =, ==, !=, <>, <, >, <=, >=, is, is not
  • containment: contains, begins with, ends with, is in, is not in
  • concatenation: &

Implicit Runtime Values

  • result (read-only)
  • pronouns: it, its, my, me
  • event context:
  • direct keys (for example request_id)
  • aggregate event record

Example:

set senderName to event's sender's name
set requestIdText to request_id as text
return senderName & ":" & requestIdText

Advanced Event Handlers

Inside tell application, you can register host-dispatched handlers:

tell application "router"
    on get "/"
        return "ok"
    end get
end tell

For detailed host contract and dispatch examples, see Advanced Handlers.

Including Script Files

use script "lib/common"
return greet("Ada")

use script loads and inlines script files once per evaluation, including nested includes.