#moonfory

let bytes = @moonfory.dumps(42)          // 01 ff 04 2a 00 00 00
let back  : Int = @moonfory.loads(bytes)

#Install

moon add moonbitstack/moonfory

import {
  "moonbitstack/moonfory",
}

#Documentation

• The site — the guide, the annotated byte examples and the reference.
• API reference — one page per public item, generated from the interface and the doc comments below.

#Two entry points, four verbs

// One value, all of it.
let bytes : Bytes = @moonfory.dumps(value)
let value : T     = @moonfory.loads(bytes)

// The same, without allocating a fresh buffer.
@moonfory.dump(value, buffer)
let value : T = @moonfory.load(reader)

#Making a type travel

pub impl Codec for UserId with fn ty(_self) {
  TypeId::Int64
}

pub impl Codec for UserId with fn write_data(self, w) {
  w.write_i64(self.0)
}

pub impl Codec for UserId with fn read_data(r, _ty) {
  UserId(r.read_i64())
}

#The type table

#Numbers, in one place

#Configuration

// The preset, with one field changed.
@moonfory.dumps(v, track_ref=true)

// A whole config, then one field overridden on top of it.
@moonfory.dumps(v, config=my_config, depth=8)

// Refuse rather than pick when the two disagree.
@moonfory.dumps(v, config=my_config, xlang=false, clash=Panic)

#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 meta = @moonfory.StructMeta::of(
  model, user=101, children=[point], refs=["home"],
)

#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 value = @moonfory.Value::Struct(node, [
  ("val", @moonfory.Value::Int(1L)),
  ("next", @moonfory.Value::Pointer(0)),
])

@moonfory.dumps(value, track_ref=true)   // 01 00 1b ac02 eecb234f 02 fe 00

let once = @moonfory.shared(7, "the same string")
let twice = [once, once]                    // two references, one body
let bytes = @moonfory.dumps(twice, track_ref=true)

#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 bytes = row.finish()
let cur = @moonfory.RowCursor::new(bytes[:], schema)
cur.get_field(1)                 // RowValue::String("ada"), field 0 never read
cur.is_null(2)                   // true

#Time

let date   = @moonfory.date_of_days(19_000L)                 // a Date, as DATE
let moment = @moonfory.moment_of_parts(1_700_000_000L, 0)    // a Moment, as TIMESTAMP
let span   = @moonfory.span_of_parts(3L, 500_000_000)        // a Span, as DURATION
@moonfory.dumps(moment)                                      // and back through loads

#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