~singpolyma/dhall-ruby

3c62b2e5690f577402bfcda3e260b0ac60682a0b — Stephen Paul Weber 2 years ago c6423bf
Document Dhall::Coder
2 files changed, 39 insertions(+), 1 deletions(-)

M README.md
M test/test_readme.rb
M README.md => README.md +20 -1
@@ 45,7 45,7 @@ Wherever possible, you should use the `Promise` API and treat `Dhall.load` as an

    Dhall.load("1 + 1").sync # => #<Dhall::Natural value=2>

**This will block the thread it is run from until the whole load operation is complete.  Never call #sync from an async context.**
**This will block the thread it is run from until the whole load operation is complete.  Never call `#sync` from an async context.**

### Customizing Import Resolution



@@ 241,6 241,25 @@ You may wish to convert your existing Ruby objects to Dhall expressions.  This c

Many methods on Dhall expressions call `#as_dhall` on their arguments, so you can define it on your own objects to produce a custom serialization.

If your object is already set up to customise its YAML serialization using `#encode_with`, the default `#as_dhall` implementation will use that.

When you want a full replacement for `YAML.safe_load` you can use the `Dhall::Coder` API:

    Dhall::Coder.dump(1)               # => "\x82\x0F\x01"
    Dhall::Coder.load("\x82\x0F\x01")  # => 1
    Dhall::Coder.dump(Object.new)      # => ArgumentError

    coder = Dhall::Coder.new(safe: Object)
    coder.load_async(coder.dump(Object.new)).then do |value|
      value # => #<Object:0x...>
    end

**Warning: calling `Dhall::Coder.load` or `Dhall::Coder#load` on an expression with imports will perform synchronous IO. See the warnings for the `#sync` method above.**

Both `Dhall::Coder` and all instances of `Dhall::Coder` are compatible to drop-in for `ActiveRecord::Base#serialize` like so in your models:

    serialize :column, Dhall::Coder

## Porting from YAML or JSON Configuration

To aid in converting your existing configurations or serialized data, there are included some experimental scripts:

M test/test_readme.rb => test/test_readme.rb +19 -0
@@ 399,4 399,23 @@ class TestReadme < Minitest::Test
	def test_union_extract
		assert_equal Dhall::Natural.new(value: 1), UNION.extract
	end

	def test_coder_dump
		assert_equal "\x82\x0F\x01".b, Dhall::Coder.dump(1)
	end

	def test_coder_load
		assert_equal 1, Dhall::Coder.load("\x82\x0F\x01".b)
	end

	def test_coder_dump_object
		assert_raises ArgumentError do
			Dhall::Coder.dump(Object.new)
		end
	end

	def test_coder_roundtrip
		coder = Dhall::Coder.new(safe: Object)
		assert_equal Object, coder.load_async(coder.dump(Object.new)).sync.class
	end
end