democritus 0.2.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 8db17897f669a971aa5b22ba819978953a3eda10
-  data.tar.gz: d3f9514bb722c2dd6eb51a4beb06d0e48e606524
+  metadata.gz: 31bf7a0b474a852c085027772e7d40715b88ae07
+  data.tar.gz: ed1008231c6ec39463300838f284f16951d51850
 SHA512:
-  metadata.gz: 22a3ec1e45a1e3dce5cb8c36751723c88a37002d6a654e7ac7899a0dd926a5f3657f422592e5e94795df8cf1235e1bc6023a277dcef638445dbd99cbfeb1c3c3
-  data.tar.gz: d34e1f0f3288fa495664c7c63710185ee1a9eb7ae2a61591a3e50b85c8a2b561e67ac5f5184cefcf3bca1bb44a7508dbc3de949fec934943d1159c8be8b4810a
+  metadata.gz: d931a7f8efab73769eeaedaa45ee3935693e17c0bf88d8b3da9f1116a1538f84cd644821c2f048f0fa6562efcd76667cde7fe0a6ba9155e8fb686d6245ef3877
+  data.tar.gz: 6ecc80dbd308f689ca8fc19ec4571dab4587c9b8de7620d66669c27715b4a7613c494d5a8ddf56c11b1bc428cfa37c36a2ebab216a3049849680c9de82991c15

data/.gitignore

@@ -7,3 +7,5 @@
 /pkg/
 /spec/reports/
 /tmp/
+/.tags*
+/tags

data/.rspec

@@ -0,0 +1,3 @@
+--color
+--order random
+

data/README.md

@@ -6,7 +6,7 @@
 [![Test Coverage](https://codeclimate.com/github/jeremyf/democritus/badges/coverage.svg)](https://codeclimate.com/github/jeremyf/democritus)
 [![Documentation Status](http://inch-ci.org/github/jeremyf/democritus.svg?branch=master)](http://inch-ci.org/github/jeremyf/democritus)
 
-Democritus is a plugin for building class from reusable components.
+Democritus is library for building classes from reusable components.
 
 Democritus is inspired as followup of a common pattern that I saw in the development of [Sipity's](https://github.com/ndlib/sipity/) form objects.
 It also aims to address the needs of Sipity's yet to be developed sibling application; The dissemination of processed data.
@@ -57,5 +57,5 @@ ApprovalForm = Demcritus.build_from_json(json)
   - [x] [Command::Attirubtes](./lib/democritus/class_builder/commands/attributes.rb)
 - [ ] Create the commands that build a Sipity processing form
 - [X] Build class from JSON configuration
-  - [ ] Basic case for nested commands
-  - [ ] Allow for "constantization" of command_namespaces option.
+  - [X] Basic case for nested commands
+  - [X] Allow for "constantization" of command_namespaces option.

data/Rakefile

@@ -30,3 +30,4 @@ FlayTask.new do |task|
 end
 
 task(default: ['rubocop', 'reek', 'flay', 'spec'])
+task(release: :default)

data/democritus.gemspec

@@ -9,8 +9,8 @@ Gem::Specification.new do |spec|
   spec.authors       = ["Jeremy Friesen"]
   spec.email         = ["jeremy.n.friesen@gmail.com"]
 
-  spec.summary       = %q{A placeholder for an attribute declaration mechanism}
-  spec.description   = %q{A placeholder for an attribute declaration mechanism}
+  spec.summary       = %q{Democritus is library for building classes from reusable components.}
+  spec.description   = %q{Democritus is library for building classes from reusable components.}
   spec.homepage      = "https://github.com/jeremyf/democritus"
 
   spec.files         = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
@@ -23,11 +23,10 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency "rake", "~> 10.0"
   spec.add_development_dependency "rspec", "~> 3.2"
   spec.add_development_dependency "rspec-its", "~> 1.2"
-  spec.add_development_dependency "reek"
-  spec.add_development_dependency "flay"
+  spec.add_development_dependency "rubycritic"
   spec.add_development_dependency "rubocop"
   spec.add_development_dependency "rubocop-rspec"
   spec.add_development_dependency "simplecov"
   spec.add_development_dependency "codeclimate-test-reporter"
-  spec.add_development_dependency "byebug"
+  spec.add_development_dependency "shoulda-matchers"
 end

data/lib/democritus.rb

@@ -8,11 +8,23 @@ require 'democritus/from_json_class_builder'
 # for understanding the galaxy of objects.
 module Democritus
   # @api public
+  # @since 0.1.0
   #
   # Responsible for building a class based on atomic components.
   #
-  # @yield [Democritus::ClassBuilder] Gives a builder to provide additional command style customizations
+  # @yield [Democritus::ClassBuilder] a builder object to provide additional command style customizations
   # @return Class
+  #
+  # @example
+  #   NamedPerson = Democritus.build do |builder|
+  #     builder.attributes do
+  #       attribute(name: :given_name)
+  #       attribute(name: :surname)
+  #     end
+  #   end
+  #   NamedPerson.new(given_name: 'Farrokh', surname: 'Bulsara')
+  #
+  # @see Demcoritus::ClassBuilder
   def self.build(&configuration_block)
     builder = ClassBuilder.new
     builder.customize(&configuration_block)
@@ -20,10 +32,21 @@ module Democritus
   end
 
   # @api public
+  # @since 0.2.0
   #
   # Responsible for building a class based on the given JSON object.
   #
+  # @param [String] A "well-formed" JSON document
   # @return Class
+  #
+  #   NamedPerson = Democritus.build_from_json(%{
+  #     "#attributes": {
+  #       "#attribute": [{ "name": "given_name" }, { "name": "surname"}]
+  #     }
+  #   })
+  #   NamedPerson.new(given_name: 'Farrokh', surname: 'Bulsara')
+  #
+  # @see Demcoritus::FromJsonClassBuilder for details on "well-formed"
   def self.build_from_json(json)
     builder = FromJsonClassBuilder.new(json)
     builder.generate_class

data/lib/democritus/class_builder.rb

@@ -29,11 +29,23 @@ module Democritus
     # The above #a_customization method is captured in the customization_module and applied as an instance method
     # to the generated class.
     attr_accessor :customization_module
+
+    # The module with the generated code.
+    #
+    # @example
+    #   Democritus.build do |builder|
+    #     builder.a_command
+    #     def a_customization
+    #     end
+    #   end
+    #
+    # The above `builder.a_command` invocation is captured and is applied to the generation_module.
     attr_accessor :generation_module
 
     # Command operations to be applied as class methods of the generated_class.
     attr_accessor :class_operations
 
+    # The default namespaces in which Democritus will look up commands.
     def default_command_namespaces
       [Democritus::ClassBuilder::Commands]
     end
@@ -42,7 +54,14 @@ module Democritus
     attr_reader :command_namespaces
 
     def command_namespaces=(input)
-      @command_namespaces = Array(input)
+      @command_namespaces = Array(input).map do |command_namespace|
+        case command_namespace
+        when Module, Class
+          command_namespace
+        else
+          Object.const_get(command_namespace.to_s)
+        end
+      end
     end
 
     # Command operations to be applied as instance methods of the generated_class.
@@ -89,17 +108,36 @@ module Democritus
       customization_mod = customization_module # get a local binding
       apply_operations(instance_operations, generation_mod)
       generated_class = Class.new do
+        # requires the local binding from above
         const_set :GeneratedMethods, generation_mod
         const_set :Customizations, customization_mod
+        # because == and case operators are useful
         include DemocritusObjectTag
         include generation_mod
+
+        # customization should be applied last as it allows for "overrides" of generated methods
         include customization_mod
       end
       generated_class
     end
     # rubocop:enable MethodLength
 
-    def defer(options = {}, &deferred_operation)
+    # @api public
+    #
+    # When configuring the class that is being built, we don't want to apply all of the modifications at once, instead allowing them
+    # to be applied in a specified order.
+    #
+    # @example
+    #   Democritus::ClassBuilder.new.defer(prepend: true) do
+    #     define_method(:help) { 'Did you try turning it off and on again?' }
+    #   end
+    #
+    # @param [Hash] options
+    # @option options [Boolean] :prepend Is there something about this deferred_operation that should happen first?
+    # @param deferred_operation [#call] The operation that will be applied to the generated class
+    #
+    # @return void
+    def defer(**options, &deferred_operation)
       if options[:prepend]
         instance_operations.unshift(deferred_operation)
       else
@@ -121,6 +159,16 @@ module Democritus
     private
 
     # @api public
+    #
+    # The guts of the Democritus plugin system. The ClassBuilder brokers missing methods to registered commands within the
+    # CommandNamespace.
+    #
+    # @param method_name [Symbol] Name of the message being sent to this object
+    # @param args Non-keyword arguments for the message sent to this object
+    # @param kargs Keyword arguments for the message sent to this object
+    # @param block Block argument for the message sent to this object
+    # @return void if there is a Command object that is called
+    # @return unknown if no Command object is found
     def method_missing(method_name, *args, **kargs, &block)
       command_name = self.class.command_name_for_method(method_name)
       command_namespace = command_namespace_for(command_name)
@@ -133,17 +181,26 @@ module Democritus
     end
 
     # @api public
+    #
+    # A required sibling method when implementing #method_missing
+    #
+    # @param method_name [Symbol] Name of the message being sent to this object
+    # @param args Additional arguments passed to the query
+    # @return Boolean
     def respond_to_missing?(method_name, *args)
       respond_to_definition(method_name, :respond_to_missing?, *args)
     end
 
-    # @api public
+    # @api private
     def respond_to_definition(method_name, *)
       command_name = self.class.command_name_for_method(method_name)
       command_namespace_for(command_name)
     end
 
     # @api private
+    #
+    # Find the first matching the command_namespace that contains the given
+    # command_name
     def command_namespace_for(command_name)
       command_namespaces.detect { |cs| cs.const_defined?(command_name) }
     end

data/lib/democritus/class_builder/command.rb

@@ -1,3 +1,5 @@
+require 'forwardable'
+
 module Democritus
   class ClassBuilder
     # @api public
@@ -17,16 +19,17 @@ module Democritus
       end
 
       # @api public
-      #
       # @abstract Subclass and override #call to implement
+      #
+      # Responsible for applying changes to the class that is being built.
+      #
+      # @return void
       def call
         fail(NotImplementedError, 'Method #call should be overriden in child classes')
       end
 
-      # @api private
-      def defer(options = {}, &block)
-        builder.defer(options, &block)
-      end
+      extend Forwardable
+      def_delegator :builder, :defer
 
       private
 

data/lib/democritus/class_builder/commands/attribute.rb

@@ -5,14 +5,21 @@ module Democritus
     module Commands
       # Command to assign an attribute to the given built class.
       class Attribute < ::Democritus::ClassBuilder::Command
+        # @param builder [#defer, Democritus::ClassBuilder]
+        # @param name [#to_sym] The name of the attribute
+        # @param options [Hash] The configuration options of the attribute
         def initialize(name:, **options)
           self.builder = options.fetch(:builder)
           self.name = name
           self.options = options
         end
 
-        attr_reader :name, :options
+        attr_reader :name
+        attr_reader :options
 
+        # Generate the code for the attribute
+        #
+        # @return void
         # :reek:NestedIterators: { exclude: [ 'Democritus::ClassBuilder::Commands::Attribute#call' ] }
         def call
           defer do |subject|
@@ -26,7 +33,11 @@ module Democritus
 
         private
 
-        attr_writer :name, :options
+        attr_writer :options
+
+        def name=(input)
+          @name = input.to_sym
+        end
       end
     end
   end

data/lib/democritus/class_builder/commands/attributes.rb

@@ -12,39 +12,74 @@ module Democritus
       #   end
       class Attributes < ::Democritus::ClassBuilder::Command
         # @param builder [Democritus::ClassBuilder]
-        # @param additional_configuration [Proc] A means to nest additional configuration
-        def initialize(builder:, &additional_configuration)
+        # @param pre_deferment_operation [Proc] A means to nest additional operations
+        def initialize(builder:, &pre_deferment_operation)
           self.builder = builder
-          self.additional_configuration = additional_configuration
+          self.pre_deferment_operation = pre_deferment_operation
           self.attribute_names = []
         end
 
-        # :reek:NestedIterators: { exclude: [ 'Democritus::ClassBuilder::Commands::Attributes#call' ] }
-        # :reek:TooManyStatements: { exclude: [ 'Democritus::ClassBuilder::Commands::Attributes#call' ] }
+        # @api public
+        #
+        # Method that generates the behavior for the Attributes command
+        #
+        # @return void
+        # @see Democritus::ClassBuilder#defer
         def call
+          # In order to register any nested attributes, the pre_deferment_operation must be performed
+          # outside of the defer method call. If it were done inside the defer block, then the pre_deferment_operation
+          # might get lost.
+          execute_pre_deferment_operation
+          defer { |subject| configure(subject: subject) }
+        end
+
+        private
+
+        def execute_pre_deferment_operation
+          return unless pre_deferment_operation.respond_to?(:call)
           # It may seem a little odd to yield self via an instance_exec, however in some cases I need a
           # receiver for messages (i.e. FromJsonClassBuilder)
-          instance_exec(self, &additional_configuration) if additional_configuration.respond_to?(:call)
-          defer do |subject|
-            subject.module_exec(@attribute_names) do |attribute_names|
-              define_method(:initialize) do |**attributes|
-                attribute_names.each do |attribute_name|
-                  send("#{attribute_name}=", attributes.fetch(attribute_name.to_sym, nil))
-                end
+          instance_exec(self, &pre_deferment_operation)
+        end
+
+        # :reek:NestedIterators: { exclude: [ 'Democritus::ClassBuilder::Commands::Attributes#configure' ] }
+        def configure(subject:)
+          subject.module_exec(@attribute_names) do |attribute_names|
+            define_method(:initialize) do |**attributes|
+              attribute_names.each do |attribute_name|
+                send("#{attribute_name}=", attributes.fetch(attribute_name.to_sym, nil))
               end
             end
           end
         end
 
+        public
+
+        # @!group Commands Available Within the pre_deferment_operation
+
+        # @api public
+        #
+        # Exposes a mechanism for assigning individual attributes as part of the #attributes command.
+        #
+        # @param name [#to_sym] the name of the attribute
+        # @param options [Hash] additional options passed to the builder#attribute command
+        #
+        # @see Democritus::ClassBuilder::Commands::Attribute
+        # @see Democritus::ClassBuilder
         def attribute(name:, **options)
           name = name.to_sym
           attribute_names << name
           builder.attribute(name: name, **options)
         end
 
+        # @!endgroup
+
         private
 
-        attr_accessor :additional_configuration, :attribute_names
+        attr_accessor :pre_deferment_operation
+
+        # [Array] of attribute names that have been generated
+        attr_accessor :attribute_names
       end
     end
   end

data/lib/democritus/from_json_class_builder.rb

@@ -49,6 +49,7 @@ module Democritus
       class_builder.generate_class
     end
 
+    # Used to answer the question "Does the given Hash key represent a command?"
     KEY_IS_COMMAND_REGEXP = /\A\#(.+)$/.freeze
 
     private

data/lib/democritus/version.rb

@@ -2,5 +2,5 @@ module Democritus
   # Democritus is striving to adhere to semantic versioning.
   #
   # @see semver.org
-  VERSION = "0.2.0"
+  VERSION = "0.2.1"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: democritus
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.2.1
 platform: ruby
 authors:
 - Jeremy Friesen
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2016-01-07 00:00:00.000000000 Z
+date: 2016-01-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -67,21 +67,7 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '1.2'
 - !ruby/object:Gem::Dependency
-  name: reek
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-- !ruby/object:Gem::Dependency
-  name: flay
+  name: rubycritic
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
@@ -151,7 +137,7 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
-  name: byebug
+  name: shoulda-matchers
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
@@ -164,7 +150,7 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-description: A placeholder for an attribute declaration mechanism
+description: Democritus is library for building classes from reusable components.
 email:
 - jeremy.n.friesen@gmail.com
 executables: []
@@ -173,6 +159,7 @@ extra_rdoc_files: []
 files:
 - ".gitignore"
 - ".hound.yml"
+- ".rspec"
 - ".travis.yml"
 - Gemfile
 - LICENSE
@@ -211,5 +198,5 @@ rubyforge_project:
 rubygems_version: 2.4.7
 signing_key: 
 specification_version: 4
-summary: A placeholder for an attribute declaration mechanism
+summary: Democritus is library for building classes from reusable components.
 test_files: []