Documentation
¶
Index ¶
- func ExtractGoType(def *ir.Node, s *schema.Schema, registry *schema.SchemaRegistry) (reflect.Type, error)
- func FromTony(data []byte, v interface{}, opts ...UnmapOption) error
- func FromTonyIR(node *ir.Node, v interface{}, opts ...UnmapOption) error
- func GetDefaultRegistries() (*schema.SchemaRegistry, *schema.ContextRegistry)
- func IsNullable(def *ir.Node, s *schema.Schema, registry *schema.SchemaRegistry) bool
- func ParseStructTag(tag string) (map[string]string, error)
- func SetDefaultRegistries(schemaReg *schema.SchemaRegistry, ctxReg *schema.ContextRegistry)
- func ToEncodeOptions(opts ...MapOption) []encode.EncodeOption
- func ToParseOptions(opts ...UnmapOption) []parse.ParseOption
- func ToTony(v interface{}, opts ...MapOption) ([]byte, error)
- func ToTonyIR(v interface{}, opts ...MapOption) (*ir.Node, error)
- type FieldInfo
- type MapOption
- type Mapper
- type MarshalError
- type SchemaError
- type StructSchema
- type TypeError
- type UnmapOption
- type UnmarshalError
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func ExtractGoType ¶
func ExtractGoType(def *ir.Node, s *schema.Schema, registry *schema.SchemaRegistry) (reflect.Type, error)
ExtractGoType extracts Go type information from a schema definition node. It resolves .[name] references, handles !or [null, T] patterns for nullable types, parameterized types like .array(string), and constructs a reflect.Type that represents the Go type.
Examples:
- "string" → reflect.TypeOf("")
- ".[int]" → resolves to int definition, returns reflect.TypeOf(0)
- "!or [null, string]" → returns reflect.PtrTo(reflect.TypeOf(""))
- ".array(string)" → returns reflect.SliceOf(reflect.TypeOf("")) ([]string)
- ".array(.array(string))" → returns [][]string
- ".sparsearray(string)" → returns map[uint32]string
The function recursively resolves references and builds up complex types, including nested parameterized types.
func FromTony ¶ added in v0.0.6
func FromTony(data []byte, v interface{}, opts ...UnmapOption) error
FromTony unmarshals Tony-formatted bytes to a Go value. It first unmarshals the bytes to an IR node (using parseOpts from opts), then converts the IR node to the value (using FromTonyIR with opts).
func FromTonyIR ¶ added in v0.0.6
func FromTonyIR(node *ir.Node, v interface{}, opts ...UnmapOption) error
FromTonyIR converts a Tony IR node to a Go value. v must be a pointer to the target type. It automatically uses a FromTonyIR() method if available (user-implemented or generated), otherwise falls back to reflection-based conversion.
func GetDefaultRegistries ¶
func GetDefaultRegistries() (*schema.SchemaRegistry, *schema.ContextRegistry)
GetDefaultRegistries returns the current default registries.
func IsNullable ¶
IsNullable checks if a definition allows null (via !or with null). It returns true if the definition is a !or pattern that includes null as one of its options.
Examples:
- !or [null, string] → true
- !or [string] → false
- string → false
- .[nullable-string] → recursively checks the referenced definition
The function checks for null in three forms:
- ir.NullType node type
- Tag == "null"
- StringType with String == "null"
func ParseStructTag ¶
ParseStructTag parses a struct tag string and returns a map of key-value pairs. Handles comma-separated values: `tony:"key1=value1,key2=value2,flag"` Supports quoted values with spaces: `tony:"key='value with spaces'"`
func SetDefaultRegistries ¶
func SetDefaultRegistries(schemaReg *schema.SchemaRegistry, ctxReg *schema.ContextRegistry)
SetDefaultRegistries sets the default registries used when nil is passed to NewMapper. This allows global configuration of schema registries.
func ToEncodeOptions ¶ added in v0.0.7
func ToEncodeOptions(opts ...MapOption) []encode.EncodeOption
ToEncodeOptions extracts EncodeOptions from a slice of MapOptions.
func ToParseOptions ¶ added in v0.0.7
func ToParseOptions(opts ...UnmapOption) []parse.ParseOption
ToParseOptions extracts ParseOptions from a slice of UnmapOptions.
Types ¶
type FieldInfo ¶
type FieldInfo struct {
// Name is the struct field name
Name string
// SchemaFieldName is the field name in the schema (may differ from struct field name)
SchemaFieldName string
// Type is the Go type of the field
Type reflect.Type
// Optional indicates if the field is optional (nullable or can be empty)
Optional bool
// Omit indicates if the field should be omitted from marshaling/unmarshaling
Omit bool
// Required indicates if the field is required (overrides type-based inference)
Required bool
// CommentFieldName is the name of a struct field (type []string) to populate with comment data
CommentFieldName string
// LineCommentFieldName is the name of a struct field (type []string) to populate with line comment data
LineCommentFieldName string
// ImplementsTextMarshaler indicates if the field type implements encoding.TextMarshaler
ImplementsTextMarshaler bool
// ImplementsTextUnmarshaler indicates if the field type implements encoding.TextUnmarshaler
ImplementsTextUnmarshaler bool
}
FieldInfo holds field metadata extracted from struct tags
func GetStructFields ¶
func GetStructFields(typ reflect.Type, s *schema.Schema, mode string, allowExtra bool, registry *schema.SchemaRegistry) ([]*FieldInfo, error)
GetStructFields extracts field information from a struct type. The behavior depends on the mode:
- "schema" mode: Schema is source of truth, match struct fields to schema fields
- "schemagen" mode: Struct is source of truth, extract field info from struct
registry can be nil for single-schema cases, but is required for cross-schema references.
type MapOption ¶ added in v0.0.7
type MapOption interface {
// contains filtered or unexported methods
}
MapOption is an option for controlling the mapping process from Go to Tony IR.
type Mapper ¶
type Mapper struct {
// contains filtered or unexported fields
}
Mapper provides schema-aware marshaling and unmarshaling. It holds optional schema and context registries for resolving schema references. If registries are nil, the default registries are used (set via SetDefaultRegistries).
func DefaultMapper ¶
func DefaultMapper() *Mapper
DefaultMapper returns a Mapper using the default registries. This is a convenience function equivalent to NewMapper(nil, nil).
func NewMapper ¶
func NewMapper(schemaReg *schema.SchemaRegistry, ctxReg *schema.ContextRegistry) *Mapper
NewMapper creates a new Mapper with the given registries. If either registry is nil, the corresponding default registry is used. If no default registries are set, schema resolution will be disabled for that registry.
func (*Mapper) ContextRegistry ¶
func (m *Mapper) ContextRegistry() *schema.ContextRegistry
ContextRegistry returns the context registry being used by this mapper.
func (*Mapper) FromTonyIR ¶ added in v0.0.6
func (m *Mapper) FromTonyIR(node *ir.Node, v interface{}, opts ...UnmapOption) error
FromTonyIR converts a Tony IR node to a Go value using schema-aware unmarshaling. v must be a pointer to the target type. It automatically uses a FromTony() method if available (user-implemented or generated), otherwise falls back to schema-aware or reflection-based conversion.
func (*Mapper) SchemaRegistry ¶
func (m *Mapper) SchemaRegistry() *schema.SchemaRegistry
SchemaRegistry returns the schema registry being used by this mapper.
type MarshalError ¶
type MarshalError struct {
FieldPath string // Field path (e.g., "person.address.street")
Message string
Err error
}
MarshalError represents an error during marshaling
func (*MarshalError) Error ¶
func (e *MarshalError) Error() string
func (*MarshalError) Unwrap ¶
func (e *MarshalError) Unwrap() error
type SchemaError ¶
SchemaError represents an error during schema resolution
func (*SchemaError) Error ¶
func (e *SchemaError) Error() string
func (*SchemaError) Unwrap ¶
func (e *SchemaError) Unwrap() error
type StructSchema ¶
type StructSchema struct {
// Mode is either "schema" (usage mode) or "schemagen" (definition mode)
Mode string
// SchemaName is the schema name/URI from the tag
SchemaName string
// Context is the schema context URI (e.g., "tony-format/context")
// If empty, defaults to "tony-format/context"
Context string
// AllowExtra allows struct to have extra fields not in schema (default: false, strict)
AllowExtra bool
// CommentFieldName is the name of a struct field (type []string) to populate with comment data
CommentFieldName string
// LineCommentFieldName is the name of a struct field (type []string) to populate with line comment data
LineCommentFieldName string
// TagFieldName is the name of a struct field (type string) to populate with the IR node's tag
TagFieldName string
}
StructSchema holds schema reference and mode information extracted from struct tags
func GetStructSchema ¶
func GetStructSchema(typ reflect.Type) (*StructSchema, error)
GetStructSchema extracts schema information from a struct type. It looks for an anonymous field with a `tony:"schema=..."` or `tony:"schemagen=..."` tag.
Schema tags are only checked on direct anonymous fields of the struct, not recursively into embedded structs. If a struct embeds another struct that has a schema tag, only the outer struct's schema tag is used.
Example:
type A struct {
schemaTag `tony:"schema=person"`
Name string
}
type B struct {
schemaTag `tony:"schema=company"` // This tag is used for B
A // A's schema tag is ignored
CompanyName string
}
type UnmapOption ¶ added in v0.0.7
type UnmapOption interface {
// contains filtered or unexported methods
}
UnmapOption is an option for controlling the unmapping process from Tony IR to Go.
type UnmarshalError ¶
type UnmarshalError struct {
FieldPath string // Field path (e.g., "person.address.street")
Message string
Err error
}
UnmarshalError represents an error during unmarshaling
func (*UnmarshalError) Error ¶
func (e *UnmarshalError) Error() string
func (*UnmarshalError) Unwrap ¶
func (e *UnmarshalError) Unwrap() error
Source Files
Directories