README
¶
codec
Pluggable structured-text codecs (JSON, TOML, YAML, …) over a single canonical in-memory model. Any package that reads or writes a config file, manifest, or document reuses these codecs instead of re-implementing "bounded read → parse → typed error" per format.
Install
go get github.com/kbukum/gokit
Quick Start
package main
import (
"fmt"
"github.com/kbukum/gokit/codec"
)
type Config struct {
Name string `json:"name"`
Retries int `json:"retries"`
}
func main() {
c := codec.PrettyJSON()
text, _ := codec.Encode(c, Config{Name: "svc", Retries: 3})
fmt.Println(text)
cfg, _ := codec.Decode[Config](c, text)
fmt.Println(cfg.Retries) // 3
// Select a codec at runtime by name or file path.
if tc, ok := codec.CodecForPath("app.toml"); ok {
_, _ = codec.Encode(tc, cfg)
}
}
Key Types & Functions
| Name | Description |
|---|---|
Codec |
Interface encoding/decoding one text format through the Value model |
Value (= any) |
Canonical format-neutral tree (documented opaque-value exception) |
Encode[T](codec, value) / Decode[T](codec, contents) |
Generic typed encode/decode |
PrettyJSON() / CompactJSON() |
JSON codecs (multiline / single-line) |
NewTOMLCodec() |
TOML codec |
NewYAMLCodec() |
YAML codec |
CodecForName(name) / CodecForPath(path) |
Runtime codec selection by format name or file path |
Documentation
¶
Overview ¶
Package codec provides pluggable structured-text codecs over a shared value tree.
A Codec encodes and decodes one on-disk/text format (JSON, TOML, YAML, …) through a single canonical in-memory model, Value. Any package that reads or writes a config file, manifest, or document reuses these codecs instead of re-implementing "bounded read → parse → typed error" per format.
Value model ¶
Value is the canonical format-neutral tree produced by decoding JSON into an untyped Go value: nested map[string]any, []any, float64, string, bool, and nil. It is a deliberate, documented opaque-value exception to the no-any rule — the tree's leaf values are genuinely heterogeneous and cannot be given a closed type. Formats without a JSON equivalent (notably TOML datetimes) are not part of the model; represent such values as strings.
Runtime selection ¶
Codec is an interface, so a codec can be selected at runtime — for example by file extension via CodecForPath. The generic conveniences Encode and Decode take a Codec and any Go value, routing it through the value tree so callers can use ordinary structs and slices without touching Value directly.
Framing ¶
The github.com/kbukum/gokit/codec/framing subpackage carries one codec-encoded value per length-delimited frame over any blocking io.Reader/io.Writer, with every read bounded so a hostile peer cannot force an unbounded allocation.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
Types ¶
type Codec ¶
type Codec interface {
// Name returns a short identifier for diagnostics (for example "toml").
Name() string
// EncodeValue encodes a value tree into this codec's textual representation,
// returning a typed error (cause preserved) when value cannot be represented.
EncodeValue(value Value) (string, error)
// DecodeValue decodes text into a value tree,
// returning a typed error (cause preserved) when contents is malformed for this format.
DecodeValue(contents string) (Value, error)
}
Codec encodes and decodes one structured-text format over the Value model.
Implementations translate a single on-disk/text representation (JSON, TOML, …) to and from Value. The interface is intentionally small so a codec can be held as an interface value and selected at runtime; type-driven conversions live in the free functions Encode and Decode.
func CodecForName ¶
CodecForName returns a codec for a format name (for example "toml", "yaml", "json"), matched case-insensitively. The boolean is false when no codec matches.
func CodecForPath ¶
CodecForPath returns a codec for path's file extension. The boolean is false when the extension is missing or unrecognized.
type JSONCodec ¶
type JSONCodec struct {
// contains filtered or unexported fields
}
JSONCodec is the built-in JSON codec, always available because JSON backs the package's value model. It defaults to pretty-printed output.
func CompactJSON ¶
func CompactJSON() JSONCodec
CompactJSON returns a compact (single-line) JSON codec for machine streams.
func (JSONCodec) DecodeValue ¶
DecodeValue parses JSON text into a value tree.
func (JSONCodec) EncodeValue ¶
EncodeValue serializes a value tree as JSON in the codec's style.
type JSONStyle ¶
type JSONStyle int
JSONStyle selects the output layout for JSONCodec.
const ( // JSONStylePretty emits human-readable, indented output. It is the default. JSONStylePretty JSONStyle = iota // JSONStyleCompact emits minimal single-line output for machine streams (newline-delimited JSON, length-framed payloads) where size // and one value per line matter. JSONStyleCompact )
type TOMLCodec ¶
type TOMLCodec struct{}
TOMLCodec is the built-in TOML codec.
It decodes TOML into the canonical Value tree and encodes a value tree back to TOML. The top-level value must be a table (TOML has no top-level scalar or array document), and a nil value has no TOML representation — both surface as typed errors rather than panics.
func (TOMLCodec) DecodeValue ¶
DecodeValue parses TOML text into a value tree.
func (TOMLCodec) EncodeValue ¶
EncodeValue serializes a value tree as TOML.
type Value ¶
type Value = any
Value is the canonical in-memory value tree shared by every Codec.
It is the untyped result of decoding JSON — nested map[string]any, []any, float64, string, bool, and nil. Using any here is a deliberate, documented exception to the no-any rule: the tree carries genuinely heterogeneous document data whose leaf values cannot be given a closed type.
type YAMLCodec ¶
type YAMLCodec struct{}
YAMLCodec is the built-in YAML codec.
It decodes YAML into the canonical Value tree and encodes a value tree back to YAML. Like the TOML codec, the top-level value must be a mapping (the config-shaped document contract), and a non-mapping top level surfaces as a typed error rather than a panic — on both decode and encode, so round-trips stay symmetric.
Security: unlike TOML and JSON, YAML supports anchors and aliases, which the parser expands during decode. A small hostile document can reference-expand into a much larger in-memory tree ("billion laughs"). This codec does not cap expansion, so callers must decode only size-bounded input (for example via fs bounded reads); do not feed unbounded or untrusted streams straight into DecodeValue.
func (YAMLCodec) DecodeValue ¶
DecodeValue parses YAML text into a value tree. The top-level value must be a mapping.
func (YAMLCodec) EncodeValue ¶
EncodeValue serializes a value tree as YAML. The top-level value must be a mapping.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package framing provides bounded length-delimited framing for streaming codec values over a byte transport.
|
Package framing provides bounded length-delimited framing for streaming codec values over a byte transport. |
|
Package value merges codec value trees with configurable array semantics.
|
Package value merges codec value trees with configurable array semantics. |