psa-parser-go

psa-parser-go is an unofficial cgo wrapper around the vendored C psa-parser library.

It parses observed PSA planogram content from a file path or byte buffer and returns a typed Go Document model that mirrors the C library's JSON document output.

This project is not affiliated with, endorsed by, or sponsored by Blue Yonder, JDA, or any related vendor. Product and company names are trademarks of their respective owners.

The project does not include proprietary documentation, vendor software, or customer planogram files.

Status

• Current release line: v0.x / pre-1.0
• API is usable, but minor releases may include breaking changes
• Models are pinned to the vendored parser snapshot in third_party/psa-parser
• Compatibility follows the vendored C parser, not an official PSA specification

Requirements

• Go 1.25+
• CGO_ENABLED=1
• C toolchain available (clang or gcc)

Supported and tested in CI:

• Linux
• macOS

Install

go get github.com/ShelfFoundry/psa-parser-go@latest

For local development:

require github.com/ShelfFoundry/psa-parser-go v0.0.0

replace github.com/ShelfFoundry/psa-parser-go => /absolute/path/to/psa-parser-go

Quick Start

package main

import (
	"errors"
	"fmt"
	"log"
	"os"

	psaparser "github.com/ShelfFoundry/psa-parser-go"
)

func main() {
	// Parse from file
	fromFile, err := psaparser.ParseFile("./sample.psa")
	if err != nil {
		log.Fatal(err)
	}

	// Parse from bytes
	data, err := os.ReadFile("./sample.psa")
	if err != nil {
		log.Fatal(err)
	}

	fromBytes, err := psaparser.ParseBytes(data)
	if err != nil {
		var parseErr *psaparser.ParseError
		if errors.As(err, &parseErr) {
			log.Fatalf("parser code=%d message=%q", parseErr.Code, parseErr.Message)
		}
		log.Fatal(err)
	}

	fmt.Println(fromFile.Header, fromBytes.Version)
}

Public API

Typed API (recommended):

• ParseFile(path string) (Document, error)
• ParseBytes(data []byte) (Document, error)

Map compatibility API:

• ParseFileMap(path string) (map[string]any, error)
• ParseBytesMap(data []byte) (map[string]any, error)

Model Notes

• Numeric fields use float64, int, and int64
• Extension slot fields are slices ([]string, []float64, []int)
• Unknown top-level fields are captured in Document.Extras

Error Codes

Parser failures return *ParseError with C parser codes:

• CodeIO, CodeParse, CodeInvalidArg, CodeNoSpace, etc.

Limitations

• Full-document parsing only (no streaming callback API)
• Behavior follows the vendored C parser snapshot
• Requires cgo and a local C toolchain

Third-Party Source

Vendored parser lives in third_party/psa-parser.

Provenance and update process:

• third_party/psa-parser/UPSTREAM.md