Requirements & Expression Engine
Extension AuthoringRequirements & Expression Engine

Requirements & Expression Engine

Visibility requirements, regex matching, and the ValidateExpression DSL engine.

Agent Prompt

Copy instruction prompt for Cursor, Claude, Antigravity, or ChatGPT.

Requirements Object

Control exactly when and where your actions appear in the popup HUD:

openclip.json
"requirements": {
  // Disables action if selection is empty (default: true)
  "requiresSelection": true,

  // Frontmost app filter
  "apps": ["com.apple.Safari", "com.google.Chrome"],
  "appsMode": "allow",      // "allow" (default) or "deny"

  // Regex pattern matching
  "regex": "^[0-9]+$",
  "regexNegated": false,

  // Short-circuit to Preferences if required options are empty
  "requiredOptions": ["apiKey"],

  // Computed DSL boolean expression
  "expression": "length(text) > 10 && !isURL(text)"
}

4-Step Visibility Pipeline

Step 1: Selection Presence

If requiresSelection: true and trimmed text is empty → Disabled.

Step 2: App Bundle Filtering

Matches frontmost application bundle ID against apps using allow/deny policy.

Step 3: Regular Expression Gate

Evaluates regex (dot-matches-all, case-insensitive). Captures are passed to context.

Step 4: Expression AST Evaluation

Parses and computes boolean result from expression DSL string.

ValidateExpression DSL Engine

OpenClip includes a bounded recursive-descent expression evaluator (ValidateExpression.swift) compiled at load time with zero runtime scripting overhead.

VariableTypeDescription
textStringFull selected text string.
matchedStringSubstring matched by Step 3 regex (or full text).
appStringSource application bundle ID (e.g. "com.apple.Safari").
appNameStringSource application localized display name (e.g. "Safari").
hasSelectionBoolTrue if selection contains non-whitespace characters.
capturesArrayArray of regex capture group strings.

Built-in DSL Functions

FunctionSignatureDescription
length(val)String | Array -> NumberCharacter length or array count.
isEmail(str)String -> BoolTests standard email regex pattern.
isURL(str)String -> BoolTests URL format (http/https/ftp/file/www).
contains(a, b)String, String -> BoolSubstring or array containment check.
startsWith(a, b)String, String -> BoolPrefix check (hasPrefix).
endsWith(a, b)String, String -> BoolSuffix check (hasSuffix).
trim(str)String -> StringTrims whitespace and newlines.
lower(str)String -> StringLowercases string.
upper(str)String -> StringUppercases string.
matches(str, regex)String, String -> BoolEvaluates regex against string.