#moonfory

let bytes : Bytes = @moonfory.dumps(42)
assert_eq(bytes, b"\x01\xff\x04\x2a\x00\x00\x00")
let back : Int = @moonfory.loads(bytes)
assert_eq(back, 42)

#Install

moon add moonbitstack/moonfory

import {
  "moonbitstack/moonfory",
}

#Documentation

• The site — the front page and the annotated byte examples.
• The guide — the whole interface on one page, install to errors.
• API reference — one page per public item, generated from the interface and the doc comments below.
• mooncakes — the published module and its versions.
• The skill — the same knowledge, written for the agent that is about to call it.

#Two entry points, four verbs

// One value, all of it.
let message : Bytes = @moonfory.dumps(42)
let value : Int = @moonfory.loads(message)
assert_eq(value, 42)

// The same, without allocating a fresh buffer.
let sink = Buffer()
@moonfory.dump(value, sink)
let source = @moonfory.Reader::new(sink.to_bytes())
source.read_head()
let replayed : Int = @moonfory.load(source)
assert_eq(replayed, 42)

#Making a type travel

struct UserId(Int64)

pub impl @moonfory.Codec for UserId with fn ty(_self) -> @moonfory.TypeId {
  @moonfory.TypeId::Int64
}

pub impl @moonfory.Codec for UserId with fn write_data(
  self,
  w : @moonfory.Writer,
) -> Unit raise {
  w.write_i64(self.0)
}

pub impl @moonfory.Codec for UserId with fn read_data(
  r : @moonfory.Reader,
  _ty : @moonfory.TypeId,
) -> UserId raise {
  UserId(r.read_i64())
}

let user = UserId(7L)
let id_bytes = @moonfory.dumps(user)
assert_eq(id_bytes, b"\x01\xff\x06\x07\x00\x00\x00\x00\x00\x00\x00")
let same : UserId = @moonfory.loads(id_bytes)
assert_eq(same.0, 7L)

#The type table

#Numbers, in one place

#Configuration

// The preset, with one field changed.
let tracked = @moonfory.dumps(@moonfory.Value::Int(1L), track_ref=true)

// A whole config, with one field overridden on top of it.
let base = @moonfory.Config::new(depth=9)
let deeper = @moonfory.dumps(@moonfory.Value::Int(1L), config=base, depth=8)

// Two settings that disagree: refused, rather than silently picked.
let refused = try {
  @moonfory.dumps(
    @moonfory.Value::Int(1L),
    config=base,
    xlang=false,
    clash=@moonfory.OnClash::Panic,
  )
} catch {
  @moonfory.Clashed(_) => b""
  failure => raise failure
}
assert_eq(refused.length(), 0)

#Describing a struct

let point = @moonfory.StructMeta::new("Point", 100, [
  @moonfory.FieldMeta::new("x", @moonfory.TypeId::VarInt32),
  @moonfory.FieldMeta::new("y", @moonfory.TypeId::VarInt32),
])

let person = @moonfory.StructMeta::new("Person", 101, [
  @moonfory.FieldMeta::new("name", @moonfory.TypeId::String),
  @moonfory.FieldMeta::new("age", @moonfory.TypeId::VarInt32),
  // A list says what it holds, because the writer may leave the element type
  // out of the header.
  @moonfory.FieldMeta::new(
    "tags", @moonfory.TypeId::List, element=Some(@moonfory.TypeId::String),
  ),
  // A field whose type is declared sends no type ID, so the schema has to say
  // which struct it is.
  @moonfory.FieldMeta::new(
    "home", @moonfory.TypeId::Struct, nullable=true, child=Some(point),
  ),
])

let ada = @moonfory.Value::Struct(person, [
  ("name", @moonfory.Value::Str("ada")),
  ("age", @moonfory.Value::Int(36L)),
  (
    "tags",
    @moonfory.Value::List(@moonfory.TypeId::List, [
      @moonfory.Value::Str("math"),
    ]),
  ),
  ("home", @moonfory.Value::Struct(point, [
    ("x", @moonfory.Value::Int(1L)),
    ("y", @moonfory.Value::Int(2L)),
  ])),
])
let ada_bytes = @moonfory.dumps(ada)
let read_back : @moonfory.Value = @moonfory.loads(
  ada_bytes, schemas=[person, point],
)
assert_eq(read_back, ada)
// And writing it again is the bytes it came from: the writer sorts, the reader
// sorts back.
assert_eq(@moonfory.dumps(read_back), ada_bytes)

let account = @moonmodel.Model::new("Account", [
  @moonmodel.Field::new("id", @moonmodel.Int),
  @moonmodel.Field::new("nick", @moonmodel.Text),
])

let account_meta = @moonfory.StructMeta::of(account, user=102, refs=["nick"])
assert_eq(account_meta.name(), "Account")
assert_eq(account_meta.user(), 102)
assert_eq(account_meta.find("id").unwrap().ty, @moonfory.TypeId::VarInt32)

#The schema fingerprint

#Shared and circular values

let node = @moonfory.StructMeta::new("Node", 300, [
  @moonfory.FieldMeta::new("val", @moonfory.TypeId::VarInt32),
  @moonfory.FieldMeta::new("next", @moonfory.TypeId::Struct, track_ref=true),
])

// A node whose `next` is itself. Reference zero is the root, which this is.
let cyclic = @moonfory.Value::Struct(node, [
  ("val", @moonfory.Value::Int(1L)),
  ("next", @moonfory.Value::Pointer(0)),
])

let cyclic_bytes = @moonfory.dumps(cyclic, track_ref=true)
assert_eq(
  cyclic_bytes, b"\x01\x00\x1b\xac\x02\xee\xcb\x23\x4f\x02\xfe\x00",
)

let once = @moonfory.shared(7, "the same string")
let twice = [once, once] // two references, one body
let shared_bytes = @moonfory.dumps(twice, track_ref=true)
let shared_back : Array[@moonfory.Shared[String]] = @moonfory.loads(
  shared_bytes, track_ref=true,
)
assert_eq(shared_back.length(), 2)
assert_eq(shared_back[1].value, "the same string")

#The row format

let schema = @moonfory.RowSchema::new([
  { name: "id", ty: @moonfory.RowType::Int64, nullable: false },
  { name: "name", ty: @moonfory.RowType::String, nullable: false },
  { name: "age", ty: @moonfory.RowType::Int32, nullable: true },
])

let row = @moonfory.Row::new(schema)
row.set(0, @moonfory.RowValue::Int64(7L))
row.set(1, @moonfory.RowValue::String("ada"))
row.set(2, @moonfory.RowValue::Null)

let row_bytes = row.finish()
let cur = @moonfory.RowCursor::new(row_bytes[:], schema)
assert_eq(cur.get_field(1), @moonfory.RowValue::String("ada"))
assert_eq(cur.is_null(2), true)

#Time

let date = @moonfory.date_of_days(19_000L)
let moment = @moonfory.moment_of_parts(1_700_000_000L, 0)
let span = @moonfory.span_of_parts(3L, 500_000_000)

assert_eq(
  @moonfory.days_of_date(@moonfory.loads(@moonfory.dumps(date))), 19_000L,
)
let (seconds, nanos) = @moonfory.parts_of_span(
  @moonfory.loads(@moonfory.dumps(span)),
)
assert_eq(seconds, 3L)
assert_eq(nanos, 500_000_000)
let (epoch, _) = @moonfory.parts_of_moment(
  @moonfory.loads(@moonfory.dumps(moment)),
)
assert_eq(epoch, 1_700_000_000L)

#What is deliberately not here

#Errors

#Interop, as a test

python3 scripts/interop.py     # writes src/fixtures_pyfory_test.mbt
(cd scripts && go run .)       # writes src/fixtures_go_test.mbt
moon fmt                       # the generated files are formatted by the toolchain

#The API reference is generated

python3 scripts/api.py     # after changing an interface or a doc comment

#Specifications

• Fory cross-language serialization
• Fory row format
• Fory type mapping

#Licence