go-piml

go-piml is a Go package that provides functionality to marshal and unmarshal data to and from the PIML format.

Release Date

2025-11-01

Status

Active

Technologies

pimlmarkup-languagego

go-piml

Spec version: v1.1.0

go-piml is a high-performance, production-ready Go package for marshalling and unmarshalling PIML data. It is designed to feel native to Go developers, leveraging the standard library's idioms and providing a powerful reflection-based API similar to encoding/json.

As the PIML specification evolves, go-piml serves as the reference implementation for compiled languages, ensuring that performance and type safety are never compromised.

Core Principles

Developer Ergonomics: Use standard Go struct tags (piml:"key_name") to map your data structures effortlessly.
Strict Typing: Seamlessly convert PIML primitives into Go's rich type system, including support for time.Time, custom pointers, and nested slices.
Performant Parsing: The recursive descent parser is optimized for minimal allocations and high throughput.

Struct Tagging & Mapping

PIML allows for clean separation between your code's data structures and the serialized format:

type Project struct {
    ID          int      `piml:"id"`
    Title       string   `piml:"title"`
    Tags        []string `piml:"tags"`
    Released    bool     `piml:"is_released"`
    Maintenance struct {
        Active bool `piml:"active"`
    } `piml:"maintenance"`
}

Advanced PIML Example

(project_registry)
  > (Project)
    (id) 101
    (title) Warp Drive Engine
    (tags)
      > physics
      > propulsion
    (is_released) true
    (maintenance)
      (active) true

(system_metrics)
  (uptime) 14500
  (load_averages)
    > 0.15
    > 0.22
    > 0.08

(description)
  Go implementation allows for deep nesting
  of structures without losing the 
  human-readable quality of the file.

Go Ecosystem Integration

go-piml is built to fit into the Go ecosystem. Whether you are building a CLI tool that needs a readable config file, or a microservice that processes structured data, go-piml provides the reliability and speed expected of Go software.

Related Artifacts

piml - The core specification.
piml.js - PIML for the JS ecosystem.
PIML Highlighter - VS Code extension.
PIML Lab - Interactive playground.

FEATURES

Powerful Logic

Intuitive Syntax: Easy-to-read key-value pairs, supporting nested structures.
Go-like Tagging: Uses piml:"tag" struct tags for flexible field mapping.
Primitive Types: Supports strings, integers, floats, and booleans.
Complex Types: Handles structs, slices (arrays), and maps.
Nil Handling: Explicitly represents nil for pointers, empty slices, and empty maps.
Multi-line Strings: Supports multi-line string values with indentation.
Comments: Allows single-line comments using # (only lines starting with # are treated as comments).
Time Support: Marshals and unmarshals time.Time values using RFC3339Nano format.

INSTALLATION

Getting Started

To use go-piml in your Go project, simply run:

go get github.com/fezcode/go-piml

USAGE

Practical Implementation

Marshalling Go Structs to PIML

cfg := Config{
    SiteName: "My Awesome Site",
    Port: 8080,
    IsProduction: true,
}

pimlData, err := piml.Marshal(cfg)

Unmarshalling PIML to Go Structs

var cfg Config
err := piml.Unmarshal(pimlData, &cfg)

High Performance

Architecture

Spec Version: v1.1.0
Serialization: Efficient reflection-based marshaling/unmarshaling.
Reflection: Uses custom piml struct tags for mapping.
Concurrency: Thread-safe operations for high-load environments.
Standards: Native support for time.Time and RFC3339Nano.