declarative 0.0.2 → 0.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 778527256a4ef370815476115d8ac7b563f30ec6
-  data.tar.gz: 630a578c3c0e63c3a390a2147651e1020c249be2
+  metadata.gz: 2f743b248235864a196f81afcba519e36856edad
+  data.tar.gz: 1c53f46fbefe9d256f7f06d39327413b01f8c2d6
 SHA512:
-  metadata.gz: 6759dca249034da2ed5695308e37192a8b5d6f870a1797341617469e8df3de34785853d8b239ef6a233583f1182733719b9ffbc55a52a024fc2edbf6a708057d
-  data.tar.gz: 4ac48558621fe5afa9c003292559c52dce7c37f105165ceb8a3c6cdeee85344f2f8bcb5f1b9a39f88d49153416a3f25a0a4d521048ab33ce28c708a36e5bfa29
+  metadata.gz: 69271f1ac66235fd31c267665a9da238211f7d97518a0b3dc6945f5a2d845048456386d5bf7e4d969d58ad37c26ba7ea7e31eeccbaad361917717179f5f6a81a
+  data.tar.gz: eb72aec864a51461c98774eedfa138aefd1591b8b7b7655d6e6d342465f66c37386c5f00f3c085f15bd94f7178d76a31c98f3a1e8da5e17a67f0bd7aa07372e0

data/CHANGES.md

@@ -1,3 +1,9 @@
+# 0.0.3
+
+* Internals, only.
+
 # 0.0.2
 
-* First usable version with `Declarative::Schema` and friends.
+* First usable version with `Declarative::Schema` and friends.
+
+TODO: default_nested_class RM

data/README.md

@@ -16,6 +16,93 @@ Add this line to your application's Gemfile:
 gem 'declarative'
 ```
 
+## Declarative::Schema
+
+Include this into a class or module to allow defining nested schemas using the popular `::property` DSL.
+
+Normally, an abstract base class will define essential configuration.
+
+```ruby
+class Model
+  include Declarative::Schema
+
+  def self.default_nested_class
+    Model
+  end
+end
+```
+
+Concrete schema-users simply derive from the base class.
+
+```ruby
+class Song < Model
+  property :id
+
+  property :artist do
+    property :id
+    property :name
+  end
+end
+```
+
+This won't do anything but populate the `::definitions` graph.
+
+```ruby
+Song.definitions #=>
+
+<Definition "id">
+<Definition "artist" nested=..>
+  <Definition "id">
+  <Definition "name">
+```
+
+The nested schema will be a subclass of `Model`.
+
+```ruby
+Song.definitions.get(:artist) #=> <Anonymous:Model definitions=..>
+```
+
+## Overriding Nested Building
+
+When declaring nested schemas, per default, Declarative will use its own `Schema::NestedBuilder` to create the nested schema composer.
+
+Override `::nested_builder` to define your own way of doing that.
+
+```ruby
+class Model
+  include Declarative::Schema
+
+  def self.default_nested_class
+    Model
+  end
+
+  def self.nested_builder
+    ->(options) do
+      Class.new(Model) do
+        class_eval &options[:_block] # executes `property :name` etc. on nested, fresh class.
+      end
+    end
+  end
+end
+```
+
+## Features
+
+You can automatically include modules into all nested schemas by using `::feature`.
+
+```ruby
+class Model
+  include Declarative::Schema
+  feature Bla
+```
+
+## Defaults
+
+```ruby
+class Model
+  include Declarative::Schema
+  defaults visible: true
+```
 
 ## Copyright
 

data/lib/declarative/definitions.rb

@@ -27,6 +27,7 @@ module Declarative
     #   :_features
     #   :_defaults
     #   :_base
+    #   :_nested_builder
     def add(name, options={}, &block)
       options = options[:_defaults].(name, options) if options[:_defaults] # FIXME: pipeline?
       base    = options[:_base]
@@ -36,7 +37,7 @@ module Declarative
         options = parent_property.options.merge(options) # TODO: Definition#merge
       end
 
-      if block
+      if options[:_nested_builder]
         options[:nested] = build_nested(
           options.merge(
             _base: base,
@@ -57,8 +58,9 @@ module Declarative
     end
 
   private
+    # Run builder to create nested schema (or twin, or representer, or whatever).
     def build_nested(options)
-      nested = options[:_nested_builder].(options)
+      options[:_nested_builder].(options)
     end
   end
 end

data/lib/declarative/schema.rb

@@ -7,19 +7,19 @@ module Declarative
   # ::feature the way we have it in Representable, Reform, and Disposable.
   #
   # The schema with its defnitions will be kept in ::definitions.
+  #
+  # Requirements to includer: ::default_nested_class, override building with ::nested_builder.
   module Schema
     module DSL
       def property(name, options={}, &block)
         heritage.record(:property, name, options, &block)
 
-        options = {
-          _base:    default_nested_class,
-        }.merge(options)
-
-        options[:_nested_builder] = nested_builder if block
-        options[:_defaults]       = _defaults
+        default_options = {}
+        default_options[:_base]           = default_nested_class
+        default_options[:_defaults]       = _defaults
+        default_options[:_nested_builder] = nested_builder if block
 
-        definitions.add(name, options, &block)
+        definitions.add(name, default_options.merge(options), &block)
       end
 
       def defaults(options={}, &block)
@@ -42,7 +42,14 @@ module Declarative
       end
 
       def nested_builder
-        NestedBuilder
+        NestedBuilder # default implementation.
+      end
+
+      NestedBuilder = ->(options) do
+        base = Class.new(options[:_base]) do
+          feature *options[:_features]
+          class_eval(&options[:_block])
+        end
       end
     end
 
@@ -75,13 +82,5 @@ module Declarative
         defaults[:_features] << mod
       end
     end
-
-
-    NestedBuilder = ->(options) do
-      base = Class.new(options[:_base]) do
-        feature *options[:_features]
-        class_eval(&options[:_block])
-      end
-    end
   end
 end

data/lib/declarative/version.rb

@@ -1,3 +1,3 @@
 module Declarative
-  VERSION = "0.0.2"
+  VERSION = "0.0.3"
 end

data/test/schema_test.rb

@@ -75,4 +75,19 @@ class SchemaTest < Minitest::Spec
      '.
      gsub("\n", "").gsub(/\s/, "")
   end
+
+
+  describe "::property still allows passing internal options" do
+    class ConcreteWithOptions < Decorator
+      defaults cool: true
+
+      # you can pass your own _nested_builder and it will still receive correct,
+      # defaultized options.
+      property :artist, _nested_builder: ->(options) { OpenStruct.new(cool: options[:cool]) }
+    end
+
+    it do
+      ConcreteWithOptions.extend(Declarative::Inspect::Schema).inspect.must_equal 'Schema: {"artist"=>#<Declarative::Definitions::Definition: @options={:cool=>true, :nested=>#<OpenStruct cool=true>, :name=>"artist"}>}'
+    end
+  end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: declarative
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: 0.0.3
 platform: ruby
 authors:
 - Nick Sutterer
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-10-30 00:00:00.000000000 Z
+date: 2015-10-31 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: uber