YAMLStar JSON-comments parser

A reference-parser grammar extension for YAMLStar and go-yaml. The Clojure source in this repository is canonical. The Go package contains its generated namespace and shares the reference parser engine, initialization, event types, and runtime lock.

import "github.com/yamlstar/yamlstar-plugin-parser-json-comments/parser"

events, err := parser.Parse([]byte("answer: true// comment"))

(require '[yamlstar-plugin.parser.json-comments :as parser])
(parser/parse "answer: true// comment")

Select --plugin=parser=json-comments in the YAMLStar CLI. For go-yaml, use --plugin=yaml-parser=json-comments. For YAMLStar Python, use yamlstar.parser('json-comments').

go-yaml integration

The goyaml package provides the go-yaml adapter in this module. These compatibility changes require a new release: the published v0.1.0 adapter still uses the former parser API and plugin/limit test import. Use the updated local checkout until that release is available. Use it directly with yaml.WithPlugin(goyaml.New()):

import (
    "github.com/yamlstar/yamlstar-plugin-parser-json-comments/goyaml"
    "go.yaml.in/yaml/v4"
)

var value any
err := yaml.Load([]byte("answer: true// comment"), &value,
    yaml.WithPlugin(goyaml.New()))

For named selection, call goyaml.Register() during application startup, check its error, and then parse configuration with yaml.OptsYAML:

if err := goyaml.Register(); err != nil {
    return err
}
options, err := yaml.OptsYAML("plugin: {yaml-parser: json-comments@v0.1.0}")

Registration accepts no plugin-specific configuration. Duplicate registration and mismatched requested versions return errors. Importing the package does not register it, and registration preserves the native default parser. goyaml.Version reports the linked parser version.

After publishing the compatibility changes, set RELEASE to the new tag and use go-yaml's generic CLI build support:

make cli \
  PLUGIN-PACKAGE=github.com/yamlstar/yamlstar-plugin-parser-json-comments/goyaml@$RELEASE \
  PLUGIN=yaml-parser=json-comments

PLUGIN-PACKAGE links the adapter; PLUGIN selects the parser. A build that only sets PLUGIN-PACKAGE retains native defaults and can select the parser later through configuration or --plugin=yaml-parser=json-comments.

Syntax

// comments run to the line ending. /* */ comments may span lines and do not nest. Recognized comments are discarded while parsing the original input. Whitespace is required before comments within ordinary unquoted text. Complete JSON literals (null, true, false, and JSON numbers) permit adjacent comments, as do JSON structural boundaries. URLs and foo/*bar*/, True//text, and 01//text remain literal text. Quoted and block-scalar content retain comment markers.

Block comments can separate parts of a plain scalar. foo /* comment */ bar produces foo bar, preserving the two surrounding spaces. Adjacent JSON literals remain separate values: [true/*c*/false] is invalid. The parser also permits adjacent # after quoted scalars, commas, ], and }. Unterminated recognized block comments are errors. Comments and source positions are not included in the event interface.

Development

Makes installs development tools under .cache/. The source artifact and Go dependency use reference parser version 0.2.6. For coordinated local development, the sibling checkouts under the host's repos/ directory are detected automatically. YAML_PARSER_DIR can select the Clojure source checkout explicitly. Generation otherwise uses the pinned Clojars source artifact.

make generate
make test
make test-jvm
make test-race
make check-generated

CLI regression fixtures can exercise a go-yaml executable linked with this checkout's adapter. Build it with only PLUGIN-PACKAGE so native parsing remains the default, then run:

GO_YAML_CLI=/absolute/path/to/go-yaml \
  make shell CMD='go test ./goyaml -run TestCLICommands -v'

The Clojure and Go tests share testdata/cases.edn. Consumers of the generated Go package need neither Gloat nor a C compiler. Release the reference source and generated module before publishing this plugin and updating downstream release builds.

Release

From a clean main containing the changes to publish, run, for example:

make release o=0.1.0 v=0.1.1

The target checks the old version, updates the source version declarations, and regenerates Go code. It runs the Clojure, JVM, Go, race, and shell checks, verifies generated code and version declarations, and tests the Go module against its published dependencies with local workspace replacements disabled. After those checks pass, it commits the version changes and generated code. It deploys the JVM JAR and POM to Clojars and verifies that both are available. It then publishes the release branch and creates the matching tag and GitHub release at that commit. The same tag includes the goyaml adapter; no binary assets are needed. Use make release v=0.1.1 when the source version is already committed. Add a=1 to allow releasing from the current branch instead of main. The override publishes that branch and requires it to contain remote main.

Credentials follow YAMLStar's Clojure release convention. CLOJARS_USERNAME and CLOJARS_PASSWORD take precedence. Missing values come from ~/.yamlstar-secrets.yaml:

clojure:
  user: your-clojars-username
  token: your-clojars-deploy-token

CLOJARS_PASSWORD contains a Clojars deploy token. Set YAMLSTAR_SECRETS_FILE to read a different secrets file. Makes installs Leiningen and the YAMLScript reader used for credential lookup. The release also requires GitHub authentication with permission to create releases. Existing remote tags and releases, a dirty tree, a different branch without a=1, or a divergent remote main cause it to stop. If Clojars succeeds but a later step fails, retry the same release from the same source commit. A complete existing Clojars version is reused without redeployment. The original command with o=... also accepts an already committed new version when retrying. An existing Clojars version cannot be used for a new version bump. Incomplete artifacts, repository errors, and deployment failures stop the release before GitHub publication. Generation or validation failures leave version edits uncommitted for review. Use make release o=0.1.0 v=0.1.1 d=1 to preview the preparation and both publications without editing source files, committing, or uploading artifacts. The dry run does not require Clojars credentials.