jsonnet 0.1.0 → 0.4.0

data/jsonnet.gemspec

@@ -19,8 +19,10 @@ Gem::Specification.new do |spec|
   spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
   spec.require_paths = ["lib"]
 
-  spec.add_development_dependency "bundler", "~> 1.7"
-  spec.add_development_dependency "rake", "~> 10.0"
-  spec.add_development_dependency "test-unit", "~> 3.1.3"
-  spec.add_development_dependency "rake-compiler", "~> 0.9.5"
+  spec.add_runtime_dependency "mini_portile2", ">= 2.2.0"
+
+  spec.add_development_dependency "bundler", ">= 1.7"
+  spec.add_development_dependency "rake", ">= 10.0"
+  spec.add_development_dependency "test-unit", ">= 3.1.3"
+  spec.add_development_dependency "rake-compiler", ">= 0.9.5"
 end

data/lib/jsonnet.rb

@@ -1,7 +1,47 @@
 require "jsonnet/version"
-require "jsonnet/jsonnet_wrap"
 require "jsonnet/vm"
+require "json"
 
 module Jsonnet
-  # Your code goes here...
+  module_function
+
+  ##
+  # Evaluates a string of Jsonnet and returns a hash of the resulting JSON
+  #
+  # @param [String]  jsonnet  Jsonnet source string, ideally in UTF-8 encoding
+  # @param [Hash]    jsonnet_options A hash of options to for Jsonnet::VM.
+  #                                  Available options are: filename, multi,
+  #                                  import_callback, gc_growth_triger,
+  #                                  gc_min_objects, max_stack, max_trace
+  # @param [Hash]    json_options Options supported by {JSON.parse}[http://www.rubydoc.info/github/flori/json/JSON#parse-class_method]
+  # @return [Hash] The JSON representation as a hash
+  # @raise [UnsupportedOptionError] Raised when an option passed is unsupported by Jsonnet::VM
+  #
+  # @note This method runs Jsonnet::VM#evaluate and runs the string
+  #       output through {JSON.parse}[http://www.rubydoc.info/github/flori/json/JSON#parse-class_method]
+  #       so those should be looked at for furhter details
+  def evaluate(jsonnet, jsonnet_options: {}, json_options: {})
+    output = VM.evaluate(jsonnet, jsonnet_options)
+    JSON.parse(output, json_options)
+  end
+
+  ##
+  # Loads a Jsonnet file and returns a hash of the resulting JSON
+  #
+  # @param [String]  path path to the jsonnet file
+  # @param [Hash]    jsonnet_options A hash of options to for Jsonnet::VM.
+  #                                  Available options are: encoding, multi,
+  #                                  import_callback, gc_growth_triger,
+  #                                  gc_min_objects, max_stack, max_trace
+  # @param [Hash]    json_options Options supported by {JSON.parse}[http://www.rubydoc.info/github/flori/json/JSON#parse-class_method]
+  # @return [Hash] The JSON representation as a hash
+  # @raise [UnsupportedOptionError] Raised when an option passed is unsupported by Jsonnet::VM
+  #
+  # @note This method runs Jsonnet::VM#evaluate_file and runs the string
+  #       output through {JSON.parse}[http://www.rubydoc.info/github/flori/json/JSON#parse-class_method]
+  #       so those should be looked at for furhter details
+  def load(path, jsonnet_options: {}, json_options: {})
+    output = VM.evaluate_file(path, jsonnet_options)
+    JSON.parse(output, json_options)
+  end
 end

data/lib/jsonnet/version.rb

@@ -1,3 +1,3 @@
 module Jsonnet
-  VERSION = "0.1.0"
+  VERSION = "0.4.0"
 end

data/lib/jsonnet/vm.rb

@@ -1,5 +1,59 @@
+require "jsonnet/jsonnet_wrap"
+
 module Jsonnet
   class VM
+    class << self
+      ##
+      # Convenient method to evaluate a Jsonnet snippet.
+      #
+      # It implicitly instantiates a VM and then evaluate Jsonnet with the VM.
+      #
+      # @param snippet [String]  Jsonnet source string.
+      # @param options [Hash]  options to {.new} or options to {#evaluate}
+      # @return [String]
+      # @see #evaluate
+      def evaluate(snippet, options = {})
+        snippet_check = ->(key, value) { key.to_s.match(/^filename|multi$/) }
+        snippet_options = options.select(&snippet_check)
+        vm_options = options.reject(&snippet_check)
+        new(vm_options).evaluate(snippet, **snippet_options)
+      end
+
+      ##
+      # Convenient method to evaluate a Jsonnet file.
+      #
+      # It implicitly instantiates a VM and then evaluates Jsonnet with the VM.
+      #
+      # @param filename [String]  Jsonnet source file.
+      # @param options [Hash]  options to {.new} or options to {#evaluate_file}
+      # @return [String]
+      # @see #evaluate_file
+      def evaluate_file(filename, options = {})
+        file_check = ->(key, value) { key.to_s.match(/^encoding|multi$/) }
+        file_options = options.select(&file_check)
+        vm_options = options.reject(&file_check)
+        new(vm_options).evaluate_file(filename, **file_options)
+      end
+    end
+
+    ##
+    # initializes a new VM with the given configuration.
+    #
+    # @param [Hash] options  a mapping from option names to their values.
+    #    It can have names of writable attributes in VM class as keys.
+    # @return [VM] the VM.
+    def initialize(options = {})
+      options.each do |key, value|
+        method = "#{key}="
+        if respond_to?(method)
+          public_send(method, value)
+        else
+          raise UnsupportedOptionError.new("Jsonnet VM does not support #{key} option")
+        end
+      end
+      self
+    end
+
     ##
     # Evaluates Jsonnet source.
     #
@@ -11,9 +65,9 @@ module Jsonnet
     # @raise [EvaluationError] raised when the evaluation results an error.
     # @raise [UnsupportedEncodingError] raised when the encoding of jsonnet
     #        is not ASCII-compatible.
-    # @note It is recommended to encode the source string in UTF-8 because 
-    #       Jsonnet expects it is ASCII-compatible, the result JSON string 
-    #       shall be UTF-{8,16,32} according to RFC 7159 thus the only 
+    # @note It is recommended to encode the source string in UTF-8 because
+    #       Jsonnet expects it is ASCII-compatible, the result JSON string
+    #       shall be UTF-{8,16,32} according to RFC 7159 thus the only
     #       intersection between the requirements is UTF-8.
     def evaluate(jsonnet, filename: "(jsonnet)", multi: false)
       eval_snippet(jsonnet, filename, multi)
@@ -26,23 +80,88 @@ module Jsonnet
     # @param [Boolean] multi    enables multi-mode
     # @return [String] a JSON representation of the evaluation result
     # @raise [EvaluationError] raised when the evaluation results an error.
-    # @note It is recommended to encode the source file in UTF-8 because 
-    #       Jsonnet expects it is ASCII-compatible, the result JSON string 
-    #       shall be UTF-{8,16,32} according to RFC 7159 thus the only 
+    # @note It is recommended to encode the source file in UTF-8 because
+    #       Jsonnet expects it is ASCII-compatible, the result JSON string
+    #       shall be UTF-{8,16,32} according to RFC 7159 thus the only
     #       intersection between the requirements is UTF-8.
     def evaluate_file(filename, encoding: Encoding.default_external, multi: false)
       eval_file(filename, encoding, multi)
     end
 
+    ##
+    # Format Jsonnet file.
+    #
+    # @param [String] filename filename of a Jsonnet source file.
+    # @return [String] a formatted Jsonnet representation
+    # @raise [FormatError] raised when the formatting results an error.
+    def format_file(filename, encoding: Encoding.default_external)
+      fmt_file(filename, encoding)
+    end
+
+    ##
+    # Format Jsonnet snippet.
+    #
+    # @param [String] jsonnet Jsonnet source string. Must be encoded in ASCII-compatible encoding.
+    # @param [String] filename filename of the source. Used in stacktrace.
+    # @return [String] a formatted Jsonnet representation
+    # @raise [FormatError] raised when the formatting results an error.
+    # @raise [UnsupportedEncodingError] raised when the encoding of jsonnt is not ASCII-compatible.
+    def format(jsonnet, filename: "(jsonnet)")
+      fmt_snippet(jsonnet, filename)
+    end
+
     ##
     # Lets the given block handle "import" expression of Jsonnet.
     # @yieldparam  [String] base base path to resolve "rel" from.
     # @yieldparam  [String] rel  a relative or absolute path to the file to be imported
     # @yieldreturn [Array<String>] a pair of the content of the imported file and
     #                              its path.
-    def handle_import
-      self.import_callback = Proc.new
+    def handle_import(&block)
+      if block.nil?
+        raise ArgumentError, 'handle_import requires a block'
+      end
+      self.import_callback = to_method(block)
       nil
     end
+
+    ##
+    # Define a function (native extension) in the VM and let the given block
+    # handle the invocation of the function.
+    #
+    # @param name [Symbol|String] name of the function.
+    #   Must be a valid identifier in Jsonnet.
+    # @param body [#to_proc] body of the function.
+    # @yield calls the given block instead of `body` if `body` is `nil`
+    #
+    # @note Currently it cannot define keyword or optional paramters in Jsonnet.
+    #   Also all the positional optional parameters of the body are interpreted
+    #   as required parameters. And the body cannot have keyword, rest or
+    #   keyword rest paramters.
+    def define_function(name, body = nil, &block)
+      body = body ? body.to_proc : block
+      if body.nil?
+        raise ArgumentError, 'define_function requires a body argument or a block'
+      end
+      params = body.parameters.map.with_index do |(type, name), i|
+        raise ArgumentError, "rest or keyword parameters are not allowed: #{type}" \
+          unless [:req, :opt].include? type
+
+        name || "p#{i}"
+      end
+
+      register_native_callback(name.to_sym, to_method(body), params);
+    end
+
+    private
+    # Wraps the function body with a method so that `break` and `return`
+    # behave like `return` as they do in a body of Module#define_method.
+    def to_method(body)
+      mod = Module.new {
+        define_method(:dummy, body)
+      }
+      mod.instance_method(:dummy).bind(body.binding.receiver)
+    end
+
+    class UnsupportedOptionError < RuntimeError; end
   end
 end

data/test/fixtures/jpath.libsonnet

@@ -0,0 +1,3 @@
+{
+    a: 1,
+}

data/test/test_jsonnet.rb

@@ -1,8 +1,51 @@
 require 'jsonnet'
+
+require 'tempfile'
 require 'test/unit'
 
 class TestJsonnet < Test::Unit::TestCase
   test 'libversion returns a String' do
-    assert_kind_of String, Jsonnet.libversion 
+    assert_kind_of String, Jsonnet.libversion
+  end
+
+  test 'Jsonnet.evaluate returns a JSON parsed result' do
+    result = Jsonnet.evaluate('{ foo: "bar" }')
+    assert_equal result, { "foo" => "bar" }
+  end
+
+  test 'Jsonnet.evaluate can accept options for JSON' do
+    result = Jsonnet.evaluate('{ foo: "bar" }', json_options: { symbolize_names: true })
+    assert_equal result, { foo: "bar" }
+  end
+
+  test 'Jsonnet.evaluate can accept options for Jsonnet VM' do
+    result = Jsonnet.evaluate(
+      'import "imported.jsonnet"',
+      jsonnet_options: {
+        import_callback: ->(_base, _rel) do
+          return ['{ foo: "bar" }', 'imported']
+        end
+      }
+    )
+    assert_equal result, { "foo" => "bar" }
+  end
+
+  test 'Jsonnet.load returns a JSON parsed result' do
+    result = Jsonnet.load(example_jsonnet_file.path)
+    assert_equal result, { "foo1" => 1 }
+  end
+
+  private
+
+  def example_jsonnet_file
+    Tempfile.open("example.jsonnet") do |f|
+      f.write %<
+        local myvar = 1;
+        {
+          ["foo" + myvar]: myvar,
+        }
+      >
+      f
+    end
   end
 end

data/test/test_vm.rb

@@ -47,7 +47,7 @@ class TestVM < Test::Unit::TestCase
     vm = Jsonnet::VM.new
     begin
       with_example_file(%q{ ["unterminated string }) {|fname|
-        vm.evaluate_file(fname.encode(Encoding::SJIS)) 
+        vm.evaluate_file(fname.encode(Encoding::SJIS))
       }
     rescue Jsonnet::EvaluationError => e
       assert_equal Encoding::SJIS, e.message.encoding
@@ -104,19 +104,62 @@ class TestVM < Test::Unit::TestCase
   test "Jsonnet::VM#evaluate raises an error in the encoding of filename" do
     vm = Jsonnet::VM.new
     begin
-      vm.evaluate(%Q{ ["unterminated string }, filename: "テスト.json".encode(Encoding::SJIS)) 
+      vm.evaluate(%Q{ ["unterminated string }, filename: "テスト.json".encode(Encoding::SJIS))
     rescue Jsonnet::EvaluationError => e
       assert_equal Encoding::SJIS, e.message.encoding
     end
   end
 
-  test "Jsonnet::VM#ext_var binds a variable" do
+  test "Jsonnet::VM#ext_var binds a variable to a string value" do
     vm = Jsonnet::VM.new
     vm.ext_var("var1", "foo")
     result = vm.evaluate('[std.extVar("var1")]')
     assert_equal JSON.parse('["foo"]'), JSON.parse(result)
   end
 
+  test "Jsonnet::VM#ext_code binds a variable to a code fragment" do
+    vm = Jsonnet::VM.new
+    vm.ext_code("var1", "{a:1}")
+    result = vm.evaluate('[std.extVar("var1")]')
+    assert_equal JSON.parse(<<-EOS), JSON.parse(result)
+      [
+        {
+          "a": 1
+        }
+      ]
+    EOS
+  end
+
+  test "Jsonnet::VM#tla_var binds a top-level variable to a string value" do
+    vm = Jsonnet::VM.new
+    vm.tla_var("var1", "foo")
+    result = vm.evaluate('function(var1) [var1, var1]')
+    assert_equal JSON.parse('["foo", "foo"]'), JSON.parse(result)
+  end
+
+  test "Jsonnet::VM#tla_var binds a top-level argument to a string value" do
+    vm = Jsonnet::VM.new
+    vm.tla_var("var1", "foo")
+    result = vm.evaluate('function(var1) [var1, var1]')
+    assert_equal JSON.parse('["foo", "foo"]'), JSON.parse(result)
+  end
+
+  test "Jsonnet::VM#tla_code binds a top-level argument to a code fragment" do
+    vm = Jsonnet::VM.new
+    vm.tla_code("var1", "{a:1}")
+    result = vm.evaluate('function(var1) [var1, var1]')
+    assert_equal JSON.parse(<<-EOS), JSON.parse(result)
+      [
+        {
+          "a": 1
+        },
+        {
+          "a": 1
+        }
+      ]
+    EOS
+  end
+
   test 'Jsonnet::VM#evaluate returns a JSON per filename on multi mode' do
     vm = Jsonnet::VM.new
     [
@@ -211,10 +254,6 @@ class TestVM < Test::Unit::TestCase
     Jsonnet::VM.new.max_trace = 1
   end
 
-  test "Jsonnet::VM responds to debug_ast=" do
-    Jsonnet::VM.new.debug_ast = true
-  end
-
   test "Jsonnet::VM#string_output lets the VM output a raw string" do
     vm = Jsonnet::VM.new
     vm.string_output = true
@@ -229,7 +268,7 @@ class TestVM < Test::Unit::TestCase
       case [base, rel]
       when ['/path/to/base/', 'imported1.jsonnet']
         return <<-EOS, '/path/to/imported1/imported1.jsonnet'
-          import "imported2.jsonnet" {
+          (import "imported2.jsonnet") + {
             b: 2,
           }
         EOS
@@ -242,7 +281,7 @@ class TestVM < Test::Unit::TestCase
       end
     }
     result = vm.evaluate(<<-EOS, filename: "/path/to/base/example.jsonnet")
-      import "imported1.jsonnet" { c: 3 }
+      (import "imported1.jsonnet") + { c: 3 }
     EOS
 
     expected = {"a" => 1, "b" => 2, "c" => 3}
@@ -255,12 +294,276 @@ class TestVM < Test::Unit::TestCase
     vm.import_callback = ->(base, rel) { called = true; raise }
     assert_raise(Jsonnet::EvaluationError) {
       vm.evaluate(<<-EOS)
-        import "a.jsonnet" {}
+        (import "a.jsonnet") + {}
       EOS
     }
     assert_true called
   end
 
+  test "Jsonnet::VM#handle_import treats global escapes as define_method does" do
+    num_eval = 0
+    begin
+      bodies = [
+        proc   {|rel, base| return 'null', '/x.libsonnet' },
+        lambda {|rel, base| return 'null', '/x.libsonnet' },
+        proc   {|rel, base| next 'null', '/x.libsonnet' },
+        lambda {|rel, base| next 'null', '/x.libsonnet' },
+        proc   {|rel, base| break 'null', '/x.libsonnet' },
+        lambda {|rel, base| break 'null', '/x.libsonnet' },
+      ]
+      bodies.each do |prc|
+        vm = Jsonnet::VM.new
+        vm.handle_import(&prc)
+
+        result = vm.evaluate('import "a.jsonnet"')
+        assert_nil JSON.load(result)
+
+        num_eval += 1
+      end
+    ensure
+      assert_equal bodies.size, num_eval
+    end
+  end
+
+  test "Jsonnet::VM#handle_import is safe on throw" do
+    [
+      proc   {|rel, base| throw :dummy },
+      lambda {|rel, base| throw :dummy },
+    ].each do |prc|
+      vm = Jsonnet::VM.new
+      vm.handle_import(&prc)
+
+      catch(:dummy) {
+        vm.evaluate('import "a.jsonnet"')
+        flunk "never reach here"
+      }
+    end
+  end
+
+  test "Jsonnet::VM#jpath_add adds a library search path" do
+    vm = Jsonnet::VM.new
+    snippet = "(import 'jpath.libsonnet') {b: 2}"
+    assert_raise(Jsonnet::EvaluationError) {
+      vm.evaluate(snippet)
+    }
+
+    vm.jpath_add(File.join(__dir__, 'fixtures'))
+    result = vm.evaluate(snippet)
+    assert_equal JSON.parse(<<-EOS), JSON.parse(result)
+      {
+        "a": 1,
+        "b": 2
+      }
+    EOS
+  end
+
+  test "Jsonnet::VM#define_function adds a new native extension" do
+    vm = Jsonnet::VM.new
+    called = false
+
+    vm.define_function("myPow") do |x, y|
+      called = true
+      x ** y
+    end
+
+    result = vm.evaluate("std.native('myPow')(3, 4)")
+    assert_equal 3**4, JSON.load(result)
+    assert_true called
+  end
+
+  test "Jsonnet::VM#define_function passes various types of arguments" do
+    [
+      [%q(null), nil],
+      [%q("abc"), "abc"],
+      [%q(1), 1.0],
+      [%q(1.25), 1.25],
+      [%q(true), true],
+      [%q(false), false],
+    ].each do |expr, value|
+      vm = Jsonnet::VM.new
+      vm.define_function("myFunc") do |x|
+        assert_equal value, x
+        next nil
+      end
+      vm.evaluate("std.native('myFunc')(#{expr})")
+    end
+  end
+
+  test "Jsonnet::VM#define_function returns various types of values" do
+    [
+      [nil, nil],
+      ["abc", "abc"],
+      [1, 1.0],
+      [1.25, 1.25],
+      [true, true],
+      [false, false],
+    ].each do |retval, expected|
+      vm = Jsonnet::VM.new
+      vm.define_function("myFunc") { retval }
+
+      result = vm.evaluate("std.native('myFunc')()")
+      assert_equal expected, JSON.load(result)
+    end
+  end
+
+  test "Jsonnet::VM#define_function translates an exception in a native function into an error" do
+    vm = Jsonnet::VM.new
+    vm.define_function("myFunc") do |x|
+      raise "something wrong"
+    end
+    assert_raise(Jsonnet::EvaluationError) {
+      vm.evaluate("std.native('myFunc')(1)")
+    }
+  end
+
+  test "Jsonnet::VM#define_function let the function return a compound object" do
+    vm = Jsonnet::VM.new
+    vm.define_function("myCompound") do |x, y|
+      {
+        x => y,
+        y => [x, y, y, x],
+      }
+    end
+
+    result = vm.evaluate("std.native('myCompound')('abc', 'def')")
+    assert_equal JSON.parse(<<-EOS), JSON.parse(result)
+      {
+        "abc": "def",
+        "def": ["abc", "def", "def", "abc"]
+      }
+    EOS
+  end
+
+  test "Jsonnet::VM#define_function treats global escapes as define_method does" do
+    num_eval = 0
+    begin
+      bodies = [
+        proc   {|x| return x },
+        lambda {|x| return x },
+        proc   {|x| next x },
+        lambda {|x| next x },
+        proc   {|x| break x },
+        lambda {|x| break x },
+      ]
+      bodies.each do |prc|
+        vm = Jsonnet::VM.new
+        vm.define_function(:myFunc, prc)
+
+        result = vm.evaluate('std.native("myFunc")(1.25) + 0.25')
+        assert_equal 1.25 + 0.25, JSON.load(result)
+
+        num_eval += 1
+      end
+    ensure
+      assert_equal bodies.size, num_eval
+    end
+  end
+
+  test "Jsonnet::VM#define_function is safe on throw" do
+    [
+      proc   {|x| throw :dummy },
+      lambda {|x| throw :dummy },
+    ].each do |prc|
+      vm = Jsonnet::VM.new
+      vm.define_function(:myFunc, prc)
+
+      catch(:dummy) {
+        vm.evaluate('std.native("myFunc")(1.234)')
+        flunk "never reach here"
+      }
+    end
+  end
+
+  test "Jsonnet::VM#format_file formats Jsonnet file" do
+    vm = Jsonnet::VM.new
+    vm.fmt_indent = 4
+    with_example_file(%<
+      local myvar = 1;
+    {
+    "foo": myvar
+    }
+    >) {|fname|
+      result = vm.format_file(fname)
+      assert_equal <<-EOS, result
+local myvar = 1;
+{
+    foo: myvar,
+}
+      EOS
+    }
+  end
+
+  test "Jsonnet::VM#format formats Jsonnet snippet" do
+    vm = Jsonnet::VM.new
+    vm.fmt_string = 'd'
+    result = vm.format(<<-EOS)
+local myvar = 'myvar';
+{
+foo: [myvar,myvar]
+}
+    EOS
+    assert_equal <<-EOS, result
+local myvar = "myvar";
+{
+  foo: [myvar, myvar],
+}
+    EOS
+  end
+
+  test "Jsonnet::VM#fmt_string only accepts 'd', 's', or 'l'" do
+    vm = Jsonnet::VM.new
+    vm.fmt_string = Jsonnet::STRING_STYLE_DOUBLE
+    vm.fmt_string = Jsonnet::STRING_STYLE_SINGLE
+    vm.fmt_string = Jsonnet::STRING_STYLE_LEAVE
+    assert_raise(ArgumentError) do
+      vm.fmt_string = ''
+    end
+    assert_raise(ArgumentError) do
+      vm.fmt_string = 'a'
+    end
+    assert_raise(ArgumentError) do
+      vm.fmt_string = 'ds'
+    end
+    assert_raise(TypeError) do
+      vm.fmt_string = 0
+    end
+  end
+
+  test "Jsonnet::VM#fmt_comment only accepts 'h', 's', or 'l'" do
+    vm = Jsonnet::VM.new
+    vm.fmt_comment = Jsonnet::COMMENT_STYLE_HASH
+    vm.fmt_comment = Jsonnet::COMMENT_STYLE_SLASH
+    vm.fmt_comment = Jsonnet::COMMENT_STYLE_LEAVE
+    assert_raise(ArgumentError) do
+      vm.fmt_comment = ''
+    end
+    assert_raise(ArgumentError) do
+      vm.fmt_comment = 'a'
+    end
+    assert_raise(ArgumentError) do
+      vm.fmt_comment = 'hs'
+    end
+    assert_raise(TypeError) do
+      vm.fmt_comment = 0
+    end
+  end
+
+  test "Jsonnet::VM#fmt_file raises FormatError on error" do
+    vm = Jsonnet::VM.new
+    with_example_file('{foo: }') do |fname|
+      assert_raise(Jsonnet::FormatError) do
+        vm.format_file(fname)
+      end
+    end
+  end
+
+  test "Jsonnet::VM#fmt_snippet raises FormatError on error" do
+    vm = Jsonnet::VM.new
+    assert_raise(Jsonnet::FormatError) do
+      vm.format('{foo: }')
+    end
+  end
+
   private
   def with_example_file(content)
     Tempfile.open("example.jsonnet") {|f|