yam.cr

Crystal bindings for yam, a fast YAML 1.2 parser written in C11. SIMD-accelerated, zero-copy, arena-allocated.

Installation

Add the dependency to your shard.yml:

dependencies:
  yam:
    github: trans/yam.cr

Then run shards install. The C library is built automatically via the postinstall script.

Requires a C11 compiler (GCC or Clang).

Quick Start

require "yam"

data = Yam.parse("name: yam\nversion: 0.1.0")
data["name"].as_s   # => "yam"
data["version"].as_s # => "0.1.0"

Usage

Parsing to Any

Yam.parse returns a Yam::Any with automatic scalar resolution (YAML 1.2 Core schema: null, bool, int, float):

data = Yam.parse <<-YAML
  server:
    host: localhost
    port: 8080
    debug: true
  YAML

data["server"]["host"].as_s    # => "localhost"
data["server"]["port"].as_i    # => 8080
data["server"]["debug"].as_bool # => true

Quoted scalars are always strings:

Yam.parse(%("42")).as_s # => "42"
Yam.parse("42").as_i    # => 42

Multi-document

docs = Yam.parse_all("---\nfoo\n---\nbar")
docs.size        # => 2
docs[0].as_s     # => "foo"
docs[1].as_s     # => "bar"

Navigating data

data = Yam.parse("a:\n  b:\n    c: deep")

data["a"]["b"]["c"].as_s   # => "deep"
data.dig("a", "b", "c").as_s # => "deep"
data.dig?("a", "x")          # => nil

data["a"].size # => 1

Anchors and aliases

yaml = <<-YAML
  defaults: &defaults
    adapter: postgres
    host: localhost
  production:
    <<: *defaults
    database: mydb
  YAML

data = Yam.parse(yaml)
data["production"]["host"].as_s     # => "localhost"
data["production"]["database"].as_s # => "mydb"

AST (Nodes API)

For full control over the parsed structure, use the Nodes API:

doc = Yam::Nodes.parse("key: value")
map = doc[0].as(Yam::Nodes::Mapping)

key = map.nodes[0].as(Yam::Nodes::Scalar)
key.value        # => "key"
key.start_line   # => 1
key.start_column # => 1

val = map.nodes[1].as(Yam::Nodes::Scalar)
val.value        # => "value"
val.start_line   # => 1
val.start_column # => 6

Node types: Scalar, Sequence, Mapping, Alias.

PullParser (low-level)

Event-based streaming parser for maximum control:

Yam::PullParser.new("name: yam\nversion: 0.1.0") do |parser|
  parser.read_stream do
    parser.read_document do
      parser.read_mapping do
        key = parser.read_scalar   # => "name"
        value = parser.read_scalar # => "yam"
        # ...
      end
    end
  end
end

API

Yam

Yam::Any

Yam::Nodes

All nodes carry start_line, start_column, end_line, end_column (1-based source positions).

License

MIT