babl-json 0.1.4 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 2e6fcf82a20874d904622914b9253af7377adcbe
-  data.tar.gz: e74d60dee7726f6efd41d02bd1b6777673087c0e
+  metadata.gz: 20dbd1b42e36b6fa9d7f7744b2cae7caba856a05
+  data.tar.gz: 25e21d06230f8694532b962ab9062a648682cde9
 SHA512:
-  metadata.gz: c73c9e24b87d003d01f29bc1670d189fd449e3f74012141c835b833d9e657da96bbd6a1285e419ada89dd69bfc73207c0451f6ba97320d2793c082f553b43c25
-  data.tar.gz: 2863794485cca3b329105e717c76b1f69124221176f732bd9a17065cf81f2d57c17b9c8d5bd056174b9a5b89f84c088f3f7856fcb06eb08c88538d2b8fe4631f
+  metadata.gz: 3b133517888b63bef55810cd3815fc4fc5378a0b5e200e519aefebed0f3bf50d9d64141c72f9f508b181b153c3c2f6348f4126b5eba8a00a73a6908341bd8ac4
+  data.tar.gz: e762bbdc629534d829cc56d13fe40617111754b15ca64a13e0865b3f55d60ca13dd226ad8584c06be492069285b295e09b9baaa38c2bafc61dfce1cdc95e670a

data/.travis.yml

@@ -1,4 +1,4 @@
 language: ruby
 install:
   - bundle install
-script: bundle exec rspec spec
+script: bundle exec rspec spec && bundle exec rubocop

data/CHANGELOG.md

@@ -1,5 +1,11 @@
 # BABL Changelog
 
+## 0.2.0 (July 11, 2017)
+
+- Added support for producing documentation using [JSON-Schema](http://json-schema.org/).
+- Improved some error messages occurring during rendering phase.
+- Stricter validation of templates passed to the `merge` operator. Compilation will fail if at least one of them is not producing object.
+
 ## 0.1.4 (July 6, 2017)
 
 - Added operator `extends`, to simplify the common usage pattern `merge(partial(...), ...)`.

data/README.md

@@ -66,9 +66,7 @@ As of today, the only compatible preloader implementation *has not been released
 
 ### Automatic documentation
 
-Support for automatic documentation is very limited, and the output is indecently ugly. It is more a proof-of-concept than a useful feature.
-
-Mid-term goal is to generate a [JSON schema](http://json-schema.org/).
+The structure of the JSON produced by a BABL template can be documentated using [JSON-Schema](http://json-schema.org/).
 
 ### Rails integration
 

data/babl.gemspec

@@ -2,7 +2,7 @@ require File.join(File.dirname(__FILE__), 'lib/babl/version')
 
 Gem::Specification.new do |gem|
     gem.name          = "babl-json"
-    gem.version       = ::Babl::VERSION
+    gem.version       = Babl::VERSION
     gem.licenses      = ['MIT']
     gem.authors       = ['Frederic Terrazzoni']
     gem.email         = ['frederic.terrazzoni@gmail.com']
@@ -18,6 +18,8 @@ Gem::Specification.new do |gem|
     gem.add_development_dependency 'pry', '~> 0'
     gem.add_development_dependency 'rspec', '~> 3'
     gem.add_development_dependency 'rubocop', '~> 0.48'
+    gem.add_development_dependency 'json-schema', '~> 2.8'
 
     gem.add_dependency 'oj', '~> 3.0'
+    gem.add_dependency 'values', '~> 1.8'
 end

data/lib/babl.rb

@@ -1,12 +1,10 @@
 require 'babl/railtie' if defined?(Rails)
 require 'babl/template'
 require 'babl/version'
+require 'babl/rendering/noop_preloader'
+require 'babl/operators/partial'
 
 module Babl
-    class BablError < StandardError; end
-    class InvalidTemplateError < BablError; end
-    class RenderingError < BablError; end
-
     class Config
         attr_accessor :search_path, :preloader, :pretty
 
@@ -18,9 +16,9 @@ module Babl
     end
 
     class << self
-        def compile(template: ::Babl::Template.new, &source)
+        def compile(template: Babl::Template.new, &source)
             if config.search_path
-                ctx = ::Babl::Operators::Partial::AbsoluteLookupContext.new(config.search_path)
+                ctx = Babl::Operators::Partial::AbsoluteLookupContext.new(config.search_path)
                 template = template.with_lookup_context(ctx)
             end
 

data/lib/babl/builder/chain_builder.rb

@@ -1,3 +1,7 @@
+require 'babl/nodes/internal_value'
+require 'babl/nodes/terminal_value'
+require 'babl/errors'
+
 module Babl
     module Builder
         # Builder provides a simple framework for defining & chaining BABL's operators easily.
@@ -36,8 +40,8 @@ module Babl
             # Append a terminal operator, and return a new Builder object
             def construct_terminal
                 construct_node do |node, context|
-                    unless [Rendering::InternalValueNode.instance, Rendering::TerminalValueNode.instance].include?(node)
-                        raise ::Babl::InvalidTemplateError, 'Chaining is not allowed after a terminal operator'
+                    unless [Nodes::InternalValue.instance, Nodes::TerminalValue.instance].include?(node)
+                        raise Errors::InvalidTemplateError, 'Chaining is not allowed after a terminal operator'
                     end
                     yield context
                 end

data/lib/babl/builder/template_base.rb

@@ -1,3 +1,8 @@
+require 'babl/nodes/terminal_value'
+require 'babl/builder/chain_builder'
+require 'babl/rendering/compiled_template'
+require 'babl/rendering/noop_preloader'
+
 module Babl
     module Builder
         # TemplateBase is a thin wrapper around Builder.
@@ -9,8 +14,16 @@ module Babl
                 @builder = builder
             end
 
-            def compile(**options)
-                Rendering::CompiledTemplate.new(precompile, **options)
+            def compile(preloader: Rendering::NoopPreloader, pretty: true)
+                node = precompile
+
+                Rendering::CompiledTemplate.with(
+                    preloader: preloader,
+                    pretty: pretty,
+                    node: node,
+                    dependencies: node.dependencies,
+                    json_schema: node.schema.json
+                )
             end
 
             protected
@@ -20,7 +33,7 @@ module Babl
             end
 
             def precompile
-                builder.precompile(Babl::Rendering::TerminalValueNode.instance)
+                builder.precompile(Nodes::TerminalValue.instance)
             end
 
             def construct_node(**new_context, &block)

data/lib/babl/errors.rb

@@ -0,0 +1,7 @@
+module Babl
+    module Errors
+        class BablError < StandardError; end
+        class InvalidTemplateError < BablError; end
+        class RenderingError < BablError; end
+    end
+end

data/lib/babl/nodes/create_pin.rb

@@ -0,0 +1,24 @@
+require 'babl/utils/hash'
+require 'values'
+
+module Babl
+    module Nodes
+        class CreatePin < Value.new(:node, :ref)
+            def render(ctx)
+                node.render(ctx.create_pin(ref))
+            end
+
+            def schema
+                node.schema
+            end
+
+            def dependencies
+                Babl::Utils::Hash.deep_merge(node.dependencies, node.pinned_dependencies[ref] || {})
+            end
+
+            def pinned_dependencies
+                node.pinned_dependencies.reject { |k, _v| k == ref }
+            end
+        end
+    end
+end

data/lib/babl/nodes/dep.rb

@@ -0,0 +1,38 @@
+require 'babl/utils/hash'
+require 'values'
+
+module Babl
+    module Nodes
+        class Dep < Value.new(:node, :path)
+            def initialize(node, path)
+                super(node, canonicalize(path))
+            end
+
+            def render(ctx)
+                node.render(ctx)
+            end
+
+            def schema
+                node.schema
+            end
+
+            def pinned_dependencies
+                node.pinned_dependencies
+            end
+
+            def dependencies
+                Babl::Utils::Hash.deep_merge(node.dependencies, path)
+            end
+
+            private
+
+            def canonicalize(path)
+                case path
+                when ::Array then path.reduce({}) { |a, p| a.merge(canonicalize(p)) }
+                when ::Hash then path.map { |k, v| [k.to_sym, canonicalize(v)] }.to_h
+                else { path.to_sym => {} }
+                end
+            end
+        end
+    end
+end

data/lib/babl/nodes/each.rb

@@ -0,0 +1,29 @@
+require 'babl/schema/dyn_array'
+require 'babl/errors'
+require 'values'
+
+module Babl
+    module Nodes
+        class Each < Value.new(:node)
+            def dependencies
+                { __each__: node.dependencies }
+            end
+
+            def schema
+                Schema::DynArray.new(node.schema, false)
+            end
+
+            def pinned_dependencies
+                node.pinned_dependencies
+            end
+
+            def render(ctx)
+                collection = ctx.object
+                unless Enumerable === collection
+                    raise Errors::RenderingError, "Not enumerable : #{collection}\n#{ctx.formatted_stack}"
+                end
+                collection.each_with_index.map { |value, idx| node.render(ctx.move_forward(value, idx)) }
+            end
+        end
+    end
+end

data/lib/babl/nodes/fixed_array.rb

@@ -0,0 +1,25 @@
+require 'babl/utils/hash'
+require 'babl/schema/fixed_array'
+require 'values'
+
+module Babl
+    module Nodes
+        class FixedArray < Value.new(:nodes)
+            def schema
+                Schema::FixedArray.new(nodes.map(&:schema), false)
+            end
+
+            def dependencies
+                nodes.map(&:dependencies).reduce({}) { |a, b| Babl::Utils::Hash.deep_merge(a, b) }
+            end
+
+            def pinned_dependencies
+                nodes.map(&:pinned_dependencies).reduce({}) { |a, b| Babl::Utils::Hash.deep_merge(a, b) }
+            end
+
+            def render(ctx)
+                nodes.map { |node| node.render(ctx) }
+            end
+        end
+    end
+end

data/lib/babl/nodes/goto_pin.rb

@@ -0,0 +1,24 @@
+require 'babl/utils/hash'
+require 'values'
+
+module Babl
+    module Nodes
+        class GotoPin < Value.new(:node, :ref)
+            def dependencies
+                {}
+            end
+
+            def pinned_dependencies
+                Babl::Utils::Hash.deep_merge(node.pinned_dependencies, ref => node.dependencies)
+            end
+
+            def schema
+                node.schema
+            end
+
+            def render(ctx)
+                node.render(ctx.goto_pin(ref))
+            end
+        end
+    end
+end

data/lib/babl/{rendering/internal_value_node.rb → nodes/internal_value.rb}

@@ -1,17 +1,18 @@
 require 'singleton'
+require 'babl/errors'
 
 module Babl
-    module Rendering
-        # This Node plays a role similar to TerminalValueNode, but it does not perform any
+    module Nodes
+        # This Node plays a role similar to TerminalValue, but it does not perform any
         # type checking on the produced object, which is allowed to be any Ruby object,
         # including non-serializable objects.
         #
         # It is used when the output is not rendered (conditions in #switch, values passed to block in #with, ...)
-        class InternalValueNode
+        class InternalValue
             include Singleton
 
-            def documentation
-                :__value__
+            def schema
+                raise Errors::InvalidTemplateError, 'Internal nodes cannot be documented'
             end
 
             def dependencies

data/lib/babl/nodes/merge.rb

@@ -0,0 +1,102 @@
+require 'babl/utils/hash'
+require 'babl/errors'
+require 'values'
+
+module Babl
+    module Nodes
+        class Merge < Value.new(:nodes)
+            def initialize(nodes)
+                super
+            end
+
+            def dependencies
+                nodes.map(&:dependencies).reduce({}) { |a, b| Babl::Utils::Hash.deep_merge(a, b) }
+            end
+
+            def pinned_dependencies
+                nodes.map(&:pinned_dependencies).reduce({}) { |a, b| Babl::Utils::Hash.deep_merge(a, b) }
+            end
+
+            def schema
+                nodes.map(&:schema).reduce(Schema::Object::EMPTY) { |a, b| merge_doc(a, b) }
+            end
+
+            def render(ctx)
+                nodes.map { |node| node.render(ctx) }.compact.reduce({}) { |acc, val|
+                    raise Errors::RenderingError, "Only objects can be merged\n" + ctx.formatted_stack unless ::Hash === val
+                    acc.merge!(val)
+                }
+            end
+
+            private
+
+            # Merge two documentations together
+            def merge_doc(doc1, doc2)
+                doc1 = Schema::Object::EMPTY if Schema::Static::NULL == doc1
+                doc2 = Schema::Object::EMPTY if Schema::Static::NULL == doc2
+
+                case
+                when Schema::AnyOf === doc1 || Schema::AnyOf === doc2
+                    merge_extended(doc1, doc2)
+                when Schema::Object === doc1 && Schema::Object === doc2
+                    merge_object(doc1, doc2)
+                when Schema::Object === doc1 && Schema::Anything === doc2
+                    merge_object(doc1, Schema::Object::EMPTY_WITH_ADDITIONAL)
+                when Schema::Anything === doc1 && Schema::Object === doc2
+                    merge_object(Schema::Object::EMPTY_WITH_ADDITIONAL, doc2)
+                else
+                    raise Errors::InvalidTemplateError, 'Only objects can be merged'
+                end
+            end
+
+            # Merge two documention when Schema::AnyOf is involved either
+            # on left, right or both sides.
+            def merge_extended(doc1, doc2)
+                # Ensure doc1 & doc2 are both Schema::AnyOf
+                doc1ext = Schema::AnyOf.new([doc1])
+                doc2ext = Schema::AnyOf.new([doc2])
+
+                # Generate all possible combinations
+                all_docs = doc1ext.choices.product(doc2ext.choices)
+                    .map { |choice1, choice2| merge_doc(choice1, choice2) }
+
+                # Analyze each property accross all combination to
+                # generate a Schema::Object::Property filled with
+                # accurate information.
+                final_properties = all_docs.flat_map(&:properties)
+                    .group_by(&:name)
+                    .map do |name, properties|
+                    Schema::Object::Property.new(
+                        name,
+                        Schema::AnyOf.new(properties.map(&:value)).simplify,
+                        properties.size == all_docs.size && properties.all?(&:required)
+                    )
+                end
+
+                # Generate the final Schema::Object
+                Schema::Object.new(final_properties, all_docs.any?(&:additional), false)
+            end
+
+            # Merge two Schema::Object
+            def merge_object(doc1, doc2)
+                additional = doc1.additional || doc2.additional
+
+                properties = (
+                    doc1.properties.map { |property| doc2.additional ? allow_anything(property) : property } +
+                    doc2.properties
+                ).each_with_object({}) { |property, acc| acc[property.name] = property }.values
+
+                Schema::Object.new properties, additional, false
+            end
+
+            # Rewrite a property to allow Schema::Anything as value
+            def allow_anything(property)
+                Schema::Object::Property.new(
+                    property.name,
+                    Schema::AnyOf.new([property.value, Schema::Anything.instance]).simplify,
+                    property.required
+                )
+            end
+        end
+    end
+end

data/lib/babl/nodes/nav.rb

@@ -0,0 +1,33 @@
+require 'values'
+
+module Babl
+    module Nodes
+        class Nav < Value.new(:through, :node)
+            def dependencies
+                { through => node.dependencies }
+            end
+
+            def schema
+                node.schema
+            end
+
+            def pinned_dependencies
+                node.pinned_dependencies
+            end
+
+            def render(ctx)
+                node.render(ctx.move_forward_block(through) { navigate(ctx.object) })
+            end
+
+            private
+
+            def navigate(object)
+                if ::Hash === object
+                    object.fetch(through)
+                else
+                    object.send(through)
+                end
+            end
+        end
+    end
+end