Documentation
¶
Overview ¶
Package stream provides streaming encode/decode for Tony documents.
The stream package provides structural event-based encoding and decoding optimized for streaming use cases like snapshot indexing. It only supports bracketed structures ({...} and [...]) and does not handle formatting options like colors, comments, or block style.
For general parsing/encoding with full feature support, use the parse and encode packages instead.
Example: Encoding ¶
enc, err := stream.NewEncoder(writer, stream.WithBrackets())
if err != nil {
return err
}
enc.BeginObject()
enc.WriteKey("name")
enc.WriteString("value")
enc.EndObject()
Example: Decoding ¶
dec, err := stream.NewDecoder(reader, stream.WithBrackets())
if err != nil {
return err
}
event, _ := dec.ReadEvent() // EventBeginObject
event, _ := dec.ReadEvent() // EventKey("name")
event, _ := dec.ReadEvent() // EventString("value")
event, _ := dec.ReadEvent() // EventEndObject
Comments ¶
The API is comment-ready (aligned with IR specification):
- Head comments: precede a value (IR: CommentType node with 1 value in Values)
- Line comments: on same line as value (IR: CommentType node in Comment field)
Comment support is deferred to Phase 2. In Phase 1, comment methods are no-ops and comment tokens are skipped.
Index ¶
- func DecodeNode(r io.Reader, opts ...StreamOption) (*ir.Node, error)
- func EncodeNode(node *ir.Node, w io.Writer, opts ...StreamOption) error
- func EventsToNode(events []Event) (*ir.Node, error)
- type Decoder
- func (d *Decoder) CurrentIndex() int
- func (d *Decoder) CurrentKey() string
- func (d *Decoder) CurrentPath() string
- func (d *Decoder) Depth() int
- func (d *Decoder) IsInArray() bool
- func (d *Decoder) IsInObject() bool
- func (d *Decoder) Offset() int64
- func (d *Decoder) ParentPath() string
- func (d *Decoder) ReadEvent() (Event, error)
- func (d *Decoder) Reset(r io.Reader, opts ...StreamOption) error
- type Encoder
- func (e *Encoder) BeginArray() error
- func (e *Encoder) BeginObject() error
- func (e *Encoder) CurrentIndex() int
- func (e *Encoder) CurrentKey() string
- func (e *Encoder) CurrentPath() string
- func (e *Encoder) Depth() int
- func (e *Encoder) EndArray() error
- func (e *Encoder) EndObject() error
- func (e *Encoder) Flush() error
- func (e *Encoder) IsInArray() bool
- func (e *Encoder) IsInObject() bool
- func (e *Encoder) Offset() int64
- func (e *Encoder) ParentPath() string
- func (e *Encoder) Reset(w io.Writer, opts ...StreamOption) error
- func (e *Encoder) WriteBool(value bool) error
- func (e *Encoder) WriteFloat(value float64) error
- func (e *Encoder) WriteHeadComment(lines []string) error
- func (e *Encoder) WriteInt(value int64) error
- func (e *Encoder) WriteKey(key string) error
- func (e *Encoder) WriteLineComment(lines []string) error
- func (e *Encoder) WriteNull() error
- func (e *Encoder) WriteString(value string) error
- type Error
- type Event
- type EventType
- type State
- type StreamOption
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func DecodeNode ¶
DecodeNode decodes bytes to ir.Node using Decoder. Convenience function: Decoder + EventsToNode.
func EncodeNode ¶
EncodeNode encodes an ir.Node to bytes using Encoder. Convenience function: NodeToEvents + Encoder.
Types ¶
type Decoder ¶
type Decoder struct {
// contains filtered or unexported fields
}
Decoder provides structural event-based decoding. Only supports bracketed structures ({...} and [...]). Block style (TArrayElt) is not supported.
func NewDecoder ¶
func NewDecoder(r io.Reader, opts ...StreamOption) (*Decoder, error)
NewDecoder creates a new Decoder reading from r. Requires bracketed format (use WithBrackets() or WithWire()). Returns error if bracketing not specified.
func (*Decoder) CurrentIndex ¶
CurrentIndex returns the current array index (if in array).
func (*Decoder) CurrentKey ¶
CurrentKey returns the current object key (if in object).
func (*Decoder) CurrentPath ¶
CurrentPath returns the current kinded path (e.g., "", "key", "key[0]").
func (*Decoder) IsInObject ¶
IsInObject returns true if currently inside an object.
func (*Decoder) Offset ¶
Offset returns the byte offset within the chunk being read. Note: Offset tracking is deferred - returns 0 for now.
func (*Decoder) ParentPath ¶
ParentPath returns the parent path (one level up).
func (*Decoder) ReadEvent ¶
ReadEvent reads the next structural event from the stream. Returns structural events (BeginObject, Key, String, etc.) that correspond to the encoder's API. Low-level tokens (commas, colons) are elided. Returns io.EOF when stream is exhausted.
Phase 1: Comment tokens are skipped (no comment events emitted). Phase 2: Comment tokens are converted to EventHeadComment or EventLineComment.
type Encoder ¶
type Encoder struct {
// contains filtered or unexported fields
}
Encoder provides explicit stack management for streaming Tony document encoding. Only supports bracketed structures ({...} and [...]). Block style (TArrayElt) is not supported.
func NewEncoder ¶
func NewEncoder(w io.Writer, opts ...StreamOption) (*Encoder, error)
NewEncoder creates a new Encoder writing to w. Requires bracketed format (use WithBrackets() or WithWire()). Returns error if bracketing not specified.
func (*Encoder) BeginArray ¶
BeginArray begins a regular array.
func (*Encoder) BeginObject ¶
BeginObject begins an object (or sparse array). Note: Sparse arrays use BeginObject/EndObject (semantic distinction at parse layer).
func (*Encoder) CurrentIndex ¶
CurrentIndex returns the current array index (if in array).
func (*Encoder) CurrentKey ¶
CurrentKey returns the current object key (if in object).
func (*Encoder) CurrentPath ¶
CurrentPath returns the current kinded path (e.g., "", "key", "key[0]").
func (*Encoder) IsInObject ¶
IsInObject returns true if currently inside an object.
func (*Encoder) ParentPath ¶
ParentPath returns the parent path (one level up).
func (*Encoder) Reset ¶
func (e *Encoder) Reset(w io.Writer, opts ...StreamOption) error
Reset resets the encoder to write to a new writer.
func (*Encoder) WriteFloat ¶
WriteFloat writes a float value.
func (*Encoder) WriteHeadComment ¶
WriteHeadComment writes a head comment (precedes a value). IR: CommentType node with 1 value in Values. Phase 1: No-op (comment support deferred).
func (*Encoder) WriteLineComment ¶
WriteLineComment writes a line comment (on same line as value). IR: CommentType node in Comment field. Phase 1: No-op (comment support deferred).
func (*Encoder) WriteString ¶
WriteString writes a string value.
type Event ¶
type Event struct {
Type EventType
// Value fields (only one is set based on Type)
Key string
String string
Int int64
Float float64
Bool bool
// Comment fields (for EventHeadComment and EventLineComment)
CommentLines []string // Comment text lines (from IR Node.Lines)
}
Event represents a structural event from the decoder. Events correspond to the encoder's API methods, providing a symmetric encode/decode interface.
func NodeToEvents ¶
NodeToEvents converts an ir.Node to a sequence of events. Returns events that can be written via Encoder.
Phase 1: Comments are skipped (not included in events). Phase 2: Comments are converted to EventHeadComment or EventLineComment.
type EventType ¶
type EventType int
EventType represents the type of a structural event.
const ( EventBeginObject EventType = iota EventEndObject EventBeginArray EventEndArray EventKey EventString EventInt EventFloat EventBool EventNull EventHeadComment // Head comment (precedes a value) - IR: CommentType node with 1 value in Values EventLineComment // Line comment (on same line as value) - IR: CommentType node in Comment field )
type State ¶
type State struct {
// contains filtered or unexported fields
}
State provides minimal stack/state/path management. Just processes tokens and tracks state - no tokenization, no io.Reader. Use this if you already have tokens.
Only tracks bracketed structures ({...} and [...]). Block-style arrays (TArrayElt) are not tracked.
func (*State) CurrentIndex ¶
CurrentIndex returns the current array index (if in array).
func (*State) CurrentKey ¶
CurrentKey returns the current object key (if in object).
func (*State) CurrentPath ¶
CurrentPath returns the current kinded path (e.g., "", "key", "key[0]").
func (*State) IsInObject ¶
IsInObject returns true if currently inside an object.
func (*State) ParentPath ¶
ParentPath returns the parent path (one level up).
func (*State) ProcessEvent ¶
ProcessEvent processes an event and updates state/path tracking. Call this for each event in order.
type StreamOption ¶
type StreamOption func(*streamOpts)
StreamOption configures Encoder/Decoder behavior.
func WithBrackets ¶
func WithBrackets() StreamOption
WithBrackets forces bracketed style encoding/decoding.
Source Files