Declare a struct #

A struct is a record with named, typed fields. Declare it at the top of the file.

struct User
  name: String
  age: Int
end

def main() -> Void
  user = User(name: "Ana", age: 25)
  puts(user.name)
  puts(user)
end
Output
Ana
User(name: "Ana", age: 25)

Build a struct with every field, each by name, in any order. A missing field is an error:

struct Point
  x: Int
  y: Int
end

def main() -> Void
  p = Point(x: 1)
end
Does not compile
error[CHECK-MISSING-FIELD]

Default values #

A field written name: Type = value has a default, and a constructor may leave it out. A field without a default must still be given.

struct Options
  name: String
  retries: Int = 3
  tags: List[String] = []
end

def main() -> Void
  puts(Options(name: "a"))
  puts(Options(name: "b", retries: 1))
end
Output
Options(name: "a", retries: 3, tags: [])
Options(name: "b", retries: 1, tags: [])

A default follows the rules of a parameter default: a literal, true, false, nil, none, [], {}, an enum variant without a payload or the name of a constant with such a value (retries: Int = RETRIES), but not a struct built with no arguments, which only a parameter takes. Anything else is CHECK-DEFAULT-VALUE, and a value of the wrong type is CHECK-TYPE-MISMATCH.

struct Options
  retries: Int = 1 + 2
end

def main() -> Void
  puts(Options())
end
Does not compile
error[CHECK-DEFAULT-VALUE]

with and JSON.decode do not use defaults: with copies a value, and a decode still needs every key.

Change a field #

Fields cannot be assigned. value.with(...) copies the struct with the named fields changed. The original stays as it was.

struct Account
  owner: String
  balance: Int
end

def deposit(account: Account, amount: Int) -> Account = account.with(balance: account.balance + amount)

def main() -> Void
  account = Account(owner: "Bob", balance: 10)
  richer = deposit(account, 5)
  puts(richer)
  puts(account)
end
Output
Account(owner: "Bob", balance: 15)
Account(owner: "Bob", balance: 10)

Every value is computed from the struct before the update, so fields can swap:

struct Pair
  left: Int
  right: Int
  label: String
end

def main() -> Void
  pair = Pair(left: 1, right: 2, label: "p")
  swapped = pair.with(left: pair.right, right: pair.left)
  puts(swapped)
  puts(pair.with(label: "q", left: 0))
end
Output
Pair(left: 2, right: 1, label: "p")
Pair(left: 0, right: 2, label: "q")

For a field inside a struct, update both levels. Updates chain:

struct Address
  city: String
  zip: Int
end

struct User
  name: String
  address: Address
end

def main() -> Void
  ana = User(name: "Ana", address: Address(city: "Cusco", zip: 8))
  moved = ana.with(address: ana.address.with(city: "Lima"))
  puts(moved)
  puts(moved.with(name: "Bea").with(address: Address(city: "Quito", zip: 1)))
end
Output
User(name: "Ana", address: Address(city: "Lima", zip: 8))
User(name: "Bea", address: Address(city: "Quito", zip: 1))

with needs at least one field. Each must be named (PARSE-UNEXPECTED-TOKEN otherwise), appear once, exist in the struct and have the right type (CHECK-TYPE-MISMATCH):

struct Point
  x: Int
  y: Int
end

def main() -> Void
  p = Point(x: 1, y: 2)
  q = p.with(z: 5)
end
Does not compile
error[CHECK-UNKNOWN-FIELD]

A bare p.with(x: 2) changes nothing, so it is CHECK-UNUSED-VALUE. Assign the result: p = p.with(x: 2).

struct Point
  x: Int
  y: Int
end

def main() -> Void
  p = Point(x: 1, y: 2)
  p.with(x: 2)
end
Does not compile
error[CHECK-UNUSED-VALUE]

with is not reserved: a struct can have a field named with, unless that field is a function (CHECK-REDEFINED-NAME).

Structs in structs and lists #

Fields can be lists, maps, other structs and enums.

struct Item
  name: String
  price: Int
end

struct Order
  id: Int
  items: List[Item]
end

def main() -> Void
  order = Order(id: 7, items: [Item(name: "tea", price: 3), Item(name: "cake", price: 5)])
  total = order.items.reduce(0) do |sum, item| sum + item.price end
  puts("order #{order.id}: #{total}")
end
Output
order 7: 8

List the fields #

Type.members is a List[StructMember] with one entry per field of a struct type, in declaration order. A StructMember has two String fields: name and type, the field type written as source. A tool such as a table mapper can build SQL from a struct with it.

type Id = Int

struct Address
  city: String
end

struct User
  id: Id
  name: String
  tags: List[String]
  home: Address
end

def main() -> Void
  User.members.each do |m| puts("#{m.name}: #{m.type}") end
end
Output
id: Int
name: String
tags: List[String]
home: Address

The type is the one the checker prints, so an alias is expanded (Id gives Int). members is on the type and not on a value: user.members reads a field of that name, and a struct may have one. An enum, a resource or an alias is not a struct, so Color.members is CHECK-UNKNOWN-METHOD and Id.members is CHECK-UNKNOWN-TYPE.

enum Color
  Red
end

def main() -> Void
  puts(Color.members.size)
end
Does not compile
error[CHECK-UNKNOWN-METHOD]

Type.codec is next to it: the codec of a struct or enum that JSON can read, a Codec[T] with the same members plus decode, encode and from. It is how generic code gets the fields and the JSON of a type it cannot name.

Type parameters #

A struct can take type parameters after its name, as an enum does. The type argument comes from the values you give:

struct Box[T]
  value: T
end

struct Pair[A, B]
  first: A
  second: B
end

def main() -> Void
  count = Box(value: 41)
  puts(count.value + 1)
  pair = Pair(first: "one", second: count)
  puts(pair.second.value)
  puts(pair)
  puts(count.with(value: 7))
end
Output
42
41
Pair(first: "one", second: Box(value: 41))
Box(value: 7)

count is a Box[Int], so count.value is an Int. A type names all its arguments: Box[Int], Pair[String, Box[Int]]. A bare Box or the wrong number of arguments is CHECK-UNKNOWN-TYPE.

struct Box[T]
  value: T
end

def total(box: Box[List[Int]]) -> Int = box.value.sum

def main() -> Void
  puts(total(Box(value: [1, 2, 3])))
  puts(total(Box(value: [])))
end
Output
6
0

An empty list or map cannot say what the argument is, so it needs a type from the place where the struct is used: a parameter, as above, a return type, a field or a variable with a type. Without one it is CHECK-ENUM-TYPE-INFERENCE.

struct Box[T]
  value: T
end

def main() -> Void
  box = Box(value: [])
end
Does not compile
error[CHECK-ENUM-TYPE-INFERENCE]

Values that disagree are CHECK-TYPE-MISMATCH. A parameter cannot be a Map key (CHECK-MAP-KEY-TYPE), and a field named with cannot have a parameter as its type (CHECK-REDEFINED-NAME), since the argument could be a function. JSON.encode writes a generic instance, but JSON.decode and JSON.schema refuse one (CHECK-NOT-DECODABLE). An imported struct is written Models.Box[Int].

No methods #

Structs have fields only. A field named to_s shadows the text form, so write functions that take the struct:

struct Rect
  width: Int
  height: Int
end

def area(r: Rect) -> Int = r.width * r.height

def main() -> Void
  puts(area(Rect(width: 3, height: 4)))
end
Output
12

Equality #

Two structs of the same type are equal when all their fields are equal, compared in depth. Lists, maps, sets, Results and enums compare the same way:

struct User
  name: String
  tags: List[String]
end

def main() -> Void
  a = User(name: "Ana", tags: ["admin"])
  b = User(name: "Ana", tags: ["admin"])
  puts(a == b)
  puts(a.with(tags: []) != b)
  puts([a, b] == [b, a])
end
Output
true
true
true

A struct with a function field (Fn), a task, a channel, a handle or a JSON.Value inside has no equality: == on it is CHECK-TYPE-MISMATCH, and the message names the field. A Float field follows IEEE 754, so a struct that holds a NaN is not equal to itself.

Private fields #

A private line in a struct body, alone with a blank line before and after, makes the fields after it private to the module that declares the struct: its file, or the module block it is in. That module reads, sets and gives them as usual. Elsewhere the value can be passed, stored, sent, compared and printed, but its private fields cannot be read, given or set with with, and the struct is built only by the module’s functions:

module Bank
  struct Account
    owner: String

    private

    cents: Int
  end

  def open(owner: String) -> Account = Account(owner: owner, cents: 0)

  def deposit(account: Account, cents: Int) -> Account = account.with(cents: account.cents + cents)

  def balance(account: Account) -> Int = account.cents
end

def main() -> Void
  account = Bank.deposit(Bank.open("Ana"), 150)
  puts("#{account.owner} #{Bank.balance(account)}")
  puts(account)
end
Output
Ana 150
Account(owner: "Ana", cents: 150)

== compares every field, and inspect, to_s and interpolation show every field. Outside the module, account.cents, Account(owner: "Bo"), account.with(cents: 0), Account.codec and JSON.encode(account) are CHECK-PRIVATE-FIELD:

module Bank
  struct Account
    owner: String

    private

    cents: Int
  end

  def open(owner: String) -> Account = Account(owner: owner, cents: 0)
end

def main() -> Void
  puts(Bank.open("Ana").cents)
end
Does not compile
error[CHECK-PRIVATE-FIELD]

agentica doc lists the public fields and says that the struct has private fields.