csvpputil

Documentation

Overview

Package csvpputil provides utility functions for converting CSV++ data to other formats such as JSON and YAML.

JSON Streaming Encoding

For large JSON files, use JSONEncoder to stream records directly to the output:

enc := csvpputil.NewJSONEncoder(w, headers)
for {
    record, err := reader.Read()
    if err == io.EOF {
        break
    }
    if err != nil {
        return err
    }
    if err := enc.Encode(record); err != nil {
        return err
    }
}
if err := enc.Close(); err != nil {
    return err
}

Convenience Functions

For small to medium datasets, use the Marshal functions:

data, err := csvpputil.MarshalJSON(headers, records)
data, err := csvpputil.MarshalYAML(headers, records)

Index

• func MarshalJSON(headers []*csvpp.ColumnHeader, records [][]*csvpp.Field, ...) ([]byte, error)
• func MarshalYAML(headers []*csvpp.ColumnHeader, records [][]*csvpp.Field) ([]byte, error)
• func RecordToMap(headers []*csvpp.ColumnHeader, record []*csvpp.Field) map[string]any
• type JSONEncoder
  • func NewJSONEncoder(w io.Writer, headers []*csvpp.ColumnHeader, opts ...JSONEncoderOption) *JSONEncoder
  • func (e *JSONEncoder) Close() error
  • func (e *JSONEncoder) Encode(record []*csvpp.Field) error
• type JSONEncoderOption
  • func WithDeterministic(v bool) JSONEncoderOption
• type YAMLEncoder
  • func NewYAMLEncoder(w io.Writer, headers []*csvpp.ColumnHeader) *YAMLEncoder
  • func (e *YAMLEncoder) Close() error
  • func (e *YAMLEncoder) Encode(record []*csvpp.Field) error

Examples

• JSONEncoder
• MarshalJSON
• MarshalYAML
• RecordToMap
• YAMLEncoder

Functions

func MarshalJSON

func MarshalJSON(headers []*csvpp.ColumnHeader, records [][]*csvpp.Field, opts ...JSONEncoderOption) ([]byte, error)

MarshalJSON converts CSV++ records to JSON bytes. The output is a JSON array of objects, where each object represents a record.

Example

headers := []*csvpp.ColumnHeader{
	{Name: "name", Kind: csvpp.SimpleField},
	{Name: "age", Kind: csvpp.SimpleField},
}

records := [][]*csvpp.Field{
	{{Value: "Alice"}, {Value: "30"}},
	{{Value: "Bob"}, {Value: "25"}},
}

data, err := csvpputil.MarshalJSON(headers, records, csvpputil.WithDeterministic(true))
if err != nil {
	log.Fatal(err)
}
fmt.Println(string(data))

Output:

[{"age":"30","name":"Alice"},{"age":"25","name":"Bob"}]

func MarshalYAML

func MarshalYAML(headers []*csvpp.ColumnHeader, records [][]*csvpp.Field) ([]byte, error)

MarshalYAML converts CSV++ records to YAML bytes. The output is a YAML array where each element is a record.

Example

headers := []*csvpp.ColumnHeader{
	{Name: "name", Kind: csvpp.SimpleField},
	{Name: "age", Kind: csvpp.SimpleField},
}

records := [][]*csvpp.Field{
	{{Value: "Alice"}, {Value: "30"}},
	{{Value: "Bob"}, {Value: "25"}},
}

data, err := csvpputil.MarshalYAML(headers, records)
if err != nil {
	log.Fatal(err)
}
fmt.Print(string(data))

Output:

- age: "30"
  name: Alice
- age: "25"
  name: Bob

func RecordToMap

func RecordToMap(headers []*csvpp.ColumnHeader, record []*csvpp.Field) map[string]any

RecordToMap converts a single CSV++ record to a map[string]any. The resulting map uses field names as keys and converts:

• SimpleField: string value
• ArrayField: []string
• StructuredField: map[string]any with component names as keys
• ArrayStructuredField: []map[string]any

Example

headers := []*csvpp.ColumnHeader{
	{Name: "name", Kind: csvpp.SimpleField},
	{Name: "tags", Kind: csvpp.ArrayField},
}

record := []*csvpp.Field{
	{Value: "Alice"},
	{Values: []string{"go", "rust"}},
}

m := csvpputil.RecordToMap(headers, record)
fmt.Printf("name: %s\n", m["name"])
fmt.Printf("tags: %v\n", m["tags"])

Output:

name: Alice
tags: [go rust]

Types

type JSONEncoder

type JSONEncoder struct {
	// contains filtered or unexported fields
}

JSONEncoder writes CSV++ records as JSON to an output stream. It outputs a JSON array where each element is an object representing a record.

Example

headers := []*csvpp.ColumnHeader{
	{Name: "name", Kind: csvpp.SimpleField},
	{Name: "score", Kind: csvpp.SimpleField},
}

enc := csvpputil.NewJSONEncoder(os.Stdout, headers, csvpputil.WithDeterministic(true))

if err := enc.Encode([]*csvpp.Field{{Value: "Alice"}, {Value: "100"}}); err != nil {
	log.Fatal(err)
}
if err := enc.Encode([]*csvpp.Field{{Value: "Bob"}, {Value: "85"}}); err != nil {
	log.Fatal(err)
}
if err := enc.Close(); err != nil {
	log.Fatal(err)
}

Output:

[{"name":"Alice","score":"100"},{"name":"Bob","score":"85"}]

func NewJSONEncoder

func NewJSONEncoder(w io.Writer, headers []*csvpp.ColumnHeader, opts ...JSONEncoderOption) *JSONEncoder

NewJSONEncoder creates a new JSONEncoder that writes to w.

func (*JSONEncoder) Close

func (e *JSONEncoder) Close() error

Close finishes the JSON array by writing the closing bracket. It must be called after all records have been encoded.

func (*JSONEncoder) Encode

func (e *JSONEncoder) Encode(record []*csvpp.Field) error

Encode writes a single record as a JSON object. The first call writes the opening bracket of the JSON array.

type JSONEncoderOption

type JSONEncoderOption func(*JSONEncoder)

JSONEncoderOption is a functional option for JSONEncoder.

func WithDeterministic

func WithDeterministic(v bool) JSONEncoderOption

WithDeterministic sets whether JSON output should have deterministic key ordering. When true, map keys are sorted alphabetically for consistent output.

type YAMLEncoder

type YAMLEncoder struct {
	// contains filtered or unexported fields
}

YAMLEncoder writes CSV++ records as YAML to an output stream. Records are collected and written as a single YAML array on Close.

Example

headers := []*csvpp.ColumnHeader{
	{Name: "name", Kind: csvpp.SimpleField},
	{Name: "score", Kind: csvpp.SimpleField},
}

enc := csvpputil.NewYAMLEncoder(os.Stdout, headers)

if err := enc.Encode([]*csvpp.Field{{Value: "Alice"}, {Value: "100"}}); err != nil {
	log.Fatal(err)
}
if err := enc.Encode([]*csvpp.Field{{Value: "Bob"}, {Value: "85"}}); err != nil {
	log.Fatal(err)
}
if err := enc.Close(); err != nil {
	log.Fatal(err)
}

Output:

- name: Alice
  score: "100"
- name: Bob
  score: "85"

func NewYAMLEncoder

func NewYAMLEncoder(w io.Writer, headers []*csvpp.ColumnHeader) *YAMLEncoder

NewYAMLEncoder creates a new YAMLEncoder that writes to w.

func (*YAMLEncoder) Close

func (e *YAMLEncoder) Close() error

Close writes all records as a YAML array and finishes the stream.

func (*YAMLEncoder) Encode

func (e *YAMLEncoder) Encode(record []*csvpp.Field) error

Encode adds a record to the encoder. The record will be written when Close is called.