Dynamic#

The Dynamic global is your escape hatch for working with schema-free data. When you need to deal with JSON-like values that don't fit neatly into a record definition -- API responses, user-provided payloads, configuration blobs -- this is where you go.

Creating Dynamic Values#

Convert typed values into dynamic:

dynamic d1 = Dynamic.dyn(true);      // true
dynamic d2 = Dynamic.dyn(42);        // 42
dynamic d3 = Dynamic.dyn(3.14);      // 3.14
dynamic d4 = Dynamic.dyn("hello");   // "hello"

Extension methods work too:

dynamic d = (42).dyn();              // 42
dynamic s = "hello".dyn();           // "hello"

Parsing#

maybe<dynamic> parsed = Dynamic.parse("{\"name\": \"Alice\", \"age\": 30}");

if (parsed as data) {
  // use data
}

Type Extraction#

Pull typed values out of dynamic data:

dynamic data = @dynamic 42;
maybe<int> val = Dynamic.i(data);         // 42
maybe<string> str = Dynamic.str(data);    // empty (not a string)

Field-Based Extraction#

When you have a dynamic object and want to pull out a specific field, there are overloads that take a field name -- and versions with defaults so you don't have to deal with maybe when you know what you want:

dynamic user = @dynamic {"name": "Alice", "age": 30, "active": true};

maybe<string> name = Dynamic.str(user, "name");     // "Alice"
string safe_name = Dynamic.str(user, "name", "?");   // "Alice"
maybe<int> age = Dynamic.i(user, "age");              // 30
int safe_age = Dynamic.i(user, "age", 0);             // 30
maybe<bool> active = Dynamic.b(user, "active");       // true

Type Checking#

Sometimes you need to know what kind of value you're dealing with:

dynamic arr = @dynamic [1, 2, 3];
dynamic obj = @dynamic {"x": 1};

bool is_arr = Dynamic.is_array(arr);   // true
bool is_obj = Dynamic.is_object(obj);  // true

Structure Inspection#

dynamic obj = @dynamic {"a": 1, "b": 2, "c": 3};

maybe<int> sz = Dynamic.size(obj);        // 3
bool has_a = Dynamic.has(obj, "a");       // true
bool has_z = Dynamic.has(obj, "z");       // false
list<string> ks = Dynamic.keys(obj);      // ["a", "b", "c"]

Access and Navigation#

dynamic arr = @dynamic [10, 20, 30];
dynamic second = Dynamic.atIndex(arr, 1);   // 20

dynamic obj = @dynamic {"x": 42};
dynamic x_val = Dynamic.atField(obj, "x");  // 42

Transformation#

dynamic base = @dynamic {"a": 1, "b": 2};
dynamic patch = @dynamic {"b": 3, "c": 4};
dynamic merged = Dynamic.merge(base, patch);  // {"a":1,"b":3,"c":4}

string json = Dynamic.to_str(merged);          // "{\"a\":1,\"b\":3,\"c\":4}"

Json Global#

The Json global works with the json type -- a structured variant of dynamic that supports field navigation directly.

maybe<json> j = Json.parse("{\"x\": 123}");

// Field navigation on json
json data = Json.parsen("[42]");
formula first = data[0];     // 42

Common Patterns#

Processing API Responses#

procedure handle_response(dynamic response) {
  string status = Dynamic.str(response, "status", "unknown");
  if (status == "success") {
    maybe<int> count = Dynamic.i(response, "count");
    if (count as c) {
      // process count
    }
  }
}

Building Dynamic Objects#

procedure build_payload() -> dynamic {
  return Dynamic.merge(
    @dynamic {"type": "event"},
    @dynamic {"timestamp": Time.now()}
  );
}

Method Summary#