diff --git a/docs/src/data/structs.md b/docs/src/data/structs.md index 41c8c1e..ed239dc 100644 --- a/docs/src/data/structs.md +++ b/docs/src/data/structs.md @@ -163,13 +163,14 @@ print(cfg); // Config {host: "example.com", port: 8080} print(cfg.port); // 8080 ``` -Every key must be a field, and every field without a default must be -given, by the map or by the literal. The check runs when the literal -is built: +Keys that name no field are skipped, so a struct takes only what it +needs from a larger document. Every field without a default must be +given, by the map or by the literal; the check runs when the literal is +built: ```rune struct Config { host, port = 8080 } -Config { ...["host": "example.com", "timeout": 5] }; // KeyError: Config has no field 'timeout'. +print(Config { ...["host": "example.com", "timeout": 5] }); // Config {host: "example.com", port: 8080} ``` ```rune diff --git a/docs/src/programs/examples.md b/docs/src/programs/examples.md index 6cd07b2..c1910bb 100644 --- a/docs/src/programs/examples.md +++ b/docs/src/programs/examples.md @@ -143,12 +143,18 @@ rune run examples/shop.rn "apple watch" SHOP_USER=michaelw SHOP_PASS=michaelwpass rune run examples/shop.rn ``` -### [`fetch.rn`](https://github.com/kryptamine/rune/blob/master/examples/fetch.rn) — HTTP and JSON +### [`fetch.rn`](https://github.com/kryptamine/rune/blob/master/examples/fetch.rn) — HTTP and JSON into structs -Fetches a URL, parses the JSON and handles network errors with `try`. +Fetches users from [DummyJSON](https://dummyjson.com) and turns the JSON +into nested structs: each `from` spreads a map into its struct, which +keeps the fields it has and skips the rest. Groups the users by department +in a map, then writes: POST a struct, PUT one built from another with +`map(s)` and spread, PATCH a map of the changes, DELETE into a struct. +Errors come back as a typed `ApiError`. ```sh -rune run examples/fetch.rn +rune run examples/fetch.rn # first 10 users +rune run examples/fetch.rn 30 ``` ## Basics diff --git a/docs/src/stdlib/json-http.md b/docs/src/stdlib/json-http.md index eb899e5..90c73ad 100644 --- a/docs/src/stdlib/json-http.md +++ b/docs/src/stdlib/json-http.md @@ -34,8 +34,8 @@ print(json.parse("42")); // 42 ``` For typed access, spread the map into a [struct](../data/structs.md) -literal. That checks its shape: every field without a default must be -there, and no other key may be. +literal. Every field without a default must be there; other keys are +skipped. ```rune struct Order { id, total, items = [] } diff --git a/examples/fetch.rn b/examples/fetch.rn index cc39742..744b73d 100644 --- a/examples/fetch.rn +++ b/examples/fetch.rn @@ -1,8 +1,144 @@ -// Fetching data from URL +// HTTP and JSON with structs: reads DummyJSON users into structs, groups +// them by department, then sends structs back with POST, PUT, PATCH and +// DELETE. DummyJSON answers writes as if they happened but keeps nothing. +// +// ./rune run examples/fetch.rn first 10 users +// ./rune run examples/fetch.rn 30 first 30 -try { - let res = json.parse(http.request("GET", "https://dummyjson.com/todos").body); - print(res); -} catch err { - print("Failed to fetch todos: " + err.message); +const BASE = "https://dummyjson.com"; + +struct ApiError { status, message } + +impl ApiError { + fun from(status, data) { ApiError { status, message: data?.["message"] ?? "HTTP {status}" } } +} + +struct Point { lat, lng } +struct Address { city, country, coordinates } +struct Company { name, title, department } +struct User { id, firstName, lastName, email, age, address, company, phone = nil } +struct Page { users, total, skip, limit } + +// What a client sends to create or replace a user, and what a delete returns. +struct NewUser { firstName, lastName, email, age } +struct Deleted { id, isDeleted, deletedOn } + +// A struct takes the keys it has fields for and skips the rest; nested +// objects come in as maps, so each one is spread into its own struct. +impl Address { + fun from(m) { Address { ...m, coordinates: Point { ...m["coordinates"] } } } +} + +impl User { + fun from(m) { + User { ...m, address: Address.from(m["address"]), company: Company { ...m["company"] } } + } + + fun name(self) { "{self.firstName} {self.lastName}" } +} + +impl Page { + fun from(m) { Page { ...m, users: m["users"].map(User.from) } } +} + +// api sends body, any struct or map, as JSON and gives the parsed reply. +fun api(method, path, body = nil) { + let mut headers = ["Accept": "application/json"]; + + if body != nil { + headers["Content-Type"] = "application/json"; + } + + let r = http.request(method, BASE + path, HttpOptions { + headers, + body: if body == nil { nil } else { json.stringify(body) }, + timeout: 10, + }); + + let data = json.parse(r.body); + + if r.status >= 400 { + throw ApiError.from(r.status, data); + } + + return data; +} + +fun section(title) { + print(""); + print("── {title} " + "─".repeat(math.max(0, 50 - title.len()))); +} + +fun main([limit = "10"]) { + let page = try { + Page.from(api("GET", "/users?limit={limit}")) + } catch e is IOError { + io.eprint("network: {e.message}"); + return 1; + }; + + section("users {page.skip + 1}-{page.skip + page.users.len()} of {page.total}"); + + for u in page.users { + let { city, country } = u.address; + print("#{"%-3d".format(u.id)} {u.name().padEnd(22)} {"%2d".format(u.age)} {city}, {country}"); + } + + section("by department"); + let mut teams = [:]; + + for u in page.users { + let dept = u.company.department; + + if !(dept in teams) { + teams[dept] = []; + } + + teams[dept].push(u); + } + + let mut depts = teams.keys(); + depts.sort(); + + for dept in depts { + let people = teams[dept]; + let ages = people.map(u => u.age); + let avg = ages.reduce((a, b) => a + b, 0) / ages.len(); + let n = if people.len() == 1 { "1 person" } else { "{people.len()} people" }; + print("{dept.padEnd(26)} {n.padEnd(10)} average age {"%.1f".format(avg)}"); + } + + section("one user"); + let first = User.from(api("GET", "/users/{page.users[0].id}")); + let { lat, lng } = first.address.coordinates; + print("{first.name()} <{first.email}>, {first.phone ?? "no phone"}"); + print("{first.company.title} at {first.company.name}"); + print("lives at {"%.3f".format(lat)}, {"%.3f".format(lng)}"); + print(json.stringify(first.company)); + + section("create: POST a struct"); + let ann = NewUser { firstName: "Ann", lastName: "Lee", email: "ann@example.com", age: 30 }; + let created = User.from(api("POST", "/users/add", ann)); + print("created #{created.id} {created.name()} <{created.email}>"); + + section("replace: PUT a struct built from another"); + let whole = NewUser { ...map(first), lastName: "Owen" }; + print("sent " + json.stringify(whole)); + let replaced = User.from(api("PUT", "/users/{first.id}", whole)); + print("now {replaced.name()}, {replaced.age}"); + + section("update: PATCH a map of the changes"); + let patched = User.from(api("PATCH", "/users/{first.id}", ["age": first.age + 1])); + print("{patched.name()} is {patched.age} now, was {first.age}"); + + section("delete"); + let gone = Deleted { ...api("DELETE", "/users/{first.id}") }; + print("#{gone.id} deleted: {gone.isDeleted}, at {gone.deletedOn}"); + + section("errors"); + try { + api("PUT", "/users/9999", ann); + } catch e is ApiError { + print("{e.status}: {e.message}"); + } } diff --git a/examples/shop.rn b/examples/shop.rn index e0eb03b..a521632 100644 --- a/examples/shop.rn +++ b/examples/shop.rn @@ -8,6 +8,10 @@ const BASE = "https://dummyjson.com"; struct ApiError { message, status, path } +impl ApiError { + fun from(status, data, path) { ApiError { message: data?.["message"] ?? "HTTP {status}", status, path } } +} + struct Client { base = BASE, token = nil, refreshToken = nil, refreshes = 0 } impl Client { @@ -68,7 +72,7 @@ impl Client { let data = if r.body == "" { nil } else { json.parse(r.body) }; if r.status >= 400 { - throw ApiError { message: data?.["message"] ?? "HTTP {r.status}", status: r.status, path }; + throw ApiError.from(r.status, data, path); } return data; diff --git a/pkg/rune/vm_slow.go b/pkg/rune/vm_slow.go index e0f6e1b..feef240 100644 --- a/pkg/rune/vm_slow.go +++ b/pkg/rune/vm_slow.go @@ -482,12 +482,12 @@ func spreadArgs(src value.Value) ([]value.Value, bool) { return spreadItems(nil, src) } -// spreadFields copies src, a struct of type shape, into the field +// spreadFields copies src, a struct of type shape or a map, into the field // registers fields. func spreadFields(tok *ast.Token, shape *value.Shape, fields []value.Value, src value.Value) error { switch { case src.Kind() == value.Map: - return stdlib.AssignFields(tok, shape, fields, src.HashMap()) + shape.Assign(fields, src.HashMap()) case src.Kind() == value.Struct && src.Shape() == shape: value.ShareAll(src.Fields()) copy(fields, src.Fields()) diff --git a/pkg/stdlib/convert.go b/pkg/stdlib/convert.go index 2f5ef12..aacaf15 100644 --- a/pkg/stdlib/convert.go +++ b/pkg/stdlib/convert.go @@ -88,22 +88,6 @@ func NotOrdinal(enum *value.Shape) string { return enum.Name + " has variants with fields; values(), " + enum.Name + "(n) and int() are for enums without." } -// AssignFields sets the fields of shape that the keys of m name; any -// other key is a KeyError. -func AssignFields(token *ast.Token, shape *value.Shape, fields []value.Value, m *value.HashMap) error { - extra, ok := shape.Assign(fields, m) - - switch { - case ok: - return nil - case extra.IsString(): - return errors.NewRuntimeError(errors.KeyError, *token, errors.NoField(shape.Name, extra.Str())) - } - - return errors.NewRuntimeError(errors.TypeError, *token, fmt.Sprintf( - "%s has no field %s; a field is named by a string.", shape.Name, helpers.Quoted(extra))) -} - // toString is string(v): v as print shows it. var toString = &Native{"string", 1, 1, func(c *call) value.Value { if v := c.args[0]; v.IsString() { diff --git a/pkg/value/value.go b/pkg/value/value.go index e367d69..b3832d9 100644 --- a/pkg/value/value.go +++ b/pkg/value/value.go @@ -373,28 +373,18 @@ func (s *Shape) Index(name string) int { return -1 } -// Assign copies into fields the values of m whose keys name fields; -// extra is the first key naming none. -func (s *Shape) Assign(fields []Value, m *HashMap) (extra Value, ok bool) { - ok = true - +// Assign copies into fields the values of m whose keys name fields; it +// skips any other key. +func (s *Shape) Assign(fields []Value, m *HashMap) { m.Each(func(k, v Value) bool { - slot := -1 if k.IsString() { - slot = s.Index(k.Str()) - } - - if slot < 0 { - extra, ok = k, false - return false + if slot := s.Index(k.Str()); slot >= 0 { + fields[slot] = Share(v) + } } - fields[slot] = Share(v) - return true }) - - return extra, ok } // Fill gives each undefined field its default; missing is diff --git a/test/struct/convert_extra_key.rn b/test/struct/convert_extra_key.rn index 2277ad6..50db600 100644 --- a/test/struct/convert_extra_key.rn +++ b/test/struct/convert_extra_key.rn @@ -1,3 +1,3 @@ struct Point { x, y = 0 } -print(Point { ...["x": 1, "z": 2, "w": 3] }); // expect runtime error: [line: 3] KeyError: Point has no field 'z'. +print(Point { ...["x": 1, "z": 2, 3: 4] }); // expect: Point {x: 1, y: 0} diff --git a/test/struct/convert_extra_key.stderr b/test/struct/convert_extra_key.stderr deleted file mode 100644 index a50affc..0000000 --- a/test/struct/convert_extra_key.stderr +++ /dev/null @@ -1,5 +0,0 @@ -KeyError: Point has no field 'z'. - --> convert_extra_key.rn:3:15 - | -3 | print(Point { ...["x": 1, "z": 2, "w": 3] }); // expect runtime error: [line: 3] KeyError: Point has no field 'z'. - | ^^^ diff --git a/test/struct/spread.rn b/test/struct/spread.rn index 516adcd..2206ba2 100644 --- a/test/struct/spread.rn +++ b/test/struct/spread.rn @@ -27,6 +27,6 @@ Point { x: log("x", 1), ...log("spread", p), y: log("y", 2) }; print(order); // expect: ["x", "spread", "y"] print(Task { ...["id": 1, "text": "a"] }.text); // expect: a -try { Task { ...["id": 1, "nope": 2] }; } catch e is KeyError { print(e.message); } // expect: Task has no field 'nope'. +print(Task { ...["id": 1, "text": "a", "nope": 2] }.id); // expect: 1 try { Task { ...p }; } catch e is TypeError { print(e.message); } // expect: Cannot spread Point into Task. Task { ...[1] }; // expect runtime error: [line: 32] TypeError: Cannot spread array into Task.