Project

kdl

0.01
The project is in a healthy, maintained state
Ruby implementation of the KDL Document Language Spec
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
2025
 Dependencies

Runtime

~> 1.5
~> 0.2.1
~> 0.2.0
~> 3.1.6
 Project Readme

KDL

Gem Version Actions Status Coverage Status

This is a Ruby implementation of the KDL Document Language

Installation

Add this line to your application's Gemfile:

gem 'kdl'

And then execute:

$ bundle install

Or install it yourself as:

$ gem install kdl

Usage

require 'kdl'

KDL.parse(a_string) #=> KDL::Document
KDL.load_file('path/to/file') #=> KDL::Document

You can optionally provide your own type annotation handlers:

class Foo < KDL::Value::Custom
end

KDL.parse(a_string, type_parsers: {
  'foo' => Foo
})

The foo custom type will be called with instances of Value or Node with the type annotation (foo).

Custom types are expected to have a call method that takes the Value or Node, and the type annotation itself, as arguments, and is expected to return either an instance of KDL::Value::Custom or KDL::Node::Custom (depending on the input type) or nil to return the original value as is. Take a look at the built in custom types as a reference.

You can also disable type annotation parsing entirely (including the built in ones):

KDL.parse(a_string, parse_types: false)

KDL v1

kdl-rb maintains backwards compatibility with the KDL v1 spec. By default, KDL will attempt to parse a file with the v1 parser if it fails to parse with v2. This behaviour can be changed by specifying the version option:

KDL.parse(a_string, version: 2)

The resulting document will also serialize back to the same version it was parsed as. For example, if you parse a v2 document and call to_s on it, it will output a v2 document, and similarly with v1. This behaviour can be changed by specifying the output_version option:

KDL.parse(a_string, output_version: 2)

This allows you to to convert documents between versions:

KDL.parse('foo "bar" true', version: 1, output_version: 2).to_s #=> 'foo bar #true'

You can also convert an already parsed document between versions with to_v1 and to_v2:

doc = KDL.parse('foo "bar" true', version: 1)
doc.version #=> 1
doc.to_v2.to_s #=> 'foo bar #true'

You can also set the default version globally:

KDL.default_version = 2
KDL.default_output_version = 2

You can still force automatic version detection with auto_parse:

KDL.default_version = 2
KDL.parse('foo "bar" true') #=> Error
KDL.auto_parse('foo "bar" true') #=> KDL::V1::Document

Version directives are also respected:

KDL.parse("/- kdl-version 2\nfoo bar", version: 1)
#=> Version mismatch, document specified v2, but this is a v1 parser (Racc::ParseError)

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake test to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/danini-the-panini/kdl-rb.

License

The gem is available as open source under the terms of the MIT License.