go-yaml-clj

A parser-only Clojure port of go-yaml, designed for compilation by Glojure and use by YAMLStar through Gloat.

The port covers the input reader, scanner, and parser. It produces YAML parsing events and intentionally excludes go-yaml's composer, resolver, constructor, representer, serializer, and emitter.

Compatibility

The public entry point is yaml-parser.core/parse, matching the parser currently consumed by YAMLStar:

(require '[yaml-parser.core :as yaml])
(yaml/parse "key: value")

The result is a vector of event maps. Internal tokens, events, queues, and parser state use compact mutable arrays; marks are packed integers. Persistent maps are created only when events cross the public API boundary.

project.clj is the source of dependency metadata. The Makes/Lein build generates deps.edn with lein2deps, following YAMLStar's project layout.

Validation

make test           # JVM Clojure unit tests
make test-glj       # Glojure interpreter
make test-suite     # pinned official YAML event suite
make integration    # YAMLStar under Glojure and native Gloat

The event-suite gate requires every case supported by the tracked go-yaml revision. It also records go-yaml's known event failures and currently passes eight of those additional cases.

Release

Set the Clojars deploy-token credentials and provide the release version:

export CLOJARS_USERNAME=...
export CLOJARS_PASSWORD=...
make release VERSION=0.1.0

The release target requires a clean Git tree and a new version tag, runs check-all, publishes org.yamlstar/yaml-parser to Clojars, and creates the local vVERSION tag. It prints the command for pushing main and the tag after publication succeeds.

Performance contract

Performance is measured separately in the Glojure interpreter and in native code compiled by Gloat. The design requires:

• linear scanner/parser work with bounded lookahead and no grammar backtracking;
• no generated grammar, packrat memo table, callback dispatch tree, or parser frame per grammar production;
• comments disabled by default for the YAMLStar load path.

Reproducible comparison targets are:

make bench                   # this parser under the Glojure interpreter
make bench-reference         # reference parser, same interpreter
make bench-native            # this parser compiled by Gloat
make bench-native-reference  # reference parser compiled by Gloat
make bench-native-profile case=json-like

On Glojure 0.7.2, this parser is about 14x faster on the repeated mixed-document case and about 5x faster on the scalar and JSON-like cases. With Gloat 0.1.64, it is about 1.6x faster on the mixed case and about 120x faster at nested-flow depth eight; the advantage grows with nesting depth. The reference parser remains about 1.4x to 1.9x faster on some native linear scalar workloads. Removing its combinatorial behavior is the primary native win; the scalar scanner remains the main optimization target.

Port provenance

The initial source port tracks go-yaml revision b8d7755848342c16a63e5f628651aa7efb4dd55b. Files derived from go-yaml retain its Apache-2.0 and MIT attribution.