Repository navigation
Errors
rustyon returns typed errors, in the style of encoding/json. Use errors.As to inspect them. All error messages start with rustyon: .
| Error | Returned by | When |
|---|---|---|
*SyntaxError |
Parse, ParseDocument, Unmarshal, Decoder.Decode, Format, FormatIndent, ParseEditable, ronjson.ToJSON
|
the input is not valid RON |
*UnmarshalTypeError |
Unmarshal, Decoder.Decode, FromValue
|
a RON value does not fit the Go type |
*UnknownFieldError |
Decoder.Decode with DisallowUnknownFields
|
the input has a field the Go struct lacks |
*InvalidUnmarshalError |
Unmarshal, Decoder.Decode, FromValue
|
the target is not a non-nil pointer |
*UnsupportedTypeError |
Marshal, MarshalIndent, Encoder.Encode, ToValue
|
the Go type has no RON form |
*UnsupportedValueError |
Marshal, MarshalIndent, Encoder.Encode, ToValue
|
the Go value cannot be encoded |
*MarshalerError |
Marshal, MarshalIndent, Encoder.Encode, ToValue
|
a MarshalRON or MarshalText method failed |
Errors from an io.Reader or io.Writer, and errors returned by your own UnmarshalRON or UnmarshalText methods, are passed through unchanged. Decoder.Decode returns io.EOF when there are no more values.
type SyntaxError struct {
Msg string
Pos Position
}
type Position struct {
Offset int // 0-based byte offset
Line int // 1-based
Column int // 1-based, counts Unicode code points
}Position.String() returns line:column.
_, err := rustyon.Parse([]byte("[1,\n ?]"))
fmt.Println(err)
// rustyon: syntax error at 2:3: unexpected character '?'
var se *rustyon.SyntaxError
if errors.As(err, &se) {
fmt.Println(se.Pos.Line, se.Pos.Column, se.Pos.Offset, se.Pos, se.Msg)
// 2 3 6 2:3 unexpected character '?'
}The message text matches the wording of the ron-rs errors where possible, for example unexpected trailing characters, integer out of bounds or unknown escape character. Positions are those of the character where the parser gave up, which is often just after the offending token.
The rustyon CLI prints these errors as file:line:col: message followed by the source line and a caret under the column. You can build the same output from Pos.
More examples are listed on RON Syntax.
Unmarshal and Decoder report syntax errors with the same message and position as Parse, even though they decode without building a tree. When an error is returned, the decode target may already be partially filled in.
A map key that is not comparable in Go (for example a list used as a key of a map[any]int) is reported as this error too:
var m map[any]int
fmt.Println(rustyon.Unmarshal([]byte("{[1]: 2}"), &m))
// rustyon: cannot unmarshal list into Go value of type map[interface {}]int: map key is not comparable in Gotype UnmarshalTypeError struct {
Value string // description of the RON value, e.g. "string" or "tuple Triangle"
Type reflect.Type // Go type that could not hold the value
Path string // path to the value within the document, e.g. "servers[0].port"
Msg string // optional detail
}Value describes the RON value: a kind such as integer, string, list, struct, None or Some, or a named form such as identifier Insane, tuple Triangle or struct Point.
type Config struct {
Servers []Server
}
type Server struct {
Host string
Port uint16
}
src := `(servers: [(host: "a", port: 80), (host: "b", port: 70000)])`
var c Config
err := rustyon.Unmarshal([]byte(src), &c)
fmt.Println(err)
// rustyon: cannot unmarshal integer into Go value of type uint16 at servers[1].port: integer 70000 overflows
var te *rustyon.UnmarshalTypeError
if errors.As(err, &te) {
fmt.Printf("value=%q type=%s path=%q msg=%q\n", te.Value, te.Type, te.Path, te.Msg)
// value="integer" type=uint16 path="servers[1].port" msg="integer 70000 overflows"
}The path is built from the RON names of the fields that lead to the value:
| Element | Written as | Example |
|---|---|---|
| struct field |
name, joined with .
|
servers[1].port |
| list, tuple or array index | [i] |
servers[1] |
| map entry |
[key], the key in RON syntax (shortened after 40 characters) |
["eu"][0].host |
| map key itself | {key} |
{key} |
| enum variant payload | (Name) |
shapes[0].(Circle).radius |
The path is empty for an error at the top level.
var m map[string][]Server
fmt.Println(rustyon.Unmarshal([]byte(`{"eu": [(host: 1)]}`), &m))
// rustyon: cannot unmarshal integer into Go value of type string at ["eu"][0].host
var arr [2]int
fmt.Println(rustyon.Unmarshal([]byte(`[1, 2, 3]`), &arr))
// rustyon: cannot unmarshal list into Go value of type [2]int: expected 2 elements, found 3Typical Msg values: integer N overflows, float overflows, expected N elements, found M, unknown variant "X", expected an enum variant, expected a unit variant, expected a string, map keys must be strings to decode into a struct, interface type is not a registered enum, unsupported Go type.
type UnknownFieldError struct {
Field string
Type reflect.Type
Path string
}Only a Decoder with DisallowUnknownFields() returns it. It applies to struct fields and to string keys of maps decoded into structs.
dec := rustyon.NewDecoder(strings.NewReader(`(servers: [(host: "a", prot: 80)])`))
dec.DisallowUnknownFields()
var c Config
err := dec.Decode(&c)
fmt.Println(err)
// rustyon: unknown field "prot" for type main.Server at servers[0]
var ue *rustyon.UnknownFieldError
if errors.As(err, &ue) {
fmt.Println(ue.Field, ue.Type, ue.Path) // prot main.Server servers[0]
}type InvalidUnmarshalError struct {
Type reflect.Type
}The decode target must be a non-nil pointer.
var c Config
fmt.Println(rustyon.Unmarshal([]byte(`()`), c)) // rustyon: Unmarshal(non-pointer main.Config)
fmt.Println(rustyon.Unmarshal([]byte(`()`), nil)) // rustyon: Unmarshal(nil)
fmt.Println(rustyon.Unmarshal([]byte(`()`), (*Config)(nil))) // rustyon: Unmarshal(nil *main.Config)
var ie *rustyon.InvalidUnmarshalError
fmt.Println(errors.As(rustyon.Unmarshal([]byte(`()`), c), &ie)) // truetype UnsupportedTypeError struct {
Type reflect.Type
}Returned for channels, functions and complex numbers.
_, err := rustyon.Marshal(make(chan int))
fmt.Println(err) // rustyon: unsupported type: chan int
var ute *rustyon.UnsupportedTypeError
fmt.Println(errors.As(err, &ute), ute.Type) // true chan inttype UnsupportedValueError struct {
Value reflect.Value
Msg string
}Returned when a value of a supported type cannot be encoded:
- nesting deeper than 1000 levels, usually a pointer cycle;
- a field, struct or variant name that is not a valid identifier, even in raw form;
- a value of a unit enum without a registered name.
type Node struct{ Next *Node }
n := &Node{}
n.Next = n
_, err := rustyon.Marshal(n)
fmt.Println(err)
// rustyon: unsupported value: exceeded maximum nesting depth, possibly a cycle
_, err = rustyon.Marshal(struct {
A int `ron:"has space"`
}{})
fmt.Println(err)
// rustyon: unsupported value: invalid identifier "has space"
var uve *rustyon.UnsupportedValueError
fmt.Println(errors.As(err, &uve)) // trueNaN and infinities are not errors: RON can represent them as NaN, inf and -inf.
type MarshalerError struct {
Type reflect.Type
Err error
Method string // "MarshalRON" or "MarshalText"
}Wraps an error from a MarshalRON or MarshalText method, or a syntax error in the RON that MarshalRON returned. It supports errors.Unwrap, so errors.Is and errors.As see the original error.
type Broken struct{}
func (Broken) MarshalRON() ([]byte, error) { return nil, errors.New("boom") }
_, err := rustyon.Marshal(Broken{})
fmt.Println(err)
// rustyon: error calling MarshalRON for type main.Broken: boom
var me *rustyon.MarshalerError
fmt.Println(errors.As(err, &me), errors.Unwrap(me)) // true boomFor a failing MarshalText method the message names MarshalText instead.
Registering enums with invalid arguments panics instead of returning an error, because it is a programming mistake that shows up at program start. See Enums.
rustyon is licensed under the BSD-3-Clause license. It is an independent implementation of RON and is not affiliated with the ron-rs project.